flowviant 0.96.0 → 0.99.0

package/bin/lib/fleet.mjs

@@ -34,11 +34,15 @@ import {
   LIVE,
   AUTO_UPDATE,
   CREDENTIAL,
+  learnProjectId,
+  storedCredentialInUse,
 } from './config.mjs';
-import { projectLabel, setStoredProjectName } from './credentials.mjs';
+import { projectLabel, safeName, setStoredProjectName } from './credentials.mjs';
+import { credentialRejected } from './authReject.mjs';
 import { handleVersionSignal } from './update.mjs';
 import {
   git,
+  gitNetAsync,
   resetWorktree,
   repoRootOrDie,
   detectBaseRef,
@@ -73,9 +77,11 @@ import { processDeployJobs, reportDeployConfig } from './deploy.mjs';
 import { machineSnapshot } from './resources.mjs';
 import {
   detectRuntimes,
+  knownMcpServers,
   knownSkills,
   pickRuntimeFor,
   probeSkillsOnce,
+  recordMcpServers,
   recordSkills,
   RUNTIMES,
   THINK_MARKER,
@@ -86,6 +92,8 @@ import { effectiveMaxTurns, setServerMaxTurns } from './admission.mjs';
 import { scanLocalSessions, ourConversationIds } from './localSessions.mjs';
 import { repoState } from './repoState.mjs';
 import { claudeAuthContext } from './claudeAuth.mjs';
+import { readBaseTools, runnerToolCapabilities, toolReadout } from './projectTools.mjs';
+import { runtimeOfferings } from './runtimeOfferings.mjs';
 
 /** Said once per process — see the catch around `envQueryParams` below. */
 let warnedEnvIdentity = false;
@@ -161,7 +169,8 @@ async function fetchRoster(
    *  rather than re-derived: `repoRootOrDie` is resolved once at startup and
    *  running git on every poll to re-learn a constant would be a syscall for
    *  a readout. */
-  repoRoot = null
+  repoRoot = null,
+  baseRef = null
 ) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
@@ -283,6 +292,34 @@ async function fetchRoster(
   } catch {
     /* best-effort — the poll must never fail on a readout */
   }
+  // WHICH MCP SERVERS AND CONNECTORS THE CLI MOUNTED, AND HOW EACH STANDS
+  // (0.97.0) — `[{n, s}]`, learned off the same init event as the skills, this
+  // daemon's own `flowviant` server excluded AND every `connected` one with it:
+  // only what needs something leaves the box (runtimes.mjs, recordMcpServers —
+  // a teammate has no business reading which services the operator signed
+  // into). The same three states: NOT SENT
+  // until a turn (or the one probe) has taught us, `[]` sent as the fact it is.
+  // The app names every server that is not connected — a connector that needs
+  // a sign-in AT THIS BOX above all — under the serving machine's row. A
+  // daemon→server report: an older server ignores the unknown param.
+  try {
+    const mcp = knownMcpServers();
+    if (mcp !== null) url.searchParams.set('mcp', JSON.stringify(mcp));
+  } catch {
+    /* best-effort — the poll must never fail on a readout */
+  }
+  if (repoRoot && baseRef) {
+    try {
+      const offerings = detectRuntimes().some((rt) => rt.id === 'codex' && rt.installed)
+        ? runtimeOfferings(repoRoot, baseRef) : {};
+      for (const [param, report] of Object.entries(offerings)) {
+        if (Object.keys(report).length) {
+          const payload = JSON.stringify(report);
+          if (payload.length <= 8_000 && url.toString().length + encodeURIComponent(payload).length <= 14_000) url.searchParams.set(param, payload);
+        }
+      }
+    } catch { /* local readouts never fail the poll */ }
+  }
   // THIS BOX'S IDENTITY — `envpub`, and since 2026-09-21 nothing else.
   //
   // It carried two more params while the secrets vault existed: `envv` (the
@@ -406,10 +443,16 @@ async function fetchRoster(
     signal: AbortSignal.timeout(30_000), // a black-holed poll must not stall the loop
   });
   if (res.status === 401 || res.status === 403) {
-    // Fleet credential revoked/expired — retrying can't recover; signal exit.
-    const e = new Error(`fleet credential rejected (${res.status})`);
-    e.auth = true;
-    throw e;
+    // Revoked or expired — retrying can't recover, so signal exit. But ONLY on
+    // the API's own refusal: an edge 403 (Cloudflare's bot checks, which this
+    // very client class trips) is a retryable failure, and exiting on one took
+    // a machine offline for good over a credential that was still valid.
+    if (await credentialRejected(res)) {
+      const e = new Error(`fleet credential rejected (${res.status})`);
+      e.auth = true;
+      throw e;
+    }
+    throw new Error(`fleet poll refused by something in front of the API (${res.status})`);
   }
   if (!res.ok) throw new Error(`fleet poll failed (${res.status})`);
   // THE ASK IS SPENT HERE AND NOWHERE ELSE — on a poll the server actually
@@ -743,6 +786,36 @@ export async function maybeReportEnv(repoRoot) {
   }
 }
 
+const TOOLS_REPORT_URL = FLEET_URL.replace(/\/agents\/?$/, '/tools-report');
+let toolsReportSent = null;
+let toolsReportUnsupported = false;
+let toolsReportAt = 0;
+/** Repo tool readiness is a per-box daemon report. Never include env values. */
+export async function maybeReportTools(repoRoot, baseRef) {
+  if (Date.now() - toolsReportAt < 60_000) return;
+  toolsReportAt = Date.now();
+  if (toolsReportUnsupported) return;
+  const pubkey = myPubB64();
+  if (!pubkey) return;
+  let payload;
+  try {
+    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';
+    payload = JSON.stringify({ pubkey, tools: toolReadout(snapshot, runner) });
+  } catch { return; }
+  if (payload === toolsReportSent) return;
+  try {
+    const res = await fetch(TOOLS_REPORT_URL, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${FLEET_TOKEN}`, 'User-Agent': USER_AGENT, 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(15_000), body: payload,
+    });
+    if (envReportIsPermanent(res.status)) toolsReportUnsupported = true;
+    toolsReportSent = res.ok ? payload : null;
+  } catch { toolsReportSent = null; }
+}
+
 /**
  * A STOP COMMANDED BY FLOWVIANT, read off the roster poll.
  *
@@ -873,10 +946,9 @@ export function createHolderWatch({ say = () => {} } = {}) {
         const took = holder.took;
         if (took && typeof took === 'object' && !Array.isArray(took)) {
           standbyKey = null;
-          const from =
-            typeof took.from === 'string' && took.from.trim()
-              ? took.from.trim().slice(0, 64)
-              : 'another machine';
+          // scrubbed before it reaches a terminal (2026-09-24, the audit) —
+          // see printable.mjs.
+          const from = safeName(took.from)?.slice(0, 64) ?? 'another machine';
           const turns = Number.isInteger(took.turns) && took.turns > 0 ? took.turns : null;
           say(
             `took this project's machine from ${from}` +
@@ -895,10 +967,9 @@ export function createHolderWatch({ say = () => {} } = {}) {
       // The NAME is all the response carries about the other box, so it is also
       // the only thing "a distinct holder" can be keyed on. An unnamed holder
       // keys on the empty string, which is stable — one announcement, not one
-      // per poll.
-      const name = typeof holder.name === 'string' && holder.name.trim()
-        ? holder.name.trim().slice(0, 64)
-        : null;
+      // per poll. Scrubbed before it reaches a terminal (2026-09-24, the
+      // audit) — see printable.mjs.
+      const name = safeName(holder.name)?.slice(0, 64) ?? null;
       const key = name ?? '';
       if (key !== standbyKey) {
         standbyKey = key;
@@ -962,9 +1033,10 @@ export function createHolderWatch({ say = () => {} } = {}) {
 
 /** The sentence an in-flight agent turn is settled with when the machine moves
  *  out from under it. MEASURED, not inferred: the server named the box that
- *  took over, and an unnamed one says so rather than guessing. */
+ *  took over, and an unnamed one says so rather than guessing. Scrubbed
+ *  before it is relayed anywhere (2026-09-24, the audit) — see printable.mjs. */
 export function displacedTurnSentence(by) {
-  const name = typeof by === 'string' && by.trim() ? by.trim().slice(0, 64) : 'another machine';
+  const name = safeName(by)?.slice(0, 64) ?? 'another machine';
   return `The project's machine moved to ${name} while this turn was running.`;
 }
 
@@ -1030,7 +1102,9 @@ export async function standDownDisplaced({
         t.unref?.();
       }),
     ]);
-  const name = typeof by === 'string' && by.trim() ? by.trim().slice(0, 64) : null;
+  // Scrubbed before it reaches this box's own console (2026-09-24, the
+  // audit) — see printable.mjs.
+  const name = safeName(by)?.slice(0, 64) ?? null;
   /**
    * TWO KINDS, ONE CHOREOGRAPHY (2026-09-21).
    *
@@ -1046,8 +1120,7 @@ export async function standDownDisplaced({
    * drift and neither call site can invent a third.
    */
   const removed = kind === 'removed';
-  const projectName =
-    typeof project === 'string' && project.trim() ? project.trim().slice(0, 64) : 'this project';
+  const projectName = safeName(project)?.slice(0, 64) ?? 'this project';
   log.warn(
     removed
       ? `removed from ${projectName} in the app — stopping.`
@@ -1086,7 +1159,7 @@ export async function standDownDisplaced({
 // One roster agent's loop: persistent worktree, one intent per turn, reset to
 // base between tasks (fresh conversation), resume in place while on a blocker.
 
-export async function runFleetDaemon() {
+export async function runFleetDaemon({ afterLock = null } = {}) {
   console.log('');
   console.log(`  ${c.bold(c.cyan('◣ flowviant'))}  ${c.dim(`machine daemon · v${VERSION}`)}`);
   console.log(`  ${c.dim('──────────────────────────────────────────────')}`);
@@ -1127,7 +1200,7 @@ export async function runFleetDaemon() {
   // about to serve" must not require a network round trip to answer. Only when
   // the credential came from the STORE: a --fleet/env token names no project
   // until the roster does.
-  if (CREDENTIAL?.entry) {
+  if (CREDENTIAL?.entry && storedCredentialInUse()) {
     info(`serves · ${projectLabel(CREDENTIAL.entry)} ${c.dim(`(${CREDENTIAL.entry.projectId.slice(0, 8)}…)`)}`);
   }
   info(`repo   · ${repoRoot}`);
@@ -1196,6 +1269,16 @@ export async function runFleetDaemon() {
   }
   if (instance.unguarded)
     warn('could not take the single-instance lock (unwritable ~/.flowviant) — running unguarded');
+  // The repo binding the start path's picker or confirm was answered with.
+  // Persisted HERE, after the lock, so a refused start moves nothing: moving it
+  // first stranded the daemon already serving that project's own checkout at
+  // its next unattended restart. Best-effort — an unwritable store costs the
+  // next start a question, never this one its machine.
+  try {
+    afterLock?.();
+  } catch {
+    /* the binding is asked again next time */
+  }
 
   await preflight({ needGit: true });
 
@@ -1718,10 +1801,11 @@ export async function runFleetDaemon() {
           } else if (job.branch && isValidBranch(job.branch, repoRoot, baseRef)) {
             try {
               // Explicit refspec form so a leading '-' can't be a git flag.
-              execFileSync('git', ['push', 'origin', `:refs/heads/${job.branch}`], {
-                cwd: repoRoot,
-                stdio: ['ignore', 'pipe', 'pipe'],
-              });
+              // NETWORK call, so timed and non-interactive (2026-09-24, the
+              // audit): a bare execFileSync here had no timeout and could
+              // prompt on /dev/tty, freezing every poll and lease on the
+              // machine behind this cleanup's own async loop.
+              await gitNetAsync(['push', 'origin', `:refs/heads/${job.branch}`], repoRoot);
             } catch {
               /* branch already gone — fine */
             }
@@ -2120,7 +2204,10 @@ export async function runFleetDaemon() {
               // only thing missing was the handler. The wiki turn runs in a
               // detached worktree of THIS repo, so its `.claude/skills` and the
               // machine's personal ones resolve identically to a tab's.
-              onInit: (i) => recordSkills(i.skills),
+              onInit: (i) => {
+                recordSkills(i.skills);
+                recordMcpServers(i.mcpServers);
+              },
               onSpawn: (ch) => {
                 wikiChild = ch;
               },
@@ -2169,7 +2256,10 @@ export async function runFleetDaemon() {
                 streamJson: true,
                 onActivity,
                 // Same free harvest as the sweep above.
-                onInit: (i) => recordSkills(i.skills),
+                onInit: (i) => {
+                  recordSkills(i.skills);
+                  recordMcpServers(i.mcpServers);
+                },
                 onSpawn: (ch) => {
                   wikiChild = ch;
                 },
@@ -2312,7 +2402,8 @@ export async function runFleetDaemon() {
         livePreviewIds(),
         heldSessionIds(),
         admit('churn'),
-        repoRoot
+        repoRoot,
+        getBaseRef()
       );
     } catch (e) {
       if (e.auth) {
@@ -2337,7 +2428,7 @@ export async function runFleetDaemon() {
       // you're viewing project B's wiki) is obvious instead of a silent no-op.
       if (roster.project) {
         note(
-          `${c.cyan('project')} · ${c.bold(roster.project.name)} ${c.dim(`(${roster.project.id})`)}`
+          `${c.cyan('project')} · ${c.bold(projectLabel({ name: roster.project.name, projectId: roster.project.id }))} ${c.dim(`(${safeName(roster.project.id) ?? ''})`)}`
         );
         note(c.dim('  wiki + agents stream to THIS project — view its Code canvas in Flowviant.'));
         // Remember the NAME beside the stored credential, so the picker and
@@ -2392,6 +2483,9 @@ export async function runFleetDaemon() {
      */
     setServerMaxTurns(roster.maxTurns);
     if (roster.project?.id) wikiProjectId = roster.project.id; // keys the vault dir
+    // The server's word on which project this token serves — settles the env
+    // report's salt for a token that came from --fleet or the environment.
+    learnProjectId(roster.project?.id);
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
     // A COMMANDED STOP OUTRANKS AN UPDATE, and that ordering is the whole reason
     // this sits ABOVE the version signal rather than inside it. Both read the
@@ -2486,7 +2580,7 @@ export async function runFleetDaemon() {
         // The project's NAME rather than the box that took over, because no box
         // took over. Falls back to "this project" inside — an unnamed project
         // says so rather than being guessed at.
-        project: roster.standDown.project ?? roster.project?.name,
+        project: safeName(roster.standDown.project) ?? safeName(roster.project?.name) ?? undefined,
         settleAgentTurns,
         flushReports: flushWorkReports,
         teardown,
@@ -2698,6 +2792,7 @@ export async function runFleetDaemon() {
     // throttled and deduped inside, and silent forever on an older server.
     // This is what replaced the vault's sync tick — see `maybeReportEnv`.
     void maybeReportEnv(repoRoot);
+    void maybeReportTools(repoRoot, getBaseRef());
 
     // Tell the app what this machine is doing with itself. Every reconcile,
     // best-effort, and never awaited — telemetry that can delay a dispatch is

package/bin/lib/git.mjs

@@ -1,6 +1,6 @@
 /** Git worktree helpers (fleet & static-fleet modes). */
 
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
@@ -8,6 +8,134 @@ export function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
+/**
+ * THE SSH COMMAND A NETWORK GIT CALL RUNS UNDER when the operator has not named
+ * one. `BatchMode` turns a passphrase or host-key prompt on /dev/tty into an
+ * immediate failure; the keepalive pair ends a half-open connection (a laptop
+ * that slept, a Wi-Fi change) in ~30s instead of when the kernel gives up hours
+ * later. An agent key still works — BatchMode disables prompts, not keys.
+ */
+export const NET_SSH_COMMAND =
+  'ssh -o BatchMode=yes -o ConnectTimeout=20 -o ServerAliveInterval=15 -o ServerAliveCountMax=2';
+
+/** The default bound on one network git call. */
+export const GIT_NET_TIMEOUT_MS = 60_000;
+
+/**
+ * The environment a NETWORK git call runs under — never interactive.
+ *
+ * `GIT_TERMINAL_PROMPT=0` makes git fail instead of opening /dev/tty for a
+ * username (an HTTPS remote whose credential cache expired), and
+ * `GCM_INTERACTIVE=never` says the same to Git Credential Manager. The SSH
+ * command is set only when the operator has not chosen one — `GIT_SSH_COMMAND`,
+ * `GIT_SSH` or `core.sshCommand` — because the env var OUTRANKS the config key,
+ * and overriding somebody's `-i ~/.ssh/deploy_key` would break every fetch to
+ * make it non-interactive. Their own command is still bounded by the timeout.
+ */
+export function gitNetEnv(cwd, env = process.env) {
+  const out = { ...env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' };
+  if (env.GIT_SSH_COMMAND || env.GIT_SSH) return out;
+  let configured = '';
+  try {
+    configured = execFileSync('git', ['config', '--get', 'core.sshCommand'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5_000,
+    }).trim();
+  } catch {
+    /* unset (exit 1) or unreadable — ours, then */
+  }
+  if (!configured) out.GIT_SSH_COMMAND = NET_SSH_COMMAND;
+  return out;
+}
+
+/**
+ * A NETWORK git call (fetch, push), TIMED AND NON-INTERACTIVE.
+ *
+ * `git()` above is `execFileSync` with no timeout: right for a local
+ * `rev-parse`, and a daemon-wide freeze for a `fetch` — the call blocks the
+ * whole event loop, so a remote that prompts on /dev/tty or a connection that
+ * went half-open stops every poll, settle, lease renewal and relay on the
+ * machine until it returns. Every call that talks to a remote goes through
+ * here. Returns the untrimmed stdout; throws like `git()` does (a timeout
+ * throws with `code: 'ETIMEDOUT'`).
+ */
+export function gitNet(args, cwd, ms = GIT_NET_TIMEOUT_MS) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: ms,
+    killSignal: 'SIGKILL',
+    env: gitNetEnv(cwd),
+  });
+}
+
+/**
+ * The same call WITHOUT BLOCKING — for the unattended periodic fetch, where
+ * even a bounded freeze every few minutes is a daemon that goes dark for a
+ * remote's bad day. Spawned as its own process group so a timeout takes the
+ * ssh or credential helper under git with it. Resolves stdout; rejects on a
+ * non-zero exit, a spawn error or the timeout.
+ */
+export function gitNetAsync(args, cwd, ms = GIT_NET_TIMEOUT_MS) {
+  return new Promise((resolvePromise, reject) => {
+    let child;
+    try {
+      child = spawn('git', args, {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: gitNetEnv(cwd),
+        detached: true,
+      });
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    let out = '';
+    let err = '';
+    let settled = false;
+    const finish = (fn, v) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn(v);
+    };
+    const timer = setTimeout(() => {
+      try {
+        process.kill(-child.pid, 'SIGKILL');
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* already gone */
+        }
+      }
+      const e = new Error(`git ${args[0]} timed out after ${ms}ms`);
+      e.code = 'ETIMEDOUT';
+      finish(reject, e);
+    }, ms);
+    timer.unref?.();
+    child.stdout.on('data', (d) => {
+      out += d;
+    });
+    child.stderr.on('data', (d) => {
+      err += d;
+    });
+    child.on('error', (e) => finish(reject, e));
+    child.on('close', (code) => {
+      if (code === 0) finish(resolvePromise, out);
+      else {
+        const e = new Error(`git ${args[0]} exited ${code}`);
+        e.stderr = err;
+        e.status = code;
+        finish(reject, e);
+      }
+    });
+  });
+}
+
 /**
  * Same call, UNTRIMMED — for `-z` (NUL-separated) output, where trimming would
  * eat the final separator and the leading space of a status code.
@@ -143,9 +271,9 @@ export function baseBranchName(baseRef) {
 
 export function resetWorktree(wt, baseRef) {
   try {
-    git(['fetch', 'origin', '--quiet'], wt);
+    gitNet(['fetch', 'origin', '--quiet'], wt);
   } catch {
-    /* offline / no remote — reset to whatever we have */
+    /* offline / no remote / timed out — reset to whatever we have */
   }
   try {
     git(['checkout', '--detach', baseRef], wt);

package/bin/lib/hooks/readGuard.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * THE READ GUARD (2026-09-23, 0.97.0) — a Claude Code `PreToolUse` hook that
+ * refuses a Bash command able to WRITE A FILE OR RUN A PROGRAM, attached to
+ * every curated posture (consult, plan, wiki, design, research) and never to
+ * the build posture, whose `--dangerously-skip-permissions` is the operator's
+ * own choice.
+ *
+ * WHY A HOOK AND NOT A NARROWER LIST. `--allowedTools 'Bash(git log:*)'` is a
+ * PREFIX match: it says which program may start, never what its arguments may
+ * do. And the "read-only" git readers carry arguments that are writes or
+ * executions in disguise — `--output=<path>` (log, show and diff write their
+ * output to any file you name), `--ext-diff` and `--textconv` (run a
+ * configured program), `-c core.fsmonitor=…` / `--config-env` (run one named
+ * inline), `-O<pager>`, `--exec-path`, `--git-dir` / `--work-tree` (point git
+ * at a planted repository whose config does the above). A reviewer proved it:
+ * `git log -1 --format='tformat:x' --output=pwned.txt` landed under
+ * RESEARCH_PERM with `permission_denials: []`. Re-measured here with a
+ * friendlier phrasing — the file was written and nothing refused it. There is
+ * no permission-rule syntax for "this prefix, minus these arguments".
+ *
+ * PROBED on Claude Code 2.1.281 before relying on it, in a scratch git repo,
+ * `-p … --output-format stream-json --verbose --settings '<json>'` with the
+ * curated list beside it: the hook FIRED under `--allowedTools` (the input on
+ * stdin carried `tool_name: "Bash"` and the exact `tool_input.command`), exit 2
+ * BLOCKED the call (the file was not written; the result listed it under
+ * `permission_denials`), and the stderr sentence REACHED THE MODEL, which
+ * quoted it back. So this is a real fence, not a hint.
+ *
+ * WHAT IT REFUSES, after one normalisation: every quote and backslash is
+ * dropped before matching, because the shell splices `--out''put` and
+ * `--out\put` into `--output` and a raw substring test would read neither.
+ * Dropping them can only make a harmless command look worse, never a harmful
+ * one look better — over-refusal is the safe direction for a read-only turn.
+ *
+ *  · shell composition — `>`, `<(`, `|`, `;`, `&`, a backtick, any `$`
+ *    (command substitution, `${…}`, `$'…'` escapes, a variable that expands
+ *    into a flag), a newline. A read-only turn runs ONE plain command; every
+ *    one of these is a second command or a redirect wearing the first one's
+ *    permission.
+ *  · shell syntax that REWRITES A WORD after this guard read it — braces,
+ *    parentheses and glob characters (`{ } ( ) * ? [`). `--outp{u,u}t=x` is
+ *    `--output=x` by the time git sees it, and the substring tests below can
+ *    only judge the word as written. (Quoted or not: the normalisation above
+ *    has already dropped the quotes, so a quoted `*` is refused too — the
+ *    over-refusal the paragraph above accepts.)
+ *  · the git arguments above, as substrings (so `--config` covers
+ *    `--config-env`, `--output` covers `--output-directory`), plus a bare `-c`
+ *    token and any token beginning `-O`.
+ *  · an environment assignment — any `GIT_*=` anywhere, and any `NAME=` as the
+ *    command's first word (`GIT_DIR`, `GIT_EXTERNAL_DIFF`, `PAGER`,
+ *    `LESSOPEN` all change what a reader runs).
+ *
+ * FAILS CLOSED: input it cannot parse is refused, because a fence that opens
+ * whenever the CLI changes its hook payload is a fence that opens silently.
+ * The Read, Grep and Glob tools are untouched by it — the matcher is Bash —
+ * so a refused command always has a tool-shaped way to do the reading.
+ *
+ * OUT OF ITS REACH, stated: an operator who sets `disableAllHooks` (or a
+ * managed `allowManagedHooksOnly`) in their own settings turns this off, the
+ * 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.
+ */
+
+import { pathToFileURL } from 'node:url';
+
+/** Substrings that turn a git reader into a writer or an executor. */
+const BANNED_FLAGS = ['--output', '--ext-diff', '--textconv', '--exec-path', '--git-dir', '--work-tree', '--config'];
+
+/** Shell composition: each is a second command or a redirect. */
+const SHELL = [
+  ['>', 'a redirect'],
+  ['<(', 'process substitution'],
+  ['|', 'a pipe'],
+  [';', 'a second command'],
+  ['&', 'a second command'],
+  ['`', 'command substitution'],
+  ['$', 'an expansion'],
+  ['\n', 'a second line'],
+  ['\r', 'a second line'],
+  // SHELL SYNTAX THE SUBSTRING TESTS BELOW DO NOT MODEL (2026-09-24, the
+  // audit). The shell rewrites a word AFTER this guard has read it, so a banned
+  // flag can be ASSEMBLED past a substring check: `--outp{u,u}t=x` and
+  // `-{c,c}` brace-expand into `--output=x` and `-c`, and `git log -1
+  // --outp{u,u}t=pwned.txt` wrote the file with this guard returning null
+  // (measured, git 2.55). Globs do the same with a planted file name —
+  // `-?` expands to a file called `-c` — and zsh adds glob QUALIFIERS
+  // (`*(e:…:)`, which evaluate code). None of them is something a single
+  // plain read needs, so the guard refuses the syntax rather than trying to
+  // expand it the way some shell would: over-refusal is the safe direction,
+  // and the Glob tool is the tool-shaped way to match names.
+  ['{', 'brace expansion'],
+  ['}', 'brace expansion'],
+  ['(', 'a subshell or glob qualifier'],
+  [')', 'a subshell or glob qualifier'],
+  ['*', 'a glob'],
+  ['?', 'a glob'],
+  ['[', 'a glob'],
+];
+
+/**
+ * The reason this command is refused, or null when it may run.
+ * @param {string} command
+ */
+export function readGuardRefusal(command) {
+  if (typeof command !== 'string') return 'the command could not be read';
+  const flat = command.replace(/['"\\]/g, '');
+  for (const [op, what] of SHELL) {
+    if (flat.includes(op)) return `${what} (\`${op === '\n' || op === '\r' ? '\\n' : op}\`)`;
+  }
+  for (const f of BANNED_FLAGS) if (flat.includes(f)) return `\`${f}\``;
+  const words = flat.trim().split(/\s+/).filter(Boolean);
+  for (const w of words) {
+    if (w === '-c') return '`-c` (an inline config)';
+    if (w.startsWith('-O')) return '`-O`';
+    if (/^GIT_[A-Za-z0-9_]*=/.test(w)) return `an environment assignment (\`${w.split('=')[0]}=\`)`;
+  }
+  if (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) {
+    return `an environment assignment (\`${words[0].split('=')[0]}=\`)`;
+  }
+  return null;
+}
+
+/** 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 or run a program. ` +
+  'Run one plain read command at a time with no redirects, pipes or expansions, or use the Read, Grep and Glob tools.';
+
+function main() {
+  // 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.
+  process.on('uncaughtException', () => {
+    process.stderr.write(readGuardSentence('a command the guard could not judge'));
+    process.exit(2);
+  });
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (d) => (buf += d));
+  process.stdin.on('end', () => {
+    let payload;
+    try {
+      payload = JSON.parse(buf);
+    } catch {
+      process.stderr.write(readGuardSentence('a command the guard could not read'));
+      process.exit(2);
+    }
+    // The matcher is Bash; anything else reaching here is not ours to judge.
+    if (payload?.tool_name !== 'Bash') process.exit(0);
+    const why = readGuardRefusal(payload?.tool_input?.command);
+    if (why) {
+      process.stderr.write(readGuardSentence(why));
+      process.exit(2);
+    }
+    process.exit(0);
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();