Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
narrow to the refresh gate and incremental extraction
anirudhkumar-nanonetsb566db5686a8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 65686f0b..8cfdd981 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,6 +15,13 @@build's fingerprint (~3ms) and rebuild only if something moved. `check` is exempt — it isthe drift report, and refreshing first would make it always say OK.+ A refresh writes only what a query reads: the wiring graph, the `ask` sidecar, and the+ freshness record. It does **not** rewrite the markdown cards, `INDEX.md`, or your+ `.gitignore` — a query is a read, and those stay the job of an explicit `graft build`+ (which is what the Claude Code `Stop` hook already runs at the end of a turn). So the+ retrieval tools are always current, while the markdown you might `grep` by hand can lag+ an edit until the turn ends.+The refresh is structural and `$0`: it never calls the LLM, so `graft check` still reportsconcept-node drift and stale summaries until you run `graft build --deep` yourself. Arefresh that fails answers from the graph on disk rather than failing the query.@@ -24,19 +31,6 @@GRAFT_NO_REFRESH=1 # same, for every command in the process```-- **The graph and its sidecars are written atomically, and in a consistent order.** Now- that a query can rewrite the graph, a truncating write could hand a partial file to- whatever was reading it at the time — the statusline, a second MCP call, another graft- process — which surfaced as "no graph — run `graft build`" on a repo that has one. The- `ask` sidecar is written before the graph, so a reader that sees a new `wiring.json`- always sees an index that matches it.--- **A failed write under `graft/` is reported instead of being retried forever.** One- unwritable card or `INDEX.md` (a read-only mount, a directory you don't own) used to- make every later query rebuild the whole repo and fail again. The graph and its- freshness record are independent of those projections now, so a build converges and the- failure is named in the query's own output.-### Added- **Incremental extraction.** `graft build` memoizes each file's parse under `graft/.cache/`@@ -47,6 +41,11 @@now reports `parsed: N of M files (K replayed from cache)`, and `graft build --no-reuse`forces a cold parse of everything.+ Only the *parse* is skipped — every file is still read and hashed on every build. A stat+ may decide whether a query bothers rebuilding; it may not decide what the rebuild itself+ looks at, or `graft check` (which always re-hashes) could report drift that the `graft+ build` it recommends refuses to repair.+- **`GRAFT_REFRESH=hash`** — confirm every file by hashing its contents instead of trustingsize and mtime, for tooling that rewrites files while preserving both.diff --git a/README.md b/README.mdindex 7fcedc87..3cba4add 100644--- a/README.md+++ b/README.md@@ -222,8 +222,8 @@ Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's`graft init` always wires up Claude Code, and Claude Code gets more than an instruction file. From then on, any Claude Code session opened in the repo gets:-- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph (it flips back to `✓ synced` as soon as any graft query refreshes it, without waiting for the turn to end)-- **auto-sync** — every graft query brings the graph up to date first, so an answer always describes the code as it is right now, uncommitted edits included; a background rebuild also runs at the end of a turn that touched code. Both are structural and `$0` — auto-sync never calls the LLM on its own+- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph+- **auto-sync** — every graft query brings the graph up to date first, so an answer always describes the code as it is right now, uncommitted edits included. A query refreshes only what it reads; the markdown under `graft/` is refreshed by the background rebuild at the end of a turn that touched code. Both are structural and `$0` — auto-sync never calls the LLM on its own- **context on tap** — each prompt pulls the matching nodes into the session; editing a file surfaces what depends on it ("blast radius"); new sessions start with the repo map<p align="center">diff --git a/src/ask/index-file.ts b/src/ask/index-file.tsindex 8a2f9b5d..6d414bbe 100644--- a/src/ask/index-file.ts+++ b/src/ask/index-file.ts@@ -19,11 +19,10 @@* contribution is folded into the stored `df` at query time (see `ask.ts`),* which is why `df` here counts symbol/file nodes only.*/-import { existsSync, readFileSync } from "node:fs";-import { join } from "node:path";+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { dirname, join } from "node:path";import type { GraphV1 } from "../graph/types.js";import { CACHE_DIR } from "../context/node-file.js";-import { writeFileAtomic } from "../util/state.js";/** Words too common/short to carry query intent — dropped before scoring. */const STOP = new Set([@@ -126,14 +125,8 @@ export function writeAskIndex(outDir: string, graph: GraphV1): string {};const outPath = askIndexPath(outDir);- // Atomic, and `buildGraph` writes this BEFORE wiring.json. The sidecar has to- // agree with the graph — `readAskIndex` rejects one whose ids don't match — and- // the graph is what every reader gates on, so the graph must be the last of the- // pair to flip. A truncating write here would have handed a reader the new graph- // beside a half-written index, and the fallback path is badly degraded: the nodes- // in wiring.json have had `body_text` stripped, so live re-tokenization has no- // body to work from and body-only matches silently disappear.- writeFileAtomic(outPath, JSON.stringify(index) + "\n");+ mkdirSync(dirname(outPath), { recursive: true });+ writeFileSync(outPath, JSON.stringify(index) + "\n");return outPath;}diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.tsindex 87bd0bd6..26500f57 100644--- a/src/claude/skill-template.ts+++ b/src/claude/skill-template.ts@@ -80,9 +80,15 @@ hotspots, straight from the wiring graph.or ask your way through every subsystem it lists. \`--max-dirs N\` widens it.### 6 · Lifecycle: \`graft build\` / \`graft check\`-Every tool above refreshes the graph itself before answering, so what you get back-always describes the code as it is right now — including edits you just made and-have not committed. You do **not** need to run \`build\` after editing.+Every tool above refreshes the graph itself before answering, so what those tools+return always describes the code as it is right now — including edits you just made+and have not committed. You do **not** need to run \`build\` after editing.++One caveat, if you \`grep\` the markdown under \`graft/\` directly: those cards are a+projection, rebuilt at the end of the turn rather than on each query, so after an edit+they can lag. The tools above never do — prefer them, and treat a card's spans as+stale if you have edited that file this turn.+\`build\` is for the LLM layer (\`--deep\` adds a concept map; skip unless asked);\`check\` fails when \`graft/\` is stale, for CI.diff --git a/src/claude/state.ts b/src/claude/state.tsindex 19c305bf..d89fbea4 100644--- a/src/claude/state.ts+++ b/src/claude/state.ts@@ -17,7 +17,7 @@ export {patchStats,readStats,releaseLock,- writeFileAtomic,+ writeJsonAtomic,writeStats,} from '../util/state.js';export type { Stats } from '../util/state.js';diff --git a/src/claude/stats.ts b/src/claude/stats.tsindex 15ac5b28..6d85f1ac 100644--- a/src/claude/stats.ts+++ b/src/claude/stats.ts@@ -1,14 +1,25 @@import { readFileSync } from 'node:fs';import { join } from 'node:path';import type { GraphV1 } from '../graph/types.js';--/** `computeStats` lives in `util/state.ts` alongside the rest of the `.cache/`- * state, so the hooks and the graph's own pre-query refresh report the same- * numbers. Re-exported here because that's where callers already import it from. */-export { computeStats } from '../util/state.js';+import type { Stats } from './state.js';export function readWiring(projectDir: string): GraphV1 | null {try {return JSON.parse(readFileSync(join(projectDir, 'graft', '.graph', 'wiring.json'), 'utf8')) as GraphV1;} catch { return null; }}++export function computeStats(+ w: GraphV1,+): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'> {+ const nodes = w.nodes ?? [];+ const edges = w.edges ?? [];+ const readyCount = nodes.filter((n) => n.summary_state === 'ready').length;+ return {+ nodeCount: w.meta?.nodeCount ?? nodes.length,+ edgeCount: w.meta?.edgeCount ?? edges.length,+ languages: w.meta?.languages ?? [],+ totalCount: nodes.length,+ readyCount,+ };+}diff --git a/src/graph/build.ts b/src/graph/build.tsindex 2145675d..1f125e90 100644--- a/src/graph/build.ts+++ b/src/graph/build.ts@@ -25,7 +25,7 @@ import {writeExtractCache,type ExtractEntry,} from "./extract-cache.js";-import { statUnchanged, writeFingerprint } from "./fingerprint.js";+import { writeFingerprint } from "./fingerprint.js";import { listSourceStats } from "./source-files.js";import { resolveEdges, type GoModule } from "./resolve.js";import { enrichGraph, type EnrichStats } from "./enrich.js";@@ -69,6 +69,11 @@ export interface GraphBuildOptions {/** Replay unchanged files from the extraction cache instead of re-parsing them* (default true). False forces a cold parse of the whole repo. */reuse?: boolean;+ /** Write only what a query reads — the graph, the `ask` sidecar, the freshness+ * record — and skip the markdown projections and the `.gitignore` touch. Set by+ * the pre-query refresh (`graph/refresh.ts`); an explicit `graft build` never+ * sets it. See the write block in {@link buildGraph} for why the split exists. */+ graphOnly?: boolean;/** Run the Tier-2 LLM meaning pass. Absent → Tier-1 only (cache is still preserved). */summarizer?: CruxSummarizer;/** Max files summarized in parallel during the Tier-2 pass. Default is set in enrich. */@@ -140,10 +145,6 @@ export async function buildGraph(// fall out of both the cache and the fingerprint with no separate pruning pass.const priorExtract = opts.reuse === false ? emptyExtractCache() : readExtractCache(outDir);const entries: Record<string, ExtractEntry> = {};- // The Tier-2 pass reads source text for any node it must summarize, including- // one in a file we didn't re-parse — so when a summarizer is in play, read- // every file. Reading is ~0.05ms/file; parsing is the ~4.6ms we're skipping.- const needAllSources = !!opts.summarizer;let parsed = 0;let reused = 0;@@ -152,31 +153,32 @@ export async function buildGraph(opts.onProgress?.({ phase: "parse", index: i, total: files.length, file: rel });const lang = languageOf(f.abs)!;const cached = priorExtract.files[rel];- // `statUnchanged` is shared with the freshness probe on purpose: whatever the- // probe treats as "moved" must be something this loop will actually re-read,- // or a query rebuilds forever and still answers from the old parse.- const unchanged = !!cached && statUnchanged(cached, f);- let source: string | null = null;- if (!unchanged || needAllSources) {- try {- source = readFileSync(f.abs, "utf8");- } catch (err) {- const message = `${rel}: ${err instanceof Error ? err.message : String(err)}`;- errors.push(message);- // Record it anyway (with the stat we do have) so the freshness probe's- // fast path doesn't report this file as new on every single query.- entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash: "", nodes: [], rawEdges: [], error: message };- return;- }+ // Every file is read and hashed, every build — only the *parse* is memoized.+ // The tempting optimization is to trust the probe's `(size, mtimeMs)` and skip+ // the read too, but then `graft build` inherits the probe's blind spot: on a+ // filesystem with coarse mtime granularity, a same-length edit inside the same+ // second is invisible, so `graft check` reports drift (it always re-hashes) and+ // the `graft build` it tells you to run refuses to repair it — forever. A stat+ // may decide whether a *query* bothers rebuilding; it may not decide what the+ // rebuild itself looks at. Reading is ~0.05ms/file against the ~4.6ms parse+ // this still skips.+ let source: string;+ try {+ source = readFileSync(f.abs, "utf8");+ } catch (err) {+ const message = `${rel}: ${err instanceof Error ? err.message : String(err)}`;+ errors.push(message);+ // Record it anyway (with the stat we do have) so the freshness probe's+ // fast path doesn't report this file as new on every single query.+ entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash: "", nodes: [], rawEdges: [], error: message };+ return;}- // A stat mismatch is only a *suspicion*; confirm by bytes so a touch, or a- // checkout that restores identical content, still replays the cache.- const hash = source === null ? cached!.hash : contentHash(source);+ const hash = contentHash(source);if (cached && hash === cached.hash) {entries[rel] = { ...cached, size: f.size, mtimeMs: f.mtimeMs };- if (source !== null) sources.set(rel, source);+ sources.set(rel, source);reused++;if (cached.error) {errors.push(cached.error); // this file failed to parse last time too@@ -190,10 +192,10 @@ export async function buildGraph(parsed++;try {- const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source!, lang);+ const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source, lang);nodes.push(...fileNodes);rawEdges.push(...fileEdges);- sources.set(rel, source!);+ sources.set(rel, source);langs.add(lang);entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash, nodes: fileNodes, rawEdges: fileEdges };} catch (err) {@@ -244,18 +246,13 @@ export async function buildGraph(edges,};- // ---- the ordered writes -------------------------------------------------- // Order is load-bearing, and it follows from what readers gate on. A reader- // decides whether it has a usable graph by reading wiring.json; everything else- // it consults is keyed to that. So: dependencies first, wiring.json second- // (atomically, so the flip is instantaneous), freshness third, projections last.-- // `ask`'s token/IDF sidecar — moves per-query corpus tokenization to build time- // (~45% of query time on a 32k-node graph, profiled). It must land BEFORE- // wiring.json: `readAskIndex` rejects a sidecar whose ids don't match the graph,- // and the fallback is badly degraded (the nodes on disk have no `body_text`, so- // live re-tokenization has no body and body-only matches vanish). Writing it- // first means "new graph ⇒ new sidecar" always holds.+ const graphPath = writeGraph(graph, outDir);+ // `ask`'s token/IDF sidecar — moves per-query corpus tokenization to build+ // time (~45% of query time on a 32k-node graph, profiled). Lives in the+ // cache dir; `ask` falls back to live tokenization when it's absent/stale.+ // Best-effort: wiring.json is already on disk at this point, so a sidecar+ // write failure (e.g. an unwritable cache dir) must not abort cards/index/+ // covers below — record it and keep going, same as other recoverable errors.//// MUST pass the in-memory `graph` here, never a re-read of wiringPath(outDir):// `writeGraph` strips `body_text` from what it serializes (dead weight once@@ -267,42 +264,32 @@ export async function buildGraph(errors.push(`ask-index: ${err instanceof Error ? err.message : String(err)}`);}- const graphPath = writeGraph(graph, outDir);- // The graph is a local, regenerable cache — make sure git ignores it. Runs on- // every build (cheap, idempotent), so a fresh clone's first build self-ignores.- ensureGitignored(root, outDir);-// The fingerprint claims exactly one thing: "the graph on disk was built from- // these source bytes." That is true as of the line above, so it is written here.- //- // It says nothing about the projections below, and that is the point. Writing it- // after them made a failure there — one read-only INDEX.md — strand freshness- // forever: every later query would re-probe dirty, retake the lock, redo edge- // resolution + enrichment + the ask index + every card, throw again, and answer- // from a graph that was in fact already current. Projection failures are reported- // (below, and surfaced by `refreshNote`), never expressed as permanent drift.+ // these source bytes." Nothing about the projections below — which is why it is+ // safe to write here, and why `graphOnly` builds (the query path, which stops+ // right after this line) are still recorded as fresh.writeFingerprint(outDir, entries);- // Tier-2 passive surface: project the nodes into per-file markdown cards, refresh- // the INDEX roster, and backfill concept nodes with their `covers:` list (the- // OKF↔Wiring link; a no-op on a $0 build with no concept nodes). Pure projection —- // no LLM, no network — and individually fallible: a read-only card, a card path- // colliding with a directory, or ENOSPC records an error and lets the rest proceed.+ // Tier-2 passive surface: project the nodes into per-file markdown cards, and+ // refresh the INDEX roster. Pure projection — no LLM, no network.+ //+ // Skipped entirely on the query path (`graphOnly`). Retrieval answers from+ // wiring.json and the ask sidecar; the markdown surface is for humans and for+ // the agent's own greps, and it is rebuilt by an explicit `graft build` — which+ // is what the Claude Code `Stop` hook already runs at the end of a turn. Keeping+ // it off the query path is what makes a refresh cheap, leaves the repo untouched+ // (`ensureGitignored` writes `.gitignore`, which a read has no business doing),+ // and means a failure here can never be triggered by a query.let cardStats: CardStats = { written: 0, pruned: 0, files: [] };- try {+ if (!opts.graphOnly) {+ // The graph is a local, regenerable cache — make sure git ignores it. Cheap and+ // idempotent, so a fresh clone's first build self-ignores.+ ensureGitignored(root, outDir);cardStats = writeCards(graph, outDir);- } catch (err) {- errors.push(`cards: ${err instanceof Error ? err.message : String(err)}`);- }- try {writeIndex(outDir, cardStats.files);- } catch (err) {- errors.push(`INDEX.md: ${err instanceof Error ? err.message : String(err)}`);- }- try {- errors.push(...writeCovers(graph, outDir).errors);- } catch (err) {- errors.push(`covers: ${err instanceof Error ? err.message : String(err)}`);+ // Backfill concept nodes with their `covers:` symbol/file:line list (the+ // OKF↔Wiring link). No-op when there are no concept nodes (a $0 build).+ writeCovers(graph, outDir);}const byKind = {} as Record<Kind, number>;diff --git a/src/graph/cards.ts b/src/graph/cards.tsindex 969f6200..c58e78b6 100644--- a/src/graph/cards.ts+++ b/src/graph/cards.ts@@ -143,14 +143,6 @@ function pruneEmptyDirs(outDir: string): void {if (existsSync(outDir)) visit(outDir);}-function readIfExists(path: string): string | null {- try {- return readFileSync(path, "utf8");- } catch {- return null;- }-}-/*** Write one wiring card per source file into `outDir`, mirroring the source tree,* and prune cards whose source no longer exists. Returns what changed.@@ -172,12 +164,7 @@ export function writeCards(graph: GraphV1, outDir: string): CardStats {const symbols = group.filter((n) => n.kind !== "file");const cardPath = cardPathFor(outDir, sourcePath);mkdirSync(dirname(cardPath), { recursive: true });- const rendered = renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []);- // Skip identical rewrites. Cards are a pure projection, so most of them are- // unchanged on a rebuild — and now that a rebuild can run before any query- // (graph/refresh.ts), churning every card's mtime would wake editors and file- // watchers on files that didn't actually change.- if (readIfExists(cardPath) !== rendered) writeFileSync(cardPath, rendered);+ writeFileSync(cardPath, renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []));written.add(cardPath);files.push({ card: relative(outDir, cardPath), path: sourcePath, symbols: symbols.length });}@@ -231,12 +218,7 @@ export function writeIndex(outDir: string, files: CardFileInfo[]): void {);}- // Same skip-if-identical rule as the cards themselves: a rebuild runs before every- // query now, and INDEX.md is a pure projection, so rewriting it unchanged would wake- // editors and file watchers on every single retrieval call.- const rendered = lines.join("\n");- const path = join(outDir, INDEX_FILE);- if (readIfExists(path) !== rendered) writeFileSync(path, rendered);+ writeFileSync(join(outDir, INDEX_FILE), lines.join("\n"));}/** One symbol a concept node covers: its name, kind, and `path:span` pointer. */@@ -257,19 +239,11 @@ export interface CoverRef {* A surgical frontmatter patch: the generated body and every other key are* preserved verbatim; only `covers` is added/replaced. Concept nodes are the* top-level `.md` files (cards live in subdirs; INDEX.md is skipped). On a $0- * structure-only build there are no concept nodes, so this is a no-op.- *- * These are the one thing under `graft/` a human writes by hand, and a rebuild now- * runs before every query rather than only on an explicit `graft build` — so this is- * careful twice over. It never writes a file whose bytes wouldn't change, and it- * refuses to touch a node whose frontmatter didn't parse: `matter()` reports- * unparseable YAML by handing back zero keys and folding the whole `---` block into- * the content, so re-stringifying would prepend a *second* frontmatter block and- * bury the author's own text. Those are reported and skipped.+ * structure-only build there are no concept nodes, so this is a no-op. Returns+ * the number of nodes enriched.*/-export function writeCovers(graph: GraphV1, outDir: string): { enriched: number; errors: string[] } {- const errors: string[] = [];- if (!existsSync(outDir)) return { enriched: 0, errors };+export function writeCovers(graph: GraphV1, outDir: string): number {+ if (!existsSync(outDir)) return 0;const symbolsByPath = new Map<string, NodeV1[]>();for (const n of graph.nodes) {@@ -286,23 +260,7 @@ export function writeCovers(graph: GraphV1, outDir: string): { enriched: number;for (const entry of readdirSync(outDir)) {if (!entry.endsWith(".md") || entry === INDEX_FILE) continue;const full = join(outDir, entry);- const raw = readIfExists(full);- if (raw === null) continue;-- let parsed: matter.GrayMatterFile<string>;- try {- parsed = matter(raw);- } catch (err) {- errors.push(`${entry}: frontmatter unreadable, left untouched — ${err instanceof Error ? err.message : String(err)}`);- continue;- }- // Delimiters present but nothing parsed out of them: broken YAML. Rewriting would- // stack a new block on top of the old text instead of patching it.- if (raw.startsWith("---") && Object.keys(parsed.data).length === 0) {- errors.push(`${entry}: frontmatter did not parse, left untouched (fix its YAML to get \`covers:\`)`);- continue;- }-+ const parsed = matter(readFileSync(full, "utf8"));const sources = Array.isArray(parsed.data.sources)? (parsed.data.sources as Array<{ path?: string }>): [];@@ -316,10 +274,8 @@ export function writeCovers(graph: GraphV1, outDir: string): { enriched: number;// Re-stringify with covers appended last, so re-runs produce a stable diff.const { covers: _prev, ...rest } = parsed.data as Record<string, unknown>;- const rendered = matter.stringify(parsed.content, { ...rest, covers });- if (rendered === raw) continue; // nothing moved — don't touch the author's file- writeFileSync(full, rendered);+ writeFileSync(full, matter.stringify(parsed.content, { ...rest, covers }));enriched++;}- return { enriched, errors };+ return enriched;}diff --git a/src/graph/fingerprint.ts b/src/graph/fingerprint.tsindex 7823c6ea..7de3928b 100644--- a/src/graph/fingerprint.ts+++ b/src/graph/fingerprint.ts@@ -100,14 +100,12 @@ export function alwaysHash(): boolean {* May a recorded `(size, mtimeMs, hash)` be trusted for the file `f` as it is on* disk now, without reading it?*- * **One definition, shared by the probe and the builder.** They each had their own- * once, and the two disagreed in both directions: `GRAFT_REFRESH=hash` was honored- * here but not in `build.ts` (so the probe reported drift the rebuild then refused- * to repair — a rebuild on every query, forever, still answering from pre-edit- * code), and `build.ts` distrusted entries from a failed read while the probe- * fast-pathed them (so a `chmod +r` that fixed a file was never noticed, because a- * chmod changes neither size nor mtime). Any future rule about what a stat can be- * trusted for belongs here and nowhere else.+ * **The probe's rule only.** `buildGraph` deliberately does not use this: it reads+ * and hashes every file, every time. A stat may decide whether a query bothers+ * rebuilding; it may not decide what the rebuild itself looks at — otherwise+ * `graft check` (which always re-hashes) can report drift that the `graft build` it+ * recommends then refuses to repair. `GRAFT_REFRESH=hash` is the escape hatch for+ * the probe's blind spot: a same-length edit inside one mtime tick.** An empty `hash` means the last build never got the bytes — always re-read.* A *parse* failure keeps its real hash, so it stays on the fast path: re-readingdiff --git a/src/graph/refresh.ts b/src/graph/refresh.tsindex 6d89e7ff..99c78c81 100644--- a/src/graph/refresh.ts+++ b/src/graph/refresh.ts@@ -19,16 +19,22 @@* - **Never a stampede.** It takes the same `graft/.cache/.sync.lock` the* background sync uses, so concurrent MCP calls and the Stop hook can't pile up* rebuilds on top of each other.+ * - **Writes only what a query reads** (`graphOnly`): the graph, the `ask` sidecar,+ * the freshness record. Not the markdown cards, not `INDEX.md`, not `.gitignore`.+ * Those belong to an explicit `graft build` — which the `Stop` hook already runs+ * at the end of a turn — so retrieval stays cheap and a read stays a read. It+ * also leaves `stats.json` alone, so that same `Stop` hook still sees `dirty` and+ * still rebuilds the passive surface.*/import { existsSync } from "node:fs";import { join, resolve } from "node:path";import { contextDirFor } from "../context/node-file.js";-import { acquireLockIn, computeStats, patchStats, readStats, releaseLockIn } from "../util/state.js";+import { acquireLockIn, releaseLockIn } from "../util/state.js";import { CACHE_DIR } from "../context/node-file.js";import { buildGraph } from "./build.js";import { driftCount, isClean, probeDrift, type Drift } from "./fingerprint.js";import { invalidateGraphCaches } from "./load.js";-import { readGraph, wiringPath } from "./write.js";+import { wiringPath } from "./write.js";/** How long to wait for another process's in-flight rebuild before giving up and* answering from the current graph. Long enough to ride out a small repo's build,@@ -43,10 +49,6 @@ export interface RefreshResult {drift?: Drift;/** One-line explanation for the agent/user, when there's something worth saying. */note?: string;- /** Recoverable failures from the rebuild — a card that couldn't be written, a- * concept node whose frontmatter didn't parse. The graph is fine; a projection- * under `graft/` isn't, and nothing else would ever report it. */- errors?: string[];}export interface RefreshOptions {@@ -152,15 +154,14 @@ export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}):invalidateGraphCaches(outDir);return CLEAN;}- // Tier-1 only: no summarizer, so no LLM call and no network, ever.- const built = await buildGraph(dir, { contextDir: opts.contextDir });+ // Tier-1 only: no summarizer, so no LLM call and no network, ever. And+ // `graphOnly`: write the graph, the ask sidecar and the fingerprint, nothing+ // else. The markdown projections under `graft/` stay the `Stop` hook's job —+ // a query has no business rewriting the repo's `.gitignore` or churning every+ // card's mtime, and skipping them is most of what keeps this cheap.+ await buildGraph(dir, { contextDir: opts.contextDir, graphOnly: true });invalidateGraphCaches(outDir);- syncStats(dir, outDir);- // The graph itself is current, but a projection under `graft/` may have failed- // (a read-only card, ENOSPC). That can't be expressed as staleness — the- // fingerprint is written and the next probe is clean by design — so say it out- // loud instead of letting the passive markdown surface rot in silence.- return { refreshed: true, drift: drift ?? undefined, errors: built.errors };+ return { refreshed: true, drift: drift ?? undefined };} finally {unhook();releaseLockIn(lockCache);@@ -171,26 +172,6 @@ export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}):}}-/** Mirror what the background sync writes, so the statusline flips to `✓ synced`- * mid-turn instead of showing `⚠ stale` until the turn ends. Best-effort: this is- * a display cache, and the stats file only exists in a hooked-up repo anyway. */-function syncStats(dir: string, outDir: string): void {- try {- if (!readStats(dir)) return; // no hooks in this repo — nothing reads it- const w = readGraph(wiringPath(outDir));- if (!w) return;- patchStats(dir, {- dirty: false,- staleCount: 0,- syncing: false,- syncedAt: new Date().toISOString(),- ...computeStats(w),- });- } catch {- /* display-only — never let this fail a query */- }-}-/*** Workspace variant: refresh each child repo's own graph (a workspace parent holds* an index, never nodes). Children are independent, but they're refreshed in@@ -228,17 +209,8 @@ export async function ensureFreshChildren(/** The one-line note a CLI/MCP surface prints when a refresh actually happened.* Null when there's nothing to say (the overwhelmingly common case). */export function refreshNote(r: RefreshResult): string | null {- if (r.note) return `[graft] ${r.note}${errorTail(r)}`;+ if (r.note) return `[graft] ${r.note}`;if (!r.refreshed) return null;const n = r.drift ? driftCount(r.drift) : 0;- return `[graft] refreshed the graph (${n || "?"} file${n === 1 ? "" : "s"} changed) before answering${errorTail(r)}`;-}--/** Projection failures, condensed. The first one is usually the whole story (they- * share a cause — a permission, a full disk), so name it and count the rest. */-function errorTail(r: RefreshResult): string {- const errs = r.errors ?? [];- if (!errs.length) return "";- const more = errs.length > 1 ? ` (+${errs.length - 1} more)` : "";- return `; ${errs.length} write error${errs.length === 1 ? "" : "s"} under graft/: ${errs[0]}${more}`;+ return `[graft] refreshed the graph (${n || "?"} file${n === 1 ? "" : "s"} changed) before answering`;}diff --git a/src/graph/write.ts b/src/graph/write.tsindex 05c080a0..8b993a88 100644--- a/src/graph/write.ts+++ b/src/graph/write.ts@@ -8,9 +8,8 @@* timestamps, so rebuilding an unchanged repo produces a byte-identical file and* git diffs stay minimal.*/-import { readFileSync } from "node:fs";-import { join } from "node:path";-import { writeFileAtomic } from "../util/state.js";+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { dirname, join } from "node:path";import type { EdgeV1, GraphV1, NodeV1 } from "./types.js";/** Hidden subdir under the context dir that holds machine-only graph artifacts. */@@ -41,12 +40,8 @@ export function writeGraph(graph: GraphV1, outDir: string): string {edges: [...graph.edges].sort(edgeOrder),};const path = wiringPath(outDir);- // Atomic, because a query can now rebuild the graph (`graph/refresh.ts`) while- // something else is reading it — a second MCP call, the statusline's poll, a- // `graft check` from the edit hook, another graft process. None of those take- // the build lock, and a truncating write would hand them a partial document,- // which `readGraph` can only report as "no graph — run graft build".- writeFileAtomic(path, JSON.stringify(sorted, null, 2) + "\n");+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");return path;}diff --git a/src/util/state.ts b/src/util/state.tsindex cd33f1e2..0f309d4c 100644--- a/src/util/state.ts+++ b/src/util/state.ts@@ -11,7 +11,6 @@*/import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';import { join, dirname } from 'node:path';-import type { GraphV1 } from '../graph/types.js';export interface Stats {nodeCount: number; edgeCount: number; languages: string[];@@ -36,33 +35,24 @@ export function readJson<T>(p: string): T | null {try { return JSON.parse(readFileSync(p, 'utf8')) as T; } catch { return null; }}/**- * Write `text` to `p` so a concurrent reader sees either the whole old file or the- * whole new one — never a truncated prefix.+ * Write JSON to `p` via a scratch file and a rename, so a concurrent reader sees+ * either the whole old file or the whole new one — never a truncated prefix. The+ * pid in the temp name keeps two concurrent writers off each other's scratch file.*- * `writeFileSync` truncates the destination to zero and *then* streams bytes into- * it, so for the milliseconds that takes, anyone who opens the path reads a partial- * document. Writing to a scratch file and renaming over the target avoids that- * entirely: `rename` within a filesystem is atomic, and it replaces the directory- * entry rather than modifying the file in place, so a reader that already opened- * the old file keeps reading a complete one.- *- * The pid in the temp name keeps two concurrent writers off each other's scratch- * file. This is the only atomic-write implementation in the codebase on purpose —- * `graph/write.ts` uses it for `wiring.json` and `ask/index-file.ts` for the sidecar- * that has to agree with it, both of which a query can now rewrite while the- * statusline, a second graft process, or another MCP call is reading them.+ * `compact` drops the indentation, for the caches only a machine ever opens —+ * it's ~30% of the bytes on a big, deep object.** A failed write takes its scratch file with it. Every CLI invocation is a new pid,* so the names never collide and never get reused: leaving them behind means a repo- * that fails this write once per query (ENOSPC, or a Windows indexer holding the- * target open) accumulates one full-size copy of the graph per query, and nothing- * in graft ever lists `.graph/` or `.cache/` to clean them up.+ * that fails this write repeatedly (ENOSPC, or a Windows indexer holding the target+ * open) accumulates one full-size file per attempt, and nothing in graft ever lists+ * `.cache/` to clean them up.*/-export function writeFileAtomic(p: string, text: string): void {+export function writeJsonAtomic(p: string, value: unknown, compact = false): void {mkdirSync(dirname(p), { recursive: true });const tmp = `${p}.${process.pid}.tmp`;try {- writeFileSync(tmp, text);+ writeFileSync(tmp, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));renameSync(tmp, p);} catch (e) {try { rmSync(tmp, { force: true }); } catch { /* nothing more we can do */ }@@ -70,12 +60,6 @@ export function writeFileAtomic(p: string, text: string): void {}}-/** {@link writeFileAtomic} for JSON. `compact` drops the indentation, for the- * caches only a machine ever opens — it's ~30% of the bytes on a big, deep object. */-export function writeJsonAtomic(p: string, value: unknown, compact = false): void {- writeFileAtomic(p, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));-}-export function readStats(d: string): Stats | null { return readJson<Stats>(statsPath(d)); }export function writeStats(d: string, s: Stats): void { writeJsonAtomic(statsPath(d), s); }// Best-effort read-modify-write; not atomic across concurrent processes, but acceptable@@ -119,20 +103,3 @@ export function acquireLockIn(cache: string): boolean {export function releaseLockIn(cache: string): void {try { rmSync(join(cache, LOCK_FILE)); } catch { /* already gone */ }}--/** The graph-derived half of {@link Stats} — everything the statusline shows that- * isn't drift state. Lives here so the hooks and the pre-query auto-refresh report- * identical numbers. */-export function computeStats(- w: GraphV1,-): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'> {- const nodes = w.nodes ?? [];- const edges = w.edges ?? [];- return {- nodeCount: w.meta?.nodeCount ?? nodes.length,- edgeCount: w.meta?.edgeCount ?? edges.length,- languages: w.meta?.languages ?? [],- totalCount: nodes.length,- readyCount: nodes.filter((n) => n.summary_state === 'ready').length,- };-}diff --git a/test/claude-state.test.ts b/test/claude-state.test.tsindex a4900cc8..4d052edd 100644--- a/test/claude-state.test.ts+++ b/test/claude-state.test.ts@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import {emptyStats, readStats, writeStats, patchStats,- readSession, writeSession, acquireLock, releaseLock, cacheDir, LOCK_STALE_MS, writeFileAtomic,+ readSession, writeSession, acquireLock, releaseLock, cacheDir, LOCK_STALE_MS, writeJsonAtomic,} from '../src/claude/state.js';function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-state-')); }@@ -49,7 +49,7 @@ test('acquireLock reclaims a stale lock', () => {assert.equal(acquireLock(d), true, 'stale lock reclaimed');});-test('writeFileAtomic leaves no scratch file behind when the write fails', (t) => {+test('writeJsonAtomic leaves no scratch file behind when the write fails', (t) => {if (process.getuid?.() === 0) return t.skip('root writes anywhere, so a read-only dir proves nothing');const d = fresh();const dir = join(d, 'locked');@@ -57,10 +57,10 @@ test('writeFileAtomic leaves no scratch file behind when the write fails', (t) =chmodSync(dir, 0o500);// Every CLI invocation is a new pid, so a repeatedly failing write would leave one- // full-size `<path>.<pid>.tmp` per query, and nothing in graft ever lists these+ // full-size `<path>.<pid>.tmp` per attempt, and nothing in graft ever lists these// directories to clean them up — on a nearly-full disk that accelerates the ENOSPC// that caused it.- assert.throws(() => writeFileAtomic(join(dir, 'out.json'), 'x'.repeat(1024)));+ assert.throws(() => writeJsonAtomic(join(dir, 'out.json'), { pad: 'x'.repeat(1024) }));chmodSync(dir, 0o700);assert.deepEqual(readdirSync(dir), [], 'no .tmp residue');});diff --git a/test/covers.test.ts b/test/covers.test.tsindex 3cea34a6..6a9139fa 100644--- a/test/covers.test.ts+++ b/test/covers.test.ts@@ -5,7 +5,7 @@*/import { test } from "node:test";import assert from "node:assert/strict";-import { mkdtempSync, writeFileSync, readFileSync, rmSync, statSync } from "node:fs";+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";import { join } from "node:path";import { tmpdir } from "node:os";import matter from "gray-matter";@@ -74,56 +74,3 @@ test("re-running the wiring build leaves covers byte-stable", async () => {rmSync(dir, { recursive: true, force: true });}});--/**- * Concept nodes are the one thing under `graft/` a human writes by hand, and a- * rebuild now runs before every *query* rather than only on an explicit build. So- * the projection has to leave alone anything it isn't actually changing, and refuse- * to touch what it can't round-trip.- */-test("a rebuild leaves untouched concept nodes and INDEX.md alone", async () => {- const dir = makeFixture();- try {- await buildContext(dir, { model: "fake", ...fakeProviders() });- await buildGraph(dir);-- const node = join(dir, "graft", "auth-service.md");- const index = join(dir, "graft", "INDEX.md");- const before = { node: statSync(node).mtimeMs, index: statSync(index).mtimeMs };-- // Nothing about the repo changed, so nothing under graft/ should be rewritten:- // every rewrite wakes editors and file watchers, once per query.- await new Promise((r) => setTimeout(r, 12)); // let the clock move- await buildGraph(dir);-- assert.equal(statSync(node).mtimeMs, before.node, "concept node was rewritten with identical bytes");- assert.equal(statSync(index).mtimeMs, before.index, "INDEX.md was rewritten with identical bytes");- } finally {- rmSync(dir, { recursive: true, force: true });- }-});--test("a concept node whose frontmatter does not parse is reported, not overwritten", async () => {- const dir = makeFixture();- try {- await buildContext(dir, { model: "fake", ...fakeProviders() });- await buildGraph(dir);-- // Frontmatter delimiters, but YAML that yields no keys. gray-matter reports that- // by handing back zero data and folding the whole block into the content, so- // re-stringifying would stack a SECOND `---` block on top of the author's text.- const broken = join(dir, "graft", "hand-written.md");- const raw = "---\nname: [unclosed\n bad: : :\n---\n\nSome prose I wrote myself.\n";- writeFileSync(broken, raw);-- const built = await buildGraph(dir);-- assert.equal(readFileSync(broken, "utf8"), raw, "the author's file must come back byte-identical");- assert.ok(- built.errors.some((e) => e.startsWith("hand-written.md:") && /did not parse/.test(e)),- `and the skip must be reported: ${JSON.stringify(built.errors)}`,- );- } finally {- rmSync(dir, { recursive: true, force: true });- }-});diff --git a/test/graph-incremental.test.ts b/test/graph-incremental.test.tsindex ebc21b2a..783478ce 100644--- a/test/graph-incremental.test.ts+++ b/test/graph-incremental.test.ts@@ -296,29 +296,55 @@ test("with no extractor identity, nothing is memoized — and 'unknown' is neverassert.equal(stampDir(mkdtempSync(join(tmpdir(), "graft-empty-")), ".js"), null, "an empty dir has no identity");});-test("the ask sidecar lands before the graph, and lands atomically", async () => {+test("an incremental rebuild leaves the ask sidecar agreeing with the graph", async () => {const d = repo();await buildGraph(d);- const idxPath = join(outOf(d), ".cache", "ask-index.json");- const before = statSync(idxPath).ino;writeFileSync(join(d, "src", "math.ts"), `${MATH}export function mul(a: number): number {\n return a * 2;\n}\n`);- await buildGraph(d);-- // Atomic: replaced by rename, not truncated in place. A reader that catches this- // file mid-write gets a parse error, which `readAskIndex` can only report as "no- // sidecar" — and the fallback is degraded, because wiring.json's nodes have had- // `body_text` stripped, so body-only matches disappear.- assert.notEqual(statSync(idxPath).ino, before);- assert.deepEqual(readdirSync(join(outOf(d), ".cache")).filter((f) => f.includes(".tmp")), []);+ await buildGraph(d); // warm: math.ts re-parsed, everything else replayed- // Written first, so "new graph ⇒ matching sidecar" holds for anyone reading the- // pair. mtime ordering is the observable proxy for the write order.- assert.ok(- statSync(idxPath).mtimeMs <= statSync(wiringPath(outOf(d))).mtimeMs,- "the sidecar must not be newer than the graph it describes",- );+ // The sidecar is built from the in-memory graph, never from a re-read of+ // wiring.json (whose nodes have had `body_text` stripped), so a replayed node+ // has to arrive with its body intact for the pair to agree.const idx = readAskIndex(outOf(d));const g = readGraph(wiringPath(outOf(d))) as GraphV1;- assert.equal(idx?.docs.length, g.nodes.length, "and the pair agrees");+ assert.equal(idx?.docs.length, g.nodes.length, "the pair agrees on the node set");+ assert.ok(idx!.docs.some((doc) => doc.id.endsWith("#mul")), "including the new symbol");+});++/**+ * `graft check` re-reads and re-hashes every file; the builder must too. If the+ * builder trusted `(size, mtimeMs)` the way the probe does, then on a filesystem with+ * coarse mtime granularity a same-length edit inside one tick would leave `graft+ * check` reporting drift that the `graft build` it recommends could not repair — the+ * documented fix, doing nothing, forever.+ */+test("a build repairs an edit that leaves size and mtime untouched", async () => {+ const d = repo();+ await buildGraph(d);+ const file = join(d, "src", "math.ts");+ const size = statSync(file).size;++ // A rename to a same-length name.+ writeFileSync(file, readFileSync(file, "utf8").replace("export function add", "export function sum"));+ assert.equal(statSync(file).size, size, "the edit is size-neutral");++ // Now make the memo's record match the file's stat *as it is now* while keeping the+ // pre-edit hash and nodes. That is precisely the state a 1s-granularity mount hands+ // you for free, and it avoids `utimesSync`, whose float-seconds round-trip can't+ // reproduce an mtimeMs exactly.+ const memoPath = extractCachePath(outOf(d))!;+ const memo = JSON.parse(readFileSync(memoPath, "utf8")) as {+ files: Record<string, { size: number; mtimeMs: number }>;+ };+ const now = statSync(file);+ memo.files["src/math.ts"].size = now.size;+ memo.files["src/math.ts"].mtimeMs = now.mtimeMs;+ writeFileSync(memoPath, JSON.stringify(memo));++ const r = await buildGraph(d);+ assert.equal(r.parsed, 1, "the file was re-parsed despite the identical stat");+ const ids = (readGraph(wiringPath(outOf(d))) as GraphV1).nodes.map((n) => n.id);+ assert.ok(ids.includes("src/math.ts#sum"), "and the graph reflects the rename");+ assert.equal(ids.includes("src/math.ts#add"), false, "the old symbol is gone");});diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.tsindex 358003a6..ef7b5e9c 100644--- a/test/graph-refresh.test.ts+++ b/test/graph-refresh.test.ts@@ -144,7 +144,16 @@ test("a rebuild already in flight is waited out, then reported — never a hang"assert.ok(waited >= 1000 && waited < 10000, `should wait out the lock briefly, waited ${waited}ms`);});-test("a refresh updates the statusline stats, but only where they already exist", async () => {+/**+ * The gate must leave `stats.json` completely alone, and this is load-bearing rather+ * than merely tidy. `handleStop` only spawns the end-of-turn `graft build` when+ * `stats.dirty` is set. A refresh writes the graph but deliberately not the markdown+ * projections, so if it cleared `dirty` — which is exactly what "flip the statusline+ * to ✓ synced mid-turn" would mean — the one thing that rebuilds `graft/`'s cards+ * and INDEX.md would stop running, and the passive surface an agent greps would+ * never catch up.+ */+test("a refresh leaves the statusline stats alone, so the Stop hook still fires", async () => {const d = repo();await buildGraph(d);writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);@@ -153,16 +162,15 @@ test("a refresh updates the statusline stats, but only where they already exist"await ensureFreshGraph(d);assert.equal(readStats(d), null);- // With one, the refresh clears the drift flags the edit hook set mid-turn —- // that's what flips the statusline from `⚠ stale` to `✓ synced`.writeStats(d, { ...emptyStats(), dirty: true, staleCount: 3 });writeFileSync(join(d, "src", "math.ts"), `${MATH}export const Y = 2;\n`);- await ensureFreshGraph(d);+ const r = await ensureFreshGraph(d);+ assert.equal(r.refreshed, true, "the graph itself was rebuilt");+const s = readStats(d);- assert.equal(s?.dirty, false);- assert.equal(s?.staleCount, 0);- assert.ok((s?.nodeCount ?? 0) > 0, "and it refreshes the counts from the new graph");- assert.ok(s?.syncedAt);+ assert.equal(s?.dirty, true, "still dirty — the passive surface has not been rebuilt");+ assert.equal(s?.staleCount, 3, "and the edit hook's count is not overwritten");+ assert.equal(s?.syncedAt, null);});test("a failed rebuild still answers from the graph on disk", async (t) => {@@ -173,14 +181,11 @@ test("a failed rebuild still answers from the graph on disk", async (t) => {writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);// Make the graph write itself fail: the query must degrade to the old graph, not- // start erroring because a rebuild couldn't happen. The *directory* is what has- // to be blocked — `writeGraph` installs the new graph with tmp+rename now (see- // `graph-write-atomic.test.ts`), and both the scratch write and the rename need- // write permission on the directory, while the old file's own mode is irrelevant.- const graphDir = dirname(wiringPath(outOf(d)));- chmodSync(graphDir, 0o500);+ // start erroring because a rebuild couldn't happen.+ const graphFile = wiringPath(outOf(d));+ chmodSync(graphFile, 0o400);const r = await ensureFreshGraph(d);- chmodSync(graphDir, 0o700);+ chmodSync(graphFile, 0o600);assert.equal(r.refreshed, false);assert.match(r.note ?? "", /refresh skipped/);@@ -259,17 +264,14 @@ test("a file that becomes readable again is picked up through the probe", asyncassert.equal(hasSymbol(d, "src/hidden.ts#reachable"), true);});-test("the fingerprint is written even when the extract memo can't be", async (t) => {+test("an unwritable cache costs reuse, not correctness", async (t) => {if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only dir proves nothing");const d = repo();await buildGraph(d);- // An unwritable memo costs the next build its reuse. It must not cost every future- // query a full cold rebuild, which is what gating the fingerprint on it did.- //// The write has to be made to fail for real. An earlier version of this test- // chmod'd extract.json itself — useless, because `writeExtractCache` goes through- // `writeFileAtomic`, and rename(2) needs write permission on the *directory*, not+ // chmod'd extract.json itself — useless, because the sidecars go out through+ // `writeJsonAtomic`, and rename(2) needs write permission on the *directory*, not// on the file. It returned true, the test passed, and it would have passed against// the pre-fix code too.const cache = join(outOf(d), ".cache");@@ -279,56 +281,70 @@ test("the fingerprint is written even when the extract memo can't be", async (t)writeFileSync(join(d, "src", "math.ts"), `${MATH}${MUL}`);chmodSync(cache, 0o500);- const built = await buildGraph(d);+ await buildGraph(d);chmodSync(cache, 0o700);assert.equal(readFileSync(memo, "utf8"), before, "the memo really could not be written");assert.ok(hasSymbol(d, "src/math.ts#mul"), "but the graph itself was rebuilt");- // The fingerprint lives in the same unwritable dir, so it couldn't be written- // either — the invariant that matters is that the NEXT build (with the dir- // writable again) lays one down and the query path settles.+ // Losing the memo and the fingerprint is a performance failure, not a correctness+ // one: the next query rebuilds because it can't prove it doesn't need to. Once the+ // directory is writable again the fast path comes back on its own.await buildGraph(d);const drift = probeDrift(d, outOf(d));assert.ok(drift, "a fingerprint exists, so the probe has a fast path");assert.ok(isClean(drift), "and it says the graph matches the tree");assert.deepEqual((await ensureFreshGraph(d)).refreshed, false, "so a query stops rebuilding");- // The memo is the only thing whose loss is silent (it costs reuse, nothing else).- // The ask sidecar lives in the same directory and *is* worth reporting, because- // losing it degrades ranking rather than just performance.- assert.ok(- built.errors.some((e) => e.startsWith("ask-index:")),- `the sidecar failure is reported: ${JSON.stringify(built.errors)}`,- );});-test("a failed projection is reported, and never becomes permanent drift", async (t) => {- if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only file proves nothing");+/**+ * The query path writes the graph, the ask sidecar and the fingerprint — and stops.+ * Cards and INDEX.md are what a human reads and what the agent greps; they are+ * rebuilt by an explicit `graft build`, which is what the `Stop` hook runs at the+ * end of a turn. Keeping them off the query path is what makes a refresh cheap, and+ * it means a read-only card or an unparseable hand-written concept node can never be+ * reached — let alone made permanent — by a retrieval call.+ */+test("a refresh rebuilds the graph but not the markdown projections", async () => {const d = repo();await buildGraph(d);- // One unwritable file under graft/ — a dir you don't fully own, a read-only mount.const index = join(outOf(d), "INDEX.md");- assert.ok(existsSync(index));- chmodSync(index, 0o400);- // A new file changes INDEX.md's roster, so the write is actually attempted —- // an unchanged render is skipped now, by design.+ const card = join(outOf(d), "src", "math.md");+ const newCard = join(outOf(d), "src", "extra.md");+ assert.ok(existsSync(index) && existsSync(card), "an explicit build wrote both");+ const indexBefore = readFileSync(index, "utf8");+ const cardBefore = readFileSync(card, "utf8");+writeFileSync(join(d, "src", "extra.ts"), MUL);+ const r = await ensureFreshGraph(d);- // The graph must still get built, the failure must be told to the caller, and the- // fingerprint must be laid down — otherwise every later query re-runs the whole- // post-extraction pipeline (edges, enrichment, ask index, every card), throws- // again, and answers from a graph that was already current. Forever.- const first = await ensureFreshGraph(d);- assert.equal(first.refreshed, true);+ assert.equal(r.refreshed, true);assert.equal(hasSymbol(d, "src/extra.ts#mul"), true, "the graph is current");- assert.ok(first.errors?.length, "the projection failure is reported");- assert.match(refreshNote(first) ?? "", /write error.* under graft\/: INDEX\.md/);+ assert.equal(existsSync(newCard), false, "no card for it yet");+ assert.equal(readFileSync(index, "utf8"), indexBefore, "INDEX.md untouched");+ assert.equal(readFileSync(card, "utf8"), cardBefore, "existing cards untouched");- const second = await ensureFreshGraph(d);- chmodSync(index, 0o600);- assert.equal(second.refreshed, false, "and it converges — no rebuild on the next query");- assert.equal(refreshNote(second), null);+ // An explicit build — the Stop hook's job — is what catches the surface up.+ await buildGraph(d);+ assert.equal(existsSync(newCard), true);+});++test("a refresh never writes the repo's .gitignore", async () => {+ const d = repo();+ await buildGraph(d); // an explicit build DOES self-ignore — that part is unchanged+ const ignore = join(d, ".gitignore");+ assert.match(readFileSync(ignore, "utf8"), /graft\//);++ // A repo that excludes graft/ some other way (.git/info/exclude, a global+ // core.excludesfile) and deliberately has no line here. A query is a read; it must+ // not hand the user an unexplained modification to a tracked file.+ rmSync(ignore);+ writeFileSync(join(d, "src", "math.ts"), `${MATH}${MUL}`);+ const r = await ensureFreshGraph(d);++ assert.equal(r.refreshed, true, "the refresh still happened");+ assert.equal(existsSync(ignore), false, "and it left .gitignore alone");});test("after waiting out another process's rebuild, the waiter does not rebuild too", async () => {diff --git a/test/graph-write-atomic.test.ts b/test/graph-write-atomic.test.tsdeleted file mode 100644index cf9357ba..00000000--- a/test/graph-write-atomic.test.ts+++ /dev/null@@ -1,148 +0,0 @@-/**- * `wiring.json` must never be observable half-written.- *- * This stopped being theoretical when a query gained the ability to rebuild the- * graph (`graph/refresh.ts`): the writer takes the build lock, but no reader does —- * not the statusline's poll, not a second MCP call, not another graft process, not- * `graft check` from the edit hook. A truncating write hands all of them a partial- * document, and `readGraph` can only report that as null, i.e. "no graph — run- * graft build" on a repo that has one.- */-import { test } from "node:test";-import assert from "node:assert/strict";-import { closeSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";-import { spawn } from "node:child_process";-import { tmpdir } from "node:os";-import { dirname, join } from "node:path";-import { readGraph, wiringPath, writeGraph } from "../src/graph/write.js";-import type { GraphV1, NodeV1 } from "../src/graph/types.js";--/** A graph big enough that serializing it isn't instantaneous — the race window- * has to be wide enough for a concurrent reader to land inside it. */-function graph(nodeCount: number, marker: string): GraphV1 {- const nodes: NodeV1[] = [];- for (let i = 0; i < nodeCount; i++) {- nodes.push({- id: `src/m${i}.ts#fn${i}`,- name: `fn${i}`,- kind: "function",- path: `src/m${i}.ts`,- start_line: 1,- end_line: 3,- signature: `function fn${i}(a: number): number`,- body_hash: `${marker}${i}`,- summary: null,- summary_state: "pending",- // Padding, so the file is megabytes rather than kilobytes.- doc: `${marker} `.repeat(40),- } as unknown as NodeV1);- }- return {- meta: { version: 1, nodeCount, edgeCount: 0, languages: ["ts"], scopes: [] },- nodes,- edges: [],- } as unknown as GraphV1;-}--function outDir(): string {- return join(mkdtempSync(join(tmpdir(), "graft-atomic-")), "graft");-}--test("writeGraph replaces the file instead of truncating it in place", () => {- const out = outDir();- writeGraph(graph(50, "a"), out);- const path = wiringPath(out);- const before = statSync(path).ino;-- writeGraph(graph(50, "b"), out);-- // A truncating `writeFileSync` keeps the same inode and empties it; a tmp+rename- // installs a different one. This is the whole difference, and it needs no timing- // to observe.- assert.notEqual(statSync(path).ino, before, "the destination must be replaced, not modified in place");- assert.equal(readGraph(path)?.nodes[0]?.body_hash, "b0");-- // And the scratch file must not be left lying around next to it.- const strays = readdirSync(dirname(path)).filter((f) => f.includes(".tmp"));- assert.deepEqual(strays, [], `left temp files behind: ${strays.join(", ")}`);-});--test("a reader holding the file open across a rewrite still reads a whole graph", () => {- const out = outDir();- writeGraph(graph(400, "a"), out);- const path = wiringPath(out);- const original = readFileSync(path, "utf8");-- // Exactly the statusline's position: it opened the file, and mid-read a query- // rebuilt the graph underneath it.- const fd = openSync(path, "r");- try {- const head = Buffer.alloc(64);- readSync(fd, head, 0, 64, 0); // started reading...- writeGraph(graph(400, "b"), out); // ...and the graph is rewritten now-- const size = statSync(path).size;- const rest = Buffer.alloc(original.length);- const n = readSync(fd, rest, 0, original.length, 0);- const seen = rest.subarray(0, n).toString("utf8");-- // The open handle keeps the file it opened: complete, parseable, and the- // version it started with. Under a truncating write this read would return the- // new file's bytes at old offsets — a spliced document that parses to nothing.- assert.equal(seen, original, "the reader must see the whole document it opened");- assert.equal(JSON.parse(seen).nodes[0].body_hash, "a0");- assert.ok(size > 0, "and the new file is fully on disk for the next reader");- assert.equal(readGraph(path)?.nodes[0]?.body_hash, "b0");- } finally {- closeSync(fd);- }-});--test("a concurrent reader never parses a torn graph", async () => {- const out = outDir();- writeGraph(graph(3000, "a"), out);- const path = wiringPath(out);- const bytes = statSync(path).size;- assert.ok(bytes > 1_000_000, `fixture should be megabytes to widen the window, got ${bytes}`);-- // A separate process, because writes here are synchronous — nothing in this- // process could observe a partial file even if one existed.- const READ_MS = 600;- const reader = spawn(- process.execPath,- [- "-e",- `const fs = require("fs");- let ok = 0, bad = 0, empty = 0;- const end = Date.now() + ${READ_MS};- while (Date.now() < end) {- let text;- try { text = fs.readFileSync(process.argv[1], "utf8"); } catch { bad++; continue; }- if (text.length === 0) { empty++; continue; }- try { JSON.parse(text); ok++; } catch { bad++; }- }- process.stdout.write(JSON.stringify({ ok, bad, empty }));`,- path,- ],- { stdio: ["ignore", "pipe", "inherit"] },- );- let stdout = "";- reader.stdout.setEncoding("utf8");- reader.stdout.on("data", (c: string) => (stdout += c));-- // Rewrite continuously for as long as it's reading.- const deadline = Date.now() + READ_MS;- let writes = 0;- while (Date.now() < deadline) {- writeGraph(graph(3000, writes % 2 === 0 ? "a" : "b"), out);- writes++;- }-- await new Promise<void>((resolve) => reader.on("close", () => resolve()));- const r = JSON.parse(stdout) as { ok: number; bad: number; empty: number };-- assert.ok(writes > 1, `the writer should have rewritten the file repeatedly, did ${writes}`);- assert.ok(r.ok > 0, `the reader should have read it repeatedly, got ${JSON.stringify(r)}`);- assert.equal(r.empty, 0, "no reader may ever see a zero-length graph");- assert.equal(r.bad, 0, `every read must parse; got ${JSON.stringify(r)} across ${writes} writes`);-});