flowviant 0.125.4 → 0.125.6

package/bin/lib/codexSubagents.mjs

@@ -3,15 +3,22 @@
  * rollouts named by this turn's native spawn receipts, never a global latest.
  * rust-v0.160.0: exec_events.rs CollabToolCallItem; core/agent/child_config.rs
  * reapplies the live turn's approval and permission profile after role config.
+ * V2 rollout shapes measured on codex-cli 0.163.0 (codexSubagents.test.mjs).
  */
 import { open } from 'node:fs/promises';
 import { codexRolloutFile } from './runtimeLimits.mjs';
+import { CODEX_CHILD_THREAD_RE } from './conversationIds.mjs';
+import { followJsonl } from './jsonlTail.mjs';
 import { codexCollabUpdates, codexSpawnResult, statusOf } from './codexSubagentEvents.mjs';
+import { NATIVE_AGENT_TOOLS } from './nativeAgentTools.mjs';
+import { SUBAGENT_CAP } from './subagentBounds.mjs';
 
-export const SUBAGENT_LIMIT = 32;
-const READ_BYTES = 256 * 1024;
-const INITIAL_SCAN = 4 * 1024 * 1024;
-const THREAD_ID = /^[a-zA-Z0-9-]{16,64}$/;
+const CODEX = NATIVE_AGENT_TOOLS.codex;
+// A rollout shows a superset of what the gate sees: send_message and the
+// stop tools too.
+const COLLAB_CALLS = [...CODEX.spawn, ...CODEX.followup, ...CODEX.message, ...CODEX.stop];
+// The calls whose output names a child's receipt.
+const RECEIPT_CALLS = [...CODEX.spawn, ...CODEX.followup];
 
 export function createCodexSubagentReader({ since = Date.now(), env = process.env, onSubagent, onActivity, onToolEvent, onSpawnResult,
   findFile = codexRolloutFile } = {}) {
@@ -24,8 +31,9 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
   let stopped = false;
   let chain = Promise.resolve();
   const report = update => {
-    if (!update?.id || !THREAD_ID.test(update.id)) return;
-    if (!readers.has(update.id) && readers.size >= SUBAGENT_LIMIT + 1) return;
+    if (!update?.id || !CODEX_CHILD_THREAD_RE.test(update.id)) return;
+    // The root thread plus the run's children.
+    if (!readers.has(update.id) && readers.size >= SUBAGENT_CAP + 1) return;
     if (!readers.has(update.id))
       readers.set(update.id, { offset: null, rest: Buffer.alloc(0), seen: new Set(), live: false });
     const { message, ...record } = update;
@@ -35,7 +43,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
     targets.set(path, id);
     if (targets.size > 128) targets.delete(targets.keys().next().value);
   };
-  const targetId = value => targets.get(value) ?? (THREAD_ID.test(value ?? '') ? value : null);
+  const targetId = value => targets.get(value) ?? (CODEX_CHILD_THREAD_RE.test(value ?? '') ? value : null);
 
   function observe(ev, owner) {
     const at = Date.parse(ev?.timestamp ?? '');
@@ -68,40 +76,52 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
         if (command) step(p.call_id, Array.isArray(command) ? command.join(' ') : command);
         return;
       }
-      if (owner !== root && name === 'request_user_input') {
+      if (owner !== root && CODEX.ask.includes(name)) {
         questions.set(p.call_id, owner);
         if (questions.size > 128) questions.delete(questions.keys().next().value);
         report({ id: owner, status: 'asked' }); return;
       }
-      if (!['spawn_agent', 'send_input', 'send_message', 'followup_task', 'resume_agent', 'close_agent', 'interrupt_agent'].includes(name)) return;
+      if (!COLLAB_CALLS.includes(name)) return;
       let args;
       try { args = JSON.parse(p.arguments); } catch { return; }
       calls.set(p.call_id, { name, args });
       if (calls.size > 128) calls.delete(calls.keys().next().value);
       const id = targetId(args.target ?? args.id);
       if (id && name !== 'spawn_agent') {
-        const stopped = name === 'close_agent' || name === 'interrupt_agent';
+        const stopped = CODEX.stop.includes(name);
         report({ id, ...(stopped ? { status: 'stopped' } : name === 'followup_task' ? { status: 'running' } : {}) });
       }
     }
     if (ev.type === 'response_item' && p.type === 'function_call_output') {
       if (questions.has(p.call_id)) { report({ id: questions.get(p.call_id), status: 'running' }); questions.delete(p.call_id); }
       const call = calls.get(p.call_id);
-      if (!['spawn_agent', 'followup_task', 'resume_agent', 'send_input'].includes(call?.name)) return;
-      let output;
+      if (!RECEIPT_CALLS.includes(call?.name)) return;
+      let output = null;
       try {
         const body = Array.isArray(p.output) ? p.output.map(b => b.text ?? '').join('') : p.output;
         output = typeof body === 'string' ? JSON.parse(body) : body;
-      } catch { onSpawnResult?.({ callId: p.call_id, success: false }); return; }
-      const id = output?.agent_id ?? output?.thread_id;
-      const receipt = id ?? output?.agent_path ?? (call.name !== 'spawn_agent' && (output?.submission_id || output?.status) ? call.args.target ?? call.args.id : null);
-      onSpawnResult?.({ callId: p.call_id, success: Boolean(receipt), ...(receipt ? { nativeId: receipt } : {}) });
+      } catch { /* the tool's own words */ }
+      // ONLY AN EXPLICIT FAILURE FREES A SLOT (2026-10-17). These tools answer
+      // JSON on success (their output schemas), so plain text is the native
+      // error ("collab spawn failed: …"); V2 followup_task declares no output,
+      // and a JSON answer naming no receipt is unknown. Neither is a failure.
+      if (!output || typeof output !== 'object') {
+        if (call.name !== 'followup_task') onSpawnResult?.({ callId: p.call_id, success: false });
+        return;
+      }
+      // V2 (measured on 0.163) answers only the canonical task path; the
+      // thread arrived first, on the spawn's SubAgentActivity.
+      const path = output.task_name ?? output.agent_path;
+      const id = output.agent_id ?? output.thread_id ?? (typeof path === 'string' ? targets.get(path) : undefined);
+      const receipt = call.name === 'spawn_agent' ? output.agent_id ?? output.thread_id ?? path
+        : output.submission_id || output.status ? call.args.target ?? call.args.id : null;
+      if (receipt) onSpawnResult?.({ callId: p.call_id, success: true, nativeId: receipt });
       if (call.name !== 'spawn_agent') return;
       if (!id) return;
       const args = call.args;
       const title = args.task_name ?? args.description ?? output.agent_nickname ?? '';
       if (args.task_name) rememberTarget(args.task_name, id);
-      if (output.agent_path) rememberTarget(output.agent_path, id);
+      if (typeof path === 'string') rememberTarget(path, id);
       report({ id, kind: args.agent_type ?? '', title, brief: args.message ?? '', status: 'running', now: '' });
       return;
     }
@@ -112,7 +132,13 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
     if (ev.type !== 'event_msg') return;
     const activityState = item => {
       const kind = String(item.kind ?? '').toLowerCase();
-      if (item.agent_thread_id) report({ id: item.agent_thread_id, title: item.agent_path,
+      if (!item.agent_thread_id) return;
+      if (item.agent_path) rememberTarget(item.agent_path, item.agent_thread_id);
+      // A start carries the spawn's own call id (measured on 0.163): the
+      // controller binds the native thread to the record that call reserved.
+      const callId = kind === 'started' ? item.call_id ?? item.id : null;
+      report({ id: item.agent_thread_id, title: item.agent_path,
+        ...(typeof callId === 'string' && callId ? { callId } : {}),
         ...(['started', 'completed', 'interrupted'].includes(kind) ? {
           status: kind === 'completed' ? 'done' : kind === 'interrupted' ? 'stopped' : 'running',
         } : {}),
@@ -163,41 +189,18 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
       if (!file) return;
       state.file = file;
       fh = await open(file, 'r');
-      const { size } = await fh.stat();
       const initial = state.offset === null;
       const initialEvents = [];
-      if (initial) {
-        state.offset = Math.max(0, size - INITIAL_SCAN);
-        state.skip = state.offset > 0;
-      }
-      if (size < state.offset) { state.offset = 0; state.rest = Buffer.alloc(0); }
-      // Bounded work per poll, including an immediately completed child.
-      const end = Math.min(size, state.offset + INITIAL_SCAN);
-      while (state.offset < end) {
-        const buffer = Buffer.alloc(Math.min(READ_BYTES, end - state.offset));
-        const { bytesRead } = await fh.read(buffer, 0, buffer.length, state.offset);
-        if (!bytesRead) break;
-        state.offset += bytesRead;
-        const data = Buffer.concat([state.rest, buffer.subarray(0, bytesRead)]);
-        let start = 0, nl;
-        while ((nl = data.indexOf(10, start)) >= 0) {
-          const line = data.subarray(start, nl).toString('utf8');
-          start = nl + 1;
-          if (state.skip) { state.skip = false; continue; }
-          try {
-            const ev = JSON.parse(line);
-            if (initial && id !== root) initialEvents.push(ev);
-            else if (id === root || state.live || ev.type === 'session_meta') observe(ev, id);
-            else if (ev.type === 'event_msg' && ['task_started', 'turn_started'].includes(ev.payload?.type)) {
-              state.live = true; observe(ev, id);
-            }
-          } catch { /* non-JSON/unknown native events */ }
-        }
-        // Keep bytes across UTF-8 and partial-line boundaries. Oversized lines
-        // are discarded through their newline rather than reparsed as a suffix.
-        state.rest = data.subarray(start);
-        if (state.rest.length > READ_BYTES) { state.rest = Buffer.alloc(0); state.skip = true; }
-      }
+      await followJsonl(fh, state, line => {
+        try {
+          const ev = JSON.parse(line);
+          if (initial && id !== root) initialEvents.push(ev);
+          else if (id === root || state.live || ev.type === 'session_meta') observe(ev, id);
+          else if (ev.type === 'event_msg' && ['task_started', 'turn_started'].includes(ev.payload?.type)) {
+            state.live = true; observe(ev, id);
+          }
+        } catch { /* non-JSON/unknown native events */ }
+      });
       if (initial && id !== root) {
         // A fork copies the parent's old EventMsgs. Only the child's newest
         // native turn belongs to this card; inherited history is never replayed.
@@ -219,7 +222,7 @@ export function createCodexSubagentReader({ since = Date.now(), env = process.en
   };
   return {
     thread(id) {
-      if (!THREAD_ID.test(id ?? '') || root) return;
+      if (!CODEX_CHILD_THREAD_RE.test(id ?? '') || root) return;
       root = id;
       readers.set(id, { offset: null, rest: Buffer.alloc(0), seen: new Set(), live: false });
       if (!stopped) { timer = setInterval(() => void flush(), 1_000); timer.unref?.(); }

package/bin/lib/codexToml.mjs

@@ -0,0 +1,328 @@
+/**
+ * CODEX'S config.toml SYNTAX, IN ONE IMPORT-FREE HOME (2026-10-18, the SOLID
+ * pass): the bounded reader, the value writer and the key quoting every Codex
+ * module writes with. Split out because codexPersonal.mjs (the login carry)
+ * took its string quoter `toml` from projectToolRuntimes.mjs (the runtime
+ * table), which imported codexPersonal.mjs back for the reader, and
+ * codexFencedMount.mjs imported both — a three-module cycle that loaded only
+ * because every use across it sat inside a function. MEASURED on scratch
+ * copies: one top-level `toml(...)` in codexPersonal.mjs made importing
+ * projectToolRuntimes.mjs throw "Cannot access 'toml' before
+ * initialization", so which module a caller imported first decided whether
+ * the daemon started; and the uplink scrubber, which wants only the provider
+ * secrets, loaded the runtime tool table and the fenced mount through it. The
+ * one bare-key quoter had two copies (`bareOr`, `bareKeyOr`); it is `bareKey`.
+ * The string quoter had a third, orchestratorHooks.mjs's `quote` for the
+ * Codex hook rows' `-c` values; it is `toml`.
+ *
+ * A LEAF: no imports. codexPersonal.mjs, codexFencedMount.mjs and
+ * projectToolRuntimes.mjs import it, never each other for it
+ * (codexToml.test.mjs).
+ */
+
+export const toml = (value) => JSON.stringify(String(value));
+
+/** A table header's dotted keys, unquoted — null for one this reader cannot
+ *  split, which is then nobody's to strip. */
+export function headerKeys(section) {
+  const key = /\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|([A-Za-z0-9_-]+))\s*(?:\.|$)/y;
+  const keys = [];
+  for (let i = 0; i < section.length; ) {
+    key.lastIndex = i;
+    const m = key.exec(section);
+    if (!m || key.lastIndex === i) return null;
+    try {
+      keys.push(m[1] !== undefined ? JSON.parse(`"${m[1]}"`) : m[2] ?? m[3]);
+    } catch {
+      return null;
+    }
+    i = key.lastIndex;
+  }
+  return keys;
+}
+
+/** The dotted keys a `key = …` / `key.sub = …` line defines, unquoted, or
+ *  null for a line that defines none this reader can split. */
+export function lineKeys(line) {
+  const key = /\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|([A-Za-z0-9_-]+))\s*([.=])/y;
+  const keys = [];
+  for (let i = 0; ; ) {
+    key.lastIndex = i;
+    const m = key.exec(line);
+    if (!m) return null;
+    try {
+      keys.push(m[1] !== undefined ? JSON.parse(`"${m[1]}"`) : m[2] ?? m[3]);
+    } catch {
+      return null;
+    }
+    if (m[4] === '=') return keys;
+    i = key.lastIndex;
+  }
+}
+
+/** Arrays and inline tables nest no deeper than this in a file we read. */
+const MAX_DEPTH = 32;
+
+/** A number, date or time, kept as written so it is carried as written. */
+export class TomlRaw {
+  constructor(text) {
+    this.text = text;
+  }
+}
+export const newTable = () => Object.create(null);
+export const isTable = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof TomlRaw);
+
+const BARE = /[A-Za-z0-9_-]+/y;
+// First match wins, so the forms that begin like an integer come first.
+const SCALAR =
+  /[+-]?(?:inf|nan)|0x[0-9A-Fa-f](?:_?[0-9A-Fa-f])*|0o[0-7](?:_?[0-7])*|0b[01](?:_?[01])*|\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:[Zz]|[+-]\d{2}:\d{2})?)?|\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?|[+-]?\d(?:_?\d)*(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?/y;
+
+/**
+ * A BOUNDED TOML READER — the repo carries no TOML library, and the one file
+ * it reads is Codex's own config. Whole documents: tables, arrays of tables
+ * (the daemon's own `[[skills.config]]` in an agent's home), dotted and quoted
+ * keys, the four string forms, arrays, inline tables, booleans, and numbers,
+ * dates and times kept as written. Anything else throws, and the caller
+ * carries nothing — a partial read is never a license to guess.
+ */
+export function parseCodexToml(text) {
+  const src = String(text).replace(/^/, '');
+  const n = src.length;
+  let i = 0;
+  const fail = (why) => {
+    throw new Error(`config.toml: ${why} at offset ${i}`);
+  };
+  const ws = () => {
+    while (i < n && (src[i] === ' ' || src[i] === '\t')) i++;
+  };
+  const comment = () => {
+    if (src[i] === '#') while (i < n && src[i] !== '\n') i++;
+  };
+  const newline = () => {
+    if (src[i] === '\n') return (i += 1), true;
+    if (src[i] === '\r' && src[i + 1] === '\n') return (i += 2), true;
+    return false;
+  };
+  /** Blank lines, comments and whitespace, as between array items. */
+  const gap = () => {
+    for (;;) {
+      ws();
+      comment();
+      if (!newline()) return;
+    }
+  };
+  const endOfLine = () => {
+    ws();
+    comment();
+    if (i < n && !newline()) fail('expected the end of the line');
+  };
+  const hexChar = (len) => {
+    const h = src.slice(i, i + len);
+    if (h.length !== len || !/^[0-9A-Fa-f]+$/.test(h)) fail('bad escape');
+    i += len;
+    const cp = parseInt(h, 16);
+    if (cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff)) fail('bad escape');
+    return String.fromCodePoint(cp);
+  };
+  const escape = () => {
+    const e = src[i + 1];
+    i += 2;
+    switch (e) {
+      case 'b': return '\b';
+      case 't': return '\t';
+      case 'n': return '\n';
+      case 'f': return '\f';
+      case 'r': return '\r';
+      case 'e': return '\x1b';
+      case '"': return '"';
+      case '\\': return '\\';
+      case 'x': return hexChar(2);
+      case 'u': return hexChar(4);
+      case 'U': return hexChar(8);
+      default: return fail('bad escape');
+    }
+  };
+  const basicString = () => {
+    i += 1;
+    let s = '';
+    for (;;) {
+      if (i >= n) fail('unterminated string');
+      const ch = src[i];
+      if (ch === '"') return (i += 1), s;
+      if (ch === '\n' || ch === '\r') fail('newline in a string');
+      if (ch === '\\') s += escape();
+      else (s += ch), (i += 1);
+    }
+  };
+  const literalString = () => {
+    const end = src.indexOf("'", i + 1);
+    if (end < 0) fail('unterminated string');
+    const s = src.slice(i + 1, end);
+    if (/[\r\n]/.test(s)) fail('newline in a string');
+    i = end + 1;
+    return s;
+  };
+  const LINE_END_BACKSLASH = /\\[ \t]*\r?\n/y;
+  const multiline = (quote, escapes) => {
+    i += 3;
+    newline(); // a newline straight after the opening quotes is not content
+    let s = '';
+    for (;;) {
+      if (i >= n) fail('unterminated string');
+      if (src.startsWith(quote.repeat(3), i)) {
+        let q = 3;
+        while (q < 5 && src[i + q] === quote) q++; // up to two belong to the content
+        s += quote.repeat(q - 3);
+        i += q;
+        return s;
+      }
+      if (escapes && src[i] === '\\') {
+        LINE_END_BACKSLASH.lastIndex = i;
+        if (LINE_END_BACKSLASH.test(src)) {
+          i = LINE_END_BACKSLASH.lastIndex;
+          while (i < n && /[ \t\r\n]/.test(src[i])) i++;
+        } else s += escape();
+      } else (s += src[i]), (i += 1);
+    }
+  };
+  const key = () => {
+    const parts = [];
+    for (;;) {
+      ws();
+      if (src[i] === '"') {
+        if (src.startsWith('"""', i)) fail('a multi-line key');
+        parts.push(basicString());
+      } else if (src[i] === "'") {
+        if (src.startsWith("'''", i)) fail('a multi-line key');
+        parts.push(literalString());
+      } else {
+        BARE.lastIndex = i;
+        const m = BARE.exec(src);
+        if (!m) fail('expected a key');
+        parts.push(m[0]);
+        i = BARE.lastIndex;
+      }
+      ws();
+      if (src[i] !== '.') return parts;
+      i += 1;
+    }
+  };
+  const assign = (target, path, v) => {
+    let t = target;
+    for (const k of path.slice(0, -1)) {
+      if (!Object.hasOwn(t, k)) t[k] = newTable();
+      else if (!isTable(t[k])) fail(`"${k}" is not a table`);
+      t = t[k];
+    }
+    const last = path.at(-1);
+    if (Object.hasOwn(t, last)) fail(`"${last}" is defined twice`);
+    t[last] = v;
+  };
+  let depth = 0;
+  const nested = (open) => {
+    if (++depth > MAX_DEPTH) fail('nested too deep');
+    try {
+      return open();
+    } finally {
+      depth -= 1;
+    }
+  };
+  const array = () => {
+    i += 1;
+    const out = [];
+    for (;;) {
+      gap();
+      if (src[i] === ']') return (i += 1), out;
+      out.push(value());
+      gap();
+      if (src[i] === ',') i += 1;
+      else if (src[i] === ']') return (i += 1), out;
+      else fail('expected , or ]');
+    }
+  };
+  const inlineTable = () => {
+    i += 1;
+    const t = newTable();
+    for (;;) {
+      gap();
+      if (src[i] === '}') return (i += 1), t;
+      keyValue(t);
+      gap();
+      if (src[i] === ',') i += 1;
+      else if (src[i] === '}') return (i += 1), t;
+      else fail('expected , or }');
+    }
+  };
+  const word = (w) => src.startsWith(w, i) && !/[A-Za-z0-9_-]/.test(src[i + w.length] ?? '');
+  const value = () => {
+    const ch = src[i];
+    if (ch === '"') return src.startsWith('"""', i) ? multiline('"', true) : basicString();
+    if (ch === "'") return src.startsWith("'''", i) ? multiline("'", false) : literalString();
+    if (ch === '[') return nested(array);
+    if (ch === '{') return nested(inlineTable);
+    if (word('true')) return (i += 4), true;
+    if (word('false')) return (i += 5), false;
+    SCALAR.lastIndex = i;
+    const m = SCALAR.exec(src);
+    if (!m) fail('a value this reader does not know');
+    i = SCALAR.lastIndex;
+    if (/[A-Za-z0-9_.:+-]/.test(src[i] ?? '')) fail('a value this reader does not know');
+    return new TomlRaw(m[0]);
+  };
+  const keyValue = (target) => {
+    const path = key();
+    if (src[i] !== '=') fail('expected =');
+    i += 1;
+    ws();
+    assign(target, path, value());
+  };
+
+  const root = newTable();
+  let current = root;
+  for (;;) {
+    gap();
+    if (i >= n) return root;
+    if (src[i] !== '[') {
+      keyValue(current);
+      endOfLine();
+      continue;
+    }
+    const many = src[i + 1] === '[';
+    i += many ? 2 : 1;
+    const path = key();
+    if (many ? !src.startsWith(']]', i) : src[i] !== ']') fail('an unclosed table header');
+    i += many ? 2 : 1;
+    endOfLine();
+    let t = root;
+    for (const k of path.slice(0, -1)) {
+      if (!Object.hasOwn(t, k)) t[k] = newTable();
+      const v = Array.isArray(t[k]) ? t[k].at(-1) : t[k];
+      if (!isTable(v)) fail(`"${k}" is not a table`);
+      t = v;
+    }
+    const last = path.at(-1);
+    if (many) {
+      if (!Object.hasOwn(t, last)) t[last] = [];
+      if (!Array.isArray(t[last])) fail(`"${last}" is not an array of tables`);
+      current = newTable();
+      t[last].push(current);
+    } else {
+      if (!Object.hasOwn(t, last)) t[last] = newTable();
+      else if (!isTable(t[last])) fail(`"${last}" is not a table`);
+      current = t[last];
+    }
+  }
+}
+
+/** A key as TOML writes it: bare where it can be, else quoted. */
+export const bareKey = (k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : toml(k));
+
+/** One value as TOML, as a `-c` override's value is parsed. */
+export function tomlValue(v) {
+  if (typeof v === 'string') return toml(v);
+  if (typeof v === 'boolean') return String(v);
+  if (v instanceof TomlRaw) return v.text;
+  if (Array.isArray(v)) return `[${v.map(tomlValue).join(',')}]`;
+  if (isTable(v)) return `{${Object.keys(v).map((k) => `${bareKey(k)}=${tomlValue(v[k])}`).join(',')}}`;
+  throw new Error('not a TOML value');
+}

package/bin/lib/conversationIds.mjs

@@ -35,6 +35,16 @@ export const CLAUDE_SESSION_RE = /^[A-Za-z0-9_-]{8,64}$/;
  */
 export const CODEX_THREAD_RE = /^[0-9a-zA-Z][0-9a-zA-Z_-]{7,63}$/;
 
+/**
+ * A Codex native CHILD's thread id as the subagent lane follows it
+ * (codexSubagentEvents.mjs, codexSubagents.mjs). Its measured value,
+ * unchanged when its two copies moved here (2026-10-18). The rollout lookup
+ * it then reaches still guards with CODEX_THREAD_RE (runtimeLimits.mjs
+ * codexRolloutFile). Making the two one shape is a behaviour change for the
+ * owner to rule on.
+ */
+export const CODEX_CHILD_THREAD_RE = /^[a-zA-Z0-9-]{16,64}$/;
+
 /** agy conversation ids are plain UUIDs (the db filename IS the identity —
  *  measured: a renamed copy fails "trajectory not found"). Guarded the same
  *  way as the codex id: it rides in argv as `--conversation <id>`. */

package/bin/lib/fleet.mjs

@@ -38,7 +38,7 @@ import { compareVersions } from './versionOrder.mjs';
 import { emitMachineEvent } from './daemonLogging.mjs';
 import { writeDaemonState } from './daemonState.mjs';
 import { maintenanceTick, readMaintenance } from './maintenance.mjs';
-import { repoRootOrDie, detectBaseRef, baseBranchName, excludeInWorktree, usableBaseRef } from './git.mjs';
+import { repoRootOrDie, detectBaseRef, excludeInWorktree, baseRefFor } from './git.mjs';
 import { c, info, note, ok, warn, fail } from './ui.mjs';
 import { sleep } from './sleep.mjs';
 import { reapOrphanPreviews } from './previewRegistry.mjs';
@@ -576,7 +576,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     const servedBaseBranch = Array.isArray(roster.repositories)
       ? repositories.list().find((r) => r.repoRoot === repoRoot)?.baseBranch : roster.baseBranch;
     if (typeof servedBaseBranch === 'string' && servedBaseBranch.trim()) {
-      const want = usableBaseRef(repoRoot, `origin/${baseBranchName(servedBaseBranch.trim())}`);
+      const want = baseRefFor(repoRoot, servedBaseBranch.trim());
       if (want !== baseRef) {
         note(`base   · ${want} ${c.dim('(set for this project)')}`);
         baseRef = want;

package/bin/lib/git.mjs

@@ -333,6 +333,38 @@ export function usableBaseRef(repoRoot, ref) {
   return ref;
 }
 
+/**
+ * The BASE REF a repository lands on: its configured branch when a human set
+ * one (`origin/<branch>`, or the local branch where there is no origin), else
+ * the detected one. One home (2026-10-18, the SOLID pass); was written in
+ * repositoryMerge, mergeBatch, projectRepositories and fleet, so a change to
+ * how a configured base resolves needed four edits that had to agree.
+ */
+export function baseRefFor(repoRoot, baseBranch) {
+  return baseBranch ? usableBaseRef(repoRoot, `origin/${baseBranchName(baseBranch)}`) : detectBaseRef(repoRoot);
+}
+
+/**
+ * Is `a` an ancestor of `b`? A failed probe (an unknown commit included) is
+ * no. One home (2026-10-18, the SOLID pass); was a closure in repositoryMerge,
+ * mergeBatch and repositoryDelivery.
+ */
+export function isAncestor(a, b, cwd) {
+  try { git(['merge-base', '--is-ancestor', a, b], cwd); return true; } catch { return false; }
+}
+
+/**
+ * A repository's base, MEASURED NOW: fetch origin when there is one, then the
+ * base ref and the commit it names. One home (2026-10-18, the SOLID pass);
+ * was a `fetch` closure in repositoryMerge and mergeBatch. `net` is the
+ * caller's (its tests inject one).
+ */
+export function measureBase(repoRoot, baseBranch, net = gitNet) {
+  if (gitOrNull(['remote', 'get-url', 'origin'], repoRoot)) net(['fetch', 'origin', '--quiet'], repoRoot, 60_000);
+  const baseRef = baseRefFor(repoRoot, baseBranch);
+  return { baseRef, baseTip: git(['rev-parse', baseRef], repoRoot) };
+}
+
 /** True when the repository has at least one commit (HEAD resolves). */
 export function hasCommits(repoRoot) {
   try { git(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], repoRoot); return true; } catch { return false; }

package/bin/lib/heldTool.mjs

@@ -0,0 +1,49 @@
+/**
+ * A HELD TURN'S LOOPBACK TOOL, DAEMON SIDE (2026-10-18, the SOLID pass): the
+ * run-scoped capability, its one gate, the loopback listen, the env pair and
+ * the argv that starts the tool's child.
+ *
+ * A held turn's CLI never receives the machine token. A card tool it may
+ * call is a server on 127.0.0.1 that answers only a POST to `/` bearing a
+ * capability minted for this one run, and a bare 403 to anything else. That
+ * gate is a security boundary, and it was written out twice, two days apart
+ * (repositoryTool.mjs 2026-10-14, orchestrator.mjs 2026-10-15), with the
+ * listen, the env pair and the self-argv beside it. Each tool keeps its own
+ * body reader, limits, refusals and close order; the child half is
+ * mcpStdio.mjs plus each tool's own client.
+ *
+ * `heldToolArgv` keeps the `import.meta.url` form: launchCommand.mjs's
+ * `selfArgv` reads process.argv[1], which under the suite is the test file.
+ */
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { sameSecret } from './grant.mjs';
+import { runningCompiledBinary } from './launchCommand.mjs';
+
+/** One run's capability: the only credential the tool's child ever holds. */
+export const mintHeldCapability = () => randomBytes(32).toString('hex');
+
+/** The argv that starts this flowviant again as `verb`, under node or the compiled binary. */
+export function heldToolArgv(verb) {
+  return runningCompiledBinary() ? [verb] : [fileURLToPath(new URL('../cli.mjs', import.meta.url)), verb];
+}
+
+/**
+ * Listen on a loopback port for one held tool. `respond(req, res)` answers
+ * only a request that passed the gate; `isClosed()` shuts the gate before the
+ * server stops. Returns the server (the caller closes it, in its own order),
+ * the capability, `<envPrefix>_URL`/`_CAPABILITY`, and the child's argv.
+ */
+export async function listenHeldTool({ envPrefix, verb, requestTimeoutMs, capability = mintHeldCapability(), isClosed, respond }) {
+  const server = createServer(async (req, res) => {
+    if (isClosed() || req.method !== 'POST' || req.url !== '/' || !sameSecret(req.headers.authorization, `Bearer ${capability}`)) {
+      res.writeHead(403).end(); return;
+    }
+    await respond(req, res);
+  });
+  server.requestTimeout = requestTimeoutMs;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const env = { [`${envPrefix}_URL`]: `http://127.0.0.1:${server.address().port}/`, [`${envPrefix}_CAPABILITY`]: capability };
+  return { server, capability, env, args: heldToolArgv(verb) };
+}