flowviant 0.125.5 → 0.125.7

package/README.md

@@ -3,8 +3,8 @@
 Run your own coding CLIs as build agents for [Flowviant](https://flowviant.com) — [Claude Code](https://claude.com/claude-code), Codex or Antigravity, on your own credentials. This daemon holds your sessions, keeps a worktree per tab, and ships branches on your word. The daemon does not send your Claude, Codex or GitHub logins to Flowviant; it shells out to CLIs you signed in yourself.
 
 ```sh
-curl -fsSL https://api.flowviant.com/install.sh | sh
-flowviant   # approve the code in Flowviant → connected
+curl -fsSL https://api.flowviant.com/install.sh | sh && ~/.flowviant/bin/flowviant
+# approve the code in Flowviant → connected; new terminals just run `flowviant`
 ```
 
 Login keeps going straight into the daemon — there is no second command to run.
@@ -31,11 +31,10 @@ On the machine that runs the daemon:
 Download the standalone binary, then start it in your checkout:
 
 ```sh
-curl -fsSL https://api.flowviant.com/install.sh | sh
-flowviant
+curl -fsSL https://api.flowviant.com/install.sh | sh && ~/.flowviant/bin/flowviant
 ```
 
-It shows a short code. Open your project's **Workbench** in Flowviant and enter the code where it offers to connect a machine. The credential is stored at `~/.flowviant/credentials.json`, and from then on `flowviant` just runs. The installer prints a PATH hint if needed; `FLOWVIANT_INSTALL_DIR` changes its destination. It verifies SHA-256 and never uses sudo.
+The full path is for this first run only: the installer adds its folder to your shell's startup file, which new terminals read. It shows a short code. Open your project's **Workbench** in Flowviant and enter the code where it offers to connect a machine. The credential is stored at `~/.flowviant/credentials.json`, and from then on `flowviant` just runs. The installer prints a PATH hint if needed; `FLOWVIANT_INSTALL_DIR` changes its destination. It verifies SHA-256 and never uses sudo.
 
 Run `flowviant login` from another checkout and choose the same project in the
 browser to add its repository to that board. Project settings → General lists

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,111 @@
 /** 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. */
-export function createClaudeInput(child, { onTaken = () => {} } = {}) {
+ * 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. */
+/**
+ * THE CLI'S OWN CONTEXT MEASURE (2026-10-19). `get_context_usage` with
+ * `detail: 'summary'` answers from the last response's usage and local
+ * estimates — no model call and no token-count request (measured offline on
+ * 2.1.303). It names the window, the tokens in it and the native auto-compact
+ * threshold, so `compactAt` is the CLI's, never a guess; an auto-compact that
+ * is off has none (null). A CLI that answers an error, or never answers,
+ * reports nothing: unknown draws nothing (ContextReadout.tsx).
+ */
+export function contextFromUsage(r) {
+  const used = r?.totalTokens;
+  const window = r?.maxTokens;
+  if (!Number.isSafeInteger(used) || used < 0 || !Number.isSafeInteger(window) || window <= 0) return null;
+  const threshold = r.isAutoCompactEnabled === true && Number.isFinite(r.autoCompactThreshold) && r.autoCompactThreshold > 0
+    ? Math.min(1, r.autoCompactThreshold / window)
+    : null;
+  return { usedTokens: used, windowTokens: window, compactAt: threshold, compacting: false };
+}
+const CONTEXT_EVERY_MS = 3_000;
+
+export function createClaudeInput(child, { onTaken = () => {}, onContext = null } = {}) {
   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(); } };
+  // The context readout's asks: one in flight, at most one per window, and
+  // one more owed when something moved while it was out — at once when what
+  // moved was a compaction ('now'), else on the window ('later').
+  let ctxSeq = 0;
+  let ctxAsked = null;
+  let ctxAt = 0;
+  let ctxOwed = null;
+  let compacting = false;
+  let lastContext = null;
+  const sayContext = (ctx) => {
+    lastContext = ctx;
+    try { onContext(ctx); } catch { /* a readout never fails a turn */ }
+  };
+  const askContext = (now = false) => {
+    if (!onContext || ended || broken || child.stdin.destroyed || child.stdin.writableEnded) return;
+    if (ctxAsked || (!now && Date.now() - ctxAt < CONTEXT_EVERY_MS)) {
+      if (ctxOwed !== 'now') ctxOwed = now ? 'now' : 'later';
+      return;
+    }
+    ctxAsked = `fv-context-${++ctxSeq}`;
+    ctxAt = Date.now();
+    ctxOwed = null;
+    const request = { type: 'control_request', request_id: ctxAsked, request: { subtype: 'get_context_usage', detail: 'summary' } };
+    try { child.stdin.write(JSON.stringify(request) + '\n'); } catch { ctxAsked = null; }
+  };
   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 === 'control_response' && ctxAsked && event.response?.request_id === ctxAsked) {
+        ctxAsked = null;
+        const ctx = event.response.subtype === 'success' ? contextFromUsage(event.response.response) : null;
+        if (ctx) sayContext({ ...ctx, compacting });
+        if (ctxOwed) askContext(ctxOwed === 'now');
+      }
+      if (event.type === 'system' && event.subtype === 'init') askContext(true);
+      if (event.type === 'assistant') askContext();
+      if (event.type === 'system' && event.subtype === 'status') {
+        const now = event.status === 'compacting';
+        if (now && !compacting && lastContext) sayContext({ ...lastContext, compacting: true });
+        if (!now && compacting) askContext(true);
+        compacting = now;
+      }
+      if (event.type === 'system' && event.subtype === 'compact_boundary') { compacting = false; askContext(true); }
+      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

@@ -46,9 +46,10 @@
  * swept on the next write.
  */
 import { randomBytes } from 'node:crypto';
-import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+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';
 
@@ -141,56 +142,6 @@ export function personalClaudeSettings(env = process.env) {
   return out;
 }
 
-/** 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);
-
-/**
- * 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 is keyed on the git root it was added from (`claude mcp
- *    add`'s default scope), which is the person's checkout — never the
- *    agent's worktree, so no card turn could see one even with every source.
- * 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. `{}` when the file is absent, unreadable or not an object.
- */
-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 {};
-    raw = JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return {};
-  }
-  if (!isRecord(raw)) return {};
-  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 key = keys.find((k) => Object.hasOwn(raw.projects, k));
-    if (key) take(raw.projects[key]?.mcpServers);
-  }
-  return out;
-}
-
 /** Where a fenced turn's settings file lives — the daemon's own state
  *  directory, private to this user. */
 export const turnSettingsDir = () => join(homedir(), '.flowviant', 'run');
@@ -233,7 +184,8 @@ export function writeTurnSettings(settings, { dir = turnSettingsDir() } = {}) {
 }
 
 /** Remove the settings file a turn's argv names, when it is one of ours — and
- *  the machine-MCP file (`machineMcpServers`), written the same way. */
+ *  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) => {
@@ -254,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] } });
 }