Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

make the probe and the builder agree on "unchanged"

anirudhkumar-nanonetsd171c6a93870
diff --git a/src/claude/hooks.ts b/src/claude/hooks.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 prints
return f;
}
@@ -64,13 +71,44 @@ export function writeFingerprint(outDir: string, entries: Record<string, Extract
const 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.ts
index 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.ts
index 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);