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
fix the causes the second review found, not their symptoms
anirudhkumar-nanonets815e42fd7b21
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7b08951b..65686f0b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -24,10 +24,18 @@GRAFT_NO_REFRESH=1 # same, for every command in the process```-- **`wiring.json` is written atomically.** 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 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.### Addeddiff --git a/src/ask/index-file.ts b/src/ask/index-file.tsindex 6d414bbe..8a2f9b5d 100644--- a/src/ask/index-file.ts+++ b/src/ask/index-file.ts@@ -19,10 +19,11 @@* 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, mkdirSync, readFileSync, writeFileSync } from "node:fs";-import { dirname, join } from "node:path";+import { existsSync, readFileSync } from "node:fs";+import { 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([@@ -125,8 +126,14 @@ export function writeAskIndex(outDir: string, graph: GraphV1): string {};const outPath = askIndexPath(outDir);- mkdirSync(dirname(outPath), { recursive: true });- writeFileSync(outPath, JSON.stringify(index) + "\n");+ // 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");return outPath;}diff --git a/src/claude/hooks.ts b/src/claude/hooks.tsindex 822c5628..77bea591 100644--- a/src/claude/hooks.ts+++ b/src/claude/hooks.ts@@ -30,12 +30,51 @@ export function underGraft(dir: string, file: string): boolean {/** Default budget for a graft child process invoked from a hook, matching the 8s* the installed hook entries carry. */const CHILD_TIMEOUT_MS = 8000;-/** The prompt hook's `graft ask` gets longer: its hook entry is installed with a- * 15s budget (see `settings-merge.ts`) precisely because a query now brings the- * graph up to date first, and the first one after an upgrade re-parses the repo- * once. Kept under the outer budget so the killer is this timeout — which returns- * cleanly — rather than Claude Code cutting the hook off mid-write. */-const PROMPT_ASK_TIMEOUT_MS = 13000;+/** Headroom left for the hook's own work (read stdin, score, write session, emit)+ * after its `graft ask` child returns. */+const HOOK_OVERHEAD_MS = 2000;+/** Floor, so a hand-edited tiny timeout can't leave the child no time at all. */+const MIN_CHILD_TIMEOUT_MS = 4000;++/**+ * How long the prompt hook may let `graft ask` run — derived from the budget that is+ * *actually installed* in this repo's `.claude/settings.json`, not from what the+ * current version of `settings-merge.ts` would install.+ *+ * A query now brings the graph up to date first, so `graft init` raises the+ * UserPromptSubmit budget to 15s to cover the one cold rebuild after an upgrade. But+ * `mergeGraftSettings` only runs during `graft init` — upgrading the npm package does+ * not re-run it. So every repo wired before that change keeps `"timeout": 8000`, and+ * hard-coding a 13s child there means Claude Code kills the hook first: `emit()` and+ * `writeSession()` never run, the turn gets no retrieval pack at all, and the SIGKILLed+ * child can't even release the build lock. Reading the installed number keeps the child+ * strictly inside whatever budget this repo really has.+ */+export function promptAskTimeout(dir: string): number {+ const installed = installedHookTimeout(dir, 'UserPromptSubmit');+ if (installed === null) return CHILD_TIMEOUT_MS - HOOK_OVERHEAD_MS;+ return Math.max(MIN_CHILD_TIMEOUT_MS, installed - HOOK_OVERHEAD_MS);+}++/** The timeout on this repo's graft hook entry for `event`, or null if it can't be+ * read (no settings file, hand-edited shape, unparseable JSON). */+function installedHookTimeout(dir: string, event: string): number | null {+ try {+ const settings = JSON.parse(readFileSync(join(dir, '.claude', 'settings.json'), 'utf8')) as any;+ const blocks = settings?.hooks?.[event];+ if (!Array.isArray(blocks)) return null;+ for (const block of blocks) {+ for (const h of block?.hooks ?? []) {+ if (typeof h?.command === 'string' && h.command.includes('graft-hooks.cjs') && typeof h.timeout === 'number') {+ return h.timeout;+ }+ }+ }+ return null;+ } catch {+ return null;+ }+}function graftJson(dir: string, args: string[], timeout: number = CHILD_TIMEOUT_MS): any | null {try {@@ -184,7 +223,7 @@ export async function main(event: string): Promise<void> {// repo whose lastFile resolves cleanly to one scope — see lastFileScopeHint.const scopeHint = lastFileScopeHint(dir, readStats(dir)?.lastFile);if (scopeHint) askArgs.push('--in', scopeHint);- const ask = graftJson(dir, askArgs, PROMPT_ASK_TIMEOUT_MS);+ const ask = graftJson(dir, askArgs, promptAskTimeout(dir));if (!ask) return;const id = input.session_id || 'default';const s = readSession(dir, id);diff --git a/src/claude/settings-merge.ts b/src/claude/settings-merge.tsindex 76c944ea..bf6810be 100644--- a/src/claude/settings-merge.ts+++ b/src/claude/settings-merge.ts@@ -20,9 +20,11 @@ function graftBlocks(): Record<string, Json[]> {// Longer budget than the other hooks: its `graft ask` is a real query, and a// query now brings the graph up to date first (graph/refresh.ts) — usually// milliseconds, but the first one after an upgrade re-parses the repo once.- // Paired with `PROMPT_ASK_TIMEOUT_MS` in hooks.ts, which caps the child a- // little under this; raising one without the other buys nothing, because- // whichever limit is lower is the one that fires.+ // `hooks.ts` reads this number back out of the installed settings.json at+ // runtime and caps its `graft ask` child just under it, so a repo wired before+ // this bump (8s) keeps a child that fits inside 8s. Changing the number here is+ // therefore safe on its own — but it only reaches an existing repo when someone+ // re-runs `graft init`, since that is the only caller of this function.UserPromptSubmit: [{ hooks: [{ type: 'command', command: hookCmd('prompt'), timeout: 15000 }] }],SessionStart: [{ hooks: [{ type: 'command', command: hookCmd('session-start'), timeout: 8000 }] }],Stop: [{ hooks: [{ type: 'command', command: hookCmd('stop'), timeout: 8000 }] }],diff --git a/src/claude/state.ts b/src/claude/state.tsindex 2b1290a1..19c305bf 100644--- a/src/claude/state.ts+++ b/src/claude/state.ts@@ -17,6 +17,7 @@ export {patchStats,readStats,releaseLock,+ writeFileAtomic,writeStats,} from '../util/state.js';export type { Stats } from '../util/state.js';diff --git a/src/graph/build.ts b/src/graph/build.tsindex 77e48e9b..2145675d 100644--- a/src/graph/build.ts+++ b/src/graph/build.ts@@ -30,7 +30,7 @@ import { listSourceStats } from "./source-files.js";import { resolveEdges, type GoModule } from "./resolve.js";import { enrichGraph, type EnrichStats } from "./enrich.js";import { readGraph, writeGraph, wiringPath } from "./write.js";-import { writeCards, writeIndex, writeCovers } from "./cards.js";+import { writeCards, writeIndex, writeCovers, type CardStats } from "./cards.js";import { writeAskIndex } from "../ask/index-file.js";import { discoverScopes, scopeOf } from "./scopes.js";import type { GraphV1, Kind, NodeV1, Relation, ScopeV1 } from "./types.js";@@ -244,16 +244,18 @@ export async function buildGraph(edges,};- 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);- // `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.+ // ---- 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.//// 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@@ -265,25 +267,44 @@ export async function buildGraph(errors.push(`ask-index: ${err instanceof Error ? err.message : String(err)}`);}- // Tier-2 passive surface: project the nodes into per-file markdown cards, and- // refresh the INDEX roster. Pure projection — no LLM, no network.- const cardStats = writeCards(graph, outDir);- writeIndex(outDir, cardStats.files);- // 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 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);- // Dead last, and unconditionally. The fingerprint is the claim "everything graft- // wrote describes exactly these bytes", so it may only be made once everything- // graft writes is on disk: written before the cards above, a throw in that- // projection would leave a half-written `graft/` marked permanently clean, and no- // later probe would ever ask for it again. Conversely it must NOT depend on the- // extract memo's write succeeding — a missing memo only makes the next rebuild- // cold, whereas a missing fingerprint makes *every* query rebuild the repo from- // scratch, forever. If this write itself fails, the next probe reports "unknown"- // and rebuilds once, which is the safe direction.+ // 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.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.+ let cardStats: CardStats = { written: 0, pruned: 0, files: [] };+ try {+ 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)}`);+ }+const byKind = {} as Record<Kind, number>;for (const n of nodes) byKind[n.kind] = (byKind[n.kind] ?? 0) + 1;const byRelation = {} as Record<Relation, number>;diff --git a/src/graph/cards.ts b/src/graph/cards.tsindex 3fe4ead3..969f6200 100644--- a/src/graph/cards.ts+++ b/src/graph/cards.ts@@ -231,7 +231,12 @@ export function writeIndex(outDir: string, files: CardFileInfo[]): void {);}- writeFileSync(join(outDir, INDEX_FILE), lines.join("\n"));+ // 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);}/** One symbol a concept node covers: its name, kind, and `path:span` pointer. */@@ -252,11 +257,19 @@ 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. Returns- * the number of nodes enriched.+ * 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.*/-export function writeCovers(graph: GraphV1, outDir: string): number {- if (!existsSync(outDir)) return 0;+export function writeCovers(graph: GraphV1, outDir: string): { enriched: number; errors: string[] } {+ const errors: string[] = [];+ if (!existsSync(outDir)) return { enriched: 0, errors };const symbolsByPath = new Map<string, NodeV1[]>();for (const n of graph.nodes) {@@ -273,7 +286,23 @@ export function writeCovers(graph: GraphV1, outDir: string): number {for (const entry of readdirSync(outDir)) {if (!entry.endsWith(".md") || entry === INDEX_FILE) continue;const full = join(outDir, entry);- const parsed = matter(readFileSync(full, "utf8"));+ 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 sources = Array.isArray(parsed.data.sources)? (parsed.data.sources as Array<{ path?: string }>): [];@@ -287,8 +316,10 @@ export function writeCovers(graph: GraphV1, outDir: string): number {// Re-stringify with covers appended last, so re-runs produce a stable diff.const { covers: _prev, ...rest } = parsed.data as Record<string, unknown>;- writeFileSync(full, matter.stringify(parsed.content, { ...rest, covers }));+ const rendered = matter.stringify(parsed.content, { ...rest, covers });+ if (rendered === raw) continue; // nothing moved — don't touch the author's file+ writeFileSync(full, rendered);enriched++;}- return enriched;+ return { enriched, errors };}diff --git a/src/graph/extract-cache.ts b/src/graph/extract-cache.tsindex a3209d4b..ccd5cc1c 100644--- a/src/graph/extract-cache.ts+++ b/src/graph/extract-cache.ts@@ -23,7 +23,7 @@* extraction code itself, caught by content-hashing it — see* {@link extractorStamp}. Neither asks anyone to remember to bump anything.*/-import { readFileSync, readdirSync } from "node:fs";+import { readFileSync, readdirSync, rmSync, statSync } from "node:fs";import { createHash } from "node:crypto";import { fileURLToPath } from "node:url";import { dirname, extname, join } from "node:path";@@ -34,7 +34,7 @@ import type { NodeV1 } from "./types.js";/** Bump when the on-disk shape below changes. */const CACHE_VERSION = 1;-const EXTRACT_CACHE_FILE = "extract.json";+const EXTRACT_CACHE_PREFIX = "extract";export interface ExtractEntry {size: number;@@ -58,14 +58,48 @@ export interface ExtractCache {files: Record<string, ExtractEntry>;}-export function extractCachePath(outDir: string): string {- return join(outDir, CACHE_DIR, EXTRACT_CACHE_FILE);+/**+ * Where this graft's memo lives: `<outDir>/.cache/extract.<stamp>.json`.+ *+ * The stamp is in the *filename*, not just inside the file, so two grafts working+ * on one repo keep separate memos instead of evicting each other. That is the+ * default install, not an exotic case: `graft init` wires the MCP server as+ * `npx -y @nanonets/graft` (which resolves the latest published version) while the+ * Claude Code hooks run the locally installed one. The moment those two versions+ * differ, a single shared file means the prompt hook and every MCP retrieval take+ * turns rejecting each other's entries and cold-re-parsing the whole repo — the memo+ * would never help anyone.+ *+ * Null stamp → null path → no memo at all. See {@link extractorStamp}.+ */+export function extractCachePath(outDir: string): string | null {+ const stamp = extractorStamp();+ return stamp === null ? null : join(outDir, CACHE_DIR, `${EXTRACT_CACHE_PREFIX}.${stamp}.json`);+}++/** Keep `.cache/` from growing a file per version forever: after writing, drop all+ * but the newest `keep` files sharing a prefix. Best-effort and never fatal — this+ * is a cache directory, and a failure here costs disk, not correctness. */+export function pruneSidecars(cacheDir: string, prefix: string, keep = 2): void {+ try {+ const mine = readdirSync(cacheDir)+ .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith(".json"))+ .map((f) => {+ const full = join(cacheDir, f);+ return { full, mtimeMs: statSync(full).mtimeMs };+ })+ .sort((a, b) => b.mtimeMs - a.mtimeMs);+ for (const f of mine.slice(keep)) rmSync(f.full, { force: true });+ } catch {+ /* nothing here is load-bearing */+ }}/** Computed once per process — this can't change under a running process without* the module graph itself being swapped, and a long-lived MCP server holding the- * identity of the code it actually loaded is the correct answer anyway. */-let memoizedStamp: string | null = null;+ * identity of the code it actually loaded is the correct answer anyway.+ * `undefined` = not computed yet; `null` = computed, and there is no identity. */+let memoizedStamp: string | null | undefined;/*** Identity of the code that produces the cached parses. Both sidecars key on it,@@ -92,33 +126,48 @@ let memoizedStamp: string | null = null;* graft's own files) invalidates too.** Measured at ~0.5ms for 21 files / 556KB, paid once per process.+ *+ * **Null when no identity can be established at all**, and that is deliberately not+ * a string. It used to return `"unknown"` on failure — but `"unknown"` was then+ * *written into the sidecars as a real identity*, and every later run compared equal+ * to it, so any environment where stamping fails (a `pkg`/`bun-compile` single-file+ * build, an asar-style read, a directory that can't be listed) permanently lost the+ * ability to notice an extractor change. A sentinel that doubles as a valid value+ * silently disables the whole mechanism. Null forces callers to decide instead, and+ * {@link extractCachePath} decides not to have a memo.*/-export function extractorStamp(): string {- if (memoizedStamp === null) memoizedStamp = computeStamp();+export function extractorStamp(): string | null {+ if (memoizedStamp === undefined) memoizedStamp = computeStamp();return memoizedStamp;}-function computeStamp(): string {+function computeStamp(): string | null {try {const self = fileURLToPath(import.meta.url);// `.js` when running from `dist/`, `.ts` under tsx — take the extension from// our own filename rather than guessing which layout we're in.const dir = dirname(self);- return stampDir(dir, extname(self), packageVersion(dir));+ const hashed = stampDir(dir, extname(self), packageVersion(dir) ?? "");+ if (hashed) return hashed;+ // Couldn't read the modules (bundled into one file, say). The version alone is+ // a weaker identity — it can't see a local edit — but it still turns over on+ // every upgrade, which is the case that ships broken parses to users.+ const v = packageVersion(dir);+ return v ? `v${v}` : null;} catch {- return "unknown";+ return null;}}/**- * Hash every `ext` file in `dir`, plus `version`. Separated from- * {@link extractorStamp} so a test can prove the property that matters: a change- * to *any* module in the directory moves the stamp, not just the one the old- * implementation happened to watch.+ * Hash every `ext` file in `dir`, plus `version`. Null when the directory holds no+ * such file. Separated from {@link extractorStamp} so a test can prove the property+ * that matters: a change to *any* module in the directory moves the stamp, not just+ * the one the old implementation happened to watch.*/-export function stampDir(dir: string, ext: string, version = ""): string {+export function stampDir(dir: string, ext: string, version = ""): string | null {const files = readdirSync(dir).filter((f) => f.endsWith(ext)).sort();- if (!files.length) return "unknown";+ if (!files.length) return null;const h = createHash("sha256");h.update(version);for (const f of files) {@@ -128,38 +177,45 @@ export function stampDir(dir: string, ext: string, version = ""): string {return h.digest("hex").slice(0, 16);}-/** graft's own version, or `""` when it can't be read (then the content hash- * alone carries the stamp — still correct for every local edit). */-function packageVersion(graphDir: string): string {+/** graft's own version, or null when it can't be read. */+function packageVersion(graphDir: string): string | null {try {const pkg = JSON.parse(readFileSync(join(graphDir, "..", "..", "package.json"), "utf8")) as { version?: string };- return pkg.version ?? "";+ return pkg.version ?? null;} catch {- return "";+ return null;}}export function emptyExtractCache(): ExtractCache {- return { version: CACHE_VERSION, extractor: extractorStamp(), files: {} };+ return { version: CACHE_VERSION, extractor: extractorStamp() ?? "", files: {} };}-/** The cache for `outDir`, or an empty one when it's absent, unparseable, or was- * written by a different cache version / extractor build. */+/** The cache for `outDir`, or an empty one when it's absent, unparseable, written by+ * a different cache version, or when this graft has no identity to key on (then+ * every build is cold, which is slow but never wrong). The stamp is in the filename,+ * so the `extractor` field is a second check rather than the only one. */export function readExtractCache(outDir: string): ExtractCache {- const c = readJson<ExtractCache>(extractCachePath(outDir));+ const path = extractCachePath(outDir);const stamp = extractorStamp();+ if (path === null || stamp === null) return emptyExtractCache();+ const c = readJson<ExtractCache>(path);if (!c || c.version !== CACHE_VERSION || c.extractor !== stamp || typeof c.files !== "object") {return emptyExtractCache();}return { version: c.version, extractor: c.extractor, files: c.files ?? {} };}-/** Best-effort write — a full graph is already on disk by the time this runs, so- * an unwritable cache dir must never fail the build (it only costs the next- * build its reuse). Returns false when the write failed. */+/** Best-effort write — a full graph is already on disk by the time this runs, so an+ * unwritable cache dir must never fail the build (it only costs the next build its+ * reuse). Returns false when nothing was written, including the deliberate case of+ * having no extractor identity: a parse we can't attribute must never be replayed. */export function writeExtractCache(outDir: string, cache: ExtractCache): boolean {+ const path = extractCachePath(outDir);+ if (path === null) return false;try {- writeJsonAtomic(extractCachePath(outDir), cache, true);+ writeJsonAtomic(path, cache, true);+ pruneSidecars(join(outDir, CACHE_DIR), EXTRACT_CACHE_PREFIX);return true;} catch {return false;diff --git a/src/graph/fingerprint.ts b/src/graph/fingerprint.tsindex 2e74d8ee..7823c6ea 100644--- a/src/graph/fingerprint.ts+++ b/src/graph/fingerprint.ts@@ -23,12 +23,20 @@ import { join } from "node:path";import { CACHE_DIR } from "../context/node-file.js";import { contentHash } from "../util/id.js";import { readJson, writeJsonAtomic } from "../util/state.js";-import { extractorStamp, type ExtractEntry } from "./extract-cache.js";+import { extractorStamp, pruneSidecars, type ExtractEntry } from "./extract-cache.js";import { listSourceStats } from "./source-files.js";-const FINGERPRINT_FILE = "fingerprint.json";+const FINGERPRINT_PREFIX = "fingerprint";const FINGERPRINT_VERSION = 1;+/** The identity this graft's prints are filed under. Unlike the extract memo, a+ * missing extractor identity is *not* disqualifying here: freshness is a claim about+ * source bytes, and a build with no memo is merely cold, never wrong. So stamp what+ * we can and fall back to a shared bucket. */+function stamp(): string {+ return extractorStamp() ?? "nostamp";+}+/** `[size, mtimeMs, hash]` — positional to keep the file small. */type Print = [number, number, string];@@ -53,14 +61,18 @@ export interface Drift {removed: string[];}+/** `<outDir>/.cache/fingerprint.<stamp>.json` — keyed by extractor identity for the+ * same reason the memo is (see {@link extractCachePath}): two grafts on one repo,+ * typically an `npx` MCP server and a locally installed hook binary, must not keep+ * invalidating each other's prints and forcing a cold rebuild on every call. */export function fingerprintPath(outDir: string): string {- return join(outDir, CACHE_DIR, FINGERPRINT_FILE);+ return join(outDir, CACHE_DIR, `${FINGERPRINT_PREFIX}.${stamp()}.json`);}export function readFingerprint(outDir: string): Fingerprint | null {const f = readJson<Fingerprint>(fingerprintPath(outDir));if (!f || f.version !== FINGERPRINT_VERSION || typeof f.files !== "object" || !f.files) return null;- if (f.extractor !== extractorStamp()) return null; // different extractor — re-extract, don't trust these prints+ if (f.extractor !== stamp()) return null; // different extractor — re-extract, don't trust these printsreturn f;}@@ -71,7 +83,8 @@ export function writeFingerprint(outDir: string, entries: Record<string, Extractconst files: Record<string, Print> = {};for (const [rel, e] of Object.entries(entries)) files[rel] = [e.size, e.mtimeMs, e.hash];try {- writeJsonAtomic(fingerprintPath(outDir), { version: FINGERPRINT_VERSION, extractor: extractorStamp(), files }, true);+ writeJsonAtomic(fingerprintPath(outDir), { version: FINGERPRINT_VERSION, extractor: stamp(), files }, true);+ pruneSidecars(join(outDir, CACHE_DIR), FINGERPRINT_PREFIX);return true;} catch {return false;diff --git a/src/graph/refresh.ts b/src/graph/refresh.tsindex 1c59065a..6d89e7ff 100644--- a/src/graph/refresh.ts+++ b/src/graph/refresh.ts@@ -43,6 +43,10 @@ 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 {@@ -63,6 +67,34 @@ function sleep(ms: number): Promise<void> {return new Promise((r) => setTimeout(r, ms));}+/**+ * Release the lock if this process is asked to die while holding it. Returns the+ * un-hook.+ *+ * Not hypothetical: the Claude Code prompt hook runs `graft ask` with a timeout, and+ * `execFileSync` enforces it with SIGTERM. Node's default disposition for SIGTERM is+ * to exit without unwinding, so the `finally` below never runs and the lock outlives+ * the process — after which the background sync is blocked and every query waits and+ * then answers stale until the lock ages out. Ctrl-C on a CLI query is the same story+ * with SIGINT.+ *+ * Adding a listener replaces that default disposition, so re-raise it explicitly+ * afterwards: remove ourselves, then `process.kill(process.pid, sig)`, so the exit+ * status still says "terminated by signal" for whoever is waiting on us.+ */+export function releaseOnSignal(cache: string): () => void {+ const signals: NodeJS.Signals[] = ["SIGTERM", "SIGINT"];+ const onSignal = (sig: NodeJS.Signals) => {+ releaseLockIn(cache);+ for (const s of signals) process.removeListener(s, onSignal);+ process.kill(process.pid, sig);+ };+ for (const s of signals) process.once(s, onSignal);+ return () => {+ for (const s of signals) process.removeListener(s, onSignal);+ };+}+/** Wait out someone else's rebuild, then take the lock. False when we couldn't. */async function waitForLock(cache: string): Promise<boolean> {const deadline = Date.now() + LOCK_WAIT_MS;@@ -107,13 +139,30 @@ export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}):note: "a graph rebuild is already in flight — answering from the current graph",};}+ const unhook = releaseOnSignal(lockCache);try {+ // We may have queued behind another process's rebuild for up to LOCK_WAIT_MS,+ // and that rebuild very likely fixed the same drift we saw. Re-probe rather+ // than rebuild on the strength of a stale observation: without this, four+ // parallel MCP tool calls on one edited file produce four full rebuilds, three+ // of them pure waste, and the last tool call pays for all of it. A null drift+ // means "no fingerprint" and still has to build.+ const now = drift ? probeDrift(dir, outDir) : null;+ if (now && isClean(now)) {+ invalidateGraphCaches(outDir);+ return CLEAN;+ }// Tier-1 only: no summarizer, so no LLM call and no network, ever.- await buildGraph(dir, { contextDir: opts.contextDir });+ const built = await buildGraph(dir, { contextDir: opts.contextDir });invalidateGraphCaches(outDir);syncStats(dir, outDir);- return { refreshed: true, drift: drift ?? undefined };+ // 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 };} finally {+ unhook();releaseLockIn(lockCache);}} catch (err) {@@ -179,8 +228,17 @@ 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}`;+ if (r.note) return `[graft] ${r.note}${errorTail(r)}`;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`;+ 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}`;}diff --git a/src/util/state.ts b/src/util/state.tsindex ccc4c970..cd33f1e2 100644--- a/src/util/state.ts+++ b/src/util/state.ts@@ -48,14 +48,26 @@ export function readJson<T>(p: string): T | null {** 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`, which a query can now rewrite while- * the statusline, a second graft process, or another MCP call is reading it.+ * `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.+ *+ * 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.*/export function writeFileAtomic(p: string, text: string): void {mkdirSync(dirname(p), { recursive: true });const tmp = `${p}.${process.pid}.tmp`;- writeFileSync(tmp, text);- renameSync(tmp, p);+ try {+ writeFileSync(tmp, text);+ renameSync(tmp, p);+ } catch (e) {+ try { rmSync(tmp, { force: true }); } catch { /* nothing more we can do */ }+ throw e;+ }}/** {@link writeFileAtomic} for JSON. `compact` drops the indentation, for thediff --git a/test/claude-hooks.test.ts b/test/claude-hooks.test.tsindex 60215d51..b35e1e71 100644--- a/test/claude-hooks.test.ts+++ b/test/claude-hooks.test.ts@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';import { existsSync, mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';-import { underGraft, main, lastFileScopeHint } from '../src/claude/hooks.js';+import { underGraft, main, lastFileScopeHint, promptAskTimeout } from '../src/claude/hooks.js';import { readStats, readSession } from '../src/claude/state.js';import { runSync } from '../src/claude/sync-run.js';import { savingsFooter } from '../src/context/savings.js';@@ -440,3 +440,34 @@ test('tool-savings counts a REAL savingsFooter (with the turn nudge) exactly oncdelete process.env.CLAUDE_PROJECT_DIR;}});++/**+ * The prompt hook's `graft ask` child must stay inside the budget THIS repo has+ * installed, not the one the current source would install. `mergeGraftSettings` runs+ * only during `graft init`, so an npm upgrade leaves every already-wired repo on its+ * old `timeout` — and a child that outlives it gets the whole hook killed by Claude+ * Code, which means no retrieval pack and no session write at all.+ */+function withSettings(timeout: unknown): string {+ const d = mkdtempSync(join(tmpdir(), 'graft-hooktimeout-'));+ mkdirSync(join(d, '.claude'), { recursive: true });+ const hooks = timeout === undefined ? {} : {+ UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'node ".claude/helpers/graft-hooks.cjs" prompt', timeout }] }],+ };+ writeFileSync(join(d, '.claude', 'settings.json'), JSON.stringify({ hooks }));+ return d;+}++test('promptAskTimeout is derived from the installed hook budget', () => {+ // A repo wired before the budget was raised.+ assert.equal(promptAskTimeout(withSettings(8000)), 6000);+ // A repo wired after.+ assert.equal(promptAskTimeout(withSettings(15000)), 13000);+ // Never so small the child has no chance.+ assert.equal(promptAskTimeout(withSettings(1000)), 4000);++ // Nothing readable: assume the conservative 8s budget the other hooks carry.+ assert.equal(promptAskTimeout(withSettings(undefined)), 6000);+ assert.equal(promptAskTimeout(withSettings('nonsense')), 6000);+ assert.equal(promptAskTimeout(mkdtempSync(join(tmpdir(), 'graft-nosettings-'))), 6000);+});diff --git a/test/claude-state.test.ts b/test/claude-state.test.tsindex 76fe15d4..a4900cc8 100644--- a/test/claude-state.test.ts+++ b/test/claude-state.test.ts@@ -1,11 +1,11 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { mkdtempSync, existsSync, utimesSync } from 'node:fs';+import { mkdtempSync, existsSync, chmodSync, mkdirSync, readdirSync, utimesSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import {emptyStats, readStats, writeStats, patchStats,- readSession, writeSession, acquireLock, releaseLock, cacheDir, LOCK_STALE_MS,+ readSession, writeSession, acquireLock, releaseLock, cacheDir, LOCK_STALE_MS, writeFileAtomic,} from '../src/claude/state.js';function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-state-')); }@@ -48,3 +48,19 @@ test('acquireLock reclaims a stale lock', () => {utimesSync(p, old, old);assert.equal(acquireLock(d), true, 'stale lock reclaimed');});++test('writeFileAtomic 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');+ mkdirSync(dir, { recursive: true });+ 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+ // 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)));+ chmodSync(dir, 0o700);+ assert.deepEqual(readdirSync(dir), [], 'no .tmp residue');+});diff --git a/test/covers.test.ts b/test/covers.test.tsindex 6a9139fa..3cea34a6 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 } from "node:fs";+import { mkdtempSync, writeFileSync, readFileSync, rmSync, statSync } from "node:fs";import { join } from "node:path";import { tmpdir } from "node:os";import matter from "gray-matter";@@ -74,3 +74,56 @@ 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 583bfa9a..ebc21b2a 100644--- a/test/graph-incremental.test.ts+++ b/test/graph-incremental.test.ts@@ -6,12 +6,12 @@*/import { test } from "node:test";import assert from "node:assert/strict";-import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";-import { join } from "node:path";+import { basename, join } from "node:path";import { buildGraph } from "../src/graph/build.js";import { extractCachePath, extractorStamp, readExtractCache, stampDir } from "../src/graph/extract-cache.js";-import { isClean, probeDrift, readFingerprint } from "../src/graph/fingerprint.js";+import { fingerprintPath, isClean, probeDrift, readFingerprint } from "../src/graph/fingerprint.js";import { readAskIndex } from "../src/ask/index-file.js";import { readGraph, wiringPath } from "../src/graph/write.js";import type { GraphV1 } from "../src/graph/types.js";@@ -245,3 +245,80 @@ test("a memo written by a different extractor is dropped, not replayed", async (assert.equal(cold.reused, 0);assert.equal(cold.parsed, cold.files);});++test("two grafts on one repo keep separate memos instead of evicting each other", async () => {+ const d = repo();+ await buildGraph(d);+ const cache = join(outOf(d), ".cache");+ const mine = extractCachePath(outOf(d))!;+ assert.ok(existsSync(mine));+ // The mechanism: the identity is in the FILENAME, not only inside the file. A+ // single shared `extract.json` is what made two installs evict each other.+ assert.ok(basename(mine).includes(extractorStamp()!), `stamp missing from ${basename(mine)}`);+ assert.ok(basename(fingerprintPath(outOf(d))).includes(extractorStamp()!), "same for the probe sidecar");++ // Stand in for the other install — `graft init` wires the MCP server as+ // `npx -y @nanonets/graft` while the hooks run the locally installed dist, so two+ // different versions on one repo is the DEFAULT setup, not an exotic one. With a+ // single shared filename they took turns rejecting each other's entries and+ // cold-re-parsing the whole repo on every call.+ const theirs = join(cache, "extract.0000000000000000.json");+ writeFileSync(theirs, readFileSync(mine, "utf8"));++ const again = await buildGraph(d);+ assert.equal(again.parsed, 0, "our own memo still applies");+ assert.equal(again.reused, again.files);+ assert.ok(existsSync(theirs), "and the other install's memo is left intact");++ // Bounded, though: `.cache/` must not grow a file per version forever.+ for (const n of ["1111", "2222", "3333"]) {+ writeFileSync(join(cache, `extract.${n}00000000000000.json`), "{}");+ }+ await buildGraph(d);+ const left = readdirSync(cache).filter((f) => f.startsWith("extract."));+ assert.ok(left.length <= 2, `pruned to at most 2, found ${left.join(", ")}`);+ assert.ok(left.includes(basename(mine)), "and the surviving one is the memo in use");+});++test("with no extractor identity, nothing is memoized — and 'unknown' is never stored", async () => {+ const d = repo();+ await buildGraph(d);++ // Every sidecar on disk must name a real identity. `"unknown"` used to be both the+ // failure sentinel AND a value written into the files, so every later run compared+ // equal to it and extractor-change invalidation silently stopped working forever.+ for (const f of readdirSync(join(outOf(d), ".cache"))) {+ if (!f.endsWith(".json")) continue;+ assert.ok(!f.includes("unknown"), `${f} is filed under the failure sentinel`);+ const body = JSON.parse(readFileSync(join(outOf(d), ".cache", f), "utf8")) as { extractor?: string };+ if (body.extractor !== undefined) assert.notEqual(body.extractor, "unknown", `${f} stores the sentinel`);+ }+ assert.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 () => {+ 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")), []);++ // 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",+ );+ 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");+});diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.tsindex 00de9133..358003a6 100644--- a/test/graph-refresh.test.ts+++ b/test/graph-refresh.test.ts@@ -5,8 +5,10 @@*/import { test } from "node:test";import assert from "node:assert/strict";-import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";+import { spawn } from "node:child_process";+import { fileURLToPath } from "node:url";import { dirname, join } from "node:path";import { buildGraph } from "../src/graph/build.js";import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "../src/graph/refresh.js";@@ -18,6 +20,8 @@ import { callTool } from "../src/mcp/tools.js";import type { GraphV1 } from "../src/graph/types.js";const MATH = "export function add(a: number, b: number): number {\n return a + b;\n}\n";+/** A *function*, because a plain `export const` is not extracted as a symbol node. */+const MUL = "export function mul(a: number, b: number): number {\n return a * b;\n}\n";function repo(): string {const d = mkdtempSync(join(tmpdir(), "graft-refresh-"));@@ -92,7 +96,7 @@ test("ensureFreshGraph is a no-op on a clean tree", async () => {test("ensureFreshGraph rebuilds once when the graph predates the fingerprint", async () => {const d = repo();await buildGraph(d);- rmSync(join(outOf(d), ".cache", "fingerprint.json"));+ rmSync(fingerprintPath(outOf(d)));const first = await ensureFreshGraph(d);assert.equal(first.refreshed, true, "no fingerprint = unknown state, so rebuild");@@ -256,21 +260,93 @@ test("a file that becomes readable again is picked up through the probe", async});test("the fingerprint is written even when the extract memo can't be", async (t) => {- if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only file proves nothing");+ 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.- const memo = extractCachePath(outOf(d));- chmodSync(memo, 0o400);- writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);+ // 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+ // 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");+ const memo = extractCachePath(outOf(d))!;+ assert.ok(existsSync(memo), "a memo exists to begin with");+ const before = readFileSync(memo, "utf8");++ writeFileSync(join(d, "src", "math.ts"), `${MATH}${MUL}`);+ chmodSync(cache, 0o500);+ const built = 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.await buildGraph(d);- chmodSync(memo, 0o600);-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");+ 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.+ writeFileSync(join(d, "src", "extra.ts"), MUL);++ // 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(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/);++ 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);+});++test("after waiting out another process's rebuild, the waiter does not rebuild too", async () => {+ const d = repo();+ await buildGraph(d);+ writeFileSync(join(d, "src", "math.ts"), `${MATH}${MUL}`);++ // Stand in for the process that got there first: take the lock, do the rebuild it+ // would have done, then release while our caller is still waiting.+ assert.equal(acquireLock(d), true);+ setTimeout(() => {+ void buildGraph(d).then(() => releaseLock(d));+ }, 150);++ const r = await ensureFreshGraph(d);+ assert.equal(r.refreshed, false, "the work was already done — re-probe, don't redo it");+ assert.equal(refreshNote(r), null, "and nothing to report");+ assert.equal(hasSymbol(d, "src/math.ts#mul"), true, "the edit is in the graph either way");});test("a fingerprint from a different extractor is not trusted", async () => {@@ -326,3 +402,45 @@ test("callTool refreshes before answering — except for graft_check", async ()const again = await callTool(d, "graft_ask", { query: "multiply two numbers" });assert.ok(!again.text.startsWith("[graft] refreshed"), "nothing moved — no note, no rebuild");});++test("a process killed while holding the lock releases it", async () => {+ const d = repo();+ const cache = join(outOf(d), ".cache");+ mkdirSync(cache, { recursive: true });+ const lock = join(cache, ".sync.lock");++ // `execFileSync(..., { timeout })` — which is how the Claude Code prompt hook runs+ // `graft ask` — enforces its timeout with SIGTERM, and node's default disposition+ // for that is to exit without unwinding. So the `finally` that releases the lock+ // never ran, and the abandoned lock then blocked the background sync and made every+ // query wait-then-answer-stale until it aged out.+ const src = fileURLToPath(new URL("../src", import.meta.url));+ const child = spawn(+ process.execPath,+ ["--import", "tsx", "-e",+ `const { acquireLockIn } = await import(${JSON.stringify(`${src}/util/state.ts`)});+ const { releaseOnSignal } = await import(${JSON.stringify(`${src}/graph/refresh.ts`)});+ const cache = process.argv[1];+ if (!acquireLockIn(cache)) { process.exit(9); }+ releaseOnSignal(cache);+ process.stdout.write("held\\n");+ setInterval(() => {}, 1000);`,+ cache],+ { stdio: ["ignore", "pipe", "inherit"] },+ );+ await new Promise<void>((done, fail) => {+ child.stdout.setEncoding("utf8");+ child.stdout.on("data", (c: string) => { if (c.includes("held")) done(); });+ child.on("exit", (code) => fail(new Error(`child exited early (${code})`)));+ });+ assert.ok(existsSync(lock), "the child holds the lock");++ child.kill("SIGTERM");+ const [code, signal] = await new Promise<[number | null, string | null]>((done) =>+ child.on("exit", (c, s) => done([c, s])),+ );++ assert.ok(!existsSync(lock), "the lock must not outlive the process that took it");+ assert.equal(signal, "SIGTERM", "and the exit still reports the signal, for whoever is waiting on us");+ assert.equal(code, null);+});