flowviant 0.117.0 → 0.124.0

package/bin/lib/maintenanceInventory.mjs

@@ -0,0 +1,39 @@
+/** The restart must also see live locks not backed by a stored project, and
+ * unguarded processes recorded in state. Neither is an empty machine. */
+import { instanceLockPath, listDaemonLocks } from './daemonLocks.mjs';
+import { daemonLockPid, readDaemonState } from './daemonState.mjs';
+import { listStoredProjects } from './credentials.mjs';
+import { processAlive } from './procRegistry.mjs';
+
+export function unknownMaintenanceDaemons({ entries = listStoredProjects(), locks = listDaemonLocks(),
+  stateFor = readDaemonState, pidFor = daemonLockPid, alive = processAlive } = {}) {
+  const known = new Set();
+  const unknown = new Set();
+  for (const entry of entries) {
+    const state = stateFor(entry.projectId);
+    const pid = pidFor(entry.fleetToken);
+    if (pid != null && pid === state.pid) known.add(pid);
+    if (Number.isInteger(state.pid) && state.pid > 0 && state.pid !== pid && alive(state.pid)) unknown.add(state.pid);
+  }
+  for (const { path, holder } of locks) {
+    if (!holder) unknown.add(path); // unreadable is not absent
+    else if (alive(holder.pid) && !known.has(holder.pid)) unknown.add(holder.pid);
+  }
+  return unknown.size;
+}
+
+/** The ordinary tray status reserves null for an absent lock. For a global
+ * restart we additionally measure the whole lock directory: no lock and no
+ * live state PID means this stored project's daemon is stopped. Unreadable
+ * directories throw rather than becoming a fabricated empty machine. */
+export function maintenanceInventory(status, { entries = listStoredProjects(), locks = listDaemonLocks({ strict: true }),
+  stateFor = readDaemonState, pidFor = daemonLockPid, alive = processAlive } = {}) {
+  const paths = new Set(locks.map(lock => lock.path));
+  const projects = status.projects.map(row => {
+    const entry = entries.find(entry => entry.projectId === row.id);
+    if (row.running !== null || !entry || paths.has(instanceLockPath(entry.fleetToken))) return row;
+    const pid = stateFor(row.id).pid;
+    return Number.isInteger(pid) && pid > 0 && alive(pid) ? row : { ...row, running: false };
+  });
+  return { projects, unknownDaemons: unknownMaintenanceDaemons({ entries, locks, stateFor, pidFor, alive }) };
+}

package/bin/lib/mcpInstall.mjs

@@ -0,0 +1,163 @@
+/**
+ * A CONFIRMED MCP INSTALL (2026-10-13, the owner; the app's half is
+ * packages/shared `mcpSetup.ts`). A project owner pressed "Install on <this
+ * machine>" on the Machines page and confirmed the exact command; the roster
+ * hands it to THIS box as `mcpInstallJobs`.
+ *
+ * WHAT THIS DOES, AND ALL IT DOES:
+ *  · claims the job (single-flight across processes, bound to this box);
+ *  · refuses, without running anything, a command its own copy of the rule
+ *    refuses (`mcpInstallCommandRefusal` — a privilege word, more than one
+ *    line, over the cap; parity rule 36 holds it to the server's);
+ *  · runs EXACTLY the text it was handed through `/bin/sh -c`, in the
+ *    project's checkout, as this daemon's own user, never with sudo, stdin
+ *    closed, as an unattended child (no machine credential, no display), in
+ *    its own process group killed whole at the timeout;
+ *  · streams the output's tail back about once a second, and at the end the
+ *    exit code;
+ *  · then looks again (`recheck`): the tool report is rescanned and posted,
+ *    and Claude Code is probed with the base branch's servers mounted, so the
+ *    page's checklist clears when the server starts.
+ *
+ * The command is never rewritten, prefixed or appended to.
+ */
+import { spawn } from 'node:child_process';
+import { DAEMON_INSTANCE, FLEET_URL } from './config.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+import { claimFleetLease, postBestEffort, settleLease } from './fleetPost.mjs';
+import { killGroup } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { scrubTail } from './uplinkScrub.mjs';
+import { c, note, ok, warn } from './ui.mjs';
+import { printableLine } from './printable.mjs';
+
+/** The server's bounds (shared `mcpSetup.ts`; parity rule 36). */
+export const MCP_INSTALL_COMMAND_MAX = 500;
+export const MCP_INSTALL_OUTPUT_MAX = 16_000;
+export const MCP_INSTALL_TIMEOUT_MS = 10 * 60_000;
+export const MCP_INSTALL_PRIVILEGE_WORDS = Object.freeze(['sudo', 'doas', 'su', 'pkexec', 'run0']);
+
+/** Why this command cannot run, or null — the shared rule, word for word. */
+export function mcpInstallCommandRefusal(command) {
+  if (typeof command !== 'string' || !command.trim()) return 'The install command is empty.';
+  if (command.length > MCP_INSTALL_COMMAND_MAX) return `The install command is over ${MCP_INSTALL_COMMAND_MAX} characters.`;
+  if (/[\r\n\0]/.test(command)) return 'The install command must be one line.';
+  const words = command.split(/[^A-Za-z0-9_-]+/);
+  const word = MCP_INSTALL_PRIVILEGE_WORDS.find((w) => words.includes(w));
+  if (word) return `Flowviant never installs with ${word}. Use a command that installs as the machine's own user.`;
+  return null;
+}
+
+const url = (tail) => fleetEndpoint(tail, FLEET_URL);
+const tail = (text) => (text.length > MCP_INSTALL_OUTPUT_MAX ? text.slice(text.length - MCP_INSTALL_OUTPUT_MAX) : text);
+
+/**
+ * Run one command and hand back `{ code, out }`. `onOutput(out)` hears the
+ * tail as it grows. `spawnChild` is a test's.
+ */
+export function runInstallCommand(command, { cwd, timeoutMs = MCP_INSTALL_TIMEOUT_MS, env = unattendedEnv(), onOutput = () => {}, spawnChild = spawn } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnChild('/bin/sh', ['-c', command], { cwd, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      resolve({ code: -1, out: `[flowviant] could not start the command: ${error?.message ?? error}` });
+      return;
+    }
+    let buf = '';
+    let settled = false;
+    const settle = (v) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(v);
+    };
+    const take = (d) => {
+      buf += d;
+      if (buf.length > 2 * MCP_INSTALL_OUTPUT_MAX) buf = scrubTail(buf, MCP_INSTALL_OUTPUT_MAX);
+      onOutput(scrubTail(buf, MCP_INSTALL_OUTPUT_MAX));
+    };
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', take);
+    child.stderr?.on('data', take);
+    const timer = setTimeout(() => {
+      killGroup(child, 'SIGKILL');
+      const minutes = Math.round(timeoutMs / 60_000);
+      settle({ code: -1, out: scrubTail(`${buf}\n[flowviant] the command ran past ${minutes >= 1 ? `${minutes} minutes` : `${timeoutMs}ms`} and was stopped`, MCP_INSTALL_OUTPUT_MAX) });
+    }, timeoutMs);
+    timer.unref?.();
+    child.on('error', (error) => settle({ code: -1, out: scrubTail(`${buf}\n[flowviant] ${error?.message ?? error}`, MCP_INSTALL_OUTPUT_MAX) }));
+    child.on('close', (code) => settle({ code: code ?? -1, out: scrubTail(buf, MCP_INSTALL_OUTPUT_MAX) }));
+  });
+}
+
+/** Job ids this process has taken — never run twice in one process. */
+const seen = new Set();
+let running = 0;
+/** Installs this process is running — the machine is busy while one is. */
+export const mcpInstallsInFlight = () => running;
+
+/**
+ * The roster's `mcpInstallJobs` for this box. `ctx` = { repoRoot, myPubB64,
+ * recheck }, and for tests `run`, `claim`, `report` and `final`.
+ */
+export function processMcpInstallJobs(jobs, ctx) {
+  if (!Array.isArray(jobs)) return;
+  for (const job of jobs) {
+    if (!job || typeof job.id !== 'string' || typeof job.command !== 'string' || seen.has(job.id)) continue;
+    seen.add(job.id);
+    void runJob(job, ctx);
+  }
+}
+
+async function runJob(job, ctx) {
+  const pubkey = ctx.myPubB64?.();
+  if (!pubkey) return;
+  const claim = ctx.claim ?? ((fields) => claimFleetLease(url('mcp-install-claim'), fields));
+  const report = ctx.report ?? ((body) => settleLease(url('mcp-install-report'), body, { timeoutMs: 15_000 }));
+  const final = ctx.final ?? ((body) => postBestEffort(url('mcp-install-report'), { ...body, instance: DAEMON_INSTANCE }));
+  const run = ctx.run ?? runInstallCommand;
+  if (!(await claim({ jobId: job.id, pubkey }))) return;
+  const name = printableLine(String(job.serverName ?? 'MCP server'), 60);
+  const refusal = mcpInstallCommandRefusal(job.command);
+  if (refusal) {
+    warn(`${c.cyan('mcp')} ${c.dim(`— not installing ${name}: ${refusal}`)}`);
+    await final({ jobId: job.id, pubkey, output: `[flowviant] ${refusal}`, done: true, exitCode: -1 });
+    return;
+  }
+  running += 1;
+  note(`${c.cyan('mcp')} ${c.dim(`— installing ${name}, as confirmed in the app: ${printableLine(job.command, 200)}`)}`);
+  let latest = '';
+  let sentAt = 0;
+  let sending = false;
+  const beat = () => {
+    if (sending || latest === '' || Date.now() - sentAt < 1000) return;
+    sending = true;
+    sentAt = Date.now();
+    const output = latest;
+    void Promise.resolve(report({ jobId: job.id, pubkey, output, done: false, exitCode: null })).catch(() => {}).finally(() => { sending = false; });
+  };
+  const timer = setInterval(beat, 1000);
+  timer.unref?.();
+  try {
+    const timeoutMs = Number.isInteger(job.timeoutMs) && job.timeoutMs > 0 ? Math.min(job.timeoutMs, MCP_INSTALL_TIMEOUT_MS) : MCP_INSTALL_TIMEOUT_MS;
+    const { code, out } = await run(job.command, { cwd: ctx.repoRoot, timeoutMs, onOutput: (o) => { latest = tail(o); } });
+    clearInterval(timer);
+    await final({ jobId: job.id, pubkey, output: tail(out), done: true, exitCode: code });
+    if (code === 0) ok(`${c.cyan('mcp')} ${c.dim(`— installed ${name}; checking it again`)}`);
+    else warn(`${c.cyan('mcp')} ${c.dim(`— installing ${name} exited ${code}`)}`);
+  } finally {
+    clearInterval(timer);
+    running -= 1;
+    try {
+      await ctx.recheck?.();
+    } catch { /* a re-check is best-effort; the next beat looks anyway */ }
+  }
+}
+
+/** Tests only. */
+export function resetMcpInstallsForTest() {
+  seen.clear();
+  running = 0;
+}

package/bin/lib/mcpInventory.mjs

@@ -0,0 +1,119 @@
+/**
+ * EVERY MCP SERVER EACH CLI ON THIS BOX HAS, FOR THE MACHINES PAGE (2026-10-13,
+ * the owner: "see at a glance what Flowviant can do on this project, from what
+ * the serving machine's CLIs actually have").
+ *
+ * Per installed CLI, one list: the servers the CLI itself reported (Claude
+ * Code's init, harvested in runtimeCapabilities.mjs; Codex's `mcp list`, read
+ * in runtimeOfferings.mjs) and every server the base branch's `.mcp.json`
+ * declares (projectTools.mjs). Rides this box's own `tools-report`
+ * (fleetReports.mjs), so its 60-second beat and write-on-change dedup are the
+ * lane's; the server stores it per box (packages/shared `mcpInventory.ts`,
+ * the shape and the bounds, held equal by parity rule 35).
+ *
+ * DECLARED IS NOT PRESENT. A base `.mcp.json` server the CLI did not report
+ * running is `declared`, with the reason this daemon would leave it unmounted
+ * (`env X unset`, `command y not on PATH`, a transport the CLI refuses) when
+ * there is one — never shown as available because the file lists it.
+ *
+ * Names, statuses, sources, reasons and tool names only: no env value, header,
+ * token, URL or path leaves the box.
+ */
+import { toolReadout } from './projectTools.mjs';
+import { MCP_NAME_MAX } from './runtimeCapabilities.mjs';
+
+/** The server's bounds (shared `mcpInventory.ts`; parity rule 35). */
+export const MCP_INVENTORY_MAX_SERVERS = 80;
+export const MCP_INVENTORY_NAME_MAX = MCP_NAME_MAX;
+export const MCP_INVENTORY_TOOLS_PER_SERVER = 100;
+export const MCP_INVENTORY_TOOLS_PER_CLI = 1000;
+export const MCP_INVENTORY_TOOL_NAME_MAX = 64;
+export const MCP_INVENTORY_REASON_MAX = 200;
+
+const SOURCE_ORDER = { project: 0, personal: 1, claudeai: 2 };
+const TOOL_NAME = /^[A-Za-z0-9_.:-]+$/;
+
+/**
+ * Claude Code's scope word → the page's source. `project` is a checkout's
+ * `.mcp.json`; `claudeai` an account connector; `dynamic` is a server named on
+ * the command line, which on a turn the harvest records is the base copy when
+ * the name is declared and otherwise this daemon's own — not the person's.
+ * Every other scope (user, local, plugin, enterprise, managed, agent) is the
+ * CLI's own config on this box.
+ */
+function claudeSource(scope, name, declared) {
+  if (scope === 'claudeai' || name.startsWith('claude.ai ')) return 'claudeai';
+  if (scope === 'project') return 'project';
+  if (scope === 'dynamic') return declared.has(name) ? 'project' : null;
+  return 'personal';
+}
+
+const declaredRows = (snapshot, runner) =>
+  snapshot ? toolReadout(snapshot, runner).filter((t) => t.kind === 'mcp') : [];
+
+/** One CLI's list, bounded the way the server re-applies it. */
+function bound(servers) {
+  let budget = MCP_INVENTORY_TOOLS_PER_CLI;
+  const seen = new Set();
+  return servers
+    .map((s) => ({ ...s, name: s.name.trim().slice(0, MCP_INVENTORY_NAME_MAX).trim() }))
+    .filter((s) => s.name && s.name !== 'flowviant' && !seen.has(s.name) && seen.add(s.name))
+    .sort((a, b) => SOURCE_ORDER[a.source] - SOURCE_ORDER[b.source] || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .slice(0, MCP_INVENTORY_MAX_SERVERS)
+    .map((s) => {
+      let tools = null;
+      if (Array.isArray(s.tools)) {
+        tools = [...new Set(s.tools.filter((t) => typeof t === 'string' && t.length <= MCP_INVENTORY_TOOL_NAME_MAX && TOOL_NAME.test(t)))]
+          .sort()
+          .slice(0, Math.min(MCP_INVENTORY_TOOLS_PER_SERVER, budget));
+        budget -= tools.length;
+      }
+      return { name: s.name, source: s.source, status: s.status, reason: s.reason == null ? null : String(s.reason).slice(0, MCP_INVENTORY_REASON_MAX), tools };
+    });
+}
+
+/** Claude Code: what its init reported, then each declaration it did not. */
+export function claudeInventory(harvested, snapshot) {
+  const declared = new Map(declaredRows(snapshot, 'claude').map((t) => [t.name, t]));
+  const servers = [];
+  for (const h of harvested ?? []) {
+    const source = claudeSource(h.scope, h.name, declared);
+    if (!source) continue;
+    const why = source === 'project' && h.status !== 'connected' ? declared.get(h.name)?.reason ?? null : null;
+    servers.push({ name: h.name, source, status: h.status, reason: why, tools: h.status === 'connected' ? h.tools ?? [] : null });
+  }
+  const running = new Set(servers.filter((s) => s.source === 'project').map((s) => s.name));
+  for (const [name, d] of declared) {
+    if (!running.has(name)) servers.push({ name, source: 'project', status: 'declared', reason: d.reason, tools: null });
+  }
+  return { reported: harvested != null, servers: bound(servers) };
+}
+
+/**
+ * Codex: its own config's servers, then each declaration. A declared server
+ * replaces a personal one of the same name on a card's turn
+ * (projectToolRuntimes.mjs `isolatedCodexHome`), so the declaration is the
+ * row. Codex names no tools without starting a server, so `tools` is null.
+ */
+export function codexInventory(rows, snapshot) {
+  const declared = declaredRows(snapshot, 'codex');
+  const names = new Set(declared.map((d) => d.name));
+  const servers = [
+    ...declared.map((d) => ({ name: d.name, source: 'project', status: 'declared', reason: d.reason, tools: null })),
+    ...(rows ?? []).filter((r) => !names.has(r.name)).map((r) => ({ name: r.name, source: 'personal', status: r.status, reason: r.reason, tools: null })),
+  ];
+  return { reported: rows != null, servers: bound(servers) };
+}
+
+/**
+ * The `mcp` key of the tools report: `{ claude?, codex? }`, a CLI only when it
+ * is installed here. `snapshot` is the base-branch read (null when it could
+ * not be read — the declarations are then unknown, and only the CLI's own
+ * list is said).
+ */
+export function buildMcpInventory({ installed, snapshot, claude, codex }) {
+  const out = {};
+  if (installed.includes('claude')) out.claude = claudeInventory(claude, snapshot);
+  if (installed.includes('codex')) out.codex = codexInventory(codex, snapshot);
+  return out;
+}

package/bin/lib/planDependencies.mjs

@@ -0,0 +1,70 @@
+/** The planner declares prerequisites; the daemon enforces them without reading
+ * human prose. Declared collisions use the same compatible groups; evidence stays on the wire. */
+export function groupDependencies(agents, dependencies, collisions) {
+  if (dependencies === undefined && collisions === undefined) return agents;
+  if (dependencies === undefined) dependencies = [];
+  if (collisions === undefined) collisions = [];
+  if (!Array.isArray(collisions) || collisions.length > 1200) return null;
+  if (!Array.isArray(dependencies) || dependencies.length > 1200) return null;
+  if (!dependencies.length && !collisions.length) return agents;
+  const owner = new Map();
+  for (const [i, group] of agents.entries()) {
+    for (const id of group.taskIds) {
+      if (owner.has(id)) return null;
+      owner.set(id, i);
+    }
+  }
+  const parents = agents.map((_, i) => i);
+  const root = (i) => {
+    while (parents[i] !== i) i = parents[i];
+    return i;
+  };
+  const needs = new Map();
+  for (const edge of dependencies) {
+    if (!edge || !owner.has(edge.taskId) || !Array.isArray(edge.requires) || edge.requires.length > 60) return null;
+    for (const id of edge.requires) {
+      if (!owner.has(id) || id === edge.taskId) return null;
+      const a = root(owner.get(edge.taskId));
+      const b = root(owner.get(id));
+      parents[Math.max(a, b)] = Math.min(a, b);
+      if (!needs.has(edge.taskId)) needs.set(edge.taskId, new Set());
+      needs.get(edge.taskId).add(id);
+    }
+  }
+  for (const collision of collisions) {
+    if (!collision || !Array.isArray(collision.taskIds) || new Set(collision.taskIds).size < 2 || collision.taskIds.length > 60) return null;
+    for (const id of collision.taskIds) {
+      if (!owner.has(id)) return null;
+      const a = root(owner.get(collision.taskIds[0]));
+      const b = root(owner.get(id));
+      parents[Math.max(a, b)] = Math.min(a, b);
+    }
+  }
+  const groups = new Map();
+  for (const [i, group] of agents.entries()) {
+    const key = root(i);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(group);
+  }
+  const result = [];
+  for (const members of groups.values()) {
+    const attached = [...new Set(members.map((g) => g.intoAgentId).filter(Boolean))];
+    if (attached.length > 1) return null;
+    const pending = members.flatMap((g) => g.taskIds);
+    if (pending.length > 60) return null;
+    const taskIds = [];
+    // Stable topological order: unrelated cards keep their proposed order.
+    while (pending.length) {
+      const at = pending.findIndex((id) => [...(needs.get(id) ?? [])].every((need) => taskIds.includes(need)));
+      if (at < 0) return null; // a cycle cannot become a runnable proposal
+      taskIds.push(...pending.splice(at, 1));
+    }
+    const budget = members.reduce((sum, g) => sum + (g.pointsBudget ?? 0), 0);
+    result.push({ ...members[0], taskIds,
+      ...(members.some(g => g.rationale) ? { rationale: members.map(g => g.rationale).filter(Boolean).join('\n').slice(0, 1000) } : {}),
+      ...(budget ? { pointsBudget: Math.min(budget, 100_000) } : {}),
+      ...(attached.length ? { intoAgentId: attached[0] } : {}),
+    });
+  }
+  return result;
+}

package/bin/lib/postureTools.mjs

@@ -0,0 +1,85 @@
+/** Per-turn readout of mounted tools and remaining permission boundaries.
+ * Kind selects the delivery contract; CLI/configuration and the filesystem
+ * fence determine supporting capabilities. Keep these claims beside the
+ * actual builders and the spawned-lane tests in artifactProjectMcp.test.mjs.
+ */
+
+/** What the machine's own MCP servers are, per CLI. */
+const MACHINE = {
+  claude: 'the MCP servers and claude.ai connectors this machine’s Claude Code has (its user and local servers)',
+  codex: 'the MCP servers in this machine’s Codex config',
+};
+
+/** Per posture and CLI: what the card has and what it lacks. */
+const POSTURES = {
+  research: {
+    claude: {
+      has: 'the repository’s files (never .env files), the project’s knowledge library, web search and web fetch, and writing under .flowviant/artifacts/ and the granted scratch directory',
+      lacks: 'no measured native image-generation tool, no delegation, guarded read commands only (no helper scripts or browsers), and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
+    },
+    codex: {
+      has: 'a sandboxed shell over an isolated copy of the repository (no .env, credential or git files, and no network from the shell), web search, and writing under .flowviant/artifacts/ and the granted scratch directory',
+      lacks: 'no host files outside that copy except native generated images; native image generation depends on this CLI and account',
+    },
+  },
+  design: {
+    claude: {
+      has: 'the repository’s files (never .env files), the project’s knowledge library, guarded read commands, web search and web fetch, and writing under .flowviant/artifacts/ and the granted scratch directory',
+      lacks: 'no measured native image-generation tool, no delegation, no helper scripts or browsers, and no plugins from this machine’s Claude Code (nor the MCP servers a plugin brings)',
+    },
+    codex: {
+      has: 'a sandboxed shell that reads the repository and writes only under .flowviant/artifacts/, with no shell network, scratch writes, and native image generation when this CLI and account expose it',
+      lacks: 'no native web on this broad-read fence (host credentials are readable); use a configured project web MCP server when available',
+    },
+  },
+  image: {
+    codex: {
+      has: 'a sandboxed shell that reads the repository and writes only under .flowviant/artifacts/, with no shell network, scratch writes, and native image generation when this CLI and account expose it',
+      lacks: 'no web',
+    },
+  },
+};
+
+/** Configuration supplies tools; a skill supplies instructions, not a tool. */
+const SUPPORTING_CAPABILITIES = `The kind defines the delivered product, not which supporting capabilities
+may be used. Use available tools needed for the person's request, including
+native image generation for requested textures or illustrations. A listed skill
+is not proof that its tool is installed, mounted or entitled on this account.
+Do not re-file the kind or require a separate image card just to use a tool.
+If a needed tool is absent or fails, relay the measured limitation and ask for
+the missing configuration or a decision. A separately billed CLI/API fallback
+requires the person's explicit choice first; never default to OPENAI_API_KEY.
+Use personal connectors only for the requested work; sending messages or other
+external writes requires explicit authorization. Never open the person's browser
+or desktop; headless inspection must stay within the granted filesystem fence.
+Delegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.`;
+
+const list = (names) => names.join(', ');
+
+/**
+ * The note for a turn, or '' when its posture withholds nothing to say.
+ * `mounted` is the names of the base `.mcp.json` servers this turn mounted;
+ * `machine` whether the machine's own servers were mounted beside them (a
+ * Claude turn whose `.mcp.json` walk could not be bounded mounts the base copy
+ * alone); `unmounted` is `[{ name, reason, source }]` for the servers it
+ * could not mount — `source` 'project' (the base `.mcp.json`) or 'machine'.
+ */
+export function postureToolsNote({ posture, runtime, mounted = [], machine = true, unmounted = [] }) {
+  const row = POSTURES[posture]?.[runtime];
+  if (!row) return posture === 'build' ? `TOOLS ON THIS CARD. Use the tools actually exposed by this CLI and its configuration. ${SUPPORTING_CAPABILITIES.replace('Delegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.', 'Delegate only when the person explicitly requests it.')} ` : '';
+  const fromProject = unmounted.filter((u) => u.source !== 'machine');
+  const fromMachine = unmounted.filter((u) => u.source === 'machine');
+  const project = mounted.length
+    ? `The project’s MCP servers from the base branch’s .mcp.json are mounted: ${list(mounted)}.`
+    : fromProject.length
+      ? 'None of the project’s MCP servers is mounted on this machine.'
+      : 'The base branch’s .mcp.json lists no MCP server.';
+  const own = machine
+    ? ` So are ${MACHINE[runtime]}.`
+    : ` ${MACHINE[runtime][0].toUpperCase()}${MACHINE[runtime].slice(1)} are not mounted on this turn.`;
+  const missing = (rows, where) => (rows.length ? ` ${where}, but not mounted here: ${list(rows.map(({ name, reason }) => `${name} (${reason})`))}.` : '');
+  return `TOOLS ON THIS CARD. You have ${row.has}. You have ${row.lacks}. ${project}${own}${missing(fromProject, 'Listed in the base branch’s .mcp.json')}${missing(fromMachine, `In ${MACHINE[runtime]}`)} A server added to .mcp.json only in this worktree is not mounted; the base branch’s file is the one that counts.
+There is no Flowviant setting that adds a tool, so never invent one. A missing
+server can be configured in the base branch's .mcp.json or the machine's CLI.
+${SUPPORTING_CAPABILITIES}`;
+}