flowviant 0.117.0 → 0.124.1

package/bin/lib/artifactReporter.mjs

@@ -4,7 +4,7 @@
  *
  * Network delivery is its own reason to change, apart from what is on the disk
  * (artifacts.mjs) and how a page is screenshotted (artifactPreview.mjs). The
- * reporter imports neither: it is HANDED the three functions it runs —
+ * uploader is HANDED the three functions it runs —
  * `listChanged(placeDir, before)` (what the turn wrote), `buildUpload(entry,
  * owner, scrub, secretIn)` (one scrubbed body) and `renderPreview(bytes)` (the
  * screenshot) — so the delivery rules below are tested against a fake server
@@ -12,8 +12,8 @@
  *
  * ── DELIVERY ──
  *
- * A 2xx is delivered. A considered 4xx (fleetWire.mjs's `isConsideredRefusal`:
- * other than 408/429) is TREATED AS DELIVERED — an older SERVER 404s the whole
+ * A 2xx is stored. A considered 4xx (fleetWire.mjs's `isConsideredRefusal`:
+ * other than 408/429) ENDS THE RETRY — an older SERVER 404s the whole
  * route, and holding bodies it will refuse forever would be the trace relay's
  * wedge wearing a retry's clothes; a refusal of one file (ended session, wrong
  * owner) is equally permanent. EXCEPT 401 AND 403, which are a "later"
@@ -28,8 +28,21 @@
  *
  * A PREVIEW THAT FAILS NEVER STOPS THE ARTIFACT: an HTML body goes out with
  * `renderState: 'unavailable'` and no preview, the renderer's explicit answer.
+ *
+ * FILE-CARD DELIVERY REQUIRES STORAGE (2026-10-14). `requireStored` makes
+ * unsuccessful first uploads fail the report, as replacements already did.
+ * A held body is still retried, but cannot advance an image/model queue into
+ * a delivery with no uploaded files. Code and Terminal artifacts keep their
+ * existing best-effort upload policy. Explicit recovery may narrow the scan
+ * with `includeNames`, so it never attributes a sibling card's files.
  */
 
+import { artifactStoredName } from './artifacts.mjs';
+import { fleetHeaders } from './fleetPost.mjs';
+import {
+  iterationSignature, iterationChanges, deletedArtifacts, localArtifact, discardLocalArtifact, iterationInstructions,
+  presentArtifacts, readSeenArtifacts, writeSeenArtifacts, seenArtifacts, serverBornAt,
+} from './artifactIteration.mjs';
 import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
 
 /** A held upload is tried this many times in all, then dropped with a line. */
@@ -39,8 +52,8 @@ const MAX_PENDING = 40;
 
 /**
  * The reporter a work manager holds for its life. `report` is called once per
- * finished turn and never awaited by the turn (a slow uplink must not hold the
- * next turn behind a readout); `retryPending` rides the settle retry beat.
+ * finished turn and awaited before settlement: a failed iteration cleanup
+ * must not become an optimistic delivery. `retryPending` rides the settle beat.
  */
 export function createArtifactReporter({
   fleetUrl,
@@ -53,13 +66,68 @@ export function createArtifactReporter({
   listChanged,
   buildUpload,
   renderPreview,
+  /** `(placeDir, owner) => path | null` — where a place records what it held
+   *  (artifactIteration.mjs). Null keeps no record: only a turn's own
+   *  snapshot then measures a deletion. */
+  seenPath = () => null,
+  /** `(placeDir) => ms | null` — when that worktree was cut. Null (the
+   *  checkout, anything unreadable) gives a place without a record no
+   *  legacy evidence at all. */
+  placeBornAt = () => null,
 }) {
   const url = fleetEndpoint('artifact', fleetUrl);
   const doFetch = fetchImpl ?? ((...a) => fetch(...a));
   const pending = new Map(); // `${owner}:${name}` -> { body, tries }
 
-  /** true = settled (delivered or permanently refused); false = hold it. */
+  const prepare = async ({ placeDir, sessionId, agentId, before }) => {
+    if (!before) return '';
+    before.iterationSignature = iterationSignature(placeDir);
+    delete before.stored;
+    delete before.seen;
+    before.inventoryFailed = false;
+    const query = new URLSearchParams(sessionId ? { sessionId } : { agentId });
+    try {
+      const sentAt = Date.now();
+      const response = await doFetch(`${fleetEndpoint('artifacts', fleetUrl)}?${query}`, {
+        method: 'GET', headers: fleetHeaders({ token, json: false }), signal: AbortSignal.timeout(15_000),
+      });
+      if (!response.ok) {
+        // Older servers have no iteration door. Other failures are unknown,
+        // not an empty inventory and not a successful cleanup.
+        before.inventoryFailed = response.status !== 404;
+        return '';
+      }
+      const result = await response.json();
+      if (!Array.isArray(result.data)) { before.inventoryFailed = true; return ''; }
+      before.stored = result.data.filter((a) => a && typeof a.id === 'string' && typeof a.name === 'string');
+      const path = seenPath(placeDir, sessionId ?? agentId);
+      before.seen = seenArtifacts(readSeenArtifacts(path), before.stored, presentArtifacts(placeDir) ?? new Set(),
+        serverBornAt(placeBornAt(placeDir), response.headers?.get?.('date'), sentAt));
+      writeSeenArtifacts(path, before.seen);
+      return iterationInstructions(before.stored);
+    } catch { before.inventoryFailed = true; return ''; }
+  };
+
+  /** A response distinguishes delivery from a permanent refusal and a retry. */
   const post = async (body) => {
+    if (body.removal) {
+      try {
+        const res = await doFetch(`${url}/remove`, {
+          method: 'POST', headers: fleetHeaders({ token }), signal: AbortSignal.timeout(30_000),
+          body: JSON.stringify(body.removal),
+        });
+        const result = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
+        if (res.ok && result?.data?.complete === true) {
+          discardLocalArtifact(body.placeDir, body.fields.name, body.local);
+          return { settled: true, success: true };
+        }
+        log(`artifact ${body.fields.name}: ${result?.error ?? `removal failed (HTTP ${res.status})`}`);
+        return { settled: res.status !== 401 && res.status !== 403 && isConsideredRefusal(res.status), success: false };
+      } catch (error) {
+        log(`artifact ${body.fields.name}: removal incomplete — ${error.message}`);
+        return { settled: false, success: false };
+      }
+    }
     const form = new FormData();
     for (const [k, v] of Object.entries(body.fields)) form.set(k, v);
     if (body.bytes) form.set('file', new Blob([body.bytes]), body.fields.name);
@@ -71,13 +139,17 @@ export function createArtifactReporter({
         signal: AbortSignal.timeout(30_000),
         body: form,
       });
-      if (res.ok) return true;
+      if (res.ok) {
+        const result = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
+        return { settled: true, success: true, id: result?.data?.id };
+      }
       // A credential blip or an edge page is a "later", bounded by MAX_TRIES
       // (2026-10-10 ruling — see the header).
-      if (res.status === 401 || res.status === 403) return false;
-      return isConsideredRefusal(res.status);
+      if (res.status === 401 || res.status === 403) return { settled: false, success: false };
+      const failure = typeof res.json === 'function' ? await res.json().catch(() => null) : null;
+      return { settled: isConsideredRefusal(res.status), success: false, error: typeof failure?.error === 'string' ? failure.error : failure?.error?.message };
     } catch {
-      return false;
+      return { settled: false, success: false };
     }
   };
 
@@ -110,17 +182,30 @@ export function createArtifactReporter({
   const send = (key, body, tries, gen) => {
     const run = (chains.get(key) ?? Promise.resolve()).then(async () => {
       if (genOf.get(key) !== gen) return; // superseded before it went out
-      const ok = await post(body);
+      const result = await post(body);
       if (genOf.get(key) !== gen) return; // a newer copy decides for this key
-      if (ok) pending.delete(key);
+      if (result.settled) pending.delete(key);
       else hold(key, body, tries + 1);
+      if (result.success && body.replacements?.length) {
+        result.cleanupFailed = [];
+        for (const removal of body.replacements) {
+          if (!result.id) { result.cleanupFailed.push(removal.fields.name); continue; }
+          removal.removal.replacementId = result.id;
+          const removalKey = `${removal.removal.sessionId ?? removal.removal.agentId}:${removal.fields.name}`;
+          // Do not let an earlier replacement retire a later turn's retained file.
+          if (genOf.get(removalKey) !== removal.generation) continue;
+          const removed = await send(removalKey, removal, 0, removal.generation);
+          if (!removed?.success) result.cleanupFailed.push(removal.fields.name);
+        }
+      }
+      return result;
     });
     const tail = run.catch(() => {});
     chains.set(key, tail);
     tail.then(() => {
       if (chains.get(key) !== tail) return;
       chains.delete(key);
-      if (!pending.has(key)) genOf.delete(key); // settled: nothing left to order
+      if (!pending.has(key) && genOf.get(key) === gen) genOf.delete(key); // settled: nothing left to order
     });
     return run;
   };
@@ -141,15 +226,37 @@ export function createArtifactReporter({
 
   /** Upload what this turn changed in `placeDir`. Resolves to the number of
    *  bodies SENT this call (delivered or held), for the tests and the log. */
-  const report = async ({ placeDir, before, sessionId, agentId, turnId }) => {
+  const report = async ({ placeDir, before, sessionId, agentId, turnId, idle = false, requireStored = false, includeNames = null }) => {
     if (!placeDir || (!sessionId && !agentId)) return 0;
-    const changed = listChanged(placeDir, before);
+    const changes = iterationChanges(placeDir, before);
+    if (!before?.stored && (changes.remove.length || Object.keys(changes.replace).length)) throw new Error('Stored artifact inventory could not be measured; removal was not attempted.');
+    const removing = new Set([...changes.remove, ...Object.keys(changes.replace), ...(before?.stored ? deletedArtifacts(placeDir, before) : [])]);
+    const stored = new Map((before?.stored ?? []).map((a) => [a.name, a]));
+    for (const name of [...changes.remove, ...Object.keys(changes.replace)]) {
+      if (!stored.has(name)) throw new Error(`No stored artifact named ${name} belongs to this conversation.`);
+    }
+    // Cancel held uploads immediately, including a copy currently in flight.
+    for (const name of removing) {
+      const key = `${sessionId ?? agentId}:${name}`;
+      pending.delete(key);
+      genOf.set(key, ++generation);
+    }
+    const changed = idle ? [] : listChanged(placeDir, before).filter((e) =>
+      !removing.has(artifactStoredName(e.name)) && (!includeNames || includeNames.has(e.name)));
+    const delivered = new Map();
+    const failures = before?.inventoryFailed
+      ? ['Stored artifact inventory could not be measured; cleanup is incomplete. Retry.'] : [];
     let n = 0;
     for (const entry of changed) {
       const body = buildUpload(entry, { sessionId, agentId, turnId }, scrub, secretIn);
-      if (!body) continue;
+      if (!body) {
+        if (requireStored) failures.push(`artifact ${entry.name} could not be read; it was not delivered`);
+        continue;
+      }
       if (body.withheld) {
         log(`artifact ${entry.name}: not uploaded — it contains the value of ${body.withheld} from this machine's environment`);
+        if (stored.has(body.fields.name)) failures.push(`artifact ${body.fields.name} replacement was withheld; its predecessor was retained`);
+        else if (requireStored) failures.push(`artifact ${body.fields.name} was withheld; it was not delivered`);
         continue;
       }
       if (body.bytes && /\.html?$/i.test(entry.name)) {
@@ -157,15 +264,72 @@ export function createArtifactReporter({
         body.fields.renderState = measured.renderState;
         if (measured.preview) body.preview = measured.preview;
       }
-      const key = `${sessionId ?? agentId}:${entry.name}`;
+      body.replacements = Object.entries(changes.replace).filter(([, to]) => to === body.fields.name).map(([name]) => {
+        const key = `${sessionId ?? agentId}:${name}`;
+        return { fields: { name }, removal: { ...(sessionId ? { sessionId } : { agentId }), id: stored.get(name).id, name },
+          placeDir, local: localArtifact(placeDir, name), generation: genOf.get(key) };
+      });
+      const key = `${sessionId ?? agentId}:${body.fields.name}`;
       pending.delete(key); // this copy supersedes a held older one
       const gen = ++generation;
       genOf.set(key, gen); // …and one still in flight
-      await send(key, body, 0, gen);
+      const result = await send(key, body, 0, gen);
+      if (result?.success && result.id) delivered.set(body.fields.name, result.id);
+      if (result?.cleanupFailed?.length) failures.push(`artifact cleanup incomplete: ${result.cleanupFailed.join(', ')}`);
+      if (!result?.success && (requireStored || stored.has(body.fields.name) || result?.error)) {
+        failures.push(result?.error ?? `artifact ${body.fields.name}${stored.has(body.fields.name) ? ' replacement' : ''} was not delivered`);
+      }
       n++;
     }
+    const removed = new Set();
+    for (const name of removing) {
+      const old = stored.get(name);
+      if (!old) continue; // A local file may belong to a sibling Terminal tab.
+      const replacementName = changes.replace[name];
+      const replacementId = replacementName ? delivered.get(replacementName) : null;
+      if (replacementName && !replacementId) {
+        failures.push(`replacement ${replacementName} was not delivered; ${name} was retained`);
+        continue;
+      }
+      if (replacementName) continue; // Its upload carries the removal through retries.
+      const body = {
+        fields: { name },
+        removal: { ...(sessionId ? { sessionId } : { agentId }), id: old.id, name,
+          ...(replacementId ? { replacementId } : {}) },
+        placeDir, local: localArtifact(placeDir, name),
+      };
+      const key = `${sessionId ?? agentId}:${name}`;
+      const gen = ++generation;
+      genOf.set(key, gen);
+      const result = await send(key, body, 0, gen);
+      if (result?.success) removed.add(name);
+      else failures.push(`artifact ${name} could not be removed; cleanup is incomplete`);
+    }
+    if (before?.stored) {
+      // What this place holds now joins its record; a failed removal stays
+      // in it, so the next measurement retries rather than forgets.
+      const present = presentArtifacts(placeDir) ?? new Set();
+      const owned = new Set([...before.stored.map((a) => a.name), ...present, ...delivered.keys()]);
+      writeSeenArtifacts(seenPath(placeDir, sessionId ?? agentId),
+        [...(before.seen ?? []), ...present, ...delivered.keys()]
+          .filter((name) => owned.has(name) && !removed.has(name)));
+    }
+    if (failures.length) throw new Error(failures.join('; '));
     return n;
   };
 
-  return { report, retryPending, pendingCount: () => pending.size };
+  /**
+   * AN IDLE DELIVERY, RECONCILED WITHOUT A TURN (2026-10-11 follow-up). A
+   * discard was relayed only when a turn settled, so an agent waiting in
+   * Review kept every stored file an earlier daemon never removed. Nothing
+   * is uploaded here; the place's measured discards are retired and a
+   * failure throws, exactly as a turn's report would.
+   */
+  const reconcile = async ({ placeDir, before, sessionId, agentId }) => {
+    if (!placeDir || !before || (!sessionId && !agentId)) return 0;
+    await prepare({ placeDir, before, sessionId, agentId });
+    return report({ placeDir, before, sessionId, agentId, idle: true });
+  };
+
+  return { prepare, report, reconcile, retryPending, pendingCount: () => pending.size };
 }

package/bin/lib/artifacts.mjs

@@ -243,8 +243,8 @@ export function snapshotArtifacts(placeDir) {
 }
 
 /** What the turn wrote: every entry whose (name, size, mtime) is not what the
- *  snapshot held. A deleted file is not reported — the server's copy is
- *  scrollback and goes with the session or the agent. */
+ *  snapshot held. Deletions and replacement relationships are reported by
+ *  artifactIteration.mjs separately from upload bodies. */
 export function changedArtifacts(before, entries) {
   return entries.filter((e) => before?.get(e.name) !== sigOf(e));
 }
@@ -293,6 +293,9 @@ function safeArtifactName(raw) {
   return clean ? cutKeepingExtension(clean) : 'artifact';
 }
 
+/** The stored name is also the key for iteration and queued upload cancellation. */
+export const artifactStoredName = (name) => name.split('/').map(safeArtifactName).join('/');
+
 /**
  * ONE UPLOAD BODY, as data — fields plus optional bytes — so a held body is
  * re-sent exactly as it was first built (scrubbed once, never re-read from a
@@ -303,7 +306,7 @@ export function buildArtifactUpload(entry, { sessionId, agentId, turnId }, scrub
   const fields = {
     ...(sessionId ? { sessionId } : { agentId }),
     ...(turnId ? { turnId } : {}),
-    name: entry.name.split('/').map(safeArtifactName).join('/'),
+    name: artifactStoredName(entry.name),
     bytes: String(entry.size),
   };
   if (!type) return { fields, bytes: null }; // reported by name only

package/bin/lib/checkoutIdentity.mjs

@@ -0,0 +1,25 @@
+import { basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { gitOrNull } from './git.mjs';
+
+/** Login registers addresses without sending a credential in an HTTPS URL.
+ * A checkout with no origin has its local path as its repository address. */
+export function checkoutIdentity(repoRoot) {
+  let remote = gitOrNull(['remote', 'get-url', 'origin'], repoRoot) ?? pathToFileURL(repoRoot).href;
+  if (remote.includes('://')) {
+    try {
+      const url = new URL(remote);
+      url.password = '';
+      if (url.protocol !== 'ssh:') url.username = '';
+      url.search = '';
+      url.hash = '';
+      remote = url.hostname.toLowerCase() === 'github.com'
+        ? url.pathname.replace(/^\//, '').replace(/\.git\/?$/, '')
+        : url.toString();
+    } catch { remote = repoRoot; }
+  }
+  const ssh = remote.match(/^(?:git@)?github\.com:([^/]+\/[^/]+?)(?:\.git)?$/i);
+  if (ssh) remote = ssh[1];
+  const name = basename(repoRoot).toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^[^a-z0-9]+/, '').slice(0, 40) || 'app';
+  return { name, remote };
+}

package/bin/lib/claudeAuth.mjs

@@ -26,8 +26,9 @@
  *    daemon started, so a variable exported weeks ago is still in there long
  *    after it left your shell. A stale one fails in a way a fresh `claude`
  *    never reproduces.
- *  · THE HOME. The CLI reads its store from $HOME. A daemon under systemd, a
- *    different user, or a container has a different one than the shell you
+ *  · THE STORE. The CLI uses $CLAUDE_CONFIG_DIR, else $HOME/.claude. A daemon
+ *    under systemd, a different user, or a container has a different one than
+ *    the shell you
  *    tested in, so "I am logged in" was measured on the wrong file.
  *
  * ── WHAT THIS IS NOT ──
@@ -75,11 +76,19 @@ export const AUTH_ENV_VARS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAU
 /** Claude Code's OAuth store, relative to the HOME the CLI will be handed. */
 const CRED_REL = ['.claude', '.credentials.json'];
 
+/** The same location Claude's personal settings reader uses. */
+export function claudeCredentialPath(env = process.env, home = null) {
+  const root = home ?? env.HOME ?? env.USERPROFILE ?? null;
+  return env.CLAUDE_CONFIG_DIR
+    ? join(env.CLAUDE_CONFIG_DIR, '.credentials.json')
+    : root ? join(root, ...CRED_REL) : null;
+}
+
 
 /**
  * What the CLI on this machine will resolve, as far as it can be seen without
  * spending anything: no process spawned, no request made, no quota touched.
- * Just this process's own environment and one file's metadata.
+ * Just this process's own environment and the CLI-selected file's metadata.
  *
  * `env` and `home` are parameters rather than reads of `process` so the tests
  * can drive every branch — and so the caller passes the SAME environment the
@@ -98,9 +107,10 @@ export function claudeAuthContext({ env = process.env, home = null } = {}) {
   let refreshExpiresAt = null;
   let accessExpiresAt = null;
   let subscriptionType = null;
-  if (HOME) {
+  const credentialPath = claudeCredentialPath(env, HOME);
+  if (credentialPath) {
     try {
-      const raw = readFileSync(join(HOME, ...CRED_REL), 'utf8');
+      const raw = readFileSync(credentialPath, 'utf8');
       const oauth = JSON.parse(raw)?.claudeAiOauth;
       if (oauth && typeof oauth === 'object') {
         hasFile = true;

package/bin/lib/claudeInput.mjs

@@ -0,0 +1,32 @@
+/** 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 = () => {} } = {}) {
+  const sent = new Set();
+  const pending = new Set();
+  let accepting = true;
+  let ended = false;
+  let resultSeen = false;
+  child.stdin.on('error', () => { accepting = false; }); // EPIPE leaves the message queued
+  const send = (id, prompt) => {
+    if (!accepting || 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; }
+  };
+  return {
+    send,
+    event(event) {
+      if (event.type === 'user' && event.isReplay === true && pending.delete(event.uuid)) onTaken(event.uuid);
+      if (event.type === 'result') {
+        resultSeen = true;
+        accepting = false;
+        if ((pending.size === 0 || event.is_error === true) && !ended) { ended = true; child.stdin.end(); }
+      }
+    },
+    close() { accepting = false; ended = true; },
+    get resultSeen() { return resultSeen; },
+  };
+}

package/bin/lib/claudePosture.mjs

@@ -12,6 +12,7 @@
 
 import { fileURLToPath } from 'node:url';
 import { SAFE } from './config.mjs';
+import { runningCompiledBinary } from './launchCommand.mjs';
 
 /**
  * THE READ GUARD, ON EVERY CURATED POSTURE (2026-09-23) — see
@@ -35,20 +36,40 @@ import { SAFE } from './config.mjs';
  * `process.execPath`, never a `node` looked up on a PATH the operator may not
  * have, because a hook that fails to START is a non-blocking error and the
  * command runs anyway.
+ *
+ * …AND AS `<flowviant> __hook read-guard` UNDER THE COMPILED BINARY
+ * (2026-10-11). There `process.execPath` IS flowviant and the script path is
+ * Bun's virtual `/$bunfs/…`, so the old command was `flowviant
+ * '/$bunfs/root/hooks/readGuard.mjs'`: the CLI answered "is not a command"
+ * with exit 1 (measured on the installed 0.116.0), a non-blocking error, and
+ * every guarded command ran — the curl install had no read guard. The CLI now
+ * runs the hook itself (bin/cli.mjs, `__hook`), before anything else loads.
  */
 export const READ_GUARD_PATH = fileURLToPath(new URL('./hooks/readGuard.mjs', import.meta.url));
+export const MCP_ALLOW_PATH = fileURLToPath(new URL('./hooks/mcpAllow.mjs', import.meta.url));
 const hookQuote = (s) =>
   process.platform === 'win32' ? `"${s}"` : `'${String(s).replace(/'/g, `'\\''`)}'`;
+/** The command a hook runs as: this node and the script, or this binary and
+ *  its `__hook` word (`compiled` is runningCompiledBinary's answer; a test
+ *  passes it). */
+export function hookCommand(name, scriptPath, { compiled = runningCompiledBinary() } = {}) {
+  return compiled ? `${hookQuote(process.execPath)} __hook ${name}` : `${hookQuote(process.execPath)} ${hookQuote(scriptPath)}`;
+}
 export const READ_GUARD_SETTINGS = JSON.stringify({
   hooks: {
     PreToolUse: [
       {
         matcher: 'Bash',
-        hooks: [{ type: 'command', command: `${hookQuote(process.execPath)} ${hookQuote(READ_GUARD_PATH)}` }],
+        hooks: [{ type: 'command', command: hookCommand('read-guard', READ_GUARD_PATH) }],
       },
     ],
   },
 });
+/** The MCP allow hook's entry (hooks/mcpAllow.mjs), matched on MCP tools only. */
+export const MCP_ALLOW_HOOK = Object.freeze({
+  matcher: 'mcp__.*',
+  hooks: [{ type: 'command', command: hookCommand('mcp-allow', MCP_ALLOW_PATH) }],
+});
 /** Spread FIRST into a curated list: `--allowedTools` is variadic, so the
  *  `--settings` pair must stand before it or be swallowed as a tool name. */
 const READ_GUARD = ['--settings', READ_GUARD_SETTINGS];
@@ -278,7 +299,9 @@ export function consultPermFor(knowledgeDir) {
 
 /**
  * THE TWO NON-CODE POSTURES (0.97.0) — a design card and a research card may
- * WRITE, and only under `.flowviant/artifacts/`.
+ * HISTORICAL ARTIFACT PROBES before 2026-10-12. Current artifact lists below
+ * add guarded readers, web and scratch; arbitrary programs still cannot
+ * bypass the write fence. WRITE was only under `.flowviant/artifacts/`.
  *
  * The card's words are steered by anyone who can file a card, so "change
  * nothing" as prose is only an instruction, and the permission list is the
@@ -337,11 +360,26 @@ export function consultPermFor(knowledgeDir) {
  *    explicit `Bash(git log:*)` prefix the old list carried). With `Bash` in
  *    `--disallowedTools` the tool was not there at all.
  *
- * NO MCP, and no shell that could commit: the agent turn has no MCP anyway
- * (see SYSTEM_AGENT's header), and a posture that could run `git commit` could
- * commit the mockup it was told to keep out of git.
+ * THE PROJECT'S MCP SERVERS (2026-10-10, the owner): each list allows
+ * `mcp__<server>` for every server the agent lane mounted from the base
+ * branch's reviewed `.mcp.json` (projectTools.mjs) — the set a code card gets.
+ * Under `--allowedTools` an MCP tool with no rule is refused ("Claude requested
+ * permissions to use mcp__…, but you haven't granted it yet", measured on the
+ * plan posture), so the rule IS the mount. AND THE MACHINE'S OWN (2026-10-11):
+ * an agent turn mounts this machine's user/local servers and claude.ai
+ * connectors too, whose names only the CLI knows, so the lane adds the MCP
+ * allow hook (`withMachineMcp`, below). No shell that could commit: a posture
+ * that could run `git commit` could commit the mockup it was told to keep out
+ * of git.
  *
- * STATED, not closed: research may still read any file in the worktree and
+ * STATED, not closed: an MCP server is a process of its own, outside every
+ * list here — it reads, writes and reaches the network as the person who runs
+ * it, and a turn steered by a card's words can hand it anything the turn read,
+ * or ask it to act: the machine's claude.ai connectors are its owner's
+ * accounts. On research that sits beside the web. The base branch's
+ * `.mcp.json` is the repository's reviewed choice, and the machine's servers
+ * are its owner's (docs/decisions.md, 2026-10-10 and 2026-10-11).
+ * Research may still read any file in the worktree and
  * name it in a WebFetch URL — the repository is what a research card is about,
  * and a turn that could not read it could not answer. Design may read any
  * file in its worktree and put it in an artifact the server stores; text
@@ -356,6 +394,12 @@ export function consultPermFor(knowledgeDir) {
  * the guard's hook sees a subagent's own calls was not measured here.
  */
 const ARTIFACT_WRITE = 'Edit(.flowviant/artifacts/**)';
+/** `mcp__<server>` for each mounted project server — a name the base snapshot
+ *  already admitted (projectTools.mjs `nameOk`), checked again here because a
+ *  rule is a pattern: anything but a plain server name gets no rule, and
+ *  Flowviant's own control plane is never a project's server. */
+const projectMcpRules = (names = []) =>
+  names.filter((n) => typeof n === 'string' && /^[A-Za-z0-9_-]{1,80}$/.test(n) && n !== 'flowviant').map((n) => `mcp__${n}`);
 /**
  * PLAN MODE (0.97.0) — a Workbench tab's `planMode` switch, and Claude Code's
  * own `--permission-mode plan` INSTEAD OF every list above: the CLI reads,
@@ -386,17 +430,22 @@ const ARTIFACT_WRITE = 'Edit(.flowviant/artifacts/**)';
  *    plane whose every call the CLI refuses. See workTurnShape.mjs.
  */
 export const PLAN_MODE_PERM = ['--permission-mode', 'plan'];
-export function designPermFor(knowledgeDir) {
+export function designPermFor(knowledgeDir, projectMcp = []) {
   return [
     ...READ_GUARD,
     '--allowedTools',
     ...fencedReads(knowledgeDir),
-    'Bash(ls:*)',
+    ...CONSULT_BASH,
+    'WebSearch',
+    'WebFetch',
     ARTIFACT_WRITE,
+    'Edit(.flowviant/tmp/**)',
+    ...projectMcpRules(projectMcp),
     // A mockup is uploaded and runs scripts in a frame that may navigate
     // itself, so the checkout's own secrets are denied by name too — the same
     // pair research carries, measured load-bearing there.
     '--disallowedTools',
+    'Agent',
     'Read(./.env*)',
     'Read(./**/.env*)',
   ];
@@ -408,18 +457,21 @@ export const DESIGN_PERM = designPermFor(null);
  * outside the worktree it may read, and only the spawn knows where that is.
  * `//` is the CLI's own spelling for an absolute path in a rule.
  */
-export function researchPerm(knowledgeDir) {
+export function researchPerm(knowledgeDir, projectMcp = []) {
   return [
     ...READ_GUARD,
     '--allowedTools',
     ...fencedReads(knowledgeDir),
+    ...CONSULT_BASH,
     'WebSearch',
     'WebFetch',
     ARTIFACT_WRITE,
+    'Edit(.flowviant/tmp/**)',
+    ...projectMcpRules(projectMcp),
     '--disallowedTools',
+    'Agent',
     'Read(./.env*)',
     'Read(./**/.env*)',
-    'Bash',
   ];
 }
 /** The list with no library — what a project that keeps none runs under. */
@@ -429,6 +481,8 @@ 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.
+ * `projectMcp` is the names of the project servers the lane mounted; only the
+ * design and research lists take them (`projectMcp` in turnProfile.mjs).
  */
 const CLAUDE_PERM = {
   build: () => PERM,
@@ -436,8 +490,8 @@ const CLAUDE_PERM = {
   consult: (kd) => consultPermFor(kd),
   plan: (kd) => planPermFor(kd),
   'plan-mode': () => PLAN_MODE_PERM,
-  design: (kd) => designPermFor(kd),
-  research: (kd) => researchPerm(kd),
+  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
@@ -447,8 +501,50 @@ const CLAUDE_PERM = {
   image: (kd) => consultPermFor(kd),
 };
 export const CLAUDE_PERM_PROFILES = Object.freeze(Object.keys(CLAUDE_PERM));
-export function claudePermFor(profileName, knowledgeDir, vaultDir) {
+export function claudePermFor(profileName, knowledgeDir, vaultDir, projectMcp = []) {
   const build = Object.hasOwn(CLAUDE_PERM, profileName) ? CLAUDE_PERM[profileName] : null;
   if (!build) throw new Error(`no Claude permission list for profile '${profileName}'`);
-  return build(knowledgeDir, vaultDir);
+  return build(knowledgeDir, vaultDir, projectMcp);
+}
+
+/**
+ * THE MACHINE'S MCP SERVERS ON AN AGENT TURN (2026-10-11, the owner: "the
+ * server that is running flowviant's claude HAS these MCPs yet the agents are
+ * not using them"). A code, write-up, mockup, 3D-model or deck turn mounts what
+ * this machine's Claude Code has — its user and local servers and the account's
+ * claude.ai connectors — beside the base branch's `.mcp.json` copy. So the turn
+ * drops `--strict-mcp-config` (runtimeClaude.mjs), and its one `--settings`
+ * carries two things:
+ *
+ *  · `disabledMcpjsonServers`, every server named in a `.mcp.json` from the
+ *    worktree up to `/`. Without strict, Claude Code reads `.mcp.json` in the
+ *    cwd AND EVERY PARENT (measured, 2.1.290: a parent directory's server
+ *    loaded) wherever a settings scope approves it, so the agent's own edit of
+ *    its worktree's file would mount before review. A flag
+ *    `enableAllProjectMcpServers: false` did NOT override a lower scope's
+ *    `true`; the disabled list did, by name, and left the base copy loaded
+ *    through `--mcp-config` (a `dynamic` server) untouched — measured with both
+ *    a lower `enableAllProjectMcpServers` and a lower `enabledMcpjsonServers`.
+ *  · the MCP allow hook (`MCP_ALLOW_HOOK`), because a fenced list refuses an
+ *    MCP tool it does not name and a connector's name is the account's. The
+ *    build's bypass needs no hook; a SAFE build's curated list does, and the
+ *    hook is harmless under the bypass, so every mount carries it.
+ *
+ * `perm` is the posture's list; a list with no `--settings` (the build) gets
+ * one before its lists (`--allowedTools` is variadic). The fenced turn's
+ * personal keys are folded in after (claudePersonal.mjs); the posture's keys
+ * win there, and none of the person's kept keys is one of these.
+ *
+ * STATED, not closed: plugins stay the person's own on the build and out of
+ * every fenced turn (`--setting-sources ''`), so a plugin's MCP servers reach
+ * code cards only — a plugin also brings hooks, which would be a second author
+ * 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)];
 }