pi-graphnav 0.1.0 → 0.2.0

package/README.md

@@ -16,24 +16,53 @@ A [pi](https://github.com/earendil-works/pi-coding-agent) extension.
 
 * **Keeps the index current.** At session start, in the background: `codegraph init` for a git repo
   without an index, a full `codegraph index` when the index is stale or was built by another
-  CodeGraph version, `codegraph sync` for pending changes. While pi runs, the server's file
-  watcher follows your edits.
+  CodeGraph version, `codegraph sync` for pending changes. An index a killed run left half-built
+  is rebuilt (unless another process is indexing right now), and a failure on a stale lock gets
+  `codegraph unlock` and one more try. While pi runs, the server's file watcher follows your edits.
 * **The `codegraph_*` tools** (`explore`, `search`, `node`, `callers`, `callees`, `impact`,
   `files`, `status`) on one long-lived `codegraph serve --mcp` per project: no process start per
-  call, and the watcher stays alive.
+  call, and the watcher stays alive. Resilient, with
+  [arrow-resilience-kit](https://www.npmjs.com/package/arrow-resilience-kit): a server that dies
+  under a call is restarted and the call retried once; after 3 failed calls in a row CodeGraph
+  counts as unavailable for a minute, so calls fail fast and the gate stops sending the agent to
+  it (status line: `codegraph: unavailable`).
 * **Steers symbol searches to CodeGraph.** `rg parseConfig`, `grep -rn UserService src`,
   `git grep`, `ag`, `ack` and pi's `grep` tool with a symbol-like pattern are blocked once with
   the CodeGraph call that answers it (`enforce`), or run with that hint appended (`nudge`).
   Running the same command again is allowed: CodeGraph cannot answer everything. Searches for
   phrases, string literals or in docs and config (`*.md`, `--type yaml`, …) are never touched,
-  nor symbols already looked up with CodeGraph.
+  nor symbols already looked up with CodeGraph. Searches a codemode script makes with literal
+  `tools.bash({ command })` / `tools.grep({ pattern })` are gated the same way.
+* **Nudges file-name lookups.** `fd UserService`, `find . -name '*ParseConfig*'` and pi's `find`
+  tool with a camelCase or snake_case name run, with a hint to `codegraph_search` (never blocked).
 * **Hints after blind reading.** Reading several source files before any CodeGraph call adds
-  one hint to use `codegraph_explore`.
+  one hint to use `codegraph_explore`; reading a whole source file over 400 lines adds one to
+  fetch just the symbol with `codegraph_node`.
+* **Shows whether it helps.** `/codegraph status` counts blocked searches, how many the agent
+  answered with CodeGraph and how many it re-ran instead.
 * **Prompt guidance** that stays the same every turn, so the prompt cache survives.
 
 Needs the CodeGraph CLI: `npm i -g @colbymchenry/codegraph`. The project is the nearest
 directory with `.codegraph/`, else the git work tree; never your home directory.
 
+## Demos
+
+A repo without an index: indexed in the background, then a symbol `rg` is blocked and the
+answer comes from `codegraph_search` and `codegraph_callers`.
+
+![Overview: background indexing, a blocked rg, CodeGraph answers](examples/vhs/generated/overview.gif)
+
+`nudge` mode: the search runs, and its output points at CodeGraph.
+
+![Nudge mode: rg runs and its output carries the CodeGraph hint](examples/vhs/generated/nudge.gif)
+
+The `/codegraph` command: status, mode, off/on, sync.
+
+![The /codegraph command](examples/vhs/generated/commands.gif)
+
+Recorded with [VHS](https://github.com/charmbracelet/vhs) against a throw-away sample project and a
+scripted local model (`just vhs`, `scripts/vhs.nu`, `examples/vhs/`): a real pi with only this plugin.
+
 ## Install
 
 ```bash
@@ -64,6 +93,10 @@ Settings live in `<pi agent dir>/codegraph.json` (`PI_CODING_AGENT_DIR`, else `~
 | `readHintAfter` | `3` | source files read before the CodeGraph hint (`0`: never) |
 | `timeoutMs` | `30000` | per-call timeout of the CodeGraph server |
 
+A project can override `enabled`, `mode`, `autoInit`, `autoSync` and `readHintAfter` for itself in
+`<project>/.pi/codegraph.json` (commit it to share), e.g. `{ "mode": "nudge" }` for a repo full of
+generated code. A `/codegraph` command still wins for the session.
+
 Replaces `@vndv/pi-codegraph` (same tool names): uninstall that one first.
 
 ## Development
@@ -82,10 +115,12 @@ Layout:
 | `extensions/core/gate.ts` | spotting symbol searches in shell commands; the gate decision |
 | `extensions/core/project.ts` | project root, `codegraph status -j`, what keeps the index current |
 | `extensions/core/mcp.ts` | the long-lived `codegraph serve --mcp` client |
+| `extensions/core/resilience.ts` | circuit breaker and crash retry (arrow-resilience-kit) |
 | `extensions/core/tools.ts` | tool definitions and prompt guidelines |
 | `extensions/core/config.ts`, `extensions/command/parse.ts` | settings, `/codegraph` parsing |
 | `tests/` | `bun test`: one file per module, `extension` (hooks), `fuzz` (randomised properties) |
 | `scripts/` | Nushell only, each with a test in `scripts/tests/` |
+| `examples/vhs/` | demo tapes, the scripted model, the rendered GIFs |
 | `.github/`, `.gitea/` | CI, release, nightlies on both hosts |
 
 Releases: `just release patch` bumps `package.json`, regenerates `CHANGELOG.md` with git-cliff, tags and

package/extensions/core/config.ts

@@ -101,3 +101,35 @@ export async function saveConfig(config: Config, path = configPath()): Promise<v
 		throw e;
 	}
 }
+
+/** What a project may override for itself, in `<project>/.pi/codegraph.json` (committable). */
+export type ProjectOverrides = Partial<Pick<Config, "enabled" | "mode" | "autoInit" | "autoSync" | "readHintAfter">>;
+
+/** Keep only the valid override keys; anything else in the file is ignored. */
+export function sanitizeOverrides(raw: unknown): ProjectOverrides {
+	const r = (typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {}) as Record<string, unknown>;
+	const out: ProjectOverrides = {};
+	for (const key of ["enabled", "autoInit", "autoSync"] as const) if (typeof r[key] === "boolean") out[key] = r[key] as boolean;
+	if (MODES.includes(r.mode as Mode)) out.mode = r.mode as Mode;
+	if (typeof r.readHintAfter === "number" && Number.isFinite(r.readHintAfter)) out.readHintAfter = clampInt(r.readHintAfter, 0, 100, 0);
+	return out;
+}
+
+export const projectConfigPath = (root: string): string => join(root, ".pi", "codegraph.json");
+
+/** A project's overrides; none when the file is missing, a `problem` when it is unusable. */
+export async function readProjectConfig(root: string): Promise<{ overrides: ProjectOverrides; problem?: string }> {
+	const path = projectConfigPath(root);
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (e) {
+		const code = (e as { code?: string } | null)?.code;
+		return code === "ENOENT" ? { overrides: {} } : { overrides: {}, problem: `cannot read ${path} (${code ?? "error"})` };
+	}
+	try {
+		return { overrides: sanitizeOverrides(JSON.parse(raw)) };
+	} catch {
+		return { overrides: {}, problem: `${path} is not valid JSON` };
+	}
+}

package/extensions/core/gate.ts

@@ -13,6 +13,8 @@ export interface Search {
 	paths: string[];
 	/** `--type`/`--glob`/`--include` filters, as written. */
 	filters: string[];
+	/** A file-name lookup (`fd Foo`, `find -name '*Foo*'`): only ever nudged, never blocked. */
+	files?: true;
 }
 
 const OPERATORS = new Set(["|", "||", "&", "&&", ";", "(", ")", "\n", "|&"]);
@@ -93,6 +95,14 @@ VALUE_FLAGS["git grep"] = new Set("-A -B -C -m -e -f --after-context --before-co
 const PATTERN_FLAGS = new Set(["-e", "--regexp"]);
 const FILTER_FLAGS = new Set(["-g", "-t", "-T", "--glob", "--iglob", "--type", "--type-not", "--include", "-G", "--file-search-regex"]);
 const WRAPPERS = new Set(["sudo", "command", "exec", "time", "nice", "nohup", "env", "xargs", "timeout"]);
+/** Wrapper flags that take a separate value (`timeout -s KILL 5 rg …`, `nice -n 5 rg …`). */
+const WRAPPER_VALUE_FLAGS: Record<string, Set<string>> = {
+	timeout: new Set(["-s", "--signal", "-k", "--kill-after"]),
+	nice: new Set(["-n", "--adjustment"]),
+	sudo: new Set(["-u", "--user", "-g", "--group", "-C", "-D", "--chdir"]),
+	xargs: new Set(["-I", "-n", "-P", "-L", "-d", "-E", "-s", "-a"]),
+	env: new Set(["-u", "--unset", "-C", "--chdir"]),
+};
 
 /** The program of a simple command, skipping `VAR=x` assignments and wrappers like `xargs -0`. */
 function programIndex(words: string[]): number {
@@ -101,9 +111,10 @@ function programIndex(words: string[]): number {
 		while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]!)) i++;
 		const w = words[i];
 		if (w === undefined || !WRAPPERS.has(baseName(w))) return i;
+		const wrapper = baseName(w);
 		i++;
-		while (i < words.length && words[i]!.startsWith("-")) i++;
-		if (baseName(words[i - 1] ?? "") === "timeout" && /^\d/.test(words[i] ?? "")) i++;
+		while (i < words.length && words[i]!.startsWith("-")) i += WRAPPER_VALUE_FLAGS[wrapper]?.has(words[i]!) ? 2 : 1;
+		if (wrapper === "timeout" && /^\d/.test(words[i] ?? "")) i++;
 	}
 }
 
@@ -196,8 +207,12 @@ export function targetsOnlyNonCode(s: Search): boolean {
 		const nonCode = s.filters.every((f) => {
 			const neg = f.startsWith("!");
 			if (neg) return false;
-			const ext = /\.([A-Za-z0-9]+)\}?$/.exec(f)?.[1]?.toLowerCase() ?? (f.includes("*") || f.includes(".") ? undefined : f.toLowerCase());
-			return ext !== undefined && !CODE_EXTENSIONS.has(ext) && !CODE_TYPES.has(ext);
+			const bare = f.replace(/^\{([^,{}]*)\}$/, "$1");
+			const braces = /\.\{([A-Za-z0-9,]+)\}$/.exec(bare)?.[1];
+			const exts = braces
+				? braces.split(",").map((e) => e.toLowerCase())
+				: [/\.([A-Za-z0-9]+)$/.exec(bare)?.[1]?.toLowerCase() ?? (bare.includes("*") || bare.includes(".") ? undefined : bare.toLowerCase())];
+			return exts.every((ext) => ext !== undefined && ext !== "" && !CODE_EXTENSIONS.has(ext) && !CODE_TYPES.has(ext));
 		});
 		if (nonCode) return true;
 	}
@@ -217,7 +232,10 @@ function normalizeAlternative(raw: string): string {
 	let s = raw.trim();
 	s = s.replace(/\\[bB<>]/g, "").replace(/\[\[:<:\]\]|\[\[:>:\]\]/g, "");
 	s = s.replace(/^\^/, "").replace(/\$$/, "");
-	s = s.replace(/^\(\?:?/, "").replace(/\)$/, "");
+	for (let prev = ""; prev !== s; ) {
+		prev = s;
+		s = s.replace(/^\((?:\?:)?/, "").replace(/\)$/, "");
+	}
 	s = s.replace(DECL, "");
 	s = s.replace(/(?:\\?\(|\\?<|\s*\\s\*\\?\(|\s*\\s\*)$/, "");
 	s = s.replace(/^(?:\.\*|\\s\*|\\s\+)+|(?:\.\*|\\s\*|\\s\+)+$/g, "");
@@ -234,7 +252,7 @@ export function symbolsIn(pattern: string | undefined): string[] | undefined {
 	const alternatives = pattern.split(/\\?\|/);
 	const out: string[] = [];
 	for (const alt of alternatives) {
-		const s = normalizeAlternative(alt.replace(/^\(|\)$/g, ""));
+		const s = normalizeAlternative(alt);
 		if (s.length < 3 || !QUALIFIED.test(s) || KEYWORDS.has(s)) return undefined;
 		const parts = s.split(/::|\.|#|->/);
 		if (parts.some((p) => NOT_SYMBOLS.has(p.toLowerCase()))) return undefined;
@@ -257,7 +275,7 @@ export function lookupWords(params: Record<string, unknown>): string[] {
 export type Mode = "enforce" | "nudge" | "off";
 
 export type Decision =
-	| { action: "allow" }
+	| { action: "allow"; override?: true }
 	| { action: "block"; reason: string }
 	| { action: "nudge"; hint: string };
 
@@ -294,15 +312,23 @@ export function suggestion(symbols: string[]): string {
 export function decide(mode: Mode, searches: Search[], key: string, mem: GateMemory): Decision {
 	if (mode === "off") return { action: "allow" };
 	const symbols = new Set<string>();
+	const names = new Set<string>();
 	for (const s of searches) {
 		if (targetsOnlyNonCode(s)) continue;
-		for (const sym of symbolsIn(s.pattern) ?? []) if (!known(sym, mem)) symbols.add(sym);
+		for (const sym of (s.files ? fileSymbolIn(s.pattern) : symbolsIn(s.pattern)) ?? []) if (!known(sym, mem)) (s.files ? names : symbols).add(sym);
+	}
+	if (symbols.size === 0 && names.size === 0) return { action: "allow" };
+	if (symbols.size === 0) {
+		const [one] = [...names];
+		return {
+			action: "nudge",
+			hint: `[codegraph] "${one}" looks like a symbol name: codegraph_search({ query: "${one}" }) finds where it is defined (file and line), codegraph_files lists the indexed files.`,
+		};
 	}
-	if (symbols.size === 0) return { action: "allow" };
 	const list = [...symbols];
 	const hint = `"${list.join('", "')}" ${list.length === 1 ? "looks like a symbol" : "look like symbols"}: CodeGraph answers this structurally. Use ${suggestion(list)}.`;
 	if (mode === "nudge") return { action: "nudge", hint: `[codegraph] ${hint}` };
-	if (mem.blocked.has(key)) return { action: "allow" };
+	if (mem.blocked.has(key)) return { action: "allow", override: true };
 	mem.blocked.add(key);
 	return {
 		action: "block",
@@ -315,3 +341,78 @@ export const isSourceFile = (path: string): boolean => {
 	const ext = extOf(path);
 	return ext !== undefined && CODE_EXTENSIONS.has(ext);
 };
+
+const FD_VALUE_FLAGS = new Set(
+	"-e -t -E -d -x -X -S -c -j -g --extension --type --exclude --max-depth --min-depth --exact-depth --exec --exec-batch --size --changed-within --changed-before --owner --color --threads --max-results --base-directory --search-path --format --path-separator --batch-size --ignore-file".split(" "),
+);
+const FIND_NAME_FLAGS = new Set(["-name", "-iname", "-path", "-ipath", "-wholename", "-iwholename"]);
+
+/** File-name lookups in a shell command: `fd <pattern>`, `find … -name <glob>`. */
+export function findFileSearches(command: string): Search[] {
+	const out: Search[] = [];
+	for (const { words } of splitPipeline(command)) {
+		const at = programIndex(words);
+		const prog = baseName(words[at] ?? "");
+		const args = words.slice(at + 1);
+		if (prog === "fd" || prog === "fdfind") {
+			const positional: string[] = [];
+			for (let i = 0; i < args.length; i++) {
+				const a = args[i]!;
+				if (!a.startsWith("-")) positional.push(a);
+				else if (FD_VALUE_FLAGS.has(a)) i++;
+			}
+			if (positional.length > 0) out.push({ tool: prog, pattern: positional[0], paths: positional.slice(1), filters: [], files: true });
+		} else if (prog === "find") {
+			for (let i = 0; i < args.length - 1; i++) {
+				if (FIND_NAME_FLAGS.has(args[i]!)) out.push({ tool: "find", pattern: args[i + 1], paths: [], filters: [], files: true });
+			}
+		}
+	}
+	return out;
+}
+
+/**
+ * The symbol a file-name pattern looks for (`*ParseConfig*`, `user_service.rs`,
+ * `^AuthController`), stricter than `symbolsIn`: a plain word like `config` names files, not
+ * symbols, so it needs a camelCase/PascalCase hump or snake_case (`Readme`, `Makefile` are file names).
+ */
+export function fileSymbolIn(pattern: string | undefined): string[] | undefined {
+	if (pattern === undefined) return undefined;
+	const base = baseName(pattern)
+		.replace(/^\^?\.\*|\.\*\$?$/g, "")
+		.replace(/^[*^]+|[*$]+$/g, "")
+		.replace(/\\?\.[A-Za-z0-9]{1,5}$/, "")
+		.replace(/^[*^]+|[*$]+$/g, "");
+	if (base.length < 4 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(base) || !/[a-z][A-Z]|[a-z0-9]_[a-z]/.test(base)) return undefined;
+	if (NOT_SYMBOLS.has(base.toLowerCase())) return undefined;
+	return [base];
+}
+
+const unquote = (quote: string, body: string): string => {
+	if (quote === '"') {
+		try {
+			return JSON.parse(`"${body}"`);
+		} catch {
+			// not JSON-compatible: fall through to the plain unescape
+		}
+	}
+	return body.replace(/\\(.)/g, "$1");
+};
+
+const STRING = String.raw`(["'\`])((?:\\.|(?!\1)[^\\])*)\1`;
+const CODEMODE_BASH = new RegExp(String.raw`tools\.bash\(\s*\{[^}]*?\bcommand\s*:\s*` + STRING, "g");
+const CODEMODE_GREP = new RegExp(String.raw`tools\.grep\(\s*\{[^}]*?\bpattern\s*:\s*` + STRING, "g");
+
+/**
+ * Searches a codemode script makes through `tools.bash({ command: "…" })` and
+ * `tools.grep({ pattern: "…" })` with literal strings (a computed command is not knowable).
+ */
+export function codemodeSearches(code: string): Search[] {
+	const out: Search[] = [];
+	for (const m of code.matchAll(CODEMODE_BASH)) {
+		const command = unquote(m[1]!, m[2]!);
+		out.push(...findSearches(command), ...findFileSearches(command));
+	}
+	for (const m of code.matchAll(CODEMODE_GREP)) out.push({ tool: "grep", pattern: unquote(m[1]!, m[2]!), paths: [], filters: [] });
+	return out;
+}

package/extensions/core/mcp.ts

@@ -48,6 +48,14 @@ export function sanitize(text: string): string {
 		.slice(-MAX_STDERR);
 }
 
+/** The server process exited under a call (a crash, not a slow or failed query). */
+export class ServerExitError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ServerExitError";
+	}
+}
+
 interface Pending {
 	resolve: (v: any) => void;
 	reject: (e: Error) => void;
@@ -81,7 +89,7 @@ export class CodeGraphServer {
 			this.stderr = (this.stderr + String(chunk)).slice(-MAX_STDERR);
 		});
 		proc.on("error", (err) => this.fail(proc, err));
-		proc.on("exit", (code) => this.fail(proc, new Error(sanitize(this.stderr) || `codegraph serve exited with code ${code}`)));
+		proc.on("exit", (code) => this.fail(proc, new ServerExitError(sanitize(this.stderr) || `codegraph serve exited with code ${code}`)));
 		const rootUri = pathToFileURL(this.root).href;
 		return this.request("initialize", {
 			protocolVersion: "2024-11-05",

package/extensions/core/project.ts

@@ -3,7 +3,7 @@
  *
  * Pure, except where a function takes the file system or a process runner as a parameter.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 
@@ -71,17 +71,51 @@ export function parseStatus(json: string): IndexStatus {
 
 export type IndexAction = "init" | "index" | "sync" | "none" | "skip";
 
+/** Is a live process holding `.codegraph/codegraph.lock` (an index run in progress right now)? */
+export function lockHeld(
+	root: string,
+	read: (p: string) => string | undefined = (p) => {
+		try {
+			return readFileSync(p, "utf8");
+		} catch {
+			return undefined;
+		}
+	},
+	alive: (pid: number) => boolean = pidAlive,
+): boolean {
+	const pid = Number.parseInt(read(join(root, ".codegraph", "codegraph.lock")) ?? "", 10);
+	return Number.isInteger(pid) && pid > 0 && alive(pid);
+}
+
+export function pidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		// EPERM: it exists, it is just not ours.
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
 /**
  * What brings the index up to date: `init` when there is none (only in a git work tree, and
  * only when allowed), a full `index` when it is stale or broken, `sync` for pending changes.
+ *
+ * State `indexing` with no live lock holder is a run that was killed half-way: the index is
+ * truncated and only a full `index` repairs it. With a live holder another process is
+ * indexing right now: leave it alone.
  */
-export function planIndex(status: IndexStatus, project: Project, opts: { autoInit: boolean }): IndexAction {
+export function planIndex(status: IndexStatus, project: Project, opts: { autoInit: boolean; locked?: boolean }): IndexAction {
 	if (!status.initialized) return opts.autoInit && project.isRepo ? "init" : "skip";
-	if (status.reindexRecommended || status.versionMismatch || (status.state !== "complete" && status.state !== "indexing")) return "index";
+	if (status.state === "indexing") return opts.locked ? "none" : "index";
+	if (status.reindexRecommended || status.versionMismatch || status.state === "partial" || status.state === "failed") return "index";
 	if (status.pending > 0) return "sync";
 	return "none";
 }
 
+/** A failure that a stale lock explains: `codegraph unlock`, then one more try. */
+export const lockProblem = (output: string): boolean => /\block(ed)?\b|lock file|database is locked/i.test(output);
+
 /** The CLI arguments for an action. */
 export function actionArgs(action: Exclude<IndexAction, "none" | "skip">): string[] {
 	switch (action) {
@@ -105,18 +139,30 @@ export interface EnsureResult {
 }
 
 /** Bring the index of `project` up to date: status, then init/index/sync as planned, then status again. */
-export async function ensureIndex(project: Project, run: Runner, opts: { autoInit: boolean }): Promise<EnsureResult> {
+export async function ensureIndex(
+	project: Project,
+	run: Runner,
+	opts: { autoInit: boolean; locked?: (root: string) => boolean },
+): Promise<EnsureResult> {
 	const first = await run(["status", "-j"], project.root);
 	if (first.code === 127) return { action: "skip", status: parseStatus(""), error: "the codegraph CLI is not installed (npm i -g @colbymchenry/codegraph)" };
 	const status = parseStatus(first.stdout);
-	const action = planIndex(status, project, opts);
+	const action = planIndex(status, project, { autoInit: opts.autoInit, locked: (opts.locked ?? lockHeld)(project.root) });
 	if (action === "none" || action === "skip") return { action, status };
-	const res = await run(actionArgs(action), project.root);
+	const res = await runUnlocking(run, actionArgs(action), project.root);
 	const after = parseStatus((await run(["status", "-j"], project.root)).stdout);
 	if (res.code !== 0) return { action, status: after, error: `codegraph ${action} failed (exit ${res.code}): ${lastLine(res.stderr || res.stdout)}` };
 	return { action, status: after };
 }
 
+/** Run an index action; when it fails on a stale lock, `codegraph unlock` and try once more. */
+export async function runUnlocking(run: Runner, args: string[], root: string): ReturnType<Runner> {
+	const res = await run(args, root);
+	if (res.code === 0 || res.code === 127 || !lockProblem(res.stderr + res.stdout)) return res;
+	await run(["unlock"], root);
+	return run(args, root);
+}
+
 const lastLine = (s: string): string =>
 	s
 		.replace(/\u001b\[[0-9;]*m/g, "")

package/extensions/core/resilience.ts

@@ -0,0 +1,91 @@
+/**
+ * Resilience around the CodeGraph server, built on arrow-resilience-kit:
+ *
+ * - a circuit breaker per project: after `threshold` failed calls in a row CodeGraph counts
+ *   as unavailable for `resetMs`; calls then fail fast, and the gate stops sending the agent
+ *   to a tool that does not answer;
+ * - one retry when the server process died under a call (a crash, not a slow query): the
+ *   retry starts a fresh process.
+ *
+ * Aborts and CodeGraph's own "no such symbol" answers are not failures.
+ */
+import { CircuitBreaker, Retry } from "arrow-resilience-kit";
+import { ServerExitError } from "./mcp.ts";
+
+export const UNAVAILABLE =
+	"CodeGraph is unavailable for this project right now (its last calls failed); use rg/read meanwhile. It is retried automatically.";
+
+/** The server process went away under the call: worth one retry with a fresh process. */
+export const isCrash = (e: unknown): boolean => e instanceof ServerExitError || (e instanceof Error && /\bEPIPE\b|\bECONNRESET\b/.test(e.message));
+
+/** Failures that count against CodeGraph's health. An abort is the user's doing, not CodeGraph's. */
+export const countsAsFailure = (e: unknown): boolean => !(e instanceof Error && /^Aborted$/.test(e.message));
+
+const isOpenError = (e: unknown): boolean =>
+	(e as { constructor?: { name?: string } })?.constructor?.name === "CircuitBreakerOpenException" || /circuit breaker is open/i.test(String((e as Error)?.message));
+
+export interface GuardOptions {
+	/** Failed calls in a row before CodeGraph counts as unavailable. */
+	threshold: number;
+	/** How long it then stays unavailable before a trial call. */
+	resetMs: number;
+	/** Called when availability changes (to refresh the status line). */
+	onChange?: (available: boolean) => void;
+	now?: () => number;
+}
+
+export class Guard {
+	private openedAt: number | undefined;
+
+	private constructor(
+		private readonly breaker: CircuitBreaker,
+		private readonly opts: GuardOptions,
+	) {
+		breaker.onStateChange((from, to) => {
+			if (to === "Open") {
+				this.openedAt = this.clock();
+				opts.onChange?.(false);
+				// Tell the status line when the pause is over, even if nothing calls CodeGraph meanwhile.
+				const t = setTimeout(() => opts.onChange?.(!this.open), opts.resetMs);
+				(t as { unref?: () => void }).unref?.();
+			} else if (to === "Closed" && from !== "Closed") {
+				this.openedAt = undefined;
+				opts.onChange?.(true);
+			}
+		});
+	}
+
+	static async create(opts: GuardOptions): Promise<Guard> {
+		return new Guard(await CircuitBreaker.create(opts.threshold, opts.resetMs, 1, 1), opts);
+	}
+
+	private clock(): number {
+		return (this.opts.now ?? Date.now)();
+	}
+
+	/** CodeGraph counts as unavailable: its calls failed `threshold` times in a row, and `resetMs` has not passed. */
+	get open(): boolean {
+		return this.openedAt !== undefined && this.clock() - this.openedAt < this.opts.resetMs;
+	}
+
+	/** Run a call: retried once after a crash, counted by the breaker, failing fast while unavailable. */
+	async run<T>(block: () => Promise<T>): Promise<T> {
+		let excused: { error: unknown } | undefined;
+		try {
+			return await this.breaker.execute(async () => {
+				try {
+					return await Retry.withBackoff(block, { retries: 1, baseMillis: 0, shouldRetry: isCrash });
+				} catch (e) {
+					if (countsAsFailure(e)) throw e;
+					excused = { error: e };
+					return undefined as T;
+				}
+			});
+		} catch (e) {
+			if (isOpenError(e)) throw new Error(UNAVAILABLE);
+			throw e;
+		} finally {
+			if (excused) throw excused.error;
+		}
+	}
+}

package/extensions/graphnav.ts

@@ -14,10 +14,21 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { completions, parseCommand } from "./command/parse.ts";
-import { type Config, DEFAULT_CONFIG, readConfig, saveConfig } from "./core/config.ts";
-import { decide, findSearches, type GateMemory, isSourceFile, lookupWords, newMemory, type Search } from "./core/gate.ts";
+import { type Config, DEFAULT_CONFIG, type ProjectOverrides, readConfig, readProjectConfig, saveConfig } from "./core/config.ts";
+import {
+	codemodeSearches,
+	decide,
+	findFileSearches,
+	findSearches,
+	type GateMemory,
+	isSourceFile,
+	lookupWords,
+	newMemory,
+	type Search,
+} from "./core/gate.ts";
 import { CodeGraphServer, type Spawner } from "./core/mcp.ts";
-import { actionArgs, ensureIndex, findProject, type IndexStatus, type Project, parseStatus, type Runner } from "./core/project.ts";
+import { actionArgs, ensureIndex, findProject, type IndexStatus, type Project, parseStatus, type Runner, runUnlocking } from "./core/project.ts";
+import { Guard } from "./core/resilience.ts";
 import { GUIDELINES, isCodeGraphTool, normalizeFilesPath, resultText, TOOLS } from "./core/tools.ts";
 
 export type IndexState = "none" | "checking" | "indexing" | "ready" | "missing" | "error";
@@ -29,11 +40,20 @@ export interface Status {
 	index?: IndexStatus;
 	blocked: number;
 	nudged: number;
+	/** Blocks the agent answered with a CodeGraph call. */
+	followed: number;
+	/** Blocks the agent overrode by running the same search again. */
+	overridden: number;
+	/** CodeGraph's recent calls failed: the gate stands aside until it recovers. */
+	unavailable?: boolean;
+	/** Settings this project overrides (`.pi/codegraph.json`). */
+	overrides?: ProjectOverrides;
 	error?: string;
 }
 
 export function statusText(s: Status): string {
 	if (!s.config.enabled) return "codegraph: off";
+	if (s.unavailable) return `codegraph: unavailable · ${s.config.mode}`;
 	const files = s.index && s.state === "ready" ? ` · ${s.index.files} files` : "";
 	return `codegraph: ${s.state}${files} · ${s.config.mode}`;
 }
@@ -43,7 +63,13 @@ export function statusReport(s: Status): string {
 		statusText(s),
 		`project: ${s.project?.root ?? "(none: not in a git repo or indexed directory)"}`,
 		s.index ? `index: ${s.index.state}, ${s.index.files} files, ${s.index.pending} pending changes` : undefined,
-		`this session: ${s.blocked} searches blocked, ${s.nudged} nudged`,
+		s.overrides && Object.keys(s.overrides).length > 0
+			? `project settings (.pi/codegraph.json): ${Object.entries(s.overrides)
+					.map(([k, v]) => `${k} ${v}`)
+					.join(", ")}`
+			: undefined,
+		`this session: ${s.blocked} searches blocked (${s.followed} answered with CodeGraph, ${s.overridden} re-run), ${s.nudged} nudged`,
+		s.unavailable ? "CodeGraph is unavailable (recent calls failed): searches are not gated until it recovers" : undefined,
 		s.error ? `last error: ${s.error}` : undefined,
 	]
 		.filter(Boolean)
@@ -70,7 +96,10 @@ export const defaultRunner: Runner = (args, cwd) =>
 
 /** The searches a tool call performs, if it is one the gate looks at. */
 export function searchesOf(toolName: string, input: Record<string, unknown>): Search[] {
-	if ((toolName === "bash" || toolName === "powershell") && typeof input.command === "string") return findSearches(input.command);
+	if ((toolName === "bash" || toolName === "powershell") && typeof input.command === "string")
+		return [...findSearches(input.command), ...findFileSearches(input.command)];
+	if (toolName === "codemode" && typeof input.code === "string") return codemodeSearches(input.code);
+	if (toolName === "find" && typeof input.pattern === "string") return [{ tool: "find", pattern: input.pattern, paths: [], filters: [], files: true }];
 	if (toolName === "grep" && typeof input.pattern === "string") {
 		return [
 			{
@@ -87,22 +116,36 @@ export function searchesOf(toolName: string, input: Record<string, unknown>): Se
 export const READ_HINT =
 	"[codegraph] Several source files read without CodeGraph. codegraph_explore returns the relevant symbols' source and the call paths between them in one call; codegraph_callers/codegraph_impact show relations.";
 
-/** Seams for tests: the CLI runner and the server process. */
+export const LARGE_READ_LINES = 400;
+export const LARGE_READ_HINT =
+	"[codegraph] That was a whole large source file. To work on part of it, codegraph_node({ symbol, includeCode: true }) returns just that symbol's source, and codegraph_explore the relevant symbols across files.";
+
+/** Lines in a tool result's text. */
+const lineCount = (content: unknown): number =>
+	Array.isArray(content) ? content.reduce((n, c) => n + (typeof c?.text === "string" ? c.text.split("\n").length : 0), 0) : 0;
+
+/** Seams for tests: the CLI runner, the server process, the circuit breaker's settings. */
 export interface Deps {
 	run?: Runner;
 	spawn?: Spawner;
+	breaker?: { threshold: number; resetMs: number };
 }
 
 export function createExtension(deps: Deps = {}) {
 	const run = deps.run ?? defaultRunner;
 	return function (pi: ExtensionAPI) {
+		let base: Config = { ...DEFAULT_CONFIG };
+		let overrides: ProjectOverrides = {};
 		let config: Config = { ...DEFAULT_CONFIG };
 		let project: Project | undefined;
 		let state: IndexState = "none";
 		let index: IndexStatus | undefined;
 		let lastError: string | undefined;
 		let mem: GateMemory = newMemory();
-		let counts = { blocked: 0, nudged: 0 };
+		let counts = { blocked: 0, nudged: 0, followed: 0, overridden: 0 };
+		let awaitingFollow = false;
+		const largeReads = new Set<string>();
+		const guards = new Map<string, Promise<Guard>>();
 		let sourceReads = 0;
 		let usedCodeGraph = false;
 		let readHinted = false;
@@ -112,7 +155,9 @@ export function createExtension(deps: Deps = {}) {
 		let jobRoot: string | undefined;
 		let ui: { setStatus(key: string, text: string): void } | undefined;
 
-		const snapshot = (): Status => ({ config, project, state, index, error: lastError, ...counts });
+		const guardNow = new Map<string, Guard>();
+		const unavailable = (root = project?.root) => (root ? (guardNow.get(root)?.open ?? false) : false);
+		const snapshot = (): Status => ({ config, project, state, index, error: lastError, ...counts, unavailable: unavailable(), overrides });
 		const refresh = () => ui?.setStatus("codegraph", config.enabled && config.showStatus ? statusText(snapshot()) : "");
 
 		const server = (root: string) => {
@@ -123,6 +168,15 @@ export function createExtension(deps: Deps = {}) {
 			}
 			return s;
 		};
+		const guard = (root: string): Promise<Guard> => {
+			let g = guards.get(root);
+			if (!g) {
+				g = Guard.create({ threshold: deps.breaker?.threshold ?? 3, resetMs: deps.breaker?.resetMs ?? 60_000, onChange: () => refresh() });
+				void g.then((x) => guardNow.set(root, x));
+				guards.set(root, g);
+			}
+			return g;
+		};
 		const closeAll = () => {
 			for (const s of servers.values()) s.close();
 			servers.clear();
@@ -154,7 +208,7 @@ export function createExtension(deps: Deps = {}) {
 
 		const runAction = (action: "init" | "index" | "sync") =>
 			indexJob(async (p) => {
-				const res = await run(actionArgs(action), p.root);
+				const res = await runUnlocking(run, actionArgs(action), p.root);
 				const status = parseStatus((await run(["status", "-j"], p.root)).stdout);
 				const error =
 					res.code === 127 ? "the codegraph CLI is not installed (npm i -g @colbymchenry/codegraph)" : res.code !== 0 ? `codegraph ${action} failed (exit ${res.code})` : undefined;
@@ -171,17 +225,23 @@ export function createExtension(deps: Deps = {}) {
 
 		pi.on("session_start", async (_event, ctx) => {
 			const { config: loaded, problem } = await readConfig();
-			config = loaded;
+			base = loaded;
 			ui = ctx.ui;
 			if (problem) ctx.ui.notify(`codegraph: ${problem}; using the defaults`, "warning");
 			closeAll();
 			mem = newMemory();
-			counts = { blocked: 0, nudged: 0 };
+			counts = { blocked: 0, nudged: 0, followed: 0, overridden: 0 };
+			awaitingFollow = false;
+			largeReads.clear();
 			sourceReads = 0;
 			usedCodeGraph = false;
 			readHinted = false;
 			nudges.clear();
 			project = findProject(ctx.cwd);
+			const local = project ? await readProjectConfig(project.root) : { overrides: {} };
+			if (local.problem) ctx.ui.notify(`codegraph: ${local.problem}; ignoring it`, "warning");
+			overrides = local.overrides;
+			config = { ...base, ...overrides };
 			index = undefined;
 			lastError = undefined;
 			state = project ? "checking" : "none";
@@ -215,8 +275,12 @@ export function createExtension(deps: Deps = {}) {
 						else args.path = path;
 					}
 					usedCodeGraph = true;
+					if (awaitingFollow) {
+						awaitingFollow = false;
+						counts.followed++;
+					}
 					for (const w of lookupWords(params)) mem.lookedUp.add(w);
-					const result = await server(root).call(tool.name, args, signal);
+					const result = await (await guard(root)).run(() => server(root).call(tool.name, args, signal));
 					const text = resultText(result);
 					if (result.isError) throw new Error(text);
 					return { content: [{ type: "text" as const, text }], details: { root } };
@@ -233,15 +297,20 @@ export function createExtension(deps: Deps = {}) {
 		});
 
 		pi.on("tool_call", async (event: any) => {
-			if (!config.enabled || config.mode === "off" || state !== "ready") return;
+			if (!config.enabled || config.mode === "off" || state !== "ready" || unavailable()) return;
 			const searches = searchesOf(event.toolName, event.input ?? {});
 			if (searches.length === 0) return;
 			const d = decide(config.mode, searches, `${event.toolName}\u0000${JSON.stringify(event.input)}`, mem);
 			if (d.action === "block") {
 				counts.blocked++;
+				awaitingFollow = true;
 				refresh();
 				return { block: true, reason: d.reason };
 			}
+			if (d.action === "allow" && d.override) {
+				counts.overridden++;
+				awaitingFollow = false;
+			}
 			if (d.action === "nudge") {
 				counts.nudged++;
 				nudges.set(event.toolCallId, d.hint);
@@ -268,6 +337,22 @@ export function createExtension(deps: Deps = {}) {
 				readHinted = true;
 				hint = READ_HINT;
 			}
+			if (
+				!hint &&
+				config.enabled &&
+				config.mode !== "off" &&
+				state === "ready" &&
+				event.toolName === "read" &&
+				typeof event.input?.path === "string" &&
+				event.input.offset === undefined &&
+				event.input.limit === undefined &&
+				isSourceFile(event.input.path) &&
+				!largeReads.has(event.input.path) &&
+				lineCount(event.content) > LARGE_READ_LINES
+			) {
+				largeReads.add(event.input.path);
+				hint = LARGE_READ_HINT;
+			}
 			if (!hint) return;
 			return { content: [...(event.content ?? []), { type: "text", text: `\n${hint}` }] };
 		});
@@ -281,7 +366,7 @@ export function createExtension(deps: Deps = {}) {
 			// The setting applies to this session either way; a failed save only means it is not remembered.
 			const persist = async () => {
 				try {
-					await saveConfig(config);
+					await saveConfig(base);
 				} catch (error) {
 					ctx.ui.notify(`codegraph: could not save the setting (${(error as Error)?.message ?? String(error)}); it applies to this session only`, "warning");
 				}
@@ -293,13 +378,13 @@ export function createExtension(deps: Deps = {}) {
 					return;
 				case "on":
 				case "off":
-					config.enabled = cmd.kind === "on";
+					config.enabled = base.enabled = cmd.kind === "on";
 					if (config.enabled && project && state === "checking") startIndexing();
 					await persist();
 					ctx.ui.notify(`codegraph ${config.enabled ? "on" : "off"}`, "info");
 					return;
 				case "mode":
-					config.mode = cmd.mode;
+					config.mode = base.mode = cmd.mode;
 					await persist();
 					ctx.ui.notify(`codegraph: mode ${cmd.mode}`, "info");
 					return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-graphnav",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CodeGraph-first code navigation for pi: persistent index, auto init/sync, and a gate that steers structural searches to codegraph_* tools.",
   "keywords": [
     "pi-package",
@@ -46,5 +46,8 @@
     "@types/bun": "^1.4.4",
     "typescript": "^7.0.2",
     "@earendil-works/pi-ai": "^1.4.0"
+  },
+  "dependencies": {
+    "arrow-resilience-kit": "^0.10.2"
   }
 }