flowviant 0.25.0 → 0.27.0

package/bin/lib/fleet.mjs

@@ -54,10 +54,25 @@ import { runLiveWorker } from './live.mjs';
 import { reapOrphanPreviews } from './preview.mjs';
 import { preflight } from './preflight.mjs';
 import { connectStream } from './stream.mjs';
+import { ensureVault, syncVault } from './vault.mjs';
+import {
+  envQueryParams,
+  handleRosterEnv,
+  materializeInto,
+  scrub as envScrub,
+} from './env.mjs';
 
 async function fetchRoster(haveIds) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
+  // Env-sync identity + materialized version (the Settings "env vN" chip).
+  try {
+    for (const [k, v] of Object.entries(await envQueryParams())) {
+      if (v) url.searchParams.set(k, v);
+    }
+  } catch {
+    /* env identity is best-effort — the poll must never fail on it */
+  }
   // An explicit User-Agent is required: Node's default ("node"/empty) trips
   // Cloudflare Bot Fight Mode (403). A descriptive product UA passes.
   const res = await fetch(url, {
@@ -116,6 +131,7 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
     }
     if (!resuming && needsReset) {
       resetWorktree(cwd, baseRef); // clean slate for a new task
+      materializeInto(cwd); // reset wiped the env files (git clean -fd) — rewrite
       needsReset = false;
     }
     const { dir, path: mcpConfig } = mcpConfigFor(token, getMcpUrl());
@@ -221,6 +237,14 @@ export async function runFleetDaemon() {
     } catch {
       /* best-effort */
     }
+    // A mid-sweep wiki Claude must die with the daemon — orphaning it leaves it
+    // burning quota, and a restarted daemon would start a SECOND sweep racing
+    // it on the same vault dir + sync state.
+    try {
+      wikiChild?.kill('SIGKILL');
+    } catch {
+      /* best-effort */
+    }
     for (const [, w] of workers) {
       w.state.alive = false;
       try {
@@ -398,36 +422,31 @@ export async function runFleetDaemon() {
     }
   };
 
-  // Living-wiki work runs ONE turn at a time in a dedicated worktree (off the
-  // agents' checkouts), via the emit_wiki_node MCP tool — never code edits. Two
-  // triggers enqueue: a Regenerate click (full SWEEP) and a successful merge
-  // (incremental RE-GROUND → feature-history). One queue + runner serializes
-  // them so they never collide on the worktree. Each turn runs under its own
-  // wiki-scoped credential (minted per task below) — the server allows ONLY the
-  // wiki tools on it, and build agents' worker tokens can't touch the map. Also
-  // means wiki work needs no agent online.
+  // Living-wiki work runs ONE turn at a time in a dedicated repo worktree (off
+  // the agents' checkouts). Claude READS the repo there and writes the markdown
+  // VAULT (~/.flowviant/vaults/<projectId>) — plain files, no MCP tools; the
+  // daemon hash-diff syncs the vault to the server after each turn. Two
+  // triggers enqueue: a Regenerate click (full SWEEP, finalize-prunes) and a
+  // successful merge (incremental RE-GROUND). One queue + runner serializes
+  // them so they never collide on the worktree or the vault. Wiki work needs no
+  // agent online.
   const wikiWt = join(baseDir, 'wiki');
   const REGROUND_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/reground-done');
-  const WIKI_TOKEN_URL = FLEET_URL.replace(/\/agents\/?$/, '/wiki-token');
+  const WIKI_VAULT_URL = FLEET_URL.replace(/\/agents\/?$/, '/wiki-vault');
   const WIKI_PROGRESS_URL = FLEET_URL.replace(/\/agents\/?$/, '/wiki-progress');
   const wikiQueue = [];
   let wikiBusy = false;
+  let wikiChild = null; // the wiki turn's Claude process — tracked so teardown can kill it
   let lastSweepAt = null; // dedup: run each Regenerate request once
   const groundedIntents = new Set(); // dedup: re-ground each delivery once
-
-  const mintWikiToken = async () => {
-    try {
-      const res = await fetch(WIKI_TOKEN_URL, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${FLEET_TOKEN}`, 'User-Agent': USER_AGENT },
-        signal: AbortSignal.timeout(30_000),
-      });
-      if (!res.ok) return null;
-      return (await res.json())?.data?.token ?? null;
-    } catch {
-      return null;
-    }
-  };
+  // The vault is keyed by the server project this fleet credential serves
+  // (learned from the roster); until the first poll names it, fall back to a
+  // repo-keyed dir so a stale-server daemon still works.
+  let wikiProjectId = null;
+  const vaultDirFor = () =>
+    wikiProjectId && isSafePathSegment(wikiProjectId)
+      ? join(homedir(), '.flowviant', 'vaults', wikiProjectId)
+      : join(homedir(), '.flowviant', 'vaults', repoKey);
 
   // Stream what the wiki turn is doing to the app (the canvas renders the read
   // phase). Throttled to ~1/s — the FIRST activity of a run and the terminal
@@ -437,6 +456,14 @@ export async function runFleetDaemon() {
     const now = Date.now();
     if (!force && now - lastProgressAt < 600) return;
     lastProgressAt = now;
+    // Uplink scrub: narration/labels can quote repo content, and repo content
+    // can contain a synced secret — redact known values before anything leaves
+    // this machine.
+    const safe = {
+      ...body,
+      ...(typeof body.activity === 'string' ? { activity: envScrub(body.activity) } : {}),
+      ...(Array.isArray(body.recent) ? { recent: body.recent.map((s) => envScrub(s)) } : {}),
+    };
     try {
       await fetch(WIKI_PROGRESS_URL, {
         method: 'POST',
@@ -446,7 +473,7 @@ export async function runFleetDaemon() {
           'Content-Type': 'application/json',
         },
         signal: AbortSignal.timeout(15_000),
-        body: JSON.stringify(body),
+        body: JSON.stringify(safe),
       });
     } catch {
       /* best-effort — a dropped frame is harmless, the next one supersedes it */
@@ -456,6 +483,11 @@ export async function runFleetDaemon() {
   const enqueueSweep = (job) => {
     if (!job || job.requestedAt === lastSweepAt) return;
     lastSweepAt = job.requestedAt;
+    // A full sweep is expensive — never stack two. One queued sweep already
+    // covers any newer Regenerate click (it reads the repo fresh when it runs).
+    // A failed/partial sweep stays recoverable: re-clicking Regenerate always
+    // refreshes requestedAt server-side, beating this dedup.
+    if (wikiQueue.some((t) => t.type === 'sweep')) return;
     wikiQueue.push({ type: 'sweep' });
     void drainWiki();
   };
@@ -468,6 +500,9 @@ export async function runFleetDaemon() {
 
   // Changed files of a (merged) PR, for the re-ground prompt. Capped so a huge
   // PR can't blow up the prompt. prUrl was already validated before the merge.
+  // Returns null on a gh FAILURE (network/auth) — distinct from a PR that
+  // genuinely changed nothing — so the caller can retry instead of silently
+  // consuming the durable job with no re-ground run.
   const changedFilesForPr = (prUrl) => {
     try {
       const out = execFileSync('gh', ['pr', 'view', prUrl, '--json', 'files'], {
@@ -477,24 +512,22 @@ export async function runFleetDaemon() {
       });
       return (JSON.parse(out).files ?? []).map((f) => f.path).filter(Boolean).slice(0, 60);
     } catch {
-      return [];
+      return null;
     }
   };
+  const regroundAttempts = new Map(); // intentId -> gh-failure count
 
   async function drainWiki() {
     if (wikiBusy || wikiQueue.length === 0) return;
     wikiBusy = true;
     try {
       while (wikiQueue.length) {
-        // Fresh wiki-scoped credential per task — dedicated, so no roster
-        // re-mint can rotate it out from under a long sweep.
-        const token = await mintWikiToken();
-        if (!token) {
-          warn('wiki: could not mint the cartographer token — retrying on a later poll');
-          break; // queue intact — the reconcile loop re-drains
-        }
         const task = wikiQueue.shift();
-        const { dir, path: mcpConfig } = mcpConfigFor(token, mcpUrl);
+        // The vault is plain files — the turn needs no MCP server and no
+        // cartographer token; the daemon itself syncs afterwards on the fleet
+        // credential.
+        const vaultDir = vaultDirFor();
+        ensureVault(vaultDir);
         // Live progress for this turn: a rolling FEED of everything Claude does
         // (thinking, narration, reads, node writes), the file count, and the
         // phase — streamed to the app (throttled; each frame carries the whole
@@ -550,56 +583,115 @@ export async function runFleetDaemon() {
           } catch {
             /* detached/no HEAD — still writes the map, just ungrounded */
           }
+          // Sync the vault after the turn regardless of the sentinel: a died
+          // sweep's partial pages still persist (merge, no prune) — only a
+          // COMPLETED sweep finalizes, so an interrupted one can't erase pages.
+          const runSync = async (finalize) => {
+            try {
+              const r = await syncVault({
+                dir: vaultDir,
+                url: WIKI_VAULT_URL,
+                token: FLEET_TOKEN,
+                userAgent: USER_AGENT,
+                finalize,
+                groundedAtSha: sha || undefined,
+                // Powers the GitHub blob links behind every cited file path.
+                repoFullName: originSlug(repoRoot) || undefined,
+                warn,
+                // Redact synced secrets a page may have quoted from the repo.
+                scrub: envScrub,
+              });
+              if (r.skipped) note(`${c.cyan('wiki')} ${c.dim('— vault unchanged, nothing to sync')}`);
+              else
+                ok(
+                  `${c.cyan('wiki')} ${c.dim(
+                    `— synced ${r.uploaded} page${r.uploaded === 1 ? '' : 's'} (${r.pages} total${r.deleted ? `, ${r.deleted} removed` : ''})`
+                  )}`
+                );
+            } catch (e) {
+              warn(`wiki vault sync failed: ${e.message} — pages stay local; next turn retries`);
+            }
+          };
           if (task.type === 'sweep') {
             note(`${c.cyan('wiki')} ${c.dim('— regenerating: your Claude is reading the repo…')}`);
             const out = await runTurn({
-              prompt: WIKI_KICKOFF(sha),
+              prompt: WIKI_KICKOFF(sha, vaultDir),
               resume: false,
-              system: SYSTEM_WIKI,
+              system: SYSTEM_WIKI(vaultDir),
               cwd: wikiWt,
-              mcpConfig,
+              wikiPerm: true,
               label: c.cyan('[wiki]'),
               streamJson: true,
               onActivity,
+              onSpawn: (ch) => {
+                wikiChild = ch;
+              },
             });
-            if (sawSentinel(out, 'WIKI_DONE'))
-              ok(`${c.cyan('wiki')} ${c.dim('— regenerated from your code.')}`);
+            const complete = sawSentinel(out, 'WIKI_DONE');
+            if (complete) ok(`${c.cyan('wiki')} ${c.dim('— vault regenerated from your code.')}`);
             else
-              warn('code-wiki regeneration ended without WIKI_DONE — retry from the app if incomplete.');
+              warn('wiki sweep ended without WIKI_DONE — partial pages synced; retry from the app.');
+            await runSync(complete);
           } else {
             const files = changedFilesForPr(task.prUrl);
-            if (files.length === 0) {
+            if (files === null) {
+              // gh failed (network/auth) — retry via the durable job a couple
+              // of times before consuming it, so a transient outage doesn't
+              // silently drop the re-ground.
+              const n = (regroundAttempts.get(task.intentId) ?? 0) + 1;
+              regroundAttempts.set(task.intentId, n);
+              if (n < 3) {
+                warn(`wiki re-ground for "${task.title}": gh failed — will retry (${n}/3)`);
+                groundedIntents.delete(task.intentId); // let the roster re-offer it
+                continue;
+              }
+              warn(`wiki re-ground for "${task.title}": gh failed ${n} times — giving up (heals on the next full sweep)`);
+            } else if (files.length === 0) {
               note(`${c.cyan('wiki')} ${c.dim(`— "${task.title}": no changed files to re-ground`)}`);
             } else {
               note(`${c.cyan('wiki')} ${c.dim(`— re-grounding after "${task.title}"…`)}`);
               const out = await runTurn({
-                prompt: REGROUND_KICKOFF({ sha, title: task.title, files }),
+                prompt: REGROUND_KICKOFF({ sha, title: task.title, files, vaultDir }),
                 resume: false,
-                system: SYSTEM_REGROUND,
+                system: SYSTEM_REGROUND(vaultDir),
                 cwd: wikiWt,
-                mcpConfig,
+                wikiPerm: true,
                 label: c.cyan('[wiki]'),
                 streamJson: true,
                 onActivity,
+                onSpawn: (ch) => {
+                  wikiChild = ch;
+                },
               });
               if (sawSentinel(out, 'REGROUND_DONE'))
-                ok(`${c.cyan('wiki')} ${c.dim(`— wiki updated for "${task.title}".`)}`);
+                ok(`${c.cyan('wiki')} ${c.dim(`— vault updated for "${task.title}".`)}`);
               else warn(`wiki re-ground for "${task.title}" ended without REGROUND_DONE.`);
+              await runSync(false);
             }
-            // Consume the durable job: attempted = done (success or not — emits
-            // are idempotent and a failed turn heals on the next full sweep), so
-            // a failing re-ground can't loop-burn quota. Only a crash BEFORE
-            // this line leaves the job listed for a retry after restart.
+            // Consume the durable job: attempted = done (success or not — the
+            // sync is idempotent and a failed turn heals on the next full
+            // sweep), so a failing re-ground can't loop-burn quota. Only a
+            // crash BEFORE this line leaves the job listed for a retry.
+            regroundAttempts.delete(task.intentId);
             await reportMergeOutcome(REGROUND_DONE_URL, { intentId: task.intentId });
           }
         } catch (e) {
           warn(`wiki ${task.type} failed: ${e.message}`);
         } finally {
+          wikiChild = null;
           if (heartbeat) clearInterval(heartbeat);
           // Terminal frame so the app cover clears promptly (don't wait for the
           // freshness window to lapse). force-sent past the throttle.
           await postWikiProgress(frame({ done: true }), true);
-          rmSync(dir, { recursive: true, force: true });
+          // Safety net: the wiki turn is read-only on the repo by CONTRACT, but
+          // permission enforcement is a curated tool list, not a path jail —
+          // discard anything a confused turn wrote to the worktree so it can
+          // never leak into a later turn or a push.
+          try {
+            resetWorktree(wikiWt, baseRef);
+          } catch {
+            /* best-effort */
+          }
         }
       }
     } finally {
@@ -684,12 +776,17 @@ export async function runFleetDaemon() {
       }
     }
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
+    if (roster.project?.id) wikiProjectId = roster.project.id; // keys the vault dir
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
     // Keep the daemon current. Safe = no worker mid-task (true at startup, since
     // no workers are spawned yet). If it self-updates it re-execs into the new
     // version and this process becomes a proxy — stop the loop.
     if (roster.daemon) {
-      const safeToUpdate = [...workers.values()].every((w) => w.state.child == null);
+      // "No worker mid-task" must include the wiki runner: updating mid-sweep
+      // re-execs the daemon, orphans the wiki Claude, and the fresh process
+      // starts a second sweep racing it on the same vault.
+      const safeToUpdate =
+        !wikiBusy && [...workers.values()].every((w) => w.state.child == null);
       const updating = handleVersionSignal({
         latest: roster.daemon.latest,
         min: roster.daemon.min,
@@ -743,6 +840,11 @@ export async function runFleetDaemon() {
           fail(`could not create worktree for "${a.name}": ${e.message}`);
           continue;
         }
+        try {
+          materializeInto(wt); // synced env into the fresh worktree
+        } catch {
+          /* best-effort */
+        }
         const colorFn = LABEL_COLORS[joinCount++ % LABEL_COLORS.length];
         const label = colorFn(`[${a.name}]`);
         const state = { alive: true, child: null };
@@ -788,6 +890,21 @@ export async function runFleetDaemon() {
     for (const j of roster.regroundJobs ?? []) enqueueReground(j.intentId, j.prUrl, j.title);
     void drainWiki();
 
+    // Env sync tick: register/bootstrap/wrap/rotate/sync as the roster block
+    // dictates (self-guarded — one operation at a time, errors retry next
+    // poll). A fresh bundle rematerializes every AGENT worktree; the wiki
+    // worktree NEVER gets env (the cartographer doesn't need secrets).
+    void handleRosterEnv(roster.env, { projectId: roster.project?.id }).then(({ changed }) => {
+      if (!changed) return;
+      for (const [, w] of workers) {
+        try {
+          materializeInto(w.wt);
+        } catch {
+          /* best-effort */
+        }
+      }
+    });
+
     // Stop workers whose agent left the roster (removed in the app).
     for (const [id, w] of [...workers]) {
       if (!rosterIds.has(id)) {

package/bin/lib/live.mjs

@@ -34,6 +34,7 @@ import { c, info, ok, warn } from './ui.mjs';
 import { sleep } from './claude.mjs';
 import { git, resetWorktree, isValidBranch } from './git.mjs';
 import { loadPreviewConfig, startPreview } from './preview.mjs';
+import { materializeInto, scrub as envScrub } from './env.mjs';
 
 // Register a branch preview's tunnel URL with Flowviant (fleet-authed). The
 // reviewer then drives it via "Open live preview" in the node.
@@ -92,7 +93,9 @@ function postPreviewNote(intentId, text) {
       'Content-Type': 'application/json',
     },
     signal: AbortSignal.timeout(10_000),
-    body: JSON.stringify({ intentId, text }),
+    // Scrub: preview failure reasons can quote dev-server output, which can
+    // echo env values.
+    body: JSON.stringify({ intentId, text: envScrub(text) }),
   }).catch(() => {});
 }
 
@@ -143,7 +146,12 @@ self-report becomes your DELIVERY CARD in the task thread — it's what the team
 reads to confirm done, so write it for them, not for a log. A live preview of
 your branch is started for you automatically — you do NOT need to open a tunnel
 or register a live target. NEVER merge — a human confirms done in the thread
-(the merge card) and the merge runs separately.`;
+(the merge card) and the merge runs separately.
+SECRETS: env files (.env, .dev.vars, …) in your worktree hold the team's synced
+secrets. Their VALUES must NEVER appear in evidence, progress reports, blocker
+questions, delivery summaries, commits, or PRs — reference keys by NAME only
+(e.g. "set STRIPE_KEY"). Never screenshot a terminal or page that displays a
+credential, and never commit an env file.`;
 
 function seedPrompt(runId, brief, transcript, resumedInPlace) {
   return [
@@ -383,6 +391,7 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
   } else if (!resuming && !resumedInPlace) {
     resetWorktree(cwd, baseRef);
   }
+  materializeInto(cwd); // resets wipe the synced env files — rewrite them
   writeTaskMarker(cwd, intentId);
 
   if (resumedInPlace) {
@@ -480,7 +489,9 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
       await mcpCall(mcpUrl, token, 'stream_turn', {
         runId,
         turnId,
-        text: turnText.trim(),
+        // Uplink scrub: the model's narration can quote file contents, and a
+        // file can contain a synced secret — redact before it leaves the box.
+        text: envScrub(turnText.trim()),
         createdAt: turnAt,
       }).catch(() => {});
     }

package/bin/lib/vault.mjs

@@ -0,0 +1,258 @@
+/**
+ * Knowledge-vault plumbing: the local Obsidian-style wiki directory Claude
+ * writes (plain markdown + [[wikilinks]]) and the hash-diff sync that ships it
+ * to Flowviant. The vault lives OUTSIDE the repo and its worktrees
+ * (~/.flowviant/vaults/<projectId>) so it persists across sweeps, and gets a
+ * private `git init` so every pass is versioned locally for free — the user's
+ * repository is never touched.
+ *
+ * Sync protocol (POST /api/v2/fleet/wiki-vault, fleet-token auth): only files
+ * whose sha256 changed since the last successful sync are uploaded, chunked;
+ * the LAST request carries the finalize.manifest of a completed full sweep so
+ * the server prunes pages the sweep no longer has. The last-synced hashes live
+ * in `.flowviant-sync.json` inside the vault (dotfile — never walked, never
+ * uploaded).
+ *
+ * HARD RULE — deletion is opt-in, never inferred: a page we can't read, can't
+ * upload (oversized / invalid path), or truncated past the cap is CARRIED
+ * FORWARD at its last-synced state, not turned into a deletion. Only a page
+ * that verifiably vanished from a readable vault becomes a delete. Otherwise
+ * an append-only log.md crossing the size cap would silently erase itself
+ * server-side.
+ */
+
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { join, relative, sep } from 'node:path';
+
+const SYNC_STATE = '.flowviant-sync.json';
+// Mirror the server contract (shared schema) — a page that violates it is
+// skipped with a warning (and carried forward if previously synced), never
+// allowed to 400 the whole request and wedge the sync.
+const MAX_FILE_BYTES = 262_144;
+const MAX_PATH_CHARS = 300;
+const MAX_FILES = 400;
+const CHUNK_FILES = 30;
+const CHUNK_BYTES = 700_000;
+const MAX_DELETIONS_PER_REQ = 200;
+
+/** Daemon-side mirror of the server's isSafeVaultPath. */
+const isSafePath = (p) =>
+  p.length > 0 &&
+  p.length <= MAX_PATH_CHARS &&
+  p.endsWith('.md') &&
+  !p.includes('\\') &&
+  !p.includes('\0') &&
+  !p.startsWith('/') &&
+  p.split('/').every((seg) => seg.length > 0 && seg !== '.' && seg !== '..' && !seg.startsWith('.'));
+
+/** Create the vault dir + its private git history (best-effort). */
+export function ensureVault(dir) {
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(join(dir, '.git'))) {
+    try {
+      execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'ignore' });
+    } catch {
+      /* git unavailable — the vault still works, just unversioned */
+    }
+  }
+}
+
+/** All vault-relative .md paths (forward slashes), dotfiles/dirs skipped.
+ *  Splits on the PLATFORM separator only — a literal backslash in a Linux
+ *  filename must not be mangled into a bogus subpath. A failed directory read
+ *  bumps `errors.count` — the caller MUST treat the walk as partial then
+ *  (pages under an unreadable subtree are absent, not deleted). */
+function walkMd(dir, base = dir, out = [], errors = { count: 0 }) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    errors.count++;
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walkMd(p, base, out, errors);
+    else if (e.isFile() && e.name.endsWith('.md'))
+      out.push(relative(base, p).split(sep).join('/'));
+  }
+  return out;
+}
+
+/** Best-effort local history commit — identity pinned so it works on machines
+ *  with no global git config, and never touches the user's identity. */
+function commitVault(dir, message) {
+  try {
+    execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'ignore' });
+    execFileSync(
+      'git',
+      ['-c', 'user.name=flowviant', '-c', 'user.email=wiki@flowviant.local', 'commit', '-q', '-m', message],
+      { cwd: dir, stdio: 'ignore' }
+    );
+  } catch {
+    /* nothing to commit / git unavailable — fine */
+  }
+}
+
+/**
+ * Hash-diff sync the vault to the server. Returns counts; throws on a failed
+ * upload (the sync state is only advanced after EVERY request lands, so a
+ * partial failure re-uploads next time — server upserts are idempotent).
+ */
+export async function syncVault({ dir, url, token, userAgent, finalize, groundedAtSha, repoFullName, warn = () => {}, scrub = (t) => t }) {
+  const walkErrors = { count: 0 };
+  const found = walkMd(dir, dir, [], walkErrors).sort();
+  if (walkErrors.count > 0 && found.length === 0) {
+    // Vault root (or everything under it) unreadable — nothing to diff against.
+    warn(`vault at ${dir} is unreadable — skipping sync; check the vault dir`);
+    return { pages: 0, uploaded: 0, deleted: 0, skipped: true };
+  }
+
+  // Partition into uploadable pages and carried-forward ones. Carried = we
+  // know the page exists (or existed) but can't ship this state — keep the
+  // server's last-good copy: tracked in `current` (prev hash) + manifest,
+  // never a deletion.
+  const current = {}; // path -> sha256 tracked as the post-sync state
+  const contents = {}; // path -> markdown to upload (subset of current)
+  let prev = {};
+  try {
+    prev = JSON.parse(readFileSync(join(dir, SYNC_STATE), 'utf8'));
+  } catch {
+    /* first sync */
+  }
+  const carry = (p, why) => {
+    if (prev[p]) {
+      current[p] = prev[p];
+      warn(`vault page ${p}: ${why} — keeping the last synced copy`);
+    } else {
+      warn(`vault page ${p}: ${why} — not synced`);
+    }
+  };
+
+  let kept = 0;
+  for (const p of found) {
+    if (!isSafePath(p)) {
+      carry(p, 'name violates the sync contract (length/characters)');
+      continue;
+    }
+    if (kept >= MAX_FILES) {
+      carry(p, `vault exceeds ${MAX_FILES} pages`);
+      continue;
+    }
+    let text;
+    try {
+      text = readFileSync(join(dir, p), 'utf8');
+    } catch {
+      carry(p, 'unreadable');
+      continue;
+    }
+    // Uplink scrub: the cartographer quotes real repo files, and a repo file
+    // can contain a synced secret — redact known values before upload. The
+    // hash is computed on the SCRUBBED text so the diff state stays coherent.
+    text = scrub(text);
+    if (Buffer.byteLength(text) > MAX_FILE_BYTES) {
+      carry(p, 'exceeds 256KB');
+      continue;
+    }
+    kept++;
+    contents[p] = text;
+    current[p] = createHash('sha256').update(text).digest('hex');
+  }
+
+  // Partial walk (an unreadable SUBdirectory): every previously-synced page the
+  // walk failed to reach must be carried forward, not inferred deleted — a
+  // transient EMFILE/EACCES on e.g. docs/ must never erase those pages
+  // server-side. The hard rule: deletion is opt-in, never inferred.
+  if (walkErrors.count > 0) {
+    warn(
+      `vault walk hit ${walkErrors.count} unreadable director${walkErrors.count === 1 ? 'y' : 'ies'} — carrying missing pages forward, no deletions this pass`
+    );
+    for (const p of Object.keys(prev)) {
+      if (!(p in current)) current[p] = prev[p];
+    }
+  }
+
+  // A readable vault that suddenly presents ZERO pages while the server holds
+  // many is almost always a broken/moved dir, not an intentional wipe — refuse
+  // to mass-delete. (An intentional reset is a fresh Regenerate: the sweep
+  // rewrites pages, then finalize prunes precisely.)
+  const prevCount = Object.keys(prev).length;
+  if (Object.keys(current).length === 0 && prevCount > 0) {
+    warn(`vault at ${dir} presents 0 pages but ${prevCount} were synced — refusing to delete; check the vault dir`);
+    return { pages: 0, uploaded: 0, deleted: 0, skipped: true };
+  }
+
+  const changed = Object.keys(current).filter((p) => p in contents && prev[p] !== current[p]);
+  const deletions = Object.keys(prev).filter((p) => !(p in current));
+  const pages = Object.keys(current).length;
+  if (changed.length === 0 && deletions.length === 0 && !finalize) {
+    return { pages, uploaded: 0, deleted: 0, skipped: true };
+  }
+
+  // Finalize manifests are schema-capped server-side at MAX_FILES; carried
+  // pages can push the tracked set past it. Downgrade to a plain merge (no
+  // prune) rather than wedge the whole sync on a 400 — nothing is lost, the
+  // regen request stays pending, and the warning names the cause.
+  let doFinalize = !!finalize;
+  if (doFinalize && pages > MAX_FILES) {
+    warn(`vault tracks ${pages} pages (> ${MAX_FILES}) — skipping the finalize prune this pass`);
+    doFinalize = false;
+  }
+
+  // Build the request series: file chunks (count+byte capped), then however
+  // many deletion batches the 200-cap needs. finalize/sha ride the LAST
+  // request only, so the server prunes exactly once, after every upsert landed.
+  const fileChunks = [];
+  let cur = [];
+  let bytes = 0;
+  for (const p of changed) {
+    const size = Buffer.byteLength(contents[p]);
+    if (cur.length && (cur.length >= CHUNK_FILES || bytes + size > CHUNK_BYTES)) {
+      fileChunks.push(cur);
+      cur = [];
+      bytes = 0;
+    }
+    cur.push(p);
+    bytes += size;
+  }
+  if (cur.length) fileChunks.push(cur);
+
+  const requests = fileChunks.map((paths) => ({ files: paths.map((p) => ({ path: p, content: contents[p] })), deletions: [] }));
+  for (let i = 0; i < deletions.length; i += MAX_DELETIONS_PER_REQ) {
+    requests.push({ files: [], deletions: deletions.slice(i, i + MAX_DELETIONS_PER_REQ) });
+  }
+  if (requests.length === 0) requests.push({ files: [], deletions: [] }); // finalize-only
+
+  for (let i = 0; i < requests.length; i++) {
+    const last = i === requests.length - 1;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'User-Agent': userAgent,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(60_000),
+      body: JSON.stringify({
+        ...requests[i],
+        ...(last && doFinalize ? { finalize: { manifest: Object.keys(current) } } : {}),
+        ...(last && groundedAtSha ? { groundedAtSha } : {}),
+        ...(last && repoFullName ? { repoFullName } : {}),
+      }),
+    });
+    if (!res.ok) throw new Error(`wiki-vault sync failed (${res.status})`);
+  }
+
+  writeFileSync(join(dir, SYNC_STATE), JSON.stringify(current));
+  commitVault(dir, doFinalize ? `sweep${groundedAtSha ? ` @ ${groundedAtSha.slice(0, 7)}` : ''}` : `update${groundedAtSha ? ` @ ${groundedAtSha.slice(0, 7)}` : ''}`);
+  return { pages, uploaded: changed.length, deleted: deletions.length };
+}