flowviant 0.117.0 → 0.124.0

package/bin/lib/codexProjectRead.mjs

@@ -0,0 +1,63 @@
+/** Actual project files and Git history, with no host-wide read fallback.
+ * The CLI retains its provider/MCP login outside the tool sandbox. Shells
+ * receive neither that environment nor native image reads/shell snapshots.
+ */
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, dirname } from 'node:path';
+import { git } from './git.mjs';
+import { codexResearchHelper } from './codexResearch.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+
+export function projectReadBoundary({ cwd, knowledgeDir, env = process.env }) {
+  if (process.platform !== 'linux') throw new Error('Project-scoped Codex reads require Linux or WSL.');
+  if (!isAbsolute(cwd ?? '')) throw new Error('Project-scoped Codex reads require an absolute project directory.');
+  const helper = codexResearchHelper(env);
+  const version = execFileSync(helper, ['--version'], { encoding: 'utf8', timeout: 10000, env: unattendedEnv(env) }).match(/^codex-cli (\d+)\.(\d+)\.(\d+)/);
+  if (!version || version.slice(1).map(Number).reduce((n, v) => n * 1000 + v, 0) < 159002)
+    throw new Error('Project-scoped reads need Codex CLI 0.159.2 or newer. Update Codex before retrying.');
+  const project = realpathSync(cwd);
+  // Resolve both: linked worktrees have their own HEAD/index and shared
+  // objects/refs in the common directory. Never grant the parent checkout.
+  const gitOpts = { timeout: 10000, env: { PATH: env.PATH, HOME: '/nonexistent', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' } };
+  const local = realpathSync(git(['rev-parse', '--absolute-git-dir'], project, gitOpts));
+  const common = realpathSync(git(['rev-parse', '--path-format=absolute', '--git-common-dir'], project, gitOpts));
+  const paths = [project, local, common];
+  // Git directories also hold daemon login/thread/browser stores. They are
+  // not history. Mask non-Git directories, including other worktree stores.
+  const metadata = new Set(['HEAD', 'index', 'commondir', 'gitdir', 'config', 'config.worktree', 'objects', 'refs', 'logs', 'packed-refs', 'shallow', 'description', 'info', 'branches']);
+  const denied = [];
+  for (const dir of new Set([local, common])) {
+    for (const name of readdirSync(dir)) {
+      if (dir === common && name === 'worktrees' && local !== common) {
+        for (const sibling of readdirSync(join(common, name))) {
+          const path = join(common, name, sibling);
+          if (path !== local && path !== dirname(local)) denied.push(path);
+        }
+      } else if (!metadata.has(name) && lstatSync(join(dir, name)).isDirectory()) denied.push(join(dir, name));
+    }
+  }
+  if (knowledgeDir) paths.push(realpathSync(knowledgeDir));
+  return { paths: [...new Set(paths)], denied, helper };
+}
+
+export function projectReadFence({ paths, denied = [], helper }) {
+  const rules = { ':root': 'deny', ':minimal': 'read', [helper]: 'read' };
+  for (const path of paths) {
+    if (!isAbsolute(path) || path === '/') throw new Error('Invalid project read boundary.');
+    rules[path] = 'read';
+  }
+  for (const path of denied) rules[path] = 'deny';
+  const table = '{' + Object.entries(rules).map(([path, access]) => `${JSON.stringify(path)}=${JSON.stringify(access)}`).join(',') + '}';
+  return [
+    '-c', `permissions.flowviantproject.filesystem=${table}`,
+    '-c', 'permissions.flowviantproject.network.enabled=false',
+    '-c', 'default_permissions="flowviantproject"',
+    '-c', 'approval_policy="never"',
+    '-c', 'project_doc_max_bytes=0',
+    '-c', 'features.shell_snapshot=false', '-c', 'allow_login_shell=false',
+    '-c', 'shell_environment_policy.inherit="none"',
+    '-c', 'shell_environment_policy.set={PATH="/usr/bin:/bin",HOME="/nonexistent",GIT_CONFIG_NOSYSTEM="1",GIT_CONFIG_GLOBAL="/dev/null",GIT_PAGER="cat",BROWSER="none"}',
+    '--disable', 'view_image',
+  ];
+}

package/bin/lib/codexResearch.mjs

@@ -4,6 +4,7 @@
  * Web search is a CLI tool, not direct shell network access.
  */
 import { execFileSync } from 'node:child_process';
+import { codexHome } from './codexHome.mjs';
 import { git } from './git.mjs';
 import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
 import { closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -77,12 +78,16 @@ export function codexResearchHelper(env = process.env) {
  * in the shared fenced tail (sub-agents, browser, image generation, the
  * person's config and rules), with the web left on: it is this posture's tool.
  */
-export function researchFence({ cwd, helper }) {
+export function researchFence({ cwd, helper, generatedImages }) {
   if (process.platform !== 'linux' || !isAbsolute(cwd ?? '') || !isAbsolute(helper ?? ''))
     throw new Error('Isolated Codex research requires Linux or WSL and absolute sandbox paths.');
   const artifacts = join(cwd, '.flowviant/artifacts');
   const scratch = join(cwd, '.flowviant/tmp');
   const rules = { ':root': 'deny', ':minimal': 'read', [helper]: 'read', [cwd]: 'read', [artifacts]: 'write', [scratch]: 'write' };
+  if (generatedImages) {
+    if (!isAbsolute(generatedImages)) throw new Error('Generated image directory must be absolute.');
+    rules[generatedImages] = 'read';
+  }
   const table = '{' + Object.entries(rules).map(([path, access]) => `${JSON.stringify(path)}=${JSON.stringify(access)}`).join(',') + '}';
   return [
     '-c', `permissions.flowviantresearch.filesystem=${table}`,
@@ -93,7 +98,7 @@ export function researchFence({ cwd, helper }) {
     '-c', 'features.shell_snapshot=false', '-c', 'allow_login_shell=false',
     '-c', 'shell_environment_policy.inherit="none"',
     '-c', `shell_environment_policy.set={PATH="/usr/bin:/bin",HOME=${JSON.stringify(scratch)},TMPDIR=${JSON.stringify(scratch)},BROWSER="none"}`,
-    '--disable', 'view_image',
+    '--disable', 'view_image', // native host-file reads bypass the tool fence
     '--skip-git-repo-check',
   ];
 }
@@ -168,9 +173,17 @@ export async function runIsolatedResearch(opts, run, {
     const rewrite = (text) => typeof text === 'string'
       ? text.replaceAll(original, snapshot).replaceAll(opts.knowledgeDir || '\0', knowledge || '\0') : text;
     const intro = 'This fresh research turn uses an isolated read-only copy. Prior reports are available under .flowviant/artifacts/; previous CLI conversations are not resumed because they may contain host secrets. Git metadata, .env files, credential files, symlinks and personal CLI settings are omitted. Write the Markdown report only under .flowviant/artifacts/. Web search is available; shell networking is disabled. Use exec_command with shell=/bin/bash and login=false; personal shells are outside the fence.\n\n';
+    // Only native output pixels, never the surrounding login/config home.
+    let generatedImages;
+    if (opts.mcpEnv?.CODEX_HOME) {
+      const imageHome = realpathSync(codexHome({ ...process.env, ...opts.mcpEnv }));
+      if (!ensureRealSubdir(imageHome, 'generated_images'))
+        throw new Error('The native generated image directory is not a real directory.');
+      generatedImages = join(imageHome, 'generated_images');
+    }
     const result = await run({ ...opts, resume: false, resumeThreadId: null, resumeConversationId: null, cwd: snapshot, knowledgeDir: knowledge,
       prompt: intro + rewrite(opts.prompt), system: rewrite(opts.system),
-      researchIsolation: { cwd: snapshot, helper } });
+      researchIsolation: { cwd: snapshot, helper, generatedImages } });
     // Made, or found, real at publication too: every component checked again.
     if (!ensureRealSubdir(original, '.flowviant/artifacts'))
       throw new Error('The research artifact destination is not a real directory.');

package/bin/lib/commandSpecs.mjs

@@ -21,6 +21,12 @@
  */
 
 export const COMMANDS = [
+  {
+    name: 'maintenance', usesCheckout: false, hidden: true,
+    usage: 'flowviant maintenance <request|release> <token>',
+    summary: 'Hold new runs for a manual WSL restart; existing work finishes.',
+    group: 'manage',
+  },
   {
     name: 'start',
     usesCheckout: true,

package/bin/lib/daemonLocks.mjs

@@ -68,14 +68,16 @@ export function readLockHolder(fleetToken) {
  * neighbour in the same repo, `flowviant stop` sweeping the lot, uninstall
  * protecting the copy a live daemon runs from. An unreadable (or absent)
  * directory is not an error here, it is an empty machine. `fs` and `home` are
- * injectable for uninstall's test seams.
+ * injectable for uninstall's test seams. The manual WSL restart asks for
+ * `strict`: only a missing directory is empty; other scan failures throw.
  */
-export function listDaemonLocks({ fs = nodeFs, home = homedir() } = {}) {
+export function listDaemonLocks({ fs = nodeFs, home = homedir(), strict = false } = {}) {
   const dir = join(home, '.flowviant');
   let names;
   try {
     names = fs.readdirSync(dir);
-  } catch {
+  } catch (error) {
+    if (strict && error.code !== 'ENOENT') throw error;
     return [];
   }
   return names

package/bin/lib/desktopContract.mjs

@@ -64,6 +64,9 @@ export function desktopStatus({ entries = listStoredProjects(), runtimes = detec
         holder: liveState?.holder ?? null,
         // Measured by the daemon; null = unknown, never idle (see `busyOf`).
         busy: busyOf(liveState, nowMs),
+        maintenance: busyOf(liveState, nowMs) !== null && typeof liveState?.maintenance === 'string' ? liveState.maintenance : null,
+        maintenanceEpoch: busyOf(liveState, nowMs) !== null && typeof liveState?.maintenanceEpoch === 'string' ? liveState.maintenanceEpoch : null,
+        liveAgents: busyOf(liveState, nowMs) !== null && Number.isInteger(liveState?.liveAgents) && liveState.liveAgents >= 0 ? liveState.liveAgents : null,
         // What a standing-down daemon is finishing (`web → prod`), from its
         // lock's draining mark; null when it is not draining or unknown. A
         // daemon→desktop report field: an older tray ignores it.

package/bin/lib/discoveryContract.mjs

@@ -0,0 +1,19 @@
+/** A discovery contract for the person's CLI, never a server-side diagnosis. */
+export const REGRESSION_INVESTIGATION = `REGRESSION INVESTIGATION — for "this existed before and now is gone", restoration requests, and bugs that persist after Done:
+1. Keep the REQUESTED OUTCOME separate from a proposed cause. The runtime baseline names cwd, HEAD, execution base and dirty state; it does not prove you inspected relevant code. Reconcile differing or dirty baselines before relying on them.
+2. Before naming a cause, formula or restoration location, trace current rendering and data flow: locate the UI label/symbol, its render conditions and formatting, the calculation, its data provider, missing/loading inputs, and relevant tests. Reading tests is not running them; never claim tests passed merely because you read them. Do not run write-producing tests or builds under this read-only profile.
+3. Inspect available local Git history with supported plain readers: git log --oneline -- <relative-path>, git log -p --follow -- <relative-path>, git log -S delta -- <relative-path>, git show <commit>:<relative-path>, and relevant diffs. Compare the previous implementation with current code. Missing/shallow history or an unavailable deployed version limits the comparison; say exactly which comparison remains unverified.
+4. Explain only supported evidence. A surviving hidden display needs its render condition investigated, not an invented replacement formula. A missing input needs its provider/comparison data traced, not a claim that the display was deleted. A removed implementation needs a verified historical file/commit and a compatibility check against current code before proposing restoration.
+5. A board card marked Done is history, not proof that an implementation shipped or that the reported behavior works in the deployed version. In capture, dedupe with list_cards and list_staged; use find_cards/read_card for held or completed matches. Refine a pending/staged match in place. A recurrence after Done is new work with followUpOf, never proof of its cause. Scratch planning instead compares the supplied cards and live-agent context; it has no staging MCP.
+6. A failed read requires supported recovery before claiming repository discovery is unavailable. Preserve the actual failure and each attempted alternative; distinguish syntax refusal, permission denial, missing path/history and absent tool. Runtime outcomes are observations; model-authored path/line/commit citations and causal explanations remain separate claims. A request alone proves no successful read.
+7. In capture, still STAGE FIRST: if discovery remains unresolved, stage an investigation-first fix for the requested outcome, requiring reproduction and cause establishment before implementation. State unverified causes in assumed, explicit discovery limits and failures/attempts in the brief, and do not invent a formula or restoration path. Use optional grounding when the served staging tool advertises it; otherwise put requested outcome, observed code/history, discovery limits and recovery attempts in clearly separate description sections. Stage before asking the one remaining person-only question, and edit_staged after its answer rather than creating a twin. In scratch planning, retain that investigation-first ordering in the proposal; do not turn an unverified explanation into implementation instructions.`;
+
+export function discoveryGuide(runtime, lane) {
+  const readers = runtime === 'claude'
+    ? `Claude: scoped Read and Glob, in-workspace Grep, and approved plain shell readers (cat/head/ls/wc and git log/show/diff/rev-parse). The read guard rejects shell composition, expansions/globs and unsafe paths; quoted pipes and bracket Git paths can still be refused. Quotes/escaping do not bypass the guard. Prefer native Read/Grep/Glob after such a refusal. Replace git log -G 'delta|change' with separate plain git log -S delta and git log -S change calls. For a bracket working-tree path use native Read with the literal path; for history use a supported parent-relative Git path or a scoped commit diff and inspect the relevant entry. Never disable the guard or request unrestricted Bash.`
+    : runtime === 'codex'
+      ? `Codex: this profile uses a read-only sandbox with shell discovery such as cat, head, rg and plain Git readers; Claude's dedicated Read/Grep/Glob and read guard are not guaranteed here. Use only tools advertised this turn. No native web, subagents, browser/apps or unrestricted shell are granted. Read only the repository and explicitly supplied project knowledge.`
+      : `This runtime: use the native file/list/search readers actually advertised this turn. Shell availability is unverified and may be denied; do not claim all reading is blocked after one shell refusal. Keep the read-only profile.`;
+  return `DISCOVERY CAPABILITIES (${runtime}, ${lane}):\n${readers}\n` +
+    `Recovery order: use a cwd-relative path; use one plain reader rather than a composed command; use native Read/Grep/Glob where supported, or shell cat/head/rg where permitted; use git show <commit>:<relative-path> when a working-tree file is missing and history is available. If a utility is absent, switch to an advertised reader. Do not try to evade a secret/path denial. Re-read the actual result after each attempt. Preserve the first failure and subsequent recovery attempts, including an unresolved result; then state the remaining limit rather than asking the person to disable protections. ${lane === 'capture' ? 'Only the scoped Flowviant staging tools write records; never change repository files.' : 'Scratch planning has no Flowviant MCP; return a proposal only.'}`;
+}

package/bin/lib/fleet.mjs

@@ -36,6 +36,7 @@ import { handleVersionSignal } from './update.mjs';
 import { compareVersions } from './versionOrder.mjs';
 import { emitMachineEvent } from './daemonLogging.mjs';
 import { writeDaemonState } from './daemonState.mjs';
+import { maintenanceTick, readMaintenance } from './maintenance.mjs';
 import { repoRootOrDie, detectBaseRef, baseBranchName, excludeInWorktree, usableBaseRef } from './git.mjs';
 import { c, info, note, ok, warn, fail } from './ui.mjs';
 import { sleep } from './sleep.mjs';
@@ -56,6 +57,7 @@ import { createLeave } from './standDownExit.mjs';
 import { stopWorkLanes } from './standDownGate.mjs';
 import { markLockDraining } from './instance.mjs';
 import { reportDeployConfig } from './deployConfig.mjs';
+import { mcpInstallsInFlight, processMcpInstallJobs } from './mcpInstall.mjs';
 import { probeSkillsOnce } from './runtimeCapabilities.mjs';
 import { createWorkManager } from './work.mjs';
 import { INTAKE_ROSTER_KEY } from './workIntake.mjs';
@@ -70,6 +72,7 @@ import {
   maybeReportLocalSessions,
   maybeReportRepoState,
   maybeReportTools,
+  recheckProjectMcp,
   repoStateChanged,
   reportMachine,
 } from './fleetReports.mjs';
@@ -249,6 +252,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     flushWorkReports,
     learnPlaces,
     processWorkTurns,
+    interruptWorkTurns,
     processShipJobs,
     processDiffJobs,
     processKillJobs,
@@ -256,6 +260,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     processAgentPlanJobs,
     processIntakeJobs,
     processAgentTurnJobs,
+    interruptAgentTurns,
     processAgentMergeJobs,
     freshenManualPlaces,
     heldSessionIds,
@@ -265,9 +270,11 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     shutdownPreviews,
     retireWorkSessions,
     reportWorktrees,
+    reconcileIdleArtifacts,
     shutdownWork,
     settleAgentTurns,
     workBusy,
+    runningAgentCount,
     admit,
     liveTurns,
   } = createWorkManager({
@@ -331,9 +338,9 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
    * from the server's list of WORKING AGENTS, which cannot see a Workbench
    * turn, a ship or a deploy.
    */
-  const machineBusy = () => wiki.busy() || workBusy() || deploysInFlight() > 0;
+  const machineBusy = () => wiki.busy() || workBusy() || deploysInFlight() > 0 || mcpInstallsInFlight() > 0;
   const reportBusy = () =>
-    writeDaemonState(desktopProjectId, { busy: machineBusy(), busyAt: new Date().toISOString() });
+    writeDaemonState(desktopProjectId, { busy: machineBusy(), liveAgents: runningAgentCount(), maintenance: null, busyAt: new Date().toISOString() });
   /**
    * HOW EVERY STAND-DOWN LEAVES — after the teardown, and after any deploy in
    * flight has finished and reported (standDownExit.mjs, ruling 2026-09-26).
@@ -379,6 +386,16 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
   // share, no new deploy — only the deploys already claimed run on to their
   // report (standDownExit.mjs).
   const standingDown = () => leave.leaving();
+  let lastAgentJobs = [];
+  const reportMaintenance = (jobs = lastAgentJobs) => maintenanceTick({
+    busy: machineBusy,
+    agents: runningAgentCount,
+    flush: async () => {
+      await flushWorkReports();
+      processAgentTurnJobs(jobs, { reportsOnly: true });
+    },
+    report: (state) => writeDaemonState(desktopProjectId, state),
+  });
   for (;;) {
     if (standingDown()) return leave.drained();
     let roster;
@@ -412,7 +429,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       }
       warn(`roster poll failed: ${e.message} — retrying in ${RECONCILE_SECONDS}s`);
       // Work already running keeps running offline; the measurement keeps up.
-      reportBusy();
+      if (!await reportMaintenance()) reportBusy();
       await sleep(RECONCILE_SECONDS);
       continue;
     }
@@ -490,7 +507,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       // same one the desktop app's auto-install reads — which is how a deploy
       // in flight joined this gate (2026-09-26): re-exec'ing under one would
       // stop its heartbeat mid-run.
-      const safeToUpdate = !machineBusy();
+      const safeToUpdate = !machineBusy() && !readMaintenance();
       const updating = handleVersionSignal({
         latest: roster.daemon.latest,
         min: roster.daemon.min,
@@ -501,6 +518,19 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
       if (await updating) return;
       if (standingDown()) return leave.drained();
     }
+    // Keep polling to renew the running agents' leases and honour stops and
+    // interrupts. A paused tick admits no roster jobs, even after becoming
+    // idle; only held answers are retried until the tray releases its lease.
+    // Interrupts precede both paths so a stop arriving while paused still
+    // reaches its running CLI, and a successor sees the stop before intake.
+    interruptWorkTurns(roster.interruptTurns);
+    interruptAgentTurns(roster.interruptAgentTurns);
+    lastAgentJobs = roster.agentTurnJobs;
+    if (await reportMaintenance()) {
+      reportMachine({ worktreeDir: baseDir, liveTurns });
+      await sleep(RECONCILE_SECONDS);
+      continue;
+    }
     // Settle any turn/ship answers whose earlier report POST failed BEFORE
     // taking new work — the skip-if-pending guards make the ordering safe, but
     // delivering first keeps the tab honest a poll sooner.
@@ -594,6 +624,10 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // themselves from a browser, relayed. After retirement so a directory that
     // just went away is not reported as a place.
     reportWorktrees(roster.activeWorkSessions);
+    // …and an idle agent's delivery against what its worktree still holds:
+    // once per process, beside no turn (workArtifactReconcile.mjs). After the
+    // turn intake above, so a card about to run in a place is not raced.
+    void reconcileIdleArtifacts(roster.activeWorkSessions)?.catch(() => {});
     // Terminal-session presence, throttled + dedup'd inside; never awaited —
     // the daemon's own worktrees are carved out (a session the daemon spawned
     // is already a tab, not something to offer adopting).
@@ -657,6 +691,14 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // This is what replaced the vault's sync tick — see `maybeReportEnv`.
     void maybeReportEnv(repoRoot);
     void maybeReportTools(repoRoot, getBaseRef());
+    // INSTALLS AN OWNER CONFIRMED FOR THIS BOX (mcpInstall.mjs) — handed to
+    // the picked box whether it holds the machine or stands by; each is
+    // claimed, run exactly as confirmed, and followed by a re-check.
+    processMcpInstallJobs(roster.mcpInstallJobs, {
+      repoRoot,
+      myPubB64,
+      recheck: () => recheckProjectMcp(repoRoot, getBaseRef()),
+    });
 
     // Tell the app what this machine is doing with itself (fleetReports.mjs).
     reportMachine({ worktreeDir: baseDir, liveTurns });

package/bin/lib/fleetReports.mjs

@@ -27,8 +27,11 @@ import { detectRuntimes } from './runtimeDetection.mjs';
 import { scanLocalSessions } from './localSessions.mjs';
 import { repoState } from './repoState.mjs';
 import { claudeAuthContext } from './claudeAuth.mjs';
-import { readBaseTools, toolReadout } from './projectTools.mjs';
+import { prepareAgentTools, readBaseTools, toolReadout } from './projectTools.mjs';
 import { runnerToolCapabilities } from './projectToolRuntimes.mjs';
+import { buildMcpInventory } from './mcpInventory.mjs';
+import { knownClaudeMcpInventory, probeMcpNow } from './runtimeCapabilities.mjs';
+import { codexMcpServers } from './runtimeOfferings.mjs';
 
 /**
  * ONE READOUT LANE (audit 2026-10-10, F087/F752). The four readouts below —
@@ -292,7 +295,15 @@ export function maybeReportEnv(repoRoot) {
 // Latches on the env lane's short list for the same reason: a 401 or a 429 is
 // a "later", and a lane that dies invisibly must not die for one.
 const toolsLane = createReportLane({ endpoint: 'tools-report', isPermanent: envReportIsPermanent });
-/** Repo tool readiness is a per-box daemon report. Never include env values. */
+/**
+ * Repo tool readiness is a per-box daemon report. Never include env values.
+ *
+ * `mcp` (2026-10-13) is this box's MCP inventory — every server each installed
+ * CLI has, by name, source and status, with a connected server's tool names
+ * (mcpInventory.mjs). It rides here rather than on the poll because tool names
+ * do not fit a URL, and this lane already posts only on change. An older
+ * server's schema strips the key.
+ */
 export function maybeReportTools(repoRoot, baseRef) {
   return toolsLane(() => {
     const pubkey = myPubB64();
@@ -300,10 +311,40 @@ export function maybeReportTools(repoRoot, baseRef) {
     const snapshot = readBaseTools(repoRoot, baseRef);
     const installed = detectRuntimes().filter((r) => r.installed);
     const runner = installed.find((r) => runnerToolCapabilities(r.id).mcp)?.id ?? installed[0]?.id ?? 'none';
-    return JSON.stringify({ pubkey, tools: toolReadout(snapshot, runner) });
+    const ids = installed.map((r) => r.id);
+    let codex = null;
+    if (ids.includes('codex')) {
+      try { codex = codexMcpServers(); } catch { /* a failed local read is unknown */ }
+    }
+    const mcp = buildMcpInventory({ installed: ids, snapshot, claude: knownClaudeMcpInventory(), codex });
+    return JSON.stringify({ pubkey, tools: toolReadout(snapshot, runner), mcp });
   });
 }
 
+/**
+ * LOOK AGAIN AT THIS BOX'S MCP SERVERS, NOW (2026-10-13) — after a confirmed
+ * install (mcpInstall.mjs). Codex's list is re-read, Claude Code is probed
+ * with the base branch's servers mounted (`probeMcpNow`), and the tool report
+ * — whose "command not on PATH" was measured before the install — is rescanned
+ * and posted without waiting for its beat. Every step is best-effort.
+ */
+export async function recheckProjectMcp(repoRoot, baseRef) {
+  try {
+    if (detectRuntimes().some((r) => r.id === 'codex' && r.installed)) codexMcpServers({ refresh: true });
+  } catch { /* unknown stays unknown */ }
+  if (detectRuntimes().some((r) => r.id === 'claude' && r.installed)) {
+    let tools = null;
+    try {
+      tools = prepareAgentTools(readBaseTools(repoRoot, baseRef), 'claude');
+      await probeMcpNow(repoRoot, tools.mcpPath);
+    } catch { /* no base read, or no claude: the next turn teaches it */ } finally {
+      tools?.cleanup();
+    }
+  }
+  toolsLane.rescan();
+  await maybeReportTools(repoRoot, baseRef);
+}
+
 /**
  * "THE REPO JUST CHANGED — look again." Clears the repo-state throttle so the
  * next reconcile rescans on the beat it already runs; the work manager calls

package/bin/lib/hooks/mcpAllow.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * THE MACHINE'S MCP SERVERS, ALLOWED ON A FENCED 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 write-up or mockup/3D-model/deck turn runs under an `--allowedTools` list,
+ * and an MCP tool the list does not name is refused ("Claude requested
+ * permissions to use mcp__…, but you haven't granted it yet"). The project's
+ * base servers are named by the lane; the machine's own servers and claude.ai
+ * connectors are not knowable before the CLI connects them (a connector's tools
+ * are `mcp__claude_ai_<Name>__<tool>`, from the account), and `mcp__*` is not a
+ * rule this CLI admits (measured, Claude Code 2.1.290: refused). So this
+ * `PreToolUse` hook, matched on `mcp__.*`, answers `allow` for an MCP tool call.
+ * MEASURED on 2.1.290 under the research and design lists: the project server
+ * and a claude.ai connector each answered with no per-name rule, and Bash
+ * `touch`, an outside Write and WebFetch were refused exactly as without the
+ * hook.
+ *
+ * It decides MCP calls and nothing else: any other tool, and Flowviant's own
+ * control plane (`mcp__flowviant`, never mounted on an agent turn), get no
+ * decision, and the posture's list decides. A hook that fails gives no
+ * decision either, so a broken hook leaves MCP calls refused — closed.
+ */
+import { pathToFileURL } from 'node:url';
+
+/** The decision for one PreToolUse payload, or null for "not ours". */
+export function mcpAllowDecision(payload) {
+  const name = payload?.tool_name;
+  if (typeof name !== 'string' || !name.startsWith('mcp__')) return null;
+  if (name === 'mcp__flowviant' || name.startsWith('mcp__flowviant__')) return null;
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      permissionDecisionReason: 'an MCP server this machine mounted for the card',
+    },
+  };
+}
+
+let started = false;
+export function main() {
+  if (started) return;
+  started = true;
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (d) => (buf += d));
+  process.stdin.on('end', () => {
+    let decision = null;
+    try {
+      decision = mcpAllowDecision(JSON.parse(buf));
+    } catch {
+      decision = null;
+    }
+    if (decision) process.stdout.write(JSON.stringify(decision));
+    process.exit(0);
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/bin/lib/hooks/readGuard.mjs

@@ -77,8 +77,11 @@
  * way they could turn off anything on their own box; the prefix list is still
  * the first fence and this is the second.
  *
- * Run by the CLI as `node readGuard.mjs`, the hook JSON on stdin. Imported by
- * the tests for `readGuardRefusal`, which is the whole decision.
+ * Run by the CLI as `<daemon's node> readGuard.mjs` from npm, and as
+ * `flowviant __hook read-guard` under the compiled binary (bin/cli.mjs calls
+ * `main`), the hook JSON on stdin either way (claudePosture.mjs
+ * `hookCommand`). Imported by the tests for `readGuardRefusal`, which is the
+ * whole decision.
  */
 
 import { pathToFileURL } from 'node:url';
@@ -161,9 +164,15 @@ export function readGuardRefusal(command) {
 /** The sentence the model reads when a call is refused. */
 export const readGuardSentence = (why) =>
   `flowviant: this turn is read-only, so ${why} is refused here — it can write a file, run a program or read past this turn's fence. ` +
-  'Run one plain read command at a time with no redirects, pipes or expansions, or use the Read, Grep and Glob tools.';
+  'Run one plain read command at a time with no redirects, pipes or expansions, or use the Read, Grep and Glob tools. ' +
+  'Quoted pipe/bracket syntax is still refused: try separate literal git log -S searches, native Read for the working-tree path, or a plain scoped parent-path history read. Keep the guard enabled; do not bypass secret/path denials.';
 
-function main() {
+/** Run once per process: the CLI's `__hook read-guard` (the compiled binary)
+ *  calls it, and so may the direct-run check below. */
+let started = false;
+export function main() {
+  if (started) return;
+  started = true;
   // A hook that CRASHES is not a hook that refused: Claude Code treats any
   // exit other than 2 as a non-blocking error and runs the command anyway. So
   // every way out of this process that is not a verdict is a refusal.

package/bin/lib/imageArtifact.mjs

@@ -0,0 +1,74 @@
+import { inflateSync } from 'node:zlib';
+import { buildArtifactUpload } from './artifacts.mjs';
+
+/** Read through the artifact scanner's bounded, no-follow reader. A filename
+ * alone cannot prove that generated textures are usable. */
+export function usableImageArtifact(entry) {
+  const bytes = buildArtifactUpload(entry, { agentId: 'validation' })?.bytes;
+  if (!bytes) return false;
+  if (/\.webp$/i.test(entry.name)) {
+    return bytes.length >= 20 && bytes.toString('ascii', 0, 4) === 'RIFF'
+      && bytes.toString('ascii', 8, 12) === 'WEBP'
+      && bytes.readUInt32LE(4) + 8 === bytes.length;
+  }
+  return usablePng(bytes);
+}
+
+const crc32 = (bytes) => {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+};
+
+/** PNG structure, checksums and decoded scanlines, bounded at 64 MiB. Supports
+ * all standard colour types/bit depths and Adam7; no canvas or network needed. */
+export function usablePng(bytes) {
+  try {
+    if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return false;
+    let header = null;
+    const data = [];
+    let ended = false;
+    for (let at = 8; at < bytes.length;) {
+      if (at + 12 > bytes.length) return false;
+      const size = bytes.readUInt32BE(at);
+      const end = at + 8 + size;
+      if (end + 4 > bytes.length || crc32(bytes.subarray(at + 4, end)) !== bytes.readUInt32BE(end)) return false;
+      const type = bytes.toString('ascii', at + 4, at + 8);
+      if (!header && (type !== 'IHDR' || size !== 13)) return false;
+      if (type === 'IHDR') {
+        if (header || size !== 13) return false;
+        header = bytes.subarray(at + 8, end);
+      }
+      if (type === 'IDAT') data.push(bytes.subarray(at + 8, end));
+      if (type === 'IEND') {
+        if (size !== 0 || end + 4 !== bytes.length) return false;
+        ended = true;
+      }
+      at = end + 4;
+    }
+    if (!header || !ended || !data.length) return false;
+    const width = header.readUInt32BE(0), height = header.readUInt32BE(4);
+    const depth = header[8], colour = header[9], interlace = header[12];
+    const depths = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+    if (!width || !height || !depths[colour]?.includes(depth) || header[10] || header[11] || interlace > 1) return false;
+    const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colour];
+    const passes = interlace ? [[0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2]] : [[0, 0, 1, 1]];
+    const rows = passes.map(([x, y, dx, dy]) => {
+      const w = Math.max(0, Math.ceil((width - x) / dx));
+      const h = Math.max(0, Math.ceil((height - y) / dy));
+      return { h: w ? h : 0, stride: 1 + Math.ceil(w * channels * depth / 8) };
+    });
+    const expected = rows.reduce((n, { h, stride }) => n + h * stride, 0);
+    if (expected > 64 * 1024 * 1024) return false;
+    const pixels = inflateSync(Buffer.concat(data), { maxOutputLength: expected });
+    if (pixels.length !== expected) return false;
+    let at = 0;
+    for (const { h, stride } of rows) {
+      for (let row = 0; row < h; row++, at += stride) if (pixels[at] > 4) return false;
+    }
+    return true;
+  } catch { return false; }
+}

package/bin/lib/maintenance.mjs

@@ -0,0 +1,47 @@
+/** A manual tray restart drains intake without signalling any existing run.
+ * The lease expires if the tray crashes. A daemon acknowledges only at the
+ * reconcile boundary, after all previously admitted work has been counted. */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const MAINTENANCE_LEASE_MS = 120_000;
+const pathFor = (home) => join(home, '.flowviant', 'maintenance.json');
+export function readMaintenanceRequest({ home = homedir(), now = Date.now() } = {}) {
+  try {
+    const value = JSON.parse(readFileSync(pathFor(home), 'utf8'));
+    return typeof value.token === 'string' && /^[a-zA-Z0-9-]{1,100}$/.test(value.token) && typeof value.epoch === 'string' &&
+      Number.isFinite(value.expires) && value.expires > now && value.expires <= now + MAINTENANCE_LEASE_MS
+      ? value : null;
+  } catch { return null; }
+}
+export function readMaintenance(options) { return readMaintenanceRequest(options)?.token ?? null; }
+export function requestMaintenance(token, { home = homedir(), now = Date.now() } = {}) {
+  if (typeof token !== 'string' || !/^[a-zA-Z0-9-]{1,100}$/.test(token)) throw new Error('Invalid restart request');
+  const current = readMaintenanceRequest({ home, now });
+  if (current && current.token !== token) throw new Error('Another WSL restart is pending');
+  mkdirSync(join(home, '.flowviant'), { recursive: true });
+  const path = pathFor(home);
+  const tmp = `${path}.${process.pid}.tmp`;
+  const epoch = current?.epoch ?? randomUUID();
+  writeFileSync(tmp, JSON.stringify({ token, epoch, expires: now + MAINTENANCE_LEASE_MS }), { mode: 0o600 });
+  renameSync(tmp, path);
+  return epoch;
+}
+export function releaseMaintenance(token, { home = homedir(), now = Date.now() } = {}) {
+  if (readMaintenance({ home, now }) === token) rmSync(pathFor(home), { force: true });
+}
+
+/** The paused branch does only reporting. In particular, an acknowledgement
+ * can never be copied from a pre-pause idle measurement. */
+export async function maintenanceTick({ request = readMaintenanceRequest, busy, agents, flush, report }) {
+  const lease = request();
+  if (!lease) return false;
+  await flush();
+  // A slow network flush can outlive the request. Never acknowledge an
+  // expired generation whose next reconcile is allowed to admit work again.
+  if (request()?.epoch !== lease.epoch) return true;
+  report({ maintenance: lease.token, maintenanceEpoch: lease.epoch, busy: busy(), liveAgents: agents(), busyAt: new Date().toISOString() });
+  return true;
+}