flowviant 0.115.0 → 0.117.0

package/bin/lib/hooks/readGuard.mjs

@@ -1,10 +1,10 @@
 #!/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.
+ * refuses a Bash command able to WRITE A FILE OR RUN A PROGRAM, or (2026-10-10)
+ * to READ PAST THE TURN'S FENCE, 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
@@ -50,6 +50,22 @@
  *  · 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).
+ *  · (2026-10-10, the audit) a GIT READER AIMED OFF THE CHECKOUT. The CLI
+ *    path-validates `cat`, `ls` and `head` (measured, claudePosture.mjs
+ *    CONSULT_BASH) but nobody measured git, and `git diff` reads any file on
+ *    the box: `--no-index` compares two arbitrary paths, and git switches to
+ *    it on its own when a path lies outside the work tree — `git diff
+ *    ~/.ssh/id_ed25519 /dev/null` prints the key. So `--no-index` is refused
+ *    anywhere, and for git every argument that starts with `/` or `~` or has a
+ *    `..` segment (split on `/`, `:` and `=`, so a revision range `a..b` or
+ *    `main...HEAD` still passes). `cat`/`ls`/`head` keep their absolute
+ *    paths: the wiki's vault and the knowledge library are named that way.
+ *  · (2026-10-10) THE CHECKOUT'S SECRET FILES, BY NAME, for every reader:
+ *    `.env`, `.env.<anything>`, `.dev.vars` and `.dev.vars.<anything>` — the
+ *    shell's half of the postures' `Read(./.env*)` denies, which say nothing
+ *    about `cat` — while the templates (`.example`, `.sample`, `.template`)
+ *    still read. By NAME: a secret someone committed still shows in a whole
+ *    `git show` or `git log -p`, as it would to anyone holding the repository.
  *
  * 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.
@@ -67,8 +83,15 @@
 
 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'];
+/** Substrings that turn a git reader into a writer or an executor — or, for
+ *  `--no-index` (2026-10-10), into a reader of any file on the box. */
+const BANNED_FLAGS = ['--output', '--ext-diff', '--textconv', '--exec-path', '--git-dir', '--work-tree', '--config', '--no-index'];
+
+/** A checkout secret file, and the templates beside it that still read. */
+const SECRET_FILE = /^(\.env|\.dev\.vars)(\..+)?$/;
+const SECRET_TEMPLATE = /\.(example|sample|template)$/;
+/** The pieces of one word a path could hide in: `a/b`, `HEAD:a/b`, `--x=a/b`. */
+const pathSegments = (w) => w.split(/[/:=]/);
 
 /** Shell composition: each is a second command or a redirect. */
 const SHELL = [
@@ -121,12 +144,23 @@ export function readGuardRefusal(command) {
   if (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) {
     return `an environment assignment (\`${words[0].split('=')[0]}=\`)`;
   }
+  for (const w of words) {
+    const secret = pathSegments(w).find((seg) => SECRET_FILE.test(seg) && !SECRET_TEMPLATE.test(seg));
+    if (secret) return `reading a secret file (\`${secret}\`)`;
+  }
+  if (words.length && /(^|\/)git$/.test(words[0])) {
+    for (const w of words.slice(1)) {
+      const value = w.startsWith('-') && w.includes('=') ? w.slice(w.indexOf('=') + 1) : w;
+      if (value.startsWith('/') || value.startsWith('~')) return `a path off the checkout (\`${w}\`)`;
+      if (pathSegments(w).includes('..')) return `a path that climbs out of the checkout (\`${w}\`)`;
+    }
+  }
   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. ` +
+  `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.';
 
 function main() {

package/bin/lib/install.mjs

@@ -5,18 +5,31 @@
  * silently and never clobbering an existing install. Interactive login stays
  * yours (`claude` sign-in, `flowviant gh-auth`).
  *
- * gh is dropped into ~/.flowviant/bin (like cloudflared) rather than a system
- * path, so there's nothing to conflict with; addLocalBinToPath() puts that dir
- * on PATH so the daemon (and `flowviant gh-auth`) find it.
+ * gh is dropped into ~/.flowviant/bin (like cloudflared, and pinned and
+ * checksummed like it) rather than a system path, so there's nothing to
+ * conflict with; addLocalBinToPath() puts that dir on PATH so the daemon (and
+ * `flowviant gh-auth`) find it.
  */
 
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { writeFileSync, existsSync, mkdirSync, chmodSync, rmSync, cpSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform, arch } from 'node:os';
 
 export const LOCAL_BIN = join(homedir(), '.flowviant', 'bin');
 
+/** Is `bin` on PATH and answering `--version`? BOUNDED: a broken shim that
+ *  hangs here would stall preflight — and the daemon behind it — forever. */
+export function commandPresent(bin, { timeout = 10_000, exec = execFileSync } = {}) {
+  try {
+    exec(bin, ['--version'], { stdio: 'ignore', timeout });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Put ~/.flowviant/bin first on PATH so bundled binaries (gh, cloudflared)
  *  resolve by bare name for this process and everything it spawns. Idempotent. */
 export function addLocalBinToPath() {
@@ -61,53 +74,87 @@ export function installClaude(log) {
   }
 }
 
-async function latestGhVersion() {
-  const res = await fetch('https://api.github.com/repos/cli/cli/releases/latest', {
-    headers: { 'User-Agent': 'flowviant', Accept: 'application/vnd.github+json' },
-    redirect: 'follow',
-  });
-  if (!res.ok) throw new Error(`gh release lookup failed (http ${res.status})`);
-  const tag = (await res.json())?.tag_name;
-  if (!tag) throw new Error('no gh release tag');
-  return String(tag).replace(/^v/, '');
-}
+/**
+ * gh: PINNED AND VERIFIED, LIKE CLOUDFLARED (audit 2026-10-10, F088/F110/F662).
+ * This used to ask api.github.com for `releases/latest`, untar whatever came
+ * back and chmod it — no digest, no timeout — into the directory
+ * addLocalBinToPath puts FIRST on PATH, where it then runs with the operator's
+ * GitHub login for every push and merge. preview.mjs's rule is the rule here:
+ * we only execute what we verified. Bumping this is a release act: take the
+ * digests from the release's own `gh_<version>_checksums.txt` and replace the
+ * version and every digest together.
+ */
+export const GH_VERSION = '2.102.0';
+export const GH_SHA256 = {
+  'linux-amd64': 'bb766f710eef8ede859c18578c72c327597cd4c8a85b06001b1f3843c6019386',
+  'linux-arm64': '7862c86c72f43df3a2d93ddde6f473285b4e2af61b494849846827e513ef6484',
+  'macOS-amd64': 'b245f24eb2bf5f75b426b4c26da3651a107f8d5b6f4fddfbfccc5679041378b3',
+  'macOS-arm64': 'da922c20d1792e5b2cbf375593d7a658acf034c12c84e007e71c76ef959c337e',
+  'windows-amd64': 'ae64e556ecc240b200f7eba60d550e4bb60d78e860e69dd88c449405b86067f4',
+  'windows-arm64': '5dcf12aa8525eabd0c46ec414f323ab6cf65229fc2cd46543cc705001bbaf223',
+};
 
-/** Fetch the gh release archive into ~/.flowviant/bin and extract the binary —
- *  the cloudflared pattern: isolated, no sudo, nothing to conflict with. Returns
- *  the binary path or null (falls back to manual instructions). */
-export async function installGh(log) {
-  const os = platform();
-  const a = arch() === 'arm64' ? 'arm64' : 'amd64';
+const GH_MANUAL = 'Install from https://cli.github.com, then run: gh auth login';
+
+/** Fetch the pinned gh release archive, verify it, and put the binary in
+ *  ~/.flowviant/bin — isolated, no sudo, nothing to conflict with. The digest
+ *  is checked BEFORE anything is written or extracted (an archive is code
+ *  too). Returns the binary path, or null after saying why and how to install
+ *  it by hand. `fetch`, `os`, `cpu`, `dir` and the pin are injectable for the
+ *  tests; nothing in the daemon passes them. */
+export async function installGh(
+  log,
+  {
+    fetch: fetchImpl = (...a) => fetch(...a),
+    os = platform(),
+    cpu = arch(),
+    dir = LOCAL_BIN,
+    version = GH_VERSION,
+    sha256 = GH_SHA256,
+    timeoutMs = 120_000,
+  } = {},
+) {
+  const a = cpu === 'arm64' ? 'arm64' : cpu === 'x64' ? 'amd64' : cpu;
   const osName = os === 'darwin' ? 'macOS' : os === 'win32' ? 'windows' : 'linux';
   const ext = os === 'linux' ? 'tar.gz' : 'zip';
   const binName = os === 'win32' ? 'gh.exe' : 'gh';
-  const dest = join(LOCAL_BIN, binName);
+  const dest = join(dir, binName);
+  const want = sha256[`${osName}-${a}`];
+  if (!want) {
+    log?.(`could not install gh automatically: this machine (${os}/${cpu}) has no pinned gh build to fetch. ${GH_MANUAL}`);
+    return null;
+  }
   let archive;
   let innerDir;
   try {
-    mkdirSync(LOCAL_BIN, { recursive: true });
-    const ver = await latestGhVersion();
-    const stem = `gh_${ver}_${osName}_${a}`;
-    const url = `https://github.com/cli/cli/releases/download/v${ver}/${stem}.${ext}`;
-    log?.(`fetching gh ${ver} (${osName}-${a})…`);
-    const res = await fetch(url, { redirect: 'follow' });
+    const stem = `gh_${version}_${osName}_${a}`;
+    const url = `https://github.com/cli/cli/releases/download/v${version}/${stem}.${ext}`;
+    log?.(`fetching gh ${version} (${osName}-${a})…`);
+    const res = await fetchImpl(url, { redirect: 'follow', signal: AbortSignal.timeout(timeoutMs) });
     if (!res.ok) throw new Error(`http ${res.status}`);
-    archive = join(LOCAL_BIN, `${stem}.${ext}`);
-    writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
+    const buf = Buffer.from(await res.arrayBuffer());
+    const got = createHash('sha256').update(buf).digest('hex');
+    if (got !== want) {
+      log?.(
+        `refused to install gh ${version}: the download did not match its pinned checksum (expected ${want.slice(0, 12)}…, got ${got.slice(0, 12)}…). ${GH_MANUAL}`,
+      );
+      return null;
+    }
+    mkdirSync(dir, { recursive: true });
+    archive = join(dir, `${stem}.${ext}`);
+    writeFileSync(archive, buf);
     // linux ships tar.gz (GNU tar); mac + windows ship zip (bsdtar reads zip).
-    execFileSync('tar', [os === 'linux' ? '-xzf' : '-xf', archive, '-C', LOCAL_BIN], {
+    execFileSync('tar', [os === 'linux' ? '-xzf' : '-xf', archive, '-C', dir], {
       stdio: 'ignore',
     });
-    innerDir = join(LOCAL_BIN, stem);
+    innerDir = join(dir, stem);
     const inner = join(innerDir, 'bin', binName);
     if (!existsSync(inner)) throw new Error('gh binary not found in the archive');
     cpSync(inner, dest);
     if (os !== 'win32') chmodSync(dest, 0o755);
     return dest;
   } catch (e) {
-    log?.(
-      `could not install gh automatically (${e?.message ?? e}). Install from https://cli.github.com, then run: gh auth login`,
-    );
+    log?.(`could not install gh automatically (${e?.message ?? e}). ${GH_MANUAL}`);
     return null;
   } finally {
     if (archive) rmSync(archive, { force: true });

package/bin/lib/instance.mjs

@@ -87,7 +87,6 @@ import {
   closeSync,
   mkdirSync,
   openSync,
-  readdirSync,
   readFileSync,
   renameSync,
   rmSync,
@@ -96,36 +95,25 @@ import {
 } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
-import { createHash } from 'node:crypto';
 import { VERSION, PROCESS_STARTED_AT } from './config.mjs';
 import { compareVersions } from './versionOrder.mjs';
 import { samePath } from './repoPath.mjs';
+import { instanceLockPath, listDaemonLocks, readLockFile, readLockHolder } from './daemonLocks.mjs';
+import { processAlive } from './procRegistry.mjs';
+import { procStat } from './procStat.mjs';
 
-/** Deliberately a HASH: a credential must never become a filename. */
-export function instanceLockPath(fleetToken) {
-  const key = createHash('sha256').update(String(fleetToken || 'anon')).digest('hex').slice(0, 12);
-  return join(homedir(), '.flowviant', `daemon-${key}.lock`);
-}
+// The lock file's name, record and scan live in daemonLocks.mjs (a leaf the
+// readers share, 2026-10-10 F090); re-exported so callers keep one import.
+export {
+  DAEMON_LOCK_RE,
+  instanceLockPath,
+  listDaemonLocks,
+  parseLockRecord,
+  readLockHolder,
+} from './daemonLocks.mjs';
 
-/** Signal 0 — a liveness probe, not a kill. EPERM means alive and not ours. */
-function alive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return e.code === 'EPERM';
-  }
-}
-
-function readHolder(path) {
-  try {
-    const v = JSON.parse(readFileSync(path, 'utf8'));
-    return v && Number.isInteger(v.pid) && v.pid > 0 ? v : null;
-  } catch {
-    return null; // absent, truncated, or half-written — treat as no holder
-  }
-}
+/** Absent, truncated, half-written, or no positive pid — no holder. */
+const readHolder = (path) => readLockFile(path);
 
 /**
  * WHAT THE DAEMON HOLDING THIS CREDENTIAL'S LOCK IS FINISHING — the `target →
@@ -136,21 +124,16 @@ function readHolder(path) {
  * already measured running.
  */
 export function drainingFor(fleetToken) {
-  const what = readHolder(instanceLockPath(fleetToken))?.draining?.what;
+  const what = readLockHolder(fleetToken)?.draining?.what;
   return typeof what === 'string' && what ? what : null;
 }
 
 /** Read-only desktop measurement. No lock is unknown because an unguarded or
  * older daemon may still run; a stale lock with a dead pid measures empty. */
 export function daemonRunningFor(fleetToken) {
-  const path = instanceLockPath(fleetToken);
-  let raw;
-  try { raw = readFileSync(path, 'utf8'); }
-  catch { return null; }
-  let holder;
-  try { holder = JSON.parse(raw); } catch { return null; }
-  if (!Number.isInteger(holder?.pid) || holder.pid <= 0) return null;
-  if (!alive(holder.pid)) return false;
+  const holder = readLockHolder(fleetToken);
+  if (!holder) return null;
+  if (!processAlive(holder.pid)) return false;
   return stillTheHolder(holder);
 }
 
@@ -210,10 +193,7 @@ const ANCESTOR_DEPTH = 8;
 function parentOf(pid) {
   try {
     if (platform() === 'linux') {
-      const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
-      const close = raw.lastIndexOf(')');
-      if (close < 0) return null;
-      const ppid = Number.parseInt(raw.slice(close + 1).trim().split(/\s+/)[1], 10);
+      const ppid = procStat(pid)?.ppid;
       return Number.isInteger(ppid) && ppid > 0 ? ppid : null;
     }
     if (platform() === 'darwin') {
@@ -276,29 +256,14 @@ function neighbourLockPath(holder, fallback) {
   return NEIGHBOUR_PATHS.get(holder) ?? fallback;
 }
 
-/** Every daemon lock file on this machine, absolute, sorted for a stable read.
- *  ONE scan, because two callers walk this directory for opposite reasons —
- *  daemonInSameRepo looking for a neighbour to refuse or replace, stopAllDaemons
- *  sweeping the lot — and the FILENAME PATTERN is the thing that must not drift
- *  between them: it is what separates our locks from anything else living in
- *  ~/.flowviant. An unreadable (or absent) directory is not an error here, it is
- *  an empty machine. */
-function lockFiles() {
-  try {
-    return readdirSync(join(homedir(), '.flowviant'))
-      .filter((f) => /^daemon-[0-9a-f]{12}\.lock$/.test(f))
-      .sort()
-      .map((f) => join(homedir(), '.flowviant', f));
-  } catch {
-    return [];
-  }
-}
-
+// Every daemon lock file on this machine comes from ONE scan, listDaemonLocks
+// (daemonLocks.mjs): daemonInSameRepo looks for a neighbour to refuse or
+// replace, stopAllDaemons sweeps the lot, and uninstall protects what a live
+// daemon runs from — and the filename pattern must not drift between them.
 export function daemonInSameRepo(repoRoot, ownPath) {
-  for (const path of lockFiles()) {
+  for (const { path, holder } of listDaemonLocks()) {
     if (path === ownPath) continue; // our own credential — the lock above owns that question
-    const holder = readHolder(path);
-    if (!holder || !alive(holder.pid)) continue;
+    if (!holder || !processAlive(holder.pid)) continue;
     if (isOurReexecParent(holder.pid)) continue; // ourselves mid self-update re-exec
     if (samePath(holder.repoRoot, repoRoot)) {
       NEIGHBOUR_PATHS.set(holder, path);
@@ -369,23 +334,11 @@ function processStartedAt(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return null;
   try {
     if (platform() === 'linux') {
-      // FIELD 22 OF /proc/<pid>/stat, and the parse is the whole trap. Field 2
-      // is `comm`, which the kernel wraps in parens and which may contain BOTH
-      // spaces and parens — it is the first 15 bytes of the executable's name,
-      // and a name is not a token. A naive split on whitespace taking $22 then
-      // lands on `nice` for any such process, and `nice` is a small integer, so
-      // the answer is not a parse error but a plausible-looking "started at
-      // boot" that sails past any isFinite guard. Measured: a binary named
-      // `ev (i l) x` read 28308s too old that way.
-      //
-      // Every field after `comm` is a number or a single-character state, so no
-      // ')' can appear later: the LAST ')' in the line is always the kernel's
-      // own closing paren, even when comm itself ends in one.
-      const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
-      const close = raw.lastIndexOf(')');
-      if (close < 0) return null;
-      const fields = raw.slice(close + 1).trim().split(/\s+/); // fields[0] IS field 3
-      const ticks = Number.parseInt(fields[19], 10); // field 22 => 22 - 3
+      // FIELD 22 OF /proc/<pid>/stat, and the parse is the whole trap: field 2
+      // is `comm`, which may contain BOTH spaces and parens, and a naive split
+      // read a binary named `ev (i l) x` 28308s too old. procStat.mjs is the one
+      // parser of that line and says why its reading is the right one.
+      const ticks = procStat(pid)?.starttime;
       if (!Number.isFinite(ticks) || ticks < 0) return null;
       // `/proc/uptime` rather than `/proc/stat`'s btime, and not for precision
       // alone (measured 6ms out against 162ms). Date.now() and uptime are read
@@ -653,7 +606,7 @@ function standDown(holder, path, log, { waitOutDrain = false } = {}) {
   if (holder.pid === process.pid) return { failed: 'refusing to signal this very process' };
   const standing = () => {
     const now = readHolder(path);
-    if (!now || !alive(now.pid)) return null;
+    if (!now || !processAlive(now.pid)) return null;
     return now;
   };
   const before = standing();
@@ -737,7 +690,7 @@ function standDown(holder, path, log, { waitOutDrain = false } = {}) {
  * collapsing them once had the daemon telling people a live holder was stale.
  */
 function takeOverFrom(holder, path, log, { allowDowngrade = false } = {}) {
-  if (!holder?.pid || !alive(holder.pid)) return null; // already gone
+  if (!holder?.pid || !processAlive(holder.pid)) return null; // already gone
   const identified = stillTheHolder(holder);
   if (identified === null) {
     // We know nothing about this pid, and said so. The remedy is a human
@@ -834,7 +787,7 @@ export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
     } catch (e) {
       if (e.code !== 'EEXIST') return { ok: true, release: () => {}, unguarded: true };
       const holder = readHolder(path);
-      if (!holder || !alive(holder.pid)) {
+      if (!holder || !processAlive(holder.pid)) {
         // A crashed daemon's leftover. Clear it and take it on the next pass —
         // ownership-verified, because a concurrent start may have cleared and
         // re-created it in the gap since our read.
@@ -843,7 +796,7 @@ export function acquireInstanceLock(fleetToken, repoRoot, opts = {}) {
           // Unreadable content: re-read before clearing, so a half-written
           // record a peer is writing RIGHT NOW is not deleted mid-write.
           const again = readHolder(path);
-          if (again && alive(again.pid)) continue; // it finished writing — a real holder now
+          if (again && processAlive(again.pid)) continue; // it finished writing — a real holder now
           try {
             rmSync(path, { force: true });
           } catch {
@@ -982,7 +935,7 @@ function stopLock(path, log, tally) {
   const where = holder.repoRoot ? ` in ${holder.repoRoot}` : '';
   const what = holder.version ? ` ${holder.version}` : '';
 
-  if (!alive(holder.pid)) {
+  if (!processAlive(holder.pid)) {
     log(`pid ${holder.pid}${where} is already gone — nothing to stop.`);
     return;
   }
@@ -1117,7 +1070,7 @@ export function stopDaemonFor(fleetToken, { log = (m) => console.log(m) } = {})
  */
 export function stopAllDaemons({ log = (m) => console.log(m) } = {}) {
   const tally = { stopped: 0, unconfirmed: 0, failed: 0, running: 0, draining: 0 };
-  for (const path of lockFiles()) stopLock(path, log, tally);
+  for (const { path } of listDaemonLocks()) stopLock(path, log, tally);
   const { stopped, unconfirmed, failed, running } = tally;
 
   // WHAT WE ACTUALLY MEASURED IS LOCKS, so that is what this says. The old

package/bin/lib/intakeDraft.mjs

@@ -20,7 +20,10 @@ export function parseIntakeDraft(text, typeHint = null, scrub = envScrub) {
     const taskType = agentTaskTypeOf(typeHint) ?? v.taskType;
     const clean = (value) => String(scrub(value.trim()));
     return {
-      title: clean(v.title),
+      // ONE LINE (2026-10-10): the title is printed in later prompts, and a
+      // line break in it forged structure there; parse.ts collapses a ticket's
+      // own title the same way.
+      title: clean(v.title).replace(/\s+/g, ' ').trim(),
       description: clean(v.description),
       acceptanceCriteria: v.acceptanceCriteria.map(clean),
       taskType,

package/bin/lib/knowledgeFileSync.mjs

@@ -73,6 +73,37 @@ export function writeAtomic(path, data) {
  *  list. */
 export const isCurrent = (state) => state === 'current' || state === 'wrote';
 
+/**
+ * ONE STATE INTO A SYNC'S RESULT (2026-10-10, the audit's F111): `wrote` and
+ * `refused` are listed as such, and anything not current (`stale`, `failed`)
+ * clears `ok` — the retry contract: the driver backs off and refetches — and
+ * is listed as failed. The four fetched kinds restated this by hand. What a
+ * refusal means to the caller (a name no longer kept, a path no longer
+ * wanted) stays at the call site. Returns `state`, so the caller can branch.
+ */
+export function recordSyncState(result, state, path) {
+  if (state === 'refused') result.refused.push(path);
+  else if (state === 'wrote') result.wrote.push(path);
+  else if (!isCurrent(state)) {
+    result.ok = false;
+    result.failed.push(path);
+  }
+  return state;
+}
+
+/** A generated text file (INSTRUCTIONS.md, LIBRARY.md) made to hold `text`:
+ *  left alone when the REGULAR file there already does, else written
+ *  atomically. True when it was written. */
+export function writeTextIfChanged(path, text) {
+  try {
+    if (lstatSync(path).isFile() && readFileSync(path, 'utf8') === text) return false;
+  } catch {
+    /* absent */
+  }
+  writeAtomic(path, text);
+  return true;
+}
+
 /**
  * Make `path` hold the manifest's file.
  *