Skip to content

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

fix the causes the second review found, not their symptoms

anirudhkumar-nanonets815e42fd7b21
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.
### Added
diff --git a/src/ask/index-file.ts b/src/ask/index-file.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 prints
return f;
}
@@ -71,7 +83,8 @@ 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, 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.ts
index 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.ts
index 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 the
diff --git a/test/claude-hooks.test.ts b/test/claude-hooks.test.ts
index 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 onc
delete 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);
+});