flowviant 0.125.4 → 0.125.6

package/bin/lib/runtimeClaude.mjs

@@ -14,14 +14,12 @@ import { mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { MODEL, USER_AGENT } from './config.mjs';
-import { NO_SETTING_SOURCES, personalClaudeSettings, releaseTurnSettings, withPersonalSettings } from './claudePersonal.mjs';
-import { withMachineMcp } from './claudePosture.mjs';
+import { NO_SETTING_SOURCES, personalClaudeSettings, releaseTurnSettings, withPersonalSettings, writeTurnSettings } from './claudePersonal.mjs';
+import { machineMcpServers } from './claudeMachineMcp.mjs';
+import { claudePermFor, withMachineMcp } from './claudePosture.mjs';
+import { withSettings } from './claudeSettingsArg.mjs';
 import { orchestratorHooks } from './orchestratorHooks.mjs';
 
-/** The profiles an agent lane mounts the machine's MCP servers on (2026-10-11):
- *  the ones whose turn profile says `projectMcp` and that Claude declares. */
-const MACHINE_MCP_PROFILES = Object.freeze(['build', 'design', 'research']);
-
 function claudeMcp(token, mcpUrl) {
   const dir = mkdtempSync(join(tmpdir(), 'flowviant-mcp-'));
   const path = join(dir, 'mcp.json');
@@ -48,10 +46,10 @@ export const CLAUDE_RUNTIME = {
   bin: 'claude',
   install: 'npm i -g @anthropic-ai/claude-code',
   login: 'claude',
-  /** The Agent-SDK live session (persistent, injectable mid-task) is Claude
-   *  only — it is an Anthropic SDK, not a CLI contract. Everything else runs
-   *  the subprocess path. */
-  live: true,
+  /** Takes follow-up messages on stdin mid-turn (claudeInput.mjs,
+   *  workLiveMessages.mjs); a runtime without it gets its follow-ups as the
+   *  next turn, and its delivery is reported taken at spawn. */
+  liveInput: true,
   /**
    * Every profile, because every profile is DEFINED in its vocabulary: the
    * four `--allowedTools` lists in claudePosture.mjs are what "build", "wiki",
@@ -92,17 +90,30 @@ export const CLAUDE_RUNTIME = {
    *     RETIRED_POSTURE_KEYS), so no spelling of it reads as one.
    *   adopt: 'fork' — a terminal conversation is forked into the tab's
    *     worktree (`--resume <id> --fork-session`).
+   *   liveInput (above) — a follow-up reaches the running CLI on stdin
+   *     (2026-10-18, the SOLID pass: the tab, agent and runTurn lanes spelled
+   *     it `rt.id === 'claude'`, and the row's old `live` flag was read by
+   *     nothing).
    */
   tab: 'mcp',
   planTurns: true,
   adopt: 'fork',
   mcp: claudeMcp,
+  /**
+   * THE POSTURE AS CLAUDE'S `--allowedTools` LIST (2026-10-18, the SOLID
+   * pass), looked up by the turn profile's name (claudePosture.mjs
+   * `claudePermFor`). runTurn asks the row for it, so it knows no runtime's
+   * list: a runtime that expresses postures another way — Codex's sandbox
+   * modes, agy's flags — has no hook, and Claude's table needs no stub for a
+   * posture only another CLI runs.
+   */
+  perm: claudePermFor,
   /**
    * Claude takes the operating contract as a real system prompt, which is the
    * strongest form of it available anywhere: `--append-system-prompt` sits
    * above the conversation rather than inside it.
    */
-  args({ writableDirs = [], prompt, system, model, effort, resume, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, streamInput = false, orchestration = false }) {
+  args({ writableDirs = [], prompt, system, model, effort, resume, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, baseMcp = [], mcpCheckout = null, streamInput = false, orchestration = false }) {
     // THE CARTOGRAPHER'S FENCE NAMES ITS VAULT (2026-10-10): its one write rule
     // is the vault's absolute path (claudePosture.mjs `wikiPermFor`), so a turn
     // with no vault, or one no rule can name, has no list — refused here in
@@ -170,7 +181,6 @@ export const CLAUDE_RUNTIME = {
      * agent renders the CURRENT base snapshot, not the first turn's cache.
      */
     const fenced = profile !== 'build';
-    if (orchestration && !fenced) a.push('--settings', JSON.stringify({ hooks: orchestratorHooks(), disableAllHooks: false }));
     if (fenced) a.push(...NO_SETTING_SOURCES);
     // A FENCED POSTURE NAMES ITS OWN MODE (2026-10-10). Its lists fence only
     // under the CLI's `default` mode, where a tool the list does not name is
@@ -191,12 +201,17 @@ export const CLAUDE_RUNTIME = {
     // beside the base branch's `.mcp.json` copy the caller passes, so they are
     // not strict; `machineMcp` names every `.mcp.json` server from the
     // worktree up, which `withMachineMcp` disables so a worktree edit never
-    // mounts before review (claudePosture.mjs). Every other fenced posture —
-    // consult, wiki, and a design/research turn no lane mounted for — stays
-    // strict: it never discovers a .mcp.json, nor loads the machine's servers.
+    // mounts before review (claudePosture.mjs). Every fenced posture but plan
+    // stays strict unless the lane mounted the machine's servers — consult,
+    // wiki, and a design/research turn no lane mounted for: it never discovers
+    // a .mcp.json, nor loads the machine's servers. Keyed on the rule, not a
+    // list of names, so a posture added later is strict unless it mounts.
     // The plan profile keeps its own principal.
-    const machine = Array.isArray(machineMcp) && MACHINE_MCP_PROFILES.includes(profile);
-    if (['consult', 'wiki', 'design', 'research'].includes(profile) && !machine && !mcp.includes('--strict-mcp-config')) a.push('--strict-mcp-config');
+    //
+    // runTurn hands machineMcp only on a profile whose turn profile says
+    // projectMcp (runTurn.mjs), the one rule.
+    const machine = Array.isArray(machineMcp);
+    if (fenced && profile !== 'plan' && !machine && !mcp.includes('--strict-mcp-config')) a.push('--strict-mcp-config');
     a.push(...mcp, ...resultSchemaArgs);
     a.push('--model', model || MODEL);
     if (effort) a.push('--effort', effort);
@@ -221,8 +236,36 @@ export const CLAUDE_RUNTIME = {
     // kept is written to a private file, never onto argv (claudePersonal.mjs)
     // — so this is the LAST thing built: nothing after it may throw and
     // leave the file with no turn to release it.
-    const postured = machine ? withMachineMcp(perm, machineMcp) : perm;
-    a.push(...(fenced ? withPersonalSettings(postured, personalSettings ?? personalClaudeSettings()) : postured));
+    //
+    // …AND THE MACHINE'S SERVERS NO SOURCE OF THIS TURN READS (2026-10-17,
+    // claudeMachineMcp.mjs `machineMcpServers`): the user scope a fenced turn's
+    // empty source list drops, and the checkout's local scope every card turn
+    // missed. In a private file too — a server's env and headers are secrets —
+    // minus every name the base copy mounts, which speaks for the project.
+    const own = (machine ? machineMcpServers({ user: fenced, checkout: mcpCheckout }) : null) ?? {};
+    for (const name of baseMcp) delete own[name];
+    // A file that cannot be written costs the card these servers, never the
+    // card itself: the turn runs with what its own sources load, and says so.
+    let ownArgs = [];
+    if (Object.keys(own).length) {
+      try {
+        ownArgs = ['--mcp-config', writeTurnSettings({ mcpServers: own })];
+      } catch (error) {
+        console.warn(`[agent] this machine's MCP servers are not mounted on this turn: ${error.message}`);
+      }
+    }
+    const mounted = machine ? withMachineMcp(perm, machineMcp) : perm;
+    // The orchestrator's hooks join that same `--settings`: the CLI applies
+    // only the last one it is handed (claudeSettingsArg.mjs `withSettings`).
+    const postured = orchestration && !fenced ? withSettings(mounted, { hooks: orchestratorHooks(), disableAllHooks: false }) : mounted;
+    let tail;
+    try {
+      tail = fenced ? withPersonalSettings(postured, personalSettings ?? personalClaudeSettings()) : postured;
+    } catch (error) {
+      releaseTurnSettings(ownArgs);
+      throw error;
+    }
+    a.push(...ownArgs, ...tail);
     return a;
   },
   /** What `args` wrote for a turn — the fenced posture's settings file —

package/bin/lib/runtimeCodex.mjs

@@ -16,7 +16,7 @@ import { ARTIFACT_DIR, FENCE_TMP_DIR } from './artifacts.mjs';
 import { codexPersonalTurn } from './codexPersonal.mjs';
 import { researchFence } from './codexResearch.mjs';
 import { projectReadBoundary, projectReadFence } from './codexProjectRead.mjs';
-import { compareVersions } from './versionOrder.mjs';
+import { versionAtLeast } from './versionOrder.mjs';
 import { codexOrchestratorArgs } from './orchestratorHooks.mjs';
 
 /**
@@ -27,7 +27,11 @@ import { codexOrchestratorArgs } from './orchestratorHooks.mjs';
  * whose one tool carries no annotations (Flowviant's carry none): under the
  * capture chat's read-only argv the call failed "MCP tool call requires
  * approval, but approval policy is never" and never reached the server; under
- * the build posture (workspace-write) the same call ran unasked. With
+ * the build posture (workspace-write) the same call ran unasked — no longer
+ * so on 0.163.0, where a workspace-write card turn refuses it the same way
+ * and only danger-full-access runs it (2026-10-17; a card approves the
+ * person's own servers by name, projectToolRuntimes.mjs `personalApprovals`).
+ * With
  * `mcp_servers.flowviant.default_tools_approval_mode="approve"` beside the
  * read-only argv it ran — and in the same turn a shell write still failed
  * "Read-only file system" and an escalation still failed "approval policy is
@@ -88,8 +92,7 @@ export const NO_SUBAGENTS = Object.freeze(['-c', 'features.multi_agent=false', '
  * and V2. Older/unmeasured binaries have no inheritance evidence here. */
 export const CODEX_SUBAGENTS_MIN = '0.160.0';
 export function codexSubagentsSafe(version) {
-  const order = compareVersions(String(version ?? '').replace(/^codex-cli\s+/, ''), CODEX_SUBAGENTS_MIN);
-  return order === 0 || order === 1;
+  return versionAtLeast(String(version ?? '').replace(/^codex-cli\s+/, ''), CODEX_SUBAGENTS_MIN);
 }
 
 /**
@@ -183,7 +186,7 @@ export const CODEX_RUNTIME = {
   bin: 'codex',
   install: 'npm i -g @openai/codex',
   login: 'codex login',
-  live: false,
+  liveInput: false,
   /**
    * BUILD AND CONSULT. See `args()` below for how consult is expressed — the
    * short version is that Codex keeps the promise at the kernel rather than in
@@ -296,7 +299,7 @@ export const CODEX_RUNTIME = {
       // before it started. `-c sandbox_mode=` means the same on both.
       if (writableDirs.length) a.push('-c', `sandbox_workspace_write.writable_roots=${JSON.stringify(writableDirs)}`);
       a.push('-c', `sandbox_mode="${SAFE ? 'workspace-write' : 'danger-full-access'}"`);
-      if (cardTurn) a.push('-c', 'approval_policy="never"');
+      if (cardTurn) a.push('-c', 'approval_policy="never"', ...(agentTools?.codexApprovals ?? []));
       a.push(...(cardTurn && profile === 'build' && codexSubagentsSafe(codexVersion)
         ? ['-c', 'features.multi_agent=true', '-c', 'features.goals=false']
         : NO_SUBAGENTS));

package/bin/lib/runtimeEvents.mjs

@@ -14,7 +14,7 @@
  * own stream loop and calls `humanizeClaudeTool`/`toolEventOf` from it.
  */
 
-import { codexCollabUpdates } from './codexSubagentEvents.mjs';
+import { codexCollabUpdates, codexSpawnResult } from './codexSubagentEvents.mjs';
 
 /** Truncate for a one-line activity label. */
 const oneLine = (s, n = 140) =>
@@ -312,7 +312,10 @@ function humanizeCodexItem(item = {}, cwd = '') {
  * threadId }` — `text` accumulates the agent's own words, because the wiki
  * lane reads its sentinels (WIKI_DONE / REGROUND_DONE, claude.mjs
  * `sawSentinel`) out of exactly that; `threadId` surfaces once, off the lifecycle event, for callers that
- * need to resume THIS conversation later (runTurn's onThreadId).
+ * need to resume THIS conversation later (runTurn's onThreadId). `spawnResult`
+ * is a native spawn's receipt (codexSubagentEvents.mjs), relayed to the
+ * orchestrator; it rides any event this parser keeps, read off the same parse
+ * (2026-10-18, the SOLID pass: the spawn lane parsed every line a second time).
  */
 export function parseCodexLine(line, cwd) {
   let ev;
@@ -321,6 +324,14 @@ export function parseCodexLine(line, cwd) {
   } catch {
     return null; // not every line is JSON (warnings go to stderr, but be safe)
   }
+  const parsed = codexEventOf(ev, cwd);
+  if (!parsed) return parsed;
+  const spawnResult = codexSpawnResult(ev.item);
+  return spawnResult ? { ...parsed, spawnResult } : parsed;
+}
+
+/** One ThreadEvent, already parsed, in the daemon's vocabulary. */
+function codexEventOf(ev, cwd) {
   if (['item.started', 'item.updated', 'item.completed'].includes(ev.type) &&
       (ev.item?.type ?? ev.item?.item_type) === 'collab_tool_call')
     return { subagents: codexCollabUpdates(ev.item), activity: null, text: '' };

package/bin/lib/runtimeOfferings.mjs

@@ -1,10 +1,12 @@
 /** Local, bounded Codex readouts. No agent turn is started for these reports. */
 import { execFileSync } from 'node:child_process';
 import { accessSync, constants, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename, delimiter, isAbsolute, join } from 'node:path';
 import { readBaseTools } from './projectTools.mjs';
 import { mcpRefusal } from './projectToolRuntimes.mjs';
 import { CODEX_MCP_NAME, normalizeMcpReport } from './runtimeCapabilities.mjs';
+import { mcpCommandNotFoundReason, mcpEnvUnsetReason } from './mcpReasons.mjs';
 import { unattendedEnv } from './noWindowEnv.mjs';
 import { codexHome } from './codexHome.mjs';
 
@@ -15,9 +17,12 @@ let repoCached = null;
 const nameOk = (name) => typeof name === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(name) && name !== 'flowviant';
 // An unattended CLI child like any other (noWindowEnv.mjs, 2026-10-10): `codex
 // mcp list` may start the person's configured servers, and none of them is
-// handed the machine credential or a display.
+// handed the machine credential or a display. From the home directory
+// (2026-10-17): in a trusted checkout — the daemon's own cwd — Codex lists
+// that checkout's `.codex/config.toml` servers as well (measured, 0.163.0),
+// which no card mounts.
 const run = (args, env) => execFileSync('codex', args, {
-  encoding: 'utf8', timeout: 5000, maxBuffer: 128 * 1024,
+  encoding: 'utf8', timeout: 5000, maxBuffer: 128 * 1024, cwd: homedir(),
   stdio: ['ignore', 'pipe', 'ignore'], env: unattendedEnv(env),
 });
 /**
@@ -105,10 +110,10 @@ export function codexServerRows(servers, env = process.env) {
       reason = typeof s.disabled_reason === 'string' ? s.disabled_reason.slice(0, 200) : null;
     } else if (typeof t.command === 'string' && commandFound(t.command, env) === false) {
       status = 'failed';
-      reason = `command ${basename(t.command).slice(0, 60)} not found`;
+      reason = mcpCommandNotFoundReason(basename(t.command).slice(0, 60));
     } else if (unset.length) {
       status = 'failed';
-      reason = `env ${[...new Set(unset)].sort().join(', ')} unset`;
+      reason = mcpEnvUnsetReason([...new Set(unset)].sort());
     } else if (['needs_auth', 'not_logged_in', 'notLoggedIn'].includes(auth)) {
       status = 'needs-auth';
     } else if (auth === 'failed') {

package/bin/lib/runtimes.mjs

@@ -131,7 +131,9 @@ export const runtimeLabel = (id) => runtimeById(id)?.label ?? String(id);
  * So the restriction is gone and this is back to "installed, and this module
  * knows how to spawn it" — which is what the registry's `live` flag always
  * described: not which runtimes can run, but which get a session instead of a
- * subprocess.
+ * subprocess. (That flag is gone: since 2026-10-18 the rows carry
+ * `liveInput`, a different fact — whether follow-ups reach the running CLI
+ * on stdin.)
  *
  * LIVE is no longer read here. That is deliberate and load-bearing: this
  * predicate feeds both the roster report AND the claim, and if the two ever

package/bin/lib/subagentBounds.mjs

@@ -0,0 +1,20 @@
+/** HOW MANY NATIVE CHILDREN ONE CARD RUN RECORDS, THE FIELD CAPS EACH
+ *  CARRIES, AND THE STATUSES A CHILD HAS (2026-10-18, the SOLID pass). The
+ *  server folds at most `TRACE_AGENT_CAP` children per run, clamps each field
+ *  (`agentTraceAgents.ts`) and refuses a handed route to a child it did not
+ *  keep, so every daemon reader that tracks a child keeps the same bound: a
+ *  33rd is never half-reported, admitted by the controller while the trace
+ *  sheds its descriptor. The cap was spelled eight times across the
+ *  controller, the trace relay, runTurn and both Codex readers (the
+ *  codexSubagentEvents split had copied it), and nothing held it to the
+ *  server. A leaf of its own because trace.mjs, which the web's tests import,
+ *  reads it (mcpReportBounds.mjs argues the same); scripts/check-app-parity.mjs
+ *  holds it to the API's `TRACE_AGENT_CAP`/`TRACE_AGENT_FIELD_CAPS` and the
+ *  shared `SUBAGENT_STATUSES`. */
+
+export const SUBAGENT_CAP = 32;
+/** In the order the trace relay sends them. */
+export const SUBAGENT_FIELD_CAPS = Object.freeze({ kind: 80, title: 200, now: 400, brief: 4_000 });
+export const SUBAGENT_STATUSES = Object.freeze(['running', 'waiting', 'asked', 'stopped', 'done']);
+/** A child that has finished or been stopped: the controller revives neither. */
+export const SETTLED_SUBAGENT_STATUSES = Object.freeze(['done', 'stopped']);

package/bin/lib/trace.mjs

@@ -61,12 +61,16 @@
 
 import { THINK_MARKER, scrubNativeText } from './runtimeEvents.mjs';
 import { withoutTurnDeclaration } from './turnDeclaration.mjs';
+import { MAX_MCP_SERVERS, MCP_NAME_MAX, MCP_STATUSES } from './mcpReportBounds.mjs';
+import { SUBAGENT_CAP, SUBAGENT_FIELD_CAPS, SUBAGENT_STATUSES } from './subagentBounds.mjs';
 
 /** One batch every two seconds — the discipline the tab's narrator keeps, for
  *  the same reason: a turn emits hundreds of entries and nobody is reading them
  *  faster than that. */
 export const TRACE_FLUSH_MS = 2_000;
-/** Entries per POST. Matches the server's own per-batch cap. */
+/** Entries per POST. Matches the server's own per-batch cap
+ *  (`agentTrace.ts.TRACE_BATCH_CAP`), which refuses a larger batch whole;
+ *  scripts/check-app-parity.mjs rule 38 holds the two equal. */
 export const TRACE_BATCH = 40;
 /** Entries held while the uplink is down. Past this the OLDEST go: a trace is
  *  scrollback, and the newest steps are the ones somebody watching wants. The
@@ -77,7 +81,7 @@ export const TRACE_BUFFER = 120;
  * (`agentTrace.ts.TRACE_PROSE_CAP`); doing it here too means a pathological line
  * never becomes the POST. The two must move together — daemon at or below the
  * server's, or the server silently does the cutting and this file's caps stop
- * describing what ships.
+ * describing what ships. scripts/check-app-parity.mjs rule 38 holds them equal.
  *
  * 300 UNTIL 2026-09-16, when it was the thing clipping sentences. A trace entry
  * used to be the humanized 160-char label the console prints, so a 300 cap could
@@ -120,6 +124,7 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
    *  by the bare-marker collapse in `prose()` and nothing else. */
   let lastEntry = null;
   const agentReadings = new Map();
+  const mcpSaid = new Set();
   let dirty = orchestrationVersion === 2;
   let markerPending = dirty;
   let timer = null;
@@ -266,13 +271,13 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
       if (!update?.id) return;
       const clean = (v, n) => scrubNativeText(v, n, scrub);
       const fields = {};
-      for (const [key, cap] of Object.entries({ kind: 80, title: 200, now: 400, brief: 4_000 }))
+      for (const [key, cap] of Object.entries(SUBAGENT_FIELD_CAPS))
         if (typeof update[key] === 'string') fields[key] = clean(update[key], cap);
       if (typeof fields.now === 'string') fields.now = fields.now.replace(/\s+/g, ' ').trim();
-      if (['running', 'waiting', 'asked', 'stopped', 'done'].includes(update.status)) fields.status = update.status;
+      if (SUBAGENT_STATUSES.includes(update.status)) fields.status = update.status;
       const previous = agentReadings.get(update.id) ?? {};
       if (agentReadings.has(update.id) && Object.entries(fields).every(([k, v]) => previous[k] === v)) return;
-      if (!agentReadings.has(update.id) && agentReadings.size >= 32) return;
+      if (!agentReadings.has(update.id) && agentReadings.size >= SUBAGENT_CAP) return;
       const reading = { ...previous, ...fields };
       agentReadings.set(update.id, reading);
       // A later update repairs metadata whose first report was shed while
@@ -286,6 +291,26 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
     doing(agentId, text) {
       push({ k: 'doing', agentId: scoped(agentId), t: scrub(String(text)).slice(0, TRACE_PROSE_CAP) });
     },
+    /**
+     * WHAT THE CLI SAID OF ITS MCP SERVERS AT START (2026-10-17): Claude's
+     * init lists each with its status. A server that failed to start read to
+     * the agent and the person as "no MCP access", so each one not connected
+     * is said on the root stream, once per run. No list is unknown and says
+     * nothing; connected is good news and says nothing either.
+     */
+    mcpStatus(servers) {
+      if (!Array.isArray(servers)) return;
+      const fresh = [];
+      for (const s of servers.slice(0, MAX_MCP_SERVERS)) {
+        if (!s || typeof s.name !== 'string' || s.status === 'connected') continue;
+        const name = scrubNativeText(s.name, MCP_NAME_MAX, scrub).replace(/\s+/g, ' ').trim();
+        const status = MCP_STATUSES.has(s.status) ? s.status : 'other';
+        if (!name || mcpSaid.has(`${name}\0${status}`) || mcpSaid.size >= 4 * MAX_MCP_SERVERS) continue;
+        mcpSaid.add(`${name}\0${status}`);
+        fresh.push(`${name} (${status})`);
+      }
+      if (fresh.length) push({ k: 'note', t: scrub(`The CLI reported MCP servers that are not connected: ${fresh.join(', ')}.`).slice(0, TRACE_PROSE_CAP) });
+    },
     flush,
     /** No more entries, no more timers. The queue survives so a final flush can
      *  still deliver it. */

package/bin/lib/turnDeclaration.mjs

@@ -2,7 +2,7 @@
  * normalization/caps; the unmodified answer still goes to parseTurnResult.
  * Only standalone objects and JSON/unlabelled fences count. Code examples
  * inside prose or another language's fence stay as the CLI wrote them. */
-import { jsonObjectClosers } from './agentPlan.mjs';
+import { jsonObjectClosers } from './modelJson.mjs';
 
 const statuses = new Set(['delivered', 'blocked', 'prerequisite', 'nothing']);
 function declaration(body) {

package/bin/lib/turnDiagnostics.mjs

@@ -4,9 +4,10 @@
  * Logging is best effort and rides the daemon's existing bounded private log.
  */
 import { randomUUID } from 'node:crypto';
-import { accessSync, constants, readFileSync, realpathSync, statSync } from 'node:fs';
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
 import { delimiter, isAbsolute, resolve } from 'node:path';
 import { AUTH_ENV_VARS, claudeAuthContext, claudeCredentialPath } from './claudeAuth.mjs';
+import { settingsAt } from './claudeSettingsArg.mjs';
 import { scrub } from './uplinkScrub.mjs';
 import { printableText } from './printable.mjs';
 import { measuredRuntimeVersion } from './runtimeDetection.mjs';
@@ -47,17 +48,13 @@ function createTurnDiagnostics({ runtime, bin, env, cwd = process.cwd(), profile
   const executable = executableFor(bin, env, cwd);
   let settingsEnv = {};
   if (runtime === 'claude') {
-    const at = args.indexOf('--settings');
-    if (at >= 0) {
-      try {
-        const input = args[at + 1];
-        const settings = JSON.parse(input.startsWith('{') ? input : readFileSync(input, 'utf8'));
-        if (settings.env && typeof settings.env === 'object' && !Array.isArray(settings.env)) {
-          for (const [key, value] of Object.entries(settings.env))
-            if (typeof value === 'string') settingsEnv[key] = value;
-        }
-      } catch { /* CLI settings unavailable */ }
-    }
+    try {
+      const { settings } = settingsAt(args);
+      if (settings?.env && typeof settings.env === 'object' && !Array.isArray(settings.env)) {
+        for (const [key, value] of Object.entries(settings.env))
+          if (typeof value === 'string') settingsEnv[key] = value;
+      }
+    } catch { /* CLI settings unavailable */ }
   }
   // Only byte counts, including each terminating NUL. No values or hashes.
   const argSizes = [bin, ...args].map(value => Buffer.byteLength(value) + 1);

package/bin/lib/turnReceipts.mjs

@@ -0,0 +1,64 @@
+/**
+ * A TURN'S COMMIT RECEIPTS — every sha that landed on its branch while it ran
+ * (2026-10-18, the SOLID pass).
+ *
+ * The rule was spelled three times: the agent run's `commitsBetween`, the
+ * lane's catch (which settles a turn whose run threw, and computed the same
+ * receipts over what the run had measured), and a multi-repository place's
+ * per-repository log (repositoryPlaces.mjs). Two incidents live in it — the
+ * base commits reported as a turn's own, and the six-hour re-run below — so a
+ * fix to one copy that missed another was the risk. A leaf: it imports only
+ * git.mjs's guarded read.
+ *
+ * Every sha that landed on this branch between two points. Measured, never
+ * asserted — this is the whole reason an agent is not asked for its own.
+ *
+ * `--not <base>` and `--no-merges`, because `from..HEAD` alone reports
+ * BASE'S commits as this turn's receipts the moment anything folds base in
+ * — which the stale path does on purpose before a merge. A receipt naming
+ * somebody else's commit is worse than a missing one.
+ *
+ * IT CANNOT THROW, and that guard is the whole point of it being here.
+ *
+ * `git()` throws on a non-zero exit, and `baseRef()` is built from the
+ * project's Base branch setting — free text an owner types, never verified
+ * against the remote. Point it at a branch with no tracking ref (`develop`
+ * on a repo whose remote branch is `dev`) and this exits "fatal: ambiguous
+ * argument". The throw escaped `runAgentTurn` AFTER the CLI had already run
+ * the card, so `postAgentTurn` was never reached, the server never settled
+ * the turn, and the next poll handed back the identical turn — the same
+ * card re-run every poll for six hours, on the operator's shared account,
+ * piling commits onto the review branch, silently.
+ *
+ * An unreadable range means we cannot MEASURE the receipts, which is a
+ * smaller failure than not settling: the turn still reports, and ship-time
+ * reconciliation books whatever no card claimed. Missing beats fabricated
+ * and both beat a stall.
+ *
+ * THE CAP IS THE WIRE'S: agent-turn-done takes `commits` up to 50
+ * (machineAgentTurns.routes.ts), so a longer list is a settle refused.
+ */
+import { gitOrNull } from './git.mjs';
+
+/** The most receipts one settle carries — the API's `commits` max. */
+export const TURN_COMMITS_MAX = 50;
+
+/** The shas on `wt`'s HEAD since `from` and not on `base`, merges left out,
+ *  newest first and capped; `[]` for a range git cannot read. */
+export function commitsSince(wt, from, base) {
+  const out = gitOrNull(['log', '--format=%H', '--no-merges', `${from}..HEAD`, '--not', base], wt);
+  return out?.split('\n').map((x) => x.trim()).filter(Boolean).slice(0, TURN_COMMITS_MAX) ?? [];
+}
+
+/**
+ * The receipts one agent turn settles with: a multi-repository card's own
+ * (`repositoryReceipts()`, every writable repository's, a sha once), else
+ * this worktree's since `before`. `baseRef` is the lane's function, read only
+ * when there is a range to read; no `before` (no worktree, or a branch with
+ * no commits yet) is none.
+ */
+export function turnCommits({ repositoryReceipts, wt, before, baseRef }) {
+  return repositoryReceipts
+    ? [...new Set(repositoryReceipts().map((r) => r.sha))].slice(0, TURN_COMMITS_MAX)
+    : before ? commitsSince(wt, before, baseRef()) : [];
+}

package/bin/lib/turnSubagents.mjs

@@ -0,0 +1,91 @@
+/**
+ * THE NATIVE CHILDREN ONE CLI TURN STARTS, OBSERVED — the readers that follow
+ * them, the bound a turn with no orchestrator keeps on them, and its exit
+ * sweep (2026-10-18, the SOLID pass).
+ *
+ * Split out of runTurn.mjs, the one spawn point every lane uses, because
+ * watching a CLI's own subagents is a second vocabulary with its own reasons
+ * to change: Claude's background agents (its stream, and the agent_progress
+ * rows only its transcript keeps) and Codex's collab children (their
+ * rollouts) arrived in four commits in three days, each another runtime-id
+ * arm inside the spawn function. runTurn keeps the process and its parent
+ * stream; this keeps the children, and a third CLI with native subagents is
+ * an arm here. The Codex thread's close-time reads (its plan windows, its
+ * model) stay in runTurn: they are the turn's, not a child's.
+ *
+ * Two rules ride with it, each argued where it lives below: an orchestrator
+ * bounds and settles its own records, so only an unowned turn is counted
+ * here; and native transcript reads are readouts, so the drain at close is
+ * bounded and never holds the card's answer.
+ */
+
+import { handleStreamLine } from './claudeStream.mjs';
+import { createClaudeSubagents } from './claudeSubagents.mjs';
+import { createClaudeSubagentProgress } from './claudeSubagentProgress.mjs';
+import { createCodexSubagentReader } from './codexSubagents.mjs';
+import { SUBAGENT_CAP } from './subagentBounds.mjs';
+
+/**
+ * `sinks` are the turn's own: its console, activity, tool-event and text
+ * sinks, which a Claude child's transcript rows feed as its stream does.
+ */
+export function createTurnSubagents({ runtime, cwd, since, env, owned, onSubagent, onSpawnResult, resumeThreadId,
+  sinks: { emit, onActivity, onToolEvent, appendText } }) {
+  // An orchestrator bounds its own records and settles them at close
+  // (orchestrator.mjs). Counted here by stream id, refused retries used up
+  // the 32 and later children's updates were dropped; the exit sweep
+  // reported 'stopped' off stream state the controller had already settled.
+  const agentStates = new Map();
+  const reportSubagent = (update) => {
+    if (!update?.id) return;
+    if (!owned) {
+      if (!agentStates.has(update.id) && agentStates.size >= SUBAGENT_CAP) return;
+      agentStates.set(update.id, update.status ?? agentStates.get(update.id) ?? 'running');
+    }
+    onSubagent?.(update);
+  };
+  const subagents = createClaudeSubagents(reportSubagent);
+  const claudeProgress = runtime === 'claude' && onSubagent ? createClaudeSubagentProgress({
+    cwd, since, env,
+    onLine: line => handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, appendText,
+      answerFromResult: true, subagents }),
+  }) : null;
+  const codexAgents = runtime === 'codex' && onSubagent ? createCodexSubagentReader({
+    since, env,
+    onSubagent: reportSubagent, onActivity, onToolEvent,
+    onSpawnResult,
+  }) : null;
+  const resumed = runtime === 'codex' && typeof resumeThreadId === 'string' ? resumeThreadId : null;
+  if (resumed) codexAgents?.thread(resumed);
+  return {
+    /** Claude's child bookkeeping, handed to the parent stream's reader. */
+    collector: subagents,
+    /** Claude's session, off its init: whose transcript to follow. */
+    session: (id) => claudeProgress?.session(id),
+    /** Codex's thread, off `thread.started`: whose rollouts to follow. */
+    thread: (id) => codexAgents?.thread(id),
+    /** A child update the Codex exec stream carried. */
+    update: (update) => codexAgents?.update(update),
+    /** The spawn failed: the readers stop, unawaited. */
+    abandon() {
+      void codexAgents?.stop();
+      void claudeProgress?.stop();
+    },
+    async drain(capMs) {
+      // Native transcript reads are readouts too: a stuck filesystem must
+      // not hold the card's answer. Readers stop scheduling before draining.
+      let progressTimer;
+      try {
+        await Promise.race([
+          Promise.all([codexAgents?.stop(), claudeProgress?.stop()]),
+          new Promise(resolve => { progressTimer = setTimeout(resolve, capMs); }),
+        ]);
+      } finally { clearTimeout(progressTimer); }
+    },
+    /** After the drain: a child an unowned turn still reads as live ended with it. */
+    sweep() {
+      for (const [id, status] of agentStates)
+        if (status === 'running' || status === 'waiting') reportSubagent({ id, status: 'stopped' });
+    },
+  };
+}

package/bin/lib/turnUsage.mjs

@@ -1,12 +1,15 @@
 /**
  * ONE TURN'S TOKENS, ADDED UP ACROSS THE SPAWNS THAT MADE IT (2026-09-28).
  *
- * The agent lane SETS its usage — one spawn, one `result` — and leaves the
- * adding-up to the server. The Terminal tab, the capture chat and the wiki
- * are different: a tab turn whose resume came back empty runs a fresh retry
- * in the same turn, and BOTH spawns spent real tokens; reporting only the
- * second would under-count exactly the turns that went wrong. So those lanes
- * sum what each spawn reported before the one settle carries it.
+ * A turn can be more than one spawn: a tab turn whose resume came back empty
+ * runs a fresh retry in the same turn, and an agent turn resumes its CLI
+ * after an internal wait (agentInternalWait.mjs) or to commit a repository's
+ * work (repositoryDelivery.mjs). Every spawn spent real tokens; reporting
+ * only the last would under-count exactly the turns that went wrong. So the
+ * Terminal tab, the capture chat, the planner, the wiki and the agent lane
+ * (since 2026-10-18, the SOLID pass) sum what each spawn reported through
+ * this, and the server still charges once, behind the one settle that
+ * carries it.
  *
  * The wire shape is the agent lane's, unchanged: `{input, output,
  * cacheCreate, cacheRead, runtime}`. Null-safe on both sides — a spawn that

package/bin/lib/versionOrder.mjs

@@ -2,7 +2,11 @@
  * VERSION ORDER — the one parser and comparator every version decision on this
  * box uses: the takeover downgrade guard (instance.mjs), the self-update
  * signals (update.mjs, fleet.mjs), the behind marks in the read-only views
- * (views.mjs) and the newest nvm Node (loginPath.mjs).
+ * (views.mjs), the newest nvm Node (loginPath.mjs), and the measured CLI
+ * floors — Claude's and Codex's orchestration (orchestratorHooks.mjs,
+ * runtimeCodex.mjs) and the Codex sandbox helper's (codexResearch.mjs
+ * `CODEX_HELPER_MIN`, read by codexProjectRead.mjs too; 2026-10-18, the SOLID
+ * pass: both kept a hand-rolled reducer and the same spelled-out floor).
  *
  * Split out (SOLID F005) because four hand-written rules disagreed on a
  * version they could not read: one called it EQUAL, one called each
@@ -40,3 +44,9 @@ export function compareVersions(a, b) {
 
 /** True only when BOTH parse and `a` is strictly older. Unknown is not older. */
 export const versionBelow = (a, b) => compareVersions(a, b) === -1;
+
+/** True only when BOTH parse and `a` is at or above `b`. Unknown is not at least. */
+export const versionAtLeast = (a, b) => {
+  const o = compareVersions(a, b);
+  return o === 0 || o === 1;
+};