flowviant 0.25.0 → 0.26.0

package/bin/lib/claude.mjs

@@ -77,83 +77,122 @@ export const SINGLE_RESUME =
   'Resume your current task. Call get_blocker_resolution for the blocker you reported; ' +
   'if resolved, apply the human’s answer and finish this one intent, then stop.';
 
-// Wiki-gen turn: the local Claude READS the repo and writes the living code wiki
-// via MCP. It never edits/commits code — the ONLY writes are emit_wiki_node calls.
-export const SYSTEM_WIKI = `You are Flowviant's codebase cartographer, running FULLY AUTONOMOUSLY via the
-"flowviant" MCP server. There is NO interactive user and NO terminal. You do NOT
-write, edit, or commit code — you READ this repository and document it as a living
-wiki by calling MCP tools.
-
-Goal: map the WHOLE codebase into a graph of wiki nodes an engineer new to the
-project could read to understand it. Explore the REAL files (Read, Grep, Glob, ls,
-git) — never guess. Ground every claim in files you actually read.
-
-Emit each node with emit_wiki_node. Cover, at least:
-- ONE "overview" node (id: "overview") — what the product is, the big picture, how to run it.
-- ONE "architecture" node (id: "architecture") — the major pieces, how they fit, the data flow.
-- "schema" node(s) — the data model (DB tables / core types) when the repo has one.
-- "module" nodes — ONE per significant area/package/subsystem, at the level a developer
-  thinks in (NOT one per file).
-- "api" / "testing" / "adr" / "note" nodes where warranted (public API surface, how tests
-  run, notable decisions, cross-cutting flows).
-
-For each node:
-- id: a STABLE slug YOU choose ("overview", "architecture", "schema", "module:apps/web",
-  "api:rest", "note:auth-flow"). Reuse the SAME id to refine a node.
-- title: human-readable.
-- body: the markdown page an engineer would write after reading the code — purpose, key
-  files and what they do, important flows, gotchas. Link related nodes with [[their-id]].
-- citations: the real repo-relative files the page draws from.
-- filePaths: the files the node covers (module nodes especially).
-- edges: links FROM this node to related node ids (targetId + kind ref|coupling|bridge).
-- groundedAtSha: the commit you were told to ground to.
-
-Judge significance YOURSELF: a big/important area gets its own node; trivial things fold
-into a parent node's body. Do NOT emit a node per file.
-
-When the whole codebase is mapped, call finish_wiki_generation ONCE with keepNodeIds =
-EVERY id you emitted, then output exactly WIKI_DONE on its own line and stop.
-
-Be efficient — this spends the user's Claude quota. Read broadly and sample enough to
-document each area accurately; you needn't read every file. If a tool errors, retry a
-couple of times, then move on — never stall waiting on a human.`;
-
-export const WIKI_KICKOFF = (sha) =>
-  `Map this repository into the living code wiki now. Ground everything to commit ${sha}. ` +
-  `Read the real files, emit a node per significant area with emit_wiki_node, then call ` +
-  `finish_wiki_generation with all your node ids and output WIKI_DONE.`;
-
-// Delivery re-ground turn: a feature just MERGED. Update only the touched wiki
-// nodes + record a persistent feature-history node. INCREMENTAL — never a full
-// rewrite, never finish_wiki_generation (that prunes; this only adds/updates).
-export const SYSTEM_REGROUND = `You are Flowviant's codebase cartographer, running FULLY AUTONOMOUSLY via the
-"flowviant" MCP server. There is NO interactive user and NO terminal. You do NOT
-write, edit, or commit code — a feature just MERGED and you update the living code
-wiki to reflect it, by calling MCP tools.
+// Wiki-gen turn: the local Claude READS the repo (cwd) and writes/maintains the
+// knowledge VAULT — a plain directory of markdown files with [[wikilinks]]
+// (Obsidian-style). No MCP tools involved: the vault is just files, and the
+// daemon hash-diff syncs them to Flowviant after the turn. The repo itself is
+// strictly read-only.
+export const SYSTEM_WIKI = (vaultDir) => `You are Flowviant's codebase cartographer, running FULLY AUTONOMOUSLY. There is
+NO interactive user and NO terminal to ask in. You READ the repository you are
+running in and maintain a knowledge VAULT of markdown files at:
+
+  ${vaultDir}
+
+That vault directory is the ONLY place you may create, edit, or delete files.
+NEVER modify the repository itself — no code edits, no commits, no git writes.
+
+The vault is an LLM wiki: its readers are AI agents (including future you), so
+optimize for machine-usable DETAIL and DENSITY over human polish. Depth
+compounds — a page should teach its code area to an agent that has never read
+the code. Conventions:
+
+- One markdown file per topic: each significant module/subsystem, core concept,
+  data model, key flow, notable decision. Organize with folders as you see fit
+  (e.g. modules/, concepts/, decisions/). More pages is fine — granular beats
+  monolithic.
+- Link related pages inline with [[wikilinks]] — link LIBERALLY; the link graph
+  IS the map. A [[link]] to a page you haven't written yet marks it as worth
+  writing.
+- index.md — the entry point: a categorized catalog of every page with a
+  one-line summary each. Keep it current.
+- log.md — append-only history: one "## [<sha7>] <what happened>" entry per
+  pass. When log.md grows past ~150KB, compact its OLDEST entries into a short
+  summary section at the top (never let it exceed the 256KB sync cap).
+- Every page STARTS with YAML frontmatter listing the REAL repo files it
+  documents, then a "# Title" heading, then the body:
+
+  ---
+  files:
+    - apps/web/src/example.ts
+  ---
+  # Page Title
+
+  Body: purpose, how it works, key functions/types/tables, invariants, gotchas,
+  cross-references to [[related-pages]].
+
+Ground EVERY claim in files you actually read (Read, Grep, Glob, ls, git in the
+repo) — never guess.
+
+THE HUMAN DOCS — docs/ inside the vault. After the vault pages are current,
+COMPILE human documentation FROM them (distill your own vault pages — don't
+re-read the whole repo; spot-check a cited file only when something looks off).
+Docs are for humans: clear prose, short sections, a reading order. Fixed spine:
+- docs/00-start-here.md — "Start Here": what this codebase is, how to run it,
+  the handful of files that matter most, where to go next.
+- docs/01-architecture.md — the big picture: major pieces, how they fit, data
+  flow, and a map of the chapters below.
+- docs/1N-<chapter>.md — ONE chapter per major subsystem (10, 11, 12 …), YOUR
+  choice of chapters, derived from the vault's hub pages.
+- docs/90-decisions.md — notable design decisions and their why.
+- docs/91-glossary.md — the project's terms of art.
+Docs pages use the same frontmatter files: lists and [[wikilinks]] (they may
+link to vault pages); numeric prefixes are the reading order.
+
+Full-sweep protocol:
+1. If the vault already has pages, read index.md + log.md FIRST — update and
+   extend rather than rewrite; delete vault pages whose code no longer exists.
+2. Explore the repo broadly, then write/refresh pages area by area.
+3. Compile/refresh the docs/ chapters from the finished vault pages.
+4. Refresh index.md, append a log.md entry, then output exactly WIKI_DONE on
+   its own line and stop.
+
+Be efficient — this spends the user's Claude quota. Read broadly and sample
+enough to document each area accurately; you needn't read every file. If a tool
+errors, retry a couple of times, then move on — never stall waiting on a human.`;
+
+export const WIKI_KICKOFF = (sha, vaultDir) =>
+  `Map this repository into the knowledge vault now (vault: ${vaultDir}). Ground ` +
+  `everything to commit ${sha}. Read the real files, write/refresh the vault pages, ` +
+  `compile the docs/ chapters from them, update index.md and log.md, then output WIKI_DONE.`;
+
+// Delivery re-ground turn: a feature just MERGED. Update only the vault pages
+// the change touched + append the durable feature-history log entry.
+// INCREMENTAL — never a full rewrite.
+export const SYSTEM_REGROUND = (vaultDir) => `You are Flowviant's codebase cartographer, running FULLY AUTONOMOUSLY. There is
+NO interactive user and NO terminal. A feature just MERGED and you update the
+knowledge VAULT of markdown files at:
+
+  ${vaultDir}
+
+That vault directory is the ONLY place you may create, edit, or delete files.
+NEVER modify the repository itself — no code edits, no commits, no git writes.
 
 Steps:
-1. Call list_wiki_nodes to see the current wiki (node ids + the files each covers).
-2. For each existing node whose files OVERLAP the changed files, RE-READ that area's
-   real code and re-emit the node with emit_wiki_node using the SAME id (updating it
-   in place). Touch ONLY nodes the change actually affected — this is incremental.
-   If the change adds a genuinely new area with no node, emit a new one.
-3. Emit ONE feature-history node recording what shipped: id "feature:<short-slug>",
-   kind "note", state "built", title = the feature, body = what it added and why
-   (a durable record), citations = the changed files, edges linking to the code
-   nodes it touched. state "built" makes it permanent — a future full sweep keeps it.
-4. Do NOT call finish_wiki_generation — that is only for a full sweep and would
-   prune. Just emit, then output exactly REGROUND_DONE on its own line and stop.
+1. Read the vault's index.md (and log.md tail) to see the current pages and the
+   repo files each documents (their frontmatter "files:" lists).
+2. For each existing page whose files OVERLAP the changed files, RE-READ that
+   area's real code and update the page in place. Touch ONLY pages the change
+   actually affected — this is incremental. If the change adds a genuinely new
+   area, write a new page (with frontmatter + [[links]]) and add it to index.md.
+3. If any docs/ chapter cites or covers the updated vault pages, refresh THAT
+   chapter (docs are compiled from the vault — keep them consistent; touch only
+   affected chapters).
+4. Append ONE feature-history entry to log.md:
+   "## [<sha7>] shipped: <feature title>" followed by a short durable record of
+   what it added and why, citing the changed files and [[touched-pages]].
+5. Output exactly REGROUND_DONE on its own line and stop.
 
 Ground every claim in files you actually read. Be efficient — look only at the
 changed area, not the whole repo; spend little quota.`;
 
-export const REGROUND_KICKOFF = ({ sha, title, files }) =>
-  `A feature just merged. Re-ground the living wiki for it.\n\n` +
+export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir }) =>
+  `A feature just merged. Re-ground the knowledge vault (${vaultDir}) for it.\n\n` +
   `Feature: ${title}\n` +
   `Grounded commit: ${sha}\n` +
   `Changed files:\n${files.map((f) => `- ${f}`).join('\n')}\n\n` +
-  `Follow your instructions: list_wiki_nodes, re-emit the touched nodes (same ids), ` +
-  `emit the feature-history node (state "built"), then output REGROUND_DONE.`;
+  `Follow your instructions: update the touched vault pages (and any docs/\n` +
+  `chapter that covers them), append the feature-history entry to log.md,\n` +
+  `then output REGROUND_DONE.`;
 
 // Unattended (default) skips prompts so the agent never stalls with no terminal;
 // FLOWVIANT_SAFE=1 restricts to a curated toolset instead.
@@ -173,6 +212,36 @@ const PERM = SAFE
     ]
   : ['--dangerously-skip-permissions'];
 
+// Wiki turns are read-the-repo + write-the-vault ONLY — always curated, never
+// --dangerously-skip-permissions: no gh, no push-capable git, no package
+// managers, and nothing that can EXECUTE arbitrary commands — no `find`
+// (-exec/-delete) and no `git grep` (-O<pager> runs a shell; the Grep tool
+// covers search). Command execution is the line: it enables network exfil,
+// which plain file writes never do. `rm` IS allowed: pruning a stale vault
+// page requires a real file deletion (that's how the sync protocol learns of
+// it), and the blast radius is bounded — the daemon resets the repo worktree
+// after every wiki turn, and the vault has its own git history.
+// (Write/Edit can't be path-scoped here; the worktree reset is the backstop.)
+const WIKI_PERM = [
+  '--allowedTools',
+  'Read',
+  'Grep',
+  'Glob',
+  'Edit',
+  'Write',
+  'Bash(ls:*)',
+  'Bash(wc:*)',
+  'Bash(head:*)',
+  'Bash(cat:*)',
+  'Bash(mkdir:*)',
+  'Bash(rm:*)',
+  'Bash(git status:*)',
+  'Bash(git log:*)',
+  'Bash(git show:*)',
+  'Bash(git diff:*)',
+  'Bash(git rev-parse:*)',
+];
+
 export const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
 
 // Sentinels must appear on their OWN line (the prompts require it). Substring
@@ -215,6 +284,15 @@ export function humanizeToolUse(name, input = {}, cwd = '') {
   switch (name) {
     case 'Read':
       return { kind: 'read', label: `read ${shortPath(input.file_path, cwd)}` };
+    // Vault authoring: Write/Edit of a markdown page is the "writing" signal
+    // (the wiki turn's only legal writes are vault files). Label with the last
+    // two path segments — the vault lives outside cwd, so shortPath can't trim.
+    case 'Write':
+    case 'Edit': {
+      const p = String(input.file_path ?? '');
+      const tail = p.split('/').slice(-2).join('/');
+      return { kind: 'write', label: `${name === 'Write' ? '+ page' : '~ page'} ${tail}` };
+    }
     case 'Grep':
       return {
         kind: 'search',
@@ -286,16 +364,18 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText }) {
 // returned string for sentinel detection, and each activity is handed to
 // `onActivity` so the caller can forward progress. Build-agent turns leave it
 // off and keep the raw text passthrough + line sentinels.
-export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn, streamJson, onActivity }) {
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn, streamJson, onActivity, wikiPerm }) {
   return new Promise((resolve) => {
     const args = [];
     if (resume) args.push('--continue');
-    args.push('-p', prompt, '--mcp-config', mcpConfig, '--append-system-prompt', system);
+    args.push('-p', prompt, '--append-system-prompt', system);
+    // Wiki-vault turns are pure file work — no MCP server at all.
+    if (mcpConfig) args.push('--mcp-config', mcpConfig);
     // Pin the model — never inherit the user's global default (which may be a
     // 1M/long-context tier their subscription can't bill autonomous work on).
     args.push('--model', MODEL);
     if (streamJson) args.push('--output-format', 'stream-json', '--verbose');
-    args.push(...PERM);
+    args.push(...(wikiPerm ? WIKI_PERM : PERM));
     // Force the user's Claude Code subscription — never the API. A key exported in
     // the shell would otherwise silently bill every poll-mode turn as raw API
     // usage (same invariant live mode enforces on its SDK session env).

package/bin/lib/config.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
-export const VERSION = '0.25.0';
+export const VERSION = '0.26.0';
 
 // The model EVERY daemon Claude turn runs on — pinned so autonomous work never
 // inherits your interactive `~/.claude/settings.json` default. That matters: a

package/bin/lib/fleet.mjs

@@ -54,6 +54,7 @@ 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';
 
 async function fetchRoster(haveIds) {
   const url = new URL(FLEET_URL);
@@ -221,6 +222,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 +407,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
@@ -456,6 +460,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 +477,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 +489,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 +560,113 @@ 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,
+              });
+              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 +751,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,

package/bin/lib/vault.mjs

@@ -0,0 +1,254 @@
+/**
+ * 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 = () => {} }) {
+  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;
+    }
+    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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {