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
make the probe and the builder agree on "unchanged"
anirudhkumar-nanonetsd171c6a93870
diff --git a/src/claude/hooks.ts b/src/claude/hooks.tsindex 205c59fc..822c5628 100644--- a/src/claude/hooks.ts+++ b/src/claude/hooks.ts@@ -27,7 +27,17 @@ export function underGraft(dir: string, file: string): boolean {const rel = file.startsWith(dir) ? file.slice(dir.length) : file;return rel.replace(/^[/\\]+/, '').replace(/\\/g, '/').startsWith('graft/');}-function graftJson(dir: string, args: string[]): any | null {+/** 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;++function graftJson(dir: string, args: string[], timeout: number = CHILD_TIMEOUT_MS): any | null {try {// GRAFT_TEST_CLI is a test seam (mirrors GRAFT_TEST_STDIN/GRAFT_TEST_SYNC_RUN) so// tests can point the prompt hook's `graft ask`/`graft check` calls at a stub@@ -35,7 +45,7 @@ function graftJson(dir: string, args: string[]): any | null {// out to the real CLI (which isn't built relative to the TS source under test).const cliPath = process.env.GRAFT_TEST_CLI ?? graftCliPath();const out = execFileSync(process.execPath, [cliPath, ...args],- { cwd: dir, encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });+ { cwd: dir, encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'ignore'] });return JSON.parse(out);} catch (e: any) {// `graft check` exits non-zero when the graph is stale (by design) but still@@ -174,7 +184,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);+ const ask = graftJson(dir, askArgs, PROMPT_ASK_TIMEOUT_MS);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 90540b62..76c944ea 100644--- a/src/claude/settings-merge.ts+++ b/src/claude/settings-merge.ts@@ -20,6 +20,9 @@ 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.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/graph/build.ts b/src/graph/build.tsindex 3546a015..77e48e9b 100644--- a/src/graph/build.ts+++ b/src/graph/build.ts@@ -25,7 +25,7 @@ import {writeExtractCache,type ExtractEntry,} from "./extract-cache.js";-import { writeFingerprint } from "./fingerprint.js";+import { statUnchanged, writeFingerprint } from "./fingerprint.js";import { listSourceStats } from "./source-files.js";import { resolveEdges, type GoModule } from "./resolve.js";import { enrichGraph, type EnrichStats } from "./enrich.js";@@ -152,10 +152,10 @@ 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];- // An entry that failed last time never takes the stat fast path: a `chmod`- // that makes the file readable again changes neither size nor mtime, so- // trusting the stat would keep it broken until someone edited it.- const unchanged = !!cached && !cached.error && cached.size === f.size && cached.mtimeMs === f.mtimeMs;+ // `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) {@@ -209,7 +209,7 @@ export async function buildGraph(// and a cold build and an incremental build could disagree. The meaning layer// has its own cache (wiring.json itself, keyed on body_hash); this one is// strictly about not re-parsing.- const memoWritten = writeExtractCache(outDir, {+ writeExtractCache(outDir, {...emptyExtractCache(),files: entries,});@@ -248,11 +248,6 @@ export async function buildGraph(// 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 freshness fingerprint claims "the graph on disk describes these exact- // bytes", so it may only be written now that wiring.json is actually there —- // and only if the memo it projects from made it to disk. If either write fails- // the next probe reports drift and rebuilds, which is the safe direction.- if (memoWritten) writeFingerprint(outDir, entries);// `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.@@ -278,6 +273,17 @@ export async function buildGraph(// OKF↔Wiring link). No-op when there are no concept nodes (a $0 build).writeCovers(graph, 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.+ writeFingerprint(outDir, entries);+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/extract-cache.ts b/src/graph/extract-cache.tsindex 9ec53813..11b5dfcc 100644--- a/src/graph/extract-cache.ts+++ b/src/graph/extract-cache.ts@@ -64,7 +64,7 @@ export function extractCachePath(outDir: string): string {/** `mtime:size` of the extractor module, or `"unknown"` when it can't be stat'd.* Resolved by rewriting this module's own URL, so it works both in `dist/` (.js)* and under tsx (.ts) without knowing which layout we're in. */-function extractorStamp(): string {+export function extractorStamp(): string {try {const url = import.meta.url.replace(/extract-cache\.(c|m)?([jt]s)$/, "extract.$1$2");if (url === import.meta.url) return "unknown";diff --git a/src/graph/fingerprint.ts b/src/graph/fingerprint.tsindex b2603583..2e74d8ee 100644--- a/src/graph/fingerprint.ts+++ b/src/graph/fingerprint.ts@@ -23,7 +23,7 @@ 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 type { ExtractEntry } from "./extract-cache.js";+import { extractorStamp, type ExtractEntry } from "./extract-cache.js";import { listSourceStats } from "./source-files.js";const FINGERPRINT_FILE = "fingerprint.json";@@ -34,6 +34,12 @@ type Print = [number, number, string];export interface Fingerprint {version: number;+ /** The extractor that produced the graph these prints describe — the same stamp+ * `extract.json` carries. Without it the two sidecars can disagree about whether+ * the graph is current: an extractor change correctly drops every memo entry,+ * yet the prints still match the tree byte-for-byte, so the probe would report+ * clean and queries would keep answering from nodes the old extractor built. */+ extractor: string;files: Record<string, Print>;}@@ -54,6 +60,7 @@ export function fingerprintPath(outDir: string): string {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 printsreturn f;}@@ -64,13 +71,44 @@ 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, files }, true);+ writeJsonAtomic(fingerprintPath(outDir), { version: FINGERPRINT_VERSION, extractor: extractorStamp(), files }, true);return true;} catch {return false;}}+/** `GRAFT_REFRESH=hash` — never trust a stat, confirm every file by its bytes. */+export function alwaysHash(): boolean {+ return process.env.GRAFT_REFRESH === "hash";+}++/**+ * 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.+ *+ * 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-reading+ * bytes that failed to parse yesterday just fails to parse again.+ */+export function statUnchanged(+ rec: { size: number; mtimeMs: number; hash: string },+ f: { size: number; mtimeMs: number },+): boolean {+ if (alwaysHash()) return false;+ if (!rec.hash) return false;+ return rec.size === f.size && rec.mtimeMs === f.mtimeMs;+}+export function isClean(d: Drift): boolean {return d.changed.length === 0 && d.added.length === 0 && d.removed.length === 0;}@@ -90,7 +128,6 @@ export function driftCount(d: Drift): number {export function probeDrift(root: string, outDir: string): Drift | null {const fp = readFingerprint(outDir);if (!fp) return null;- const alwaysHash = process.env.GRAFT_REFRESH === "hash";const drift: Drift = { changed: [], added: [], removed: [] };const seen = new Set<string>();@@ -103,9 +140,11 @@ export function probeDrift(root: string, outDir: string): Drift | null {continue;}const [size, mtimeMs, hash] = print;- if (!alwaysHash && size === f.size && mtimeMs === f.mtimeMs) continue;+ if (statUnchanged({ size, mtimeMs, hash }, f)) continue;// Suspect: confirm by bytes, so a touch (or a checkout that restores the- // same content) doesn't cost a rebuild.+ // same content) doesn't cost a rebuild. An entry with an empty hash lands+ // here every time by design — that's a file the last build couldn't read, and+ // the only way to learn it's readable again is to try.let now: string;try {now = contentHash(readFileSync(f.abs, "utf8"));diff --git a/src/graph/refresh.ts b/src/graph/refresh.tsindex 2a699a2c..1c59065a 100644--- a/src/graph/refresh.ts+++ b/src/graph/refresh.ts@@ -157,7 +157,14 @@ export async function ensureFreshChildren(const refreshedIn: string[] = [];let files = 0;for (const child of children) {- const r = await ensureFreshGraph(resolve(root, child), opts);+ // Deliberately NOT `opts`: `contextDirFor` returns an override verbatim and+ // ignores the root it's handed, so forwarding the parent's `--dir` would point+ // every child at the *parent's* context dir — which holds a workspace index and+ // no wiring.json, so every child would silently be skipped. (And if it did hold+ // one, each child would build into that single shared dir in turn, the last+ // clobbering the rest.) A child's graph always lives in its own `<child>/graft`,+ // which is exactly how `loadWorkspaceGraphs` reads them back.+ const r = await ensureFreshGraph(resolve(root, child), { disabled: opts.disabled });if (!r.refreshed) continue;refreshedIn.push(child);files += r.drift ? driftCount(r.drift) : 0;diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.tsindex c75cd81a..7b0afc6b 100644--- a/test/graph-refresh.test.ts+++ b/test/graph-refresh.test.ts@@ -5,12 +5,13 @@*/import { test } from "node:test";import assert from "node:assert/strict";-import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import { buildGraph } from "../src/graph/build.js";-import { ensureFreshGraph, refreshNote } from "../src/graph/refresh.js";-import { isClean, probeDrift } from "../src/graph/fingerprint.js";+import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "../src/graph/refresh.js";+import { extractCachePath } from "../src/graph/extract-cache.js";+import { fingerprintPath, isClean, probeDrift } from "../src/graph/fingerprint.js";import { readGraph, wiringPath } from "../src/graph/write.js";import { acquireLock, readStats, releaseLock, writeStats, emptyStats } from "../src/util/state.js";import { callTool } from "../src/mcp/tools.js";@@ -184,6 +185,123 @@ test("a failed rebuild still answers from the graph on disk", async (t) => {releaseLock(d);});+/**+ * The probe and the builder must agree on what "unchanged" means, in both+ * directions. Each of the next three tests is a case where they didn't, and the+ * graph went permanently stale while every surface reported healthy.+ */+test("GRAFT_REFRESH=hash: drift the probe reports is drift the rebuild repairs", async () => {+ const d = repo();+ await buildGraph(d);+ const f = join(d, "src", "math.ts");++ // The state mtime-preserving tooling leaves behind: new bytes, but both sidecars+ // recording the file's current `(size, mtimeMs)` against its *old* hash. Written+ // out directly rather than via `utimesSync`, which takes float seconds and can't+ // put a millisecond mtime back exactly.+ const swapped = MATH.replace("add", "sum");+ assert.equal(swapped.length, MATH.length, "fixture must be a same-size rewrite");+ writeFileSync(f, swapped);+ const now = statSync(f);+ const fp = JSON.parse(readFileSync(fingerprintPath(outOf(d)), "utf8"));+ const staleHash = fp.files["src/math.ts"][2];+ fp.files["src/math.ts"] = [now.size, now.mtimeMs, staleHash];+ writeFileSync(fingerprintPath(outOf(d)), JSON.stringify(fp));+ const memo = JSON.parse(readFileSync(extractCachePath(outOf(d)), "utf8"));+ Object.assign(memo.files["src/math.ts"], { size: now.size, mtimeMs: now.mtimeMs });+ writeFileSync(extractCachePath(outOf(d)), JSON.stringify(memo));++ // Nobody notices without the flag — that's the documented trade-off, and the+ // whole reason the flag exists.+ assert.ok(isClean(probeDrift(d, outOf(d))!));++ process.env.GRAFT_REFRESH = "hash";+ try {+ assert.deepEqual(probeDrift(d, outOf(d)), { changed: ["src/math.ts"], added: [], removed: [] });+ const r = await ensureFreshGraph(d);+ assert.equal(r.refreshed, true);+ // The bug: the probe hashed, the builder trusted the stat, so the rebuild+ // replayed the old parse and the next probe reported the same drift forever.+ assert.equal(hasSymbol(d, "src/math.ts#sum"), true, "the rebuild must actually re-parse it");+ assert.equal(hasSymbol(d, "src/math.ts#add"), false);+ assert.ok(isClean(probeDrift(d, outOf(d))!), "and the drift is now gone, not permanent");+ } finally {+ delete process.env.GRAFT_REFRESH;+ }+});++test("a file that becomes readable again is picked up through the probe", async (t) => {+ if (process.getuid?.() === 0) return t.skip("root reads anything, so chmod 000 proves nothing");+ const d = repo();+ const hidden = join(d, "src", "hidden.ts");+ writeFileSync(hidden, "export function reachable(): number {\n return 1;\n}\n");+ chmodSync(hidden, 0o000);+ await buildGraph(d);+ assert.equal(hasSymbol(d, "src/hidden.ts#reachable"), false);++ // Recorded-but-unreadable must not read as new on every query...+ assert.ok(isClean(probeDrift(d, outOf(d))!), "an unreadable file doesn't churn the probe");++ // ...but a chmod changes neither size nor mtime, so trusting the stat here left+ // the file permanently missing from the graph.+ chmodSync(hidden, 0o644);+ assert.deepEqual(probeDrift(d, outOf(d)), { changed: ["src/hidden.ts"], added: [], removed: [] });+ const r = await ensureFreshGraph(d);+ assert.equal(r.refreshed, true);+ assert.equal(hasSymbol(d, "src/hidden.ts#reachable"), true);+});++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");+ 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`);+ 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");+});++test("a fingerprint from a different extractor is not trusted", async () => {+ const d = repo();+ await buildGraph(d);+ assert.ok(isClean(probeDrift(d, outOf(d))!));++ // Same bytes on disk, different extractor: the memo drops its entries, so the+ // prints describe nodes nothing would rebuild. "Unknown" is the only safe answer.+ const fp = JSON.parse(readFileSync(fingerprintPath(outOf(d)), "utf8"));+ writeFileSync(fingerprintPath(outOf(d)), JSON.stringify({ ...fp, extractor: "0:0" }));+ assert.equal(probeDrift(d, outOf(d)), null);+});++test("a workspace refreshes its children even under a --dir override", async () => {+ const d = mkdtempSync(join(tmpdir(), "graft-refresh-ws-"));+ const child = join(d, "api");+ mkdirSync(join(child, "src"), { recursive: true });+ writeFileSync(join(child, "src", "math.ts"), MATH);+ await buildGraph(child);++ const shared = join(d, "shared-context");+ mkdirSync(shared, { recursive: true });+ writeFileSync(join(shared, "workspace.json"), JSON.stringify({ version: 1, children: ["api"] }));++ writeFileSync(join(child, "src", "math.ts"), `${MATH}export function mul(a: number, b: number): number {\n return a * b;\n}\n`);+ // `contextDirFor` returns an override verbatim, so forwarding this to the child+ // resolved it to the parent's dir — no wiring.json there, so every child was+ // silently skipped and the query answered from a stale child graph.+ const r = await ensureFreshChildren(d, ["api"], { contextDir: shared });+ assert.equal(r.refreshed, true);+ assert.match(r.note ?? "", /api/);+ assert.equal(hasSymbol(child, "src/math.ts#mul"), true);+});+test("callTool refreshes before answering — except for graft_check", async () => {const d = repo();await buildGraph(d);