flowviant 0.125.4 → 0.125.6

package/bin/lib/agentInternalWait.mjs

@@ -25,11 +25,7 @@ export async function runAgentWithInternalWaits(run, options) {
     let cliFailed = false;
     let lastAnswer = null;
     let currentUsage = null;
-    const combine = () => {
-      if (!currentUsage) return total;
-      return Object.fromEntries(['input', 'output', 'cacheCreate', 'cacheRead'].map((k) =>
-        [k, (total?.[k] ?? 0) + (currentUsage[k] ?? 0)]));
-    };
+    const combine = () => currentUsage ? addUsage(total, currentUsage) : total;
     const out = await run({
       ...options,
       ...(attempt ? {

package/bin/lib/agentPlan.mjs

@@ -1,7 +1,7 @@
 /**
  * READING A MODEL'S ANSWER, in the agent lane's shapes: a planner's
- * PROPOSAL, an agent's own TURN RESULT, the AI pre-review's TRIAGE, and an
- * incoming ticket's one-card DRAFT (2026-09-28).
+ * PROPOSAL, an agent's own TURN RESULT and the AI pre-review's TRIAGE. The
+ * objects themselves are found by modelJson.mjs (2026-10-18).
  *
  * The scratch agent behind a Deploy press is asked for one JSON object and
  * nothing else. This is what turns its final message into a proposal, and it is
@@ -32,6 +32,8 @@ import { scrub as envScrub, scrubCut } from './uplinkScrub.mjs';
 import { groupDependencies } from './planDependencies.mjs';
 import { AGENT_TASK_KINDS } from './agentTaskKinds.mjs';
 import { blockedAnswer } from './agentAsk.mjs';
+import { isResearchUse } from './researchUse.mjs';
+import { candidateObjects } from './modelJson.mjs';
 
 /** The biggest a single proposal may be. Bounds on a machine, not a policy:
  *  the server caps these again at its own boundary. */
@@ -40,164 +42,6 @@ const MAX_TASKS_PER_AGENT = 60;
 const MAX_NAME = 80;
 const MAX_NOTE = 1000;
 
-/**
- * Find the objects.
- *
- * A fenced block first, because that is what was asked for. Otherwise every `{`
- * in the text is tried as a start, and its BALANCED end is found by counting
- * braces while skipping string literals — each caller then takes the first
- * candidate whose SHAPE is the one it asked for.
- *
- * The obvious cheap version — first `{` to last `}` — is wrong in a way a test
- * caught: a planner that writes "I looked at {the auth module} first" before its
- * JSON produces a span starting at the wrong brace, and the whole plan is lost
- * to a sentence. Scanning candidates costs nothing at this size and cannot be
- * defeated by prose.
- *
- * ONE SCANNER FOR EVERY READER (2026-09-16). It was written
- * twice — once here and once inline in `parseTurnResult` — and a third copy was
- * about to be written for the precheck. A brace scanner that skips string
- * literals is exactly the kind of thing where two copies quietly stop agreeing
- * about escapes and nobody notices, because the disagreement only shows up on a
- * card title with a quote in it.
- */
-/**
- * BOUNDED, BECAUSE THE TEXT IS A MODEL'S (2026-09-24, the audit).
- *
- * The scan used to walk from EVERY `{` to the end of the text, and parse every
- * balanced span it found — quadratic on both counts. A final message of eighty
- * thousand `{` (a quoted fixture, brace padding, a turn steered into writing
- * one) took nine seconds of synchronous CPU, and while it ran nothing else on
- * the machine moved: no poll, no lease renewal, no other lane. Three bounds,
- * none of which a real answer comes near:
- *
- *  · top-level objects are scanned whole, including long un-fenced replies;
- *    `fencedBody` and the brace scan are linear, with no prose-length slice;
- *  · each `{`'s closing brace is found ONCE (see `closers`), so the scan is a
- *    single right-to-left pass instead of one walk per brace;
- *  · only spans that can open an object (`{` then a key or `}`) are handed to
- *    JSON.parse. Every TOP-LEVEL span is parsed — top-level spans are
- *    disjoint, so together they are at most the scanned window — and the
- *    NESTED ones (a span inside an earlier candidate) share a budget of
- *    `MAX_NESTED_PARSES` spans and `MAX_NESTED_CHARS` characters, so a run of
- *    nested braces that parse is not re-parsed thousands of times.
- *
- * THE BUDGET NEVER REACHES A TOP-LEVEL SPAN, and the review found why it must
- * not: the first cut counted every span from the left against one budget, so
- * an answer that followed 250 JSON lines of a quoted fixture (or one large
- * nested document) was never parsed at all — the turn read as `nothing` and a
- * delivered agent went to Stuck. The contract puts the answer LAST and at the
- * top level, which is the one span a budget must never cost.
- */
-const MAX_NESTED_PARSES = 200;
-const MAX_NESTED_CHARS = 4 * 1024 * 1024;
-
-export function candidateObjects(text) {
-  const fenced = fencedBody(text);
-  const raw = text;
-  const bodies = [];
-  if (fenced !== null) bodies.push(fenced);
-  const close = closers(raw);
-  let topEnd = -1;
-  let nestedParses = 0;
-  let nestedChars = 0;
-  for (let i = 0; i < raw.length; i++) {
-    if (raw[i] !== '{') continue;
-    const end = close.get(i);
-    if (!(end > i) || !/^\{\s*["}]/.test(raw.slice(i, i + 64))) continue;
-    if (i > topEnd) {
-      topEnd = end;
-    } else {
-      const len = end - i + 1;
-      if (nestedParses >= MAX_NESTED_PARSES || nestedChars + len > MAX_NESTED_CHARS) continue;
-      nestedParses++;
-      nestedChars += len;
-    }
-    bodies.push(raw.slice(i, end + 1));
-  }
-  const out = [];
-  for (const body of bodies) {
-    if (!body.trim()) continue;
-    try {
-      const v = JSON.parse(body);
-      if (v && typeof v === 'object') out.push(v);
-    } catch {
-      /* the next candidate may be the object */
-    }
-  }
-  return out;
-}
-
-/**
- * THE FIRST FENCED BLOCK'S BODY, or null — what
- * `text.match(/```(?:json)?\s*([\s\S]*?)```/)[1]` answered, found in ONE
- * forward pass (2026-10-10, the audit's F079).
- *
- * That regex ran over the WHOLE text and backtracks quadratically on an opening fence
- * followed by a long whitespace run with no closing fence: the greedy `\s*` and
- * the lazy body re-scan the run from every split. Measured: 80 KB took 0.6 s,
- * 320 KB nine seconds, of synchronous CPU in which no poll, lease or other
- * lane moved — and a turn's stdout is model-written and uncapped. Same
- * answer, by `indexOf`: the first ``` anywhere, an optional `json`, the
- * whitespace after it skipped, and the body runs to the next ```. If that
- * opening has no closer, no later opening can have one either, so there is no
- * fence. The search stays over the whole text.
- */
-const FENCE_SPACE = /\s*/y;
-function fencedBody(text) {
-  const open = text.indexOf('```');
-  if (open < 0) return null;
-  let at = open + 3;
-  if (text.startsWith('json', at)) at += 4;
-  FENCE_SPACE.lastIndex = at;
-  FENCE_SPACE.exec(text);
-  at = FENCE_SPACE.lastIndex;
-  const close = text.indexOf('```', at);
-  return close < 0 ? null : text.slice(at, close);
-}
-
-/**
- * For every `{`, the index of the `}` that closes it when read as the START of
- * an object (outside any string), or -1 — the answer `balanced` gives, for all
- * of them in one pass.
- *
- * Right to left, so every `{` AFTER the one being closed already has its
- * answer. A walk that meets such a `{` outside a string jumps straight to that
- * brace's closer — the string state from there on is the same for both walks,
- * so the nested object ends where it ends — and if that brace never closes,
- * neither does this one. What is left for each walk is its own top level.
- */
-// The conversation-prose filter uses the same brace/string boundaries.
-export { closers as jsonObjectClosers };
-function closers(s) {
-  const close = new Map();
-  for (let i = s.lastIndexOf('{'); i >= 0; i = i > 0 ? s.lastIndexOf('{', i - 1) : -1) {
-    let inStr = false;
-    let esc = false;
-    let end = -1;
-    for (let k = i + 1; k < s.length; k++) {
-      const ch = s[k];
-      if (inStr) {
-        if (esc) esc = false;
-        else if (ch === '\\') esc = true;
-        else if (ch === '"') inStr = false;
-        continue;
-      }
-      if (ch === '"') inStr = true;
-      else if (ch === '{') {
-        const inner = close.get(k);
-        if (inner === undefined || inner < 0) break;
-        k = inner;
-      } else if (ch === '}') {
-        end = k;
-        break;
-      }
-    }
-    close.set(i, end);
-  }
-  return close;
-}
-
 function extract(raw) {
   return candidateObjects(raw).find((v) => Array.isArray(v.agents)) ?? null;
 }
@@ -411,7 +255,7 @@ export function parseTurnResult(text, scrub = envScrub) {
     if (v.status === 'delivered') {
       return {
         outcome: 'delivered',
-        ...(['tasks', 'context', 'document'].includes(v.researchUse) ? { researchUse: v.researchUse } : {}),
+        ...(isResearchUse(v.researchUse) ? { researchUse: v.researchUse } : {}),
         ...(Array.isArray(v.mergeOrder) ? { mergeOrder: v.mergeOrder.filter((id) => typeof id === 'string').slice(0, 64) } : {}),
         ...(typeof v.mergeOrderReason === 'string' ? { mergeOrderReason: clean(v.mergeOrderReason, 1000) } : {}),
         ...(Array.isArray(v.mergeOrders) ? { mergeOrders: v.mergeOrders.slice(0, 60) } : {}),
@@ -447,6 +291,12 @@ export const MAX_PRECHECK_OVERALL = 1200;
 export const MAX_PRECHECK_CRITERIA = 12;
 export const MAX_PRECHECK_CRITERION = 200;
 export const MAX_PRECHECK_LINE = 160;
+/** The verdict words the server's boundary admits (shared `agents.schema.ts`
+ *  PRECHECK_CARD_VERDICTS / PRECHECK_CRITERION_VERDICTS, 2026-10-18), held
+ *  equal by the release gate (rule 31): a word kept here and refused there
+ *  is a reading the panel never draws. */
+export const PRECHECK_CARD_VERDICTS = ['ok', 'concerns'];
+export const PRECHECK_CRITERION_VERDICTS = ['met', 'concern', 'unclear'];
 
 /**
  * ONE CARD'S CRITERIA, as the reader judged them (2026-10-10).
@@ -464,7 +314,7 @@ function precheckCriteria(raw, scrub) {
     if (out.length >= MAX_PRECHECK_CRITERIA) break;
     if (!k || typeof k !== 'object') continue;
     if (typeof k.criterion !== 'string' || !k.criterion.trim()) continue;
-    if (k.verdict !== 'met' && k.verdict !== 'concern' && k.verdict !== 'unclear') continue;
+    if (!PRECHECK_CRITERION_VERDICTS.includes(k.verdict)) continue;
     if (k.line != null && typeof k.line !== 'string') continue;
     const criterion = scrubCut(k.criterion.trim(), MAX_PRECHECK_CRITERION, scrub);
     const line = typeof k.line === 'string' ? scrubCut(k.line.trim(), MAX_PRECHECK_LINE, scrub) : '';
@@ -528,7 +378,7 @@ export function parsePrecheck(text, scrub = envScrub) {
     if (!c || typeof c !== 'object') continue;
     const taskId = typeof c.taskId === 'string' ? c.taskId.trim().slice(0, 64) : '';
     if (!taskId || seen.has(taskId)) continue;
-    if (c.verdict !== 'ok' && c.verdict !== 'concerns') continue;
+    if (!PRECHECK_CARD_VERDICTS.includes(c.verdict)) continue;
     seen.add(taskId);
     // SCRUB, THEN CUT — see the docblock. The whole field is in hand here, so an
     // exact-value match still finds a secret that spans the cap.

package/bin/lib/agentRepositories.mjs

@@ -4,6 +4,7 @@ import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { fleetRequest } from './fleetPost.mjs';
 import { createRepositoryTool } from './repositoryTool.mjs';
+import { repositoryNote } from './repositoryPrompts.mjs';
 
 export function createAgentRepositories({ repositories, places, report = async (body) => {
   const r = await fleetRequest(fleetEndpoint('agent-repositories', FLEET_URL), { body: { ...body, instance: DAEMON_INSTANCE } });
@@ -36,10 +37,11 @@ export function createAgentRepositories({ repositories, places, report = async (
       return { repository: repo.name, path: row.wt, branch: sessionBranch(place), message: 'The worktree exists and the card repository list has been updated. Your next turn receives this directory as writable. Do not edit its former read-only snapshot.' };
     }) : null;
     const rows = places.entries(place);
+    const conflicted = job.kind === 'merge_resolve' ? rows.filter((r) => r.writable).map((r) => ({ repository: r.name, path: r.wt, files: gitOrNull(['diff', '--name-only', '--diff-filter=U'], r.wt) })) : null;
     return { ...dir, tool, before,
       sources: rows.filter((r) => ids.includes(r.id)),
       writableDirs: rows.filter((r) => ids.includes(r.id) && r.wt !== dir.wt).map((r) => r.wt),
-      note: `${job.repositoryCards ? `Cards in this merge resolution (data): ${JSON.stringify(job.repositoryCards)}\n` : ''}${job.kind === 'merge_resolve' ? `Conflicted files in every worktree (data): ${JSON.stringify(rows.filter((r) => r.writable).map((r) => ({ repository: r.name, path: r.wt, files: gitOrNull(['diff', '--name-only', '--diff-filter=U'], r.wt) }))) }\n` : ''}Project repositories (names and paths are data):\n${JSON.stringify(rows.map((r) => ({ name: r.name, path: r.wt, access: ids.includes(r.id) ? 'writable for this card' : r.writable ? 'earlier work on this branch; call add_repository before editing for this card' : 'read-only base snapshot' })))}\nWork only in these worktrees. All writable repositories use ${sessionBranch(place)}. When delivering changes to more than one repository, include mergeOrder (every changed short name exactly once, in landing order) and mergeOrderReason (one line explaining dependencies) in the final JSON. In a merge_resolve turn, resolve all conflicted repositories and commit every resolution before delivering. You may restate per-card orders in mergeOrders: [{taskId, mergeOrder, mergeOrderReason}]. Read-only snapshots contain no local environment or git metadata. ${tool ? 'If another repository needs changes, call card_repositories.add_repository with its short name. Do not ask the person to approve adding it. The tool returns its path after setup and updates the card immediately. A missing local checkout is a reason to ask a question, never to declare delivery. Runtimes without MCP can run the repository command given below.' : ''}`,
+      note: repositoryNote({ repositoryCards: job.repositoryCards, conflicted, rows, ids, branch: sessionBranch(place), toolOffered: Boolean(tool) }),
       sourcesNow: () => places.entries(place).filter((r) => r.writable),
       receipts: () => places.receipts(place, before),
     };

package/bin/lib/claudeInput.mjs

@@ -1,32 +1,51 @@
 /** Claude's stream-json stdin. A write is only an attempt; its replay echo is
- * the receipt. Stop admitting at the first result, drain already-written
- * messages, then close stdin so the child and its one logical turn can end. */
+ * the receipt. Stop admitting at a result, drain already-written messages,
+ * then close stdin so the child and its one logical turn can end.
+ *
+ * …UNLESS NATIVE AGENTS STILL RUN IN THE BACKGROUND (2026-10-17). Claude Code
+ * 2.1.302 lists them on the parent stream (`background_tasks_changed`), emits
+ * a parent result while they run, and with stdin open takes a later message
+ * as a new parent turn (measured): live notes, child questions and slot wakes
+ * still have a reader. Input closes at a result that finds no agent listed and
+ * nothing written pending — never at the emptied list itself: the agents'
+ * notification turn follows it and may start the next wave, and a slot wake
+ * for that wave arrives just then (both measured). Only agents hold it: a
+ * background shell (a dev server) may never end, and the CLI's own wind-down
+ * waits on those. A CLI that never lists tasks closes at its first result. */
 export function createClaudeInput(child, { onTaken = () => {} } = {}) {
   const sent = new Set();
   const pending = new Set();
-  let accepting = true;
+  let draining = false; // a result found no live agent: admit nothing, close once pending is read
+  let broken = false;
   let ended = false;
   let resultSeen = false;
-  child.stdin.on('error', () => { accepting = false; }); // EPIPE leaves the message queued
+  let agents = 0; // live background agents, as the parent stream last listed them
+  child.stdin.on('error', () => { broken = true; }); // EPIPE leaves the message queued
+  const end = () => { if (!ended) { ended = true; child.stdin.end(); } };
   const send = (id, prompt) => {
-    if (!accepting || ended || sent.has(id) || child.stdin.destroyed || child.stdin.writableEnded) return false;
+    if (draining || broken || ended || sent.has(id) || child.stdin.destroyed || child.stdin.writableEnded) return false;
     const message = { type: 'user', uuid: id, session_id: '', message: { role: 'user', content: prompt }, parent_tool_use_id: null };
     sent.add(id);
     pending.add(id);
     try { child.stdin.write(JSON.stringify(message) + '\n'); return true; }
-    catch { pending.delete(id); accepting = false; return false; }
+    catch { pending.delete(id); broken = true; return false; }
   };
   return {
     send,
     event(event) {
       if (event.type === 'user' && event.isReplay === true && pending.delete(event.uuid)) onTaken(event.uuid);
+      if (event.type === 'system' && event.subtype === 'background_tasks_changed' && Array.isArray(event.tasks)) {
+        agents = event.tasks.filter(task => task?.task_type === 'local_agent').length;
+        if (agents > 0) draining = false; // a drained message's turn started agents
+      }
       if (event.type === 'result') {
         resultSeen = true;
-        accepting = false;
-        if ((pending.size === 0 || event.is_error === true) && !ended) { ended = true; child.stdin.end(); }
+        if (event.is_error === true) end();
+        else if (agents > 0) draining = false;
+        else { draining = true; if (pending.size === 0) end(); }
       }
     },
-    close() { accepting = false; ended = true; },
+    close() { ended = true; },
     get resultSeen() { return resultSeen; },
   };
 }

package/bin/lib/claudeMachineMcp.mjs

@@ -0,0 +1,85 @@
+/**
+ * THE MACHINE'S OWN MCP SERVERS THAT A CARD TURN'S SETTINGS SOURCES NEVER
+ * REACH (2026-10-17). The 2026-10-11 ruling mounts "the user and local
+ * servers" on every card turn, and neither arrived where the person keeps
+ * them. MEASURED on Claude Code 2.1.302, a scratch CLAUDE_CONFIG_DIR whose
+ * `.claude.json` held one user and one local server:
+ *  · `--setting-sources ''` (every fenced posture: write-up, mockup, 3D model,
+ *    deck) loaded NEITHER — a research card on the owner's box saw the
+ *    claude.ai connectors and no Roblox_Studio, a user-scope server;
+ *  · `--setting-sources user` (a code card) loaded the user server only;
+ *  · a local server (`claude mcp add`'s default scope) is keyed on the
+ *    CANONICAL git root — the main checkout, which the CLI also resolves a
+ *    linked worktree to (re-measured 2026-10-17: a worktree cwd with no
+ *    `--setting-sources` loaded it). What drops it on a card is the `local`
+ *    source the card's list leaves out, not the worktree's path.
+ * So the lane names what is missing and the adapter hands it over through a
+ * private `--mcp-config` file (runtimeClaude.mjs): `user` when the turn's
+ * sources drop the user scope, and the checkout's local servers always. A
+ * local name shadows a user one, the CLI's own precedence; an `--mcp-config`
+ * server beat a user server of the same name (measured), so a code card keeps
+ * that order too.
+ *
+ * ITS OWN MODULE (2026-10-18, the SOLID pass). It sat in claudePersonal.mjs,
+ * whose ruling is the person's settings allowlist and private settings file
+ * (2026-09-29, 2026-10-10), and was the only reason that module imported git;
+ * the agent lane imported claudePersonal.mjs for this function alone. Where
+ * Claude Code keeps user and local servers in `.claude.json` is a different
+ * fact, which moves on its own: a change to how the CLI keys them, or a new
+ * scope, opens this file and no other (claudeMachineMcp.test.mjs pins the
+ * file name to here).
+ */
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { gitOrNull } from './git.mjs';
+
+/** Far past any real CLI config — `.claude.json` also holds every project's
+ *  history; a bigger one is not read. */
+const CLI_CONFIG_MAX_BYTES = 32 * 1024 * 1024;
+const isRecord = (v) => v != null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * THREE STATES (2026-10-17): `{}` when the file is absent (measured: the
+ * machine has none), `null` when it exists but could not be read, is too big
+ * or is not an object (unknown), so a caller never says a server is mounted
+ * that was never read.
+ */
+export function machineMcpServers({ user = false, checkout = null, env = process.env } = {}) {
+  const path = env.CLAUDE_CONFIG_DIR ? join(env.CLAUDE_CONFIG_DIR, '.claude.json') : join(env.HOME || homedir(), '.claude.json');
+  let raw;
+  try {
+    if (statSync(path).size > CLI_CONFIG_MAX_BYTES) return null;
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    return error?.code === 'ENOENT' ? {} : null;
+  }
+  if (!isRecord(raw)) return null;
+  const out = {};
+  const take = (servers) => {
+    if (!isRecord(servers)) return;
+    for (const [name, config] of Object.entries(servers)) if (name !== '__proto__' && isRecord(config)) out[name] = config;
+  };
+  if (user) take(raw.mcpServers);
+  if (typeof checkout === 'string' && checkout && isRecord(raw.projects)) {
+    const keys = [resolve(checkout)];
+    try { keys.push(realpathSync(checkout)); } catch { /* the resolved path alone */ }
+    const root = canonicalGitRoot(checkout);
+    if (root) keys.unshift(root);
+    const key = keys.find((k) => Object.hasOwn(raw.projects, k));
+    if (key) take(raw.projects[key]?.mcpServers);
+  }
+  return out;
+}
+
+/** The main checkout a directory's repository resolves to — the key the CLI
+ *  files a local server under when the connected folder is itself a linked
+ *  worktree. Null when git cannot say. */
+function canonicalGitRoot(dir) {
+  const common = gitOrNull(['rev-parse', '--path-format=absolute', '--git-common-dir'], dir);
+  try {
+    return common && basename(common) === '.git' ? realpathSync(dirname(common)) : null;
+  } catch {
+    return null;
+  }
+}

package/bin/lib/claudePersonal.mjs

@@ -49,6 +49,7 @@ import { randomBytes } from 'node:crypto';
 import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
+import { replaceSettings } from './claudeSettingsArg.mjs';
 import { MACHINE_CREDENTIAL_ENV } from './machineEnv.mjs';
 import { WINDOW_ENV_REMOVED, withoutWindows } from './noWindowEnv.mjs';
 
@@ -182,11 +183,13 @@ export function writeTurnSettings(settings, { dir = turnSettingsDir() } = {}) {
   }
 }
 
-/** Remove the settings file a turn's argv names, when it is one of ours. */
+/** Remove the settings file a turn's argv names, when it is one of ours — and
+ *  the machine-MCP file (claudeMachineMcp.mjs `machineMcpServers`), written
+ *  the same way. */
 export function releaseTurnSettings(args, { dir = turnSettingsDir() } = {}) {
   if (!Array.isArray(args)) return;
   args.forEach((a, i) => {
-    if (i === 0 || args[i - 1] !== '--settings' || typeof a !== 'string') return;
+    if (i === 0 || !['--settings', '--mcp-config'].includes(args[i - 1]) || typeof a !== 'string') return;
     if (dirname(a) !== dir || !TURN_SETTINGS_FILE.test(basename(a))) return;
     rmSync(a, { force: true });
   });
@@ -203,8 +206,5 @@ export function releaseTurnSettings(args, { dir = turnSettingsDir() } = {}) {
 export function withPersonalSettings(perm, kept, { write = writeTurnSettings } = {}) {
   const personal = kept && typeof kept === 'object' && !Array.isArray(kept) ? kept : {};
   if (!Object.keys(personal).length) return [...perm];
-  const at = perm.indexOf('--settings');
-  if (at < 0) return ['--settings', write(personal), ...perm];
-  const posture = JSON.parse(perm[at + 1]);
-  return [...perm.slice(0, at), '--settings', write({ ...personal, ...posture }), ...perm.slice(at + 2)];
+  return replaceSettings(perm, (posture) => write({ ...personal, ...posture }));
 }

package/bin/lib/claudePosture.mjs

@@ -13,6 +13,7 @@
 import { fileURLToPath } from 'node:url';
 import { SAFE } from './config.mjs';
 import { runningCompiledBinary } from './launchCommand.mjs';
+import { withSettings } from './claudeSettingsArg.mjs';
 
 /**
  * THE READ GUARD, ON EVERY CURATED POSTURE (2026-09-23) — see
@@ -479,8 +480,10 @@ export const RESEARCH_PERM = researchPerm(null);
 
 /**
  * CLAUDE'S PERMISSION LIST FOR A TURN PROFILE, by the profile's name — one
- * entry per name in turnProfile.mjs (a test holds the two tables equal). The
- * builders that take the knowledge directory get it; the fixed lists ignore it.
+ * entry per profile Claude declares, plus plan-mode (runtimeClaude.mjs
+ * `profiles`; a test holds the two equal). runTurn asks for it through the
+ * row (`CLAUDE_RUNTIME.perm`), on Claude alone. The builders that take the
+ * knowledge directory get it; the fixed lists ignore it.
  * `projectMcp` is the names of the project servers the lane mounted; only the
  * design and research lists take them (`projectMcp` in turnProfile.mjs).
  */
@@ -492,13 +495,6 @@ const CLAUDE_PERM = {
   'plan-mode': () => PLAN_MODE_PERM,
   design: (kd, _vault, mcp) => designPermFor(kd, mcp),
   research: (kd, _vault, mcp) => researchPerm(kd, mcp),
-  // THE IMAGE POSTURE IS CODEX'S (0.114.0) and Claude does not declare it
-  // (runtimeClaude.mjs `profiles`), so turnProfile.mjs refuses a Claude turn
-  // under it before argv is built. The entry exists because `runTurn` looks
-  // Claude's list up BY NAME for every runtime (the adapter that is not Claude
-  // ignores it), and a missing name throws. Were it ever reached on Claude it
-  // is the consult list: read-only, no write at all — failing closed.
-  image: (kd) => consultPermFor(kd),
 };
 export const CLAUDE_PERM_PROFILES = Object.freeze(Object.keys(CLAUDE_PERM));
 export function claudePermFor(profileName, knowledgeDir, vaultDir, projectMcp = []) {
@@ -541,10 +537,5 @@ export function claudePermFor(profileName, knowledgeDir, vaultDir, projectMcp =
  * of a fenced posture.
  */
 export function withMachineMcp(perm, disabledProjectMcp) {
-  const extra = { disabledMcpjsonServers: [...disabledProjectMcp] };
-  const at = perm.indexOf('--settings');
-  if (at < 0) return ['--settings', JSON.stringify({ ...extra, hooks: { PreToolUse: [MCP_ALLOW_HOOK] } }), ...perm];
-  const posture = JSON.parse(perm[at + 1]);
-  const hooks = { ...(posture.hooks ?? {}), PreToolUse: [...(posture.hooks?.PreToolUse ?? []), MCP_ALLOW_HOOK] };
-  return [...perm.slice(0, at), '--settings', JSON.stringify({ ...posture, ...extra, hooks }), ...perm.slice(at + 2)];
+  return withSettings(perm, { disabledMcpjsonServers: [...disabledProjectMcp], hooks: { PreToolUse: [MCP_ALLOW_HOOK] } });
 }

package/bin/lib/claudeSettingsArg.mjs

@@ -0,0 +1,67 @@
+/**
+ * A TURN'S ONE `--settings`, SPLICED AND READ IN ONE PLACE (2026-10-18, the
+ * SOLID pass). Three functions in two modules spliced the flag — the machine's
+ * MCP settings and the orchestrator's hooks (claudePosture.mjs), the person's
+ * kept keys (claudePersonal.mjs) — each repeating find, parse, merge, then
+ * splice or prepend, and the turn diagnostics read it a fourth way. The
+ * 2026-10-17 bug (the orchestrator's hooks on a second `--settings`, never
+ * loaded) is that class: the next thing a turn's settings carry merges here,
+ * into the one flag, and claudeSettingsArg.test.mjs keeps every other module
+ * from finding it for itself.
+ *
+ * THE PERSONAL STEP RUNS LAST. claudePersonal.mjs `withPersonalSettings` turns
+ * the value into the path of a private file (the person's keys never ride
+ * argv), so nothing merges after it: `replaceSettings` reads inline JSON only
+ * and refuses a path in words — merging into that file would put the person's
+ * secrets back on the command line. `settingsAt`, the diagnostics' reader,
+ * reads either.
+ */
+import { readFileSync } from 'node:fs';
+
+/** The turn's `--settings`: where it stands (-1 for none) and what it holds —
+ *  null with no flag, else the inline JSON or the file it names, parsed. May
+ *  throw (a file gone, a value that does not parse); the caller decides. */
+export function settingsAt(args) {
+  const at = args.indexOf('--settings');
+  if (at < 0) return { at, settings: null };
+  const input = args[at + 1];
+  return { at, settings: JSON.parse(input.startsWith('{') ? input : readFileSync(input, 'utf8')) };
+}
+
+/** An inline value, parsed — never a path (see the header). */
+function inline(value) {
+  if (typeof value !== 'string' || !value.startsWith('{')) {
+    throw new Error("this turn's --settings already names a file; nothing merges after the personal settings");
+  }
+  return JSON.parse(value);
+}
+
+/**
+ * `perm` with its one `--settings` replaced by `fn(posture)` — `posture` the
+ * flag's own object, `{}` where there is none — standing where the flag stood,
+ * or before the lists when there was none (`--allowedTools` is variadic).
+ */
+export function replaceSettings(perm, fn) {
+  const at = perm.indexOf('--settings');
+  const value = at < 0 ? fn({}) : fn(inline(perm[at + 1]));
+  return at < 0 ? ['--settings', value, ...perm] : [...perm.slice(0, at), '--settings', value, ...perm.slice(at + 2)];
+}
+
+/**
+ * ONE `--settings` PER TURN (2026-10-17). Claude Code applies only the LAST
+ * `--settings` it is handed (measured, 2.1.302: two flags each holding a
+ * PreToolUse hook ran the second hook alone). The card orchestrator's hooks
+ * rode a flag of their own ahead of the machine-MCP settings (claudePosture.mjs
+ * `withMachineMcp`), so on every code card that mounts the machine's servers
+ * the spawn gate, child registration and checkpoints never loaded
+ * (claudeOrchestratorHooks.test.mjs
+ * re-measures it on the real CLI). `extra` hooks join the posture's per event,
+ * after its own; its other keys win over the posture's.
+ */
+export function withSettings(perm, { hooks: extraHooks = {}, ...extra }) {
+  return replaceSettings(perm, (posture) => {
+    const hooks = { ...(posture.hooks ?? {}) };
+    for (const [event, rows] of Object.entries(extraHooks)) hooks[event] = [...(hooks[event] ?? []), ...rows];
+    return JSON.stringify({ ...posture, ...extra, hooks });
+  });
+}

package/bin/lib/claudeSubagentProgress.mjs

@@ -6,11 +6,11 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { claudeProjectDir } from './claudeSessions.mjs';
 import { CLAUDE_SESSION_RE } from './conversationIds.mjs';
+import { followJsonl, newTail } from './jsonlTail.mjs';
 
-const MAX_READ = 4 * 1024 * 1024;
-const LINE_MAX = 256 * 1024;
 export function createClaudeSubagentProgress({ cwd, since = Date.now(), env = process.env, onLine }) {
-  let file, offset = null, rest = Buffer.alloc(0), skip = false, timer;
+  const tail = newTail();
+  let file, timer;
   let chain = Promise.resolve();
   const flush = () => {
     chain = chain.then(async () => {
@@ -18,31 +18,15 @@ export function createClaudeSubagentProgress({ cwd, since = Date.now(), env = pr
       let fh;
       try {
         fh = await open(file, 'r');
-        const { size } = await fh.stat();
-        if (offset === null) { offset = Math.max(0, size - MAX_READ); skip = offset > 0; }
-        if (size < offset) { offset = 0; rest = Buffer.alloc(0); }
-        const end = Math.min(size, offset + MAX_READ);
-        while (offset < end) {
-          const buf = Buffer.alloc(Math.min(LINE_MAX, end - offset));
-          const { bytesRead } = await fh.read(buf, 0, buf.length, offset);
-          if (!bytesRead) break;
-          offset += bytesRead;
-          const data = Buffer.concat([rest, buf.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 (skip) { skip = false; continue; }
-            try {
-              const ev = JSON.parse(line);
-              if (ev.type !== 'progress' || ev.data?.type !== 'agent_progress' || !ev.parentToolUseID) continue;
-              const at = Date.parse(ev.timestamp ?? '');
-              if (!Number.isFinite(at) || at < since) continue;
-              onLine(line);
-            } catch { /* torn or unknown native row */ }
-          }
-          rest = data.subarray(start);
-          if (rest.length > LINE_MAX) { rest = Buffer.alloc(0); skip = true; }
-        }
+        await followJsonl(fh, tail, line => {
+          try {
+            const ev = JSON.parse(line);
+            if (ev.type !== 'progress' || ev.data?.type !== 'agent_progress' || !ev.parentToolUseID) return;
+            const at = Date.parse(ev.timestamp ?? '');
+            if (!Number.isFinite(at) || at < since) return;
+            onLine(line);
+          } catch { /* torn or unknown native row */ }
+        });
       } catch { /* the transcript can appear after init */ }
       finally { await fh?.close().catch(() => {}); }
     }).catch(() => {});

package/bin/lib/claudeSubagents.mjs

@@ -1,3 +1,5 @@
+import { NATIVE_AGENT_TOOLS } from './nativeAgentTools.mjs';
+
 /** Native tool-use ids are stable for the lifetime of an Agent/Task call. */
 export function createClaudeSubagents(report = () => {}) {
   const calls = new Map();
@@ -29,12 +31,12 @@ export function createClaudeSubagents(report = () => {}) {
       const agentId = identify(ev);
       if (ev.type === 'assistant') {
         for (const b of ev.message?.content ?? []) {
-          if (b.type === 'tool_use' && b.name === 'AskUserQuestion' && agentId) {
+          if (b.type === 'tool_use' && NATIVE_AGENT_TOOLS.claude.ask.includes(b.name) && agentId) {
             questions.set(b.id, agentId);
             if (questions.size > 128) questions.delete(questions.keys().next().value);
             report({ id: agentId, status: 'asked' });
           }
-          if (b.type !== 'tool_use' || !['Agent', 'Task'].includes(b.name) || !b.id) continue;
+          if (b.type !== 'tool_use' || !NATIVE_AGENT_TOOLS.claude.spawn.includes(b.name) || !b.id) continue;
           const input = b.input ?? {};
           const id = aliases.get(input.resume) ?? b.id;
           calls.set(b.id, { id, input });