@colbymchenry/codegraph 1.0.1 → 1.1.1

package/dist/index.d.ts

@@ -66,6 +66,28 @@ export declare class CodeGraph {
     private fileLock;
     private watcher;
     private constructor();
+    /**
+     * (Re)build the query/extraction/graph layers over the current `this.queries`
+     * (which wraps `this.db`). Factored out of the constructor so `reopenIfReplaced`
+     * can rebuild them against a fresh connection without duplicating the wiring.
+     * The path-based `fileLock` is independent of the DB handle, so it stays put.
+     */
+    private wireLayers;
+    /**
+     * Heal a stale database handle in place. If `.codegraph/` was removed and
+     * recreated at the SAME path while this instance held the DB open — a git
+     * worktree removed and re-added, or `rm -rf .codegraph` + `codegraph init` —
+     * our open fd points at the now-unlinked inode and can never see the new
+     * index, so every query returns the pre-removal snapshot until the process
+     * restarts (#925). When that's detected, open the live file at the same path,
+     * rebuild the query layers, and swap them IN PLACE, so every holder of this
+     * instance (the MCP daemon's default project, cached projectPath connections)
+     * heals without a restart. Returns true iff it reopened.
+     *
+     * POSIX-only in practice: `isReplacedOnDisk` never fires on Windows (an open
+     * file can't be unlinked there, and st_ino is unreliable).
+     */
+    reopenIfReplaced(): boolean;
     /**
      * Initialize a new CodeGraph project
      *
@@ -144,6 +166,17 @@ export declare class CodeGraph {
      * Check if the file watcher is active.
      */
     isWatching(): boolean;
+    /**
+     * True once live watching has permanently degraded (OS watch-resource
+     * exhaustion, or a write lock held past the retry budget) and auto-sync is
+     * disabled until the next {@link watch} call. Distinct from `!isWatching()`:
+     * a stopped/never-started watcher is inactive but NOT degraded. MCP tools use
+     * this to surface a whole-index "results may be stale" notice, since
+     * `getPendingFiles()` goes empty once watching stops (#876).
+     */
+    isWatcherDegraded(): boolean;
+    /** The reason live watching degraded, or null if it is healthy (#876). */
+    getWatcherDegradedReason(): string | null;
     /**
      * Files seen by the file watcher since the last successful sync —
      * the per-file "stale" signal MCP tools attach to responses so an agent

package/dist/installer/instructions-template.d.ts

@@ -17,8 +17,8 @@
  *    runs without this block, and consistently with it — including runs
  *    with zero Read/grep fallback.
  *  - **Non-MCP harnesses** — agents with no MCP client at all can still
- *    run the `codegraph explore` / `codegraph node` CLI, which prints the
- *    same output as the MCP tools.
+ *    run the `codegraph explore` CLI, which prints the same output as the
+ *    MCP tool.
  *
  * Keep this block SHORT. The main agent reads it every turn on top of the
  * server instructions — the #529 duplication-cost argument still bounds
@@ -37,5 +37,5 @@ export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
  * indexed" claim would send subagents into failing codegraph calls (the
  * noise the unindexed-session policy exists to prevent).
  */
-export declare const CODEGRAPH_INSTRUCTIONS_BLOCK = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nIn repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:\n\n- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call \u2014 the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.\n- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` and `codegraph node <symbol-or-file>` print the same output.\n\nIf there is no `.codegraph/` directory, skip CodeGraph entirely \u2014 indexing is the user's decision.\n<!-- CODEGRAPH_END -->";
+export declare const CODEGRAPH_INSTRUCTIONS_BLOCK = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nIn repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:\n\n- **MCP tool** (when available): `codegraph_explore` answers most code questions in one call \u2014 the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.\n- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` prints the same output.\n\nIf there is no `.codegraph/` directory, skip CodeGraph entirely \u2014 indexing is the user's decision.\n<!-- CODEGRAPH_END -->";
 //# sourceMappingURL=instructions-template.d.ts.map

package/dist/installer/targets/claude.d.ts

@@ -26,22 +26,28 @@ import { AgentTarget, Location, WriteResult } from './types';
  */
 export declare function writeMcpEntry(loc: Location): WriteResult['files'][number];
 /**
- * Remove stale codegraph auto-sync hooks from Claude `settings.json`.
- *
- * Surgical at the individual-command level: only entries matching
- * `isLegacyCodegraphHookCommand` are dropped, so a sibling hook sharing
- * a matcher group (or the Stop event) with ours survives. We prune a
- * matcher group only once its `hooks` array is empty, an event only
- * once it has no groups left, and `hooks` itself only once every event
- * is gone — and none of that runs unless we actually removed a
- * codegraph command, so a settings.json with no legacy hooks is left
- * byte-for-byte untouched and reported `unchanged`.
- *
- * Exported so it can be unit-tested directly and reused by both
+ * Remove stale codegraph auto-sync hooks (`mark-dirty` / `sync-if-dirty`) that a
+ * pre-0.8 install wrote. Exported for direct unit-testing; reused by both
  * `install` (an upgrade self-heals) and `uninstall`.
  */
 export declare function cleanupLegacyHooks(loc: Location): WriteResult['files'][number];
+/**
+ * Remove the front-load `UserPromptSubmit` hook this installer writes (see
+ * writePromptHookEntry). Used by `uninstall`, and by `install` when the user
+ * opts out, so the choice round-trips.
+ */
+export declare function removePromptHookEntry(loc: Location): WriteResult['files'][number];
 export declare function writePermissionsEntry(loc: Location): WriteResult['files'][number];
+/**
+ * Write the front-load `UserPromptSubmit` hook into Claude `settings.json` —
+ * a `command` hook that runs `codegraph prompt-hook`, which injects
+ * codegraph_explore context for structural prompts so the agent reliably uses
+ * the graph. Idempotent: if our command is already wired under UserPromptSubmit
+ * the file is left byte-for-byte untouched and reported `unchanged`. Sibling
+ * hooks (the user's own, or other events) are preserved. Opt-in — the installer
+ * only calls this when the user accepts the prompt (default-yes).
+ */
+export declare function writePromptHookEntry(loc: Location): WriteResult['files'][number];
 /**
  * Strip the marker-delimited CodeGraph block from CLAUDE.md if a prior
  * install wrote one. Codegraph no longer maintains an instructions file

package/dist/installer/targets/shared.d.ts

@@ -19,8 +19,18 @@ export declare function getMcpServerConfig(): {
 };
 /**
  * Permissions list for Claude `settings.json`. Other targets that
- * have a permissions concept can compose this list directly. The
- * permission strings follow Claude's `mcp__<server>__<tool>` format.
+ * have a permissions concept can compose this list directly.
+ *
+ * One server-scoped wildcard rather than a per-tool list. By default only
+ * `codegraph_explore` is even LISTED to the agent (see DEFAULT_MCP_TOOLS in
+ * mcp/tools.ts), so in practice explore is the only tool this auto-approves —
+ * but the wildcard means that if a user re-enables another tool via
+ * CODEGRAPH_MCP_TOOLS, it's already pre-approved (no permission prompt, no
+ * hand-editing settings.json), and future tools are covered too. Claude only
+ * honors globs after a literal `mcp__<server>__` prefix, so this exact string
+ * is the way to allow-all for one server; a bare `mcp__codegraph` or `*` is
+ * ignored. The allowlist gates PROMPTING, not visibility, so a superset here
+ * never makes a hidden tool appear.
  */
 export declare function getCodeGraphPermissions(): string[];
 /**

package/dist/installer/targets/types.d.ts

@@ -63,6 +63,13 @@ export interface InstallOptions {
      * target has no permissions concept this option is a no-op.
      */
     autoAllow: boolean;
+    /**
+     * Front-load prompt hook (Claude `UserPromptSubmit`) that injects
+     * codegraph_explore context for structural prompts. `true` installs it,
+     * `false` removes any prior install (so opt-out round-trips), `undefined`
+     * leaves it untouched. Targets without a prompt-hook concept ignore it.
+     */
+    promptHook?: boolean;
 }
 export interface AgentTarget {
     /** Stable id; matches the `TargetId` union. */

package/dist/mcp/server-instructions.d.ts

@@ -7,24 +7,28 @@
  * before it sees individual tool descriptions.
  *
  * Goals when editing this:
- *   - Tool selection by intent (which tool for which question)
- *   - Common chains (refactor planning = X then Y)
- *   - Anti-patterns (don't grep when codegraph_search is faster)
+ *   - Lead the agent to codegraph_explore for any structural/flow question
+ *   - Reinforce "explore instead of Read/Grep" for indexed code
+ *   - Anti-patterns (don't re-verify with grep; don't hand-reconstruct flows)
  *
  * Keep it tight. The agent reads this every session — long instructions
- * burn tokens. Reference only tools that exist on `main`; gate any
- * conditional tools behind feature checks if/when they ship.
+ * burn tokens. The DEFAULT MCP surface is `codegraph_explore` ALONE (see
+ * DEFAULT_MCP_TOOLS in tools.ts) — reference only that tool here. The other
+ * tools (node/search/callers/…) stay defined and are re-enablable via
+ * CODEGRAPH_MCP_TOOLS, but they are NOT listed to agents, so don't name them.
  */
-export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file in\nthe workspace \u2014 pre-computed structure you would otherwise re-derive by\nreading files (cached intelligence: thousands of parse/trace decisions you\ndon't pay to re-reason each run). Reads are sub-millisecond; the index lags\nwrites by ~1s through the file watcher. Reach for it BEFORE *and* while\nwriting or editing code \u2014 not just for questions: one call returns the\nverbatim source PLUS who calls it and what it affects, so you edit with the\nblast radius in view. More accurate context, in far fewer tokens and\nround-trips than reading files yourself.\n\n## Use codegraph instead of reading files \u2014 for questions AND edits\n\nWhether you're answering \"how does X work\" or implementing a change (fixing\na bug, adding a feature), reach for codegraph before you Read. For\nunderstanding, answer DIRECTLY \u2014 usually with ONE `codegraph_explore` call.\n`codegraph_explore` takes either a natural-language question or a bag of\nsymbol/file names and returns the verbatim source of the relevant symbols\ngrouped by file, so it is Read-equivalent and most often the ONLY\ncodegraph call you need. Codegraph IS the pre-built search index \u2014 so\ndelegating the lookup to a separate file-reading sub-task/agent, or\nrunning your own grep + read loop, repeats work codegraph already did and\ncosts more for the same answer. Reach for raw Read/Grep only to confirm a\nspecific detail codegraph didn't cover. A direct codegraph answer is\ntypically one to a few calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `codegraph_explore` (PRIMARY \u2014 call FIRST; ONE capped call returns the verbatim source of the relevant symbols grouped by file; most often the ONLY call you need)\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `codegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, including dynamic-dispatch hops (callbacks, React re-render, JSX children) grep can't follow\n- **\"What is the symbol named X?\" (just its location)** \u2192 `codegraph_search`\n- **\"What calls this?\" / \"What would changing this break?\"** \u2192 `codegraph_callers` \u2014 EVERY call site with file:line, including where a function is **registered as a callback** (passed as an argument, assigned to a function pointer/field, listed in a handler table) \u2014 labeled \"via callback registration\" \u2014 so a function with no direct calls is NOT dead if it's wired up somewhere. When several UNRELATED symbols share a name (one `UserService` per monorepo app), it reports **one section per definition** (never a merged list) \u2014 pass `file` to focus the definition you mean. The wider blast radius arrives automatically on `codegraph_explore` (its \"Blast radius\" section) and `codegraph_node` (the dependents note)\n- **\"What does this call?\"** \u2192 `codegraph_node` with that symbol and `includeCode: true` \u2014 the body IS the callee list, and the caller/callee trail comes with it\n- **Reading a source FILE (any time you'd use the `Read` tool)** \u2192 `codegraph_node` with a `file` path and no `symbol`. It returns the file's **current source with line numbers \u2014 the same `<n>\\t<line>` shape `Read` gives you, safe to `Edit` from** \u2014 narrowable with `offset`/`limit` exactly like `Read`, PLUS a one-line note of which files depend on it. Same bytes as `Read`, faster (served from the index), with the blast radius attached. Use it **instead of `Read`** for indexed source files; fall back to `Read` only for what codegraph doesn't index (configs, docs). Pass `symbolsOnly: true` for just the file's structure.\n- **About to read or edit a symbol you can name** \u2192 `codegraph_node` with that `symbol` (SECONDARY \u2014 the after-explore depth tool): the verbatim source (`includeCode: true`) PLUS its caller/callee trail, so before changing it you see what calls it and what your edit would break. For an OVERLOADED name it returns EVERY matching definition's body in one call, so you never Read a file to find the right overload\n\n## Common chains\n\n- **Flow / \"how does X reach Y\"**: ONE `codegraph_explore` with the symbol names spanning the flow \u2014 it surfaces the call path among them (riding dynamic-dispatch hops) AND returns their source. No need to reconstruct the path with `codegraph_search` + `codegraph_callers`.\n- **Onboarding / understanding any area**: ONE `codegraph_explore` is usually the whole answer. Only follow up \u2014 `codegraph_node` for a specific symbol \u2014 if something is still unclear.\n- **Refactor planning**: `codegraph_callers` for the complete call-site list to update; the wider blast radius is already attached to `codegraph_explore` / `codegraph_node` output.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; `codegraph_node` on anything unexpected that appears.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don't chain `codegraph_search` + `codegraph_node`** to understand an area \u2014 ONE `codegraph_explore` returns the relevant symbols' source together in a single round-trip.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use `codegraph_node` for a single symbol.\n- **Don't reach for the `Read` tool on an indexed source file** \u2014 `codegraph_node` with a `file` reads it for you (same `<n>\\t<line>` source, `offset`/`limit` like Read, faster, with its blast radius), and with a `symbol` it returns the source plus the caller/callee trail. Reach for raw `Read` only for what codegraph doesn't index (configs, docs) or when the staleness banner flags a file as pending re-index.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph.\n\n## Limitations\n\n- If a tool reports a project isn't indexed (no `.codegraph/`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision \u2014 mention they can run `codegraph init` if it comes up, but don't run it yourself.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
+export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file in\nthe workspace \u2014 pre-computed structure you would otherwise re-derive by\nreading files (cached intelligence: thousands of parse/trace decisions you\ndon't pay to re-reason each run). Reads are sub-millisecond; the index lags\nwrites by ~1s through the file watcher. Reach for it BEFORE *and* while\nwriting or editing code \u2014 not just for questions: one call returns the\nverbatim source PLUS who calls it and what it affects, so you edit with the\nblast radius in view. More accurate context, in far fewer tokens and\nround-trips than reading files yourself.\n\n## One tool: codegraph_explore \u2014 use it instead of reading files\n\nThere is a single tool, `codegraph_explore`, and it is Read-equivalent. It\ntakes either a natural-language question or a bag of symbol/file names and\nreturns the **verbatim, line-numbered source** of the relevant symbols\ngrouped by file \u2014 the same `<n>\\t<line>` shape `Read` gives you, safe to\n`Edit` from \u2014 PLUS the call path among them (including dynamic-dispatch hops\nlike callbacks, React re-render, and JSX children that grep can't follow) and\na blast-radius summary of what depends on them.\n\nWhether you're answering \"how does X work\" or implementing a change (fixing a\nbug, adding a feature), call `codegraph_explore` before you Read. ONE call\nusually answers the whole question. Codegraph IS the pre-built search index \u2014\nso running your own grep + read loop, or delegating the lookup to a separate\nfile-reading sub-task/agent, repeats work codegraph already did and costs more\nfor the same answer. A direct codegraph answer is typically one to a few\ncalls; a grep/read exploration is dozens.\n\n## How to query\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `codegraph_explore` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `codegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.\n- **Reading or editing a file/symbol you can name** \u2192 put its name or file path in the `codegraph_explore` query \u2014 it returns that current line-numbered source (safe to `Edit` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.\n- **Need more?** Call `codegraph_explore` again with more specific names \u2014 treat the source it returns as already Read.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep or Read first** to find or understand indexed code \u2014 ONE `codegraph_explore` returns the relevant symbols' source together in a single round-trip. Reach for raw `Read`/`Grep` only to confirm a specific detail codegraph didn't cover, or for what codegraph doesn't index (configs, docs).\n- **Don't reconstruct a flow by hand** \u2014 name the endpoints in one `codegraph_explore` and it surfaces the path between them, dynamic-dispatch hops included.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. A different, rarer banner \u2014 \"\u26A0\uFE0F CodeGraph auto-sync is DISABLED\u2026\" \u2014 means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.\n\n## Limitations\n\n- If a tool reports a project isn't indexed (no `.codegraph/`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision \u2014 mention they can run `codegraph init` if it comes up, but don't run it yourself.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
 /**
- * Instructions variant sent when the workspace has NO codegraph index.
+ * Instructions variant sent when the server's own root has NO codegraph index.
  *
- * Sending the full playbook ("lean on codegraph for everything") into a
- * session where every call would fail wastes the agent's calls and — worse —
- * the failures teach it codegraph is broken. The unindexed variant is a
- * short, unambiguous "inactive this session" note; `tools/list` is gated to
- * empty in the same state, so the agent has nothing to mis-call. Indexing is
- * deliberately left to the user: the agent is told NOT to run init itself.
+ * The tools are still exposed (gating tool availability on whether `./` has an
+ * index is the bug behind #964: it breaks monorepos where only sub-projects are
+ * indexed, and a server that started before `codegraph init` never surfaces the
+ * tools afterward). Instead of an "inactive" note, this variant tells the agent
+ * codegraph works **per project**: there's no default project to query, so pass
+ * a `projectPath` to any project that HAS a `.codegraph/`. The full single-
+ * project playbook ({@link SERVER_INSTRUCTIONS}) is sent instead when the root
+ * IS indexed, so the common case stays tight.
  */
-export declare const SERVER_INSTRUCTIONS_UNINDEXED = "# Codegraph \u2014 inactive (workspace not indexed)\n\nThis workspace has no codegraph index (no `.codegraph/` directory), so no\ncodegraph tools are available this session. Work with your built-in tools as\nusual.\n\nIndexing is the user's decision \u2014 do not run it yourself. If the user asks\nabout codegraph, they can enable it by running `codegraph init` in the\nproject root and starting a new session.\n";
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# Codegraph \u2014 available (per-project; pass projectPath)\n\nCodegraph is a SQLite knowledge graph of a codebase's symbols, edges, and\nfiles: one `codegraph_explore` call returns the verbatim, line-numbered source\nof the relevant symbols PLUS the call paths between them and a blast-radius\nsummary \u2014 replacing a grep + Read loop with one round-trip.\n\nThis server started somewhere with no `.codegraph/` of its own, so there is no\ndefault project \u2014 but the tools are available and work **per project**:\n\n- To query a project that HAS a `.codegraph/` index (e.g. a service inside a\n  monorepo, or a second repo), pass its path as `projectPath` to\n  `codegraph_explore` (and any other codegraph tool). Codegraph resolves the\n  nearest `.codegraph/` at or above that path and answers from it \u2014 for as many\n  projects as you like in one session.\n- For a project with no `.codegraph/`, use your built-in tools (Read/Grep/Glob)\n  for that project. Indexing is the user's decision \u2014 don't run it yourself, but\n  if it comes up they can run `codegraph init` in a project to enable codegraph\n  there (a new index is picked up live, no restart).\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/tools.d.ts

@@ -57,7 +57,7 @@ export interface ExploreOutputBudget {
     maxCharsPerFile: number;
     /** Cluster gap threshold in lines — tighter clustering on small projects. */
     gapThreshold: number;
-    /** Max symbols listed in the per-file header (`#### path — sym(kind), ...`). */
+    /** Max symbols listed in the per-file header (``**`path`** — sym(kind), ...``). */
     maxSymbolsInFileHeader: number;
     /** Max edges shown per relationship kind in the Relationships section. */
     maxEdgesPerRelationshipKind: number;
@@ -93,6 +93,15 @@ export declare function formatStaleBanner(stale: PendingFile[]): string;
  * without bloating the main banner.
  */
 export declare function formatStaleFooter(stale: PendingFile[]): string;
+/**
+ * Whole-index degradation banner (issue #876). Emitted at the top of a read
+ * tool response when live watching has permanently stopped — at which point
+ * `getPendingFiles()` is empty, so the per-file banner above can't fire even
+ * though the index is now FROZEN and silently drifting stale. Leads with the
+ * agent-actionable instruction (Read directly) and carries the reason, which
+ * already names the operator remedy (`codegraph sync` / git hooks).
+ */
+export declare function formatDegradedBanner(reason: string | null): string;
 /**
  * MCP Tool definition
  */
@@ -163,6 +172,16 @@ export declare class ToolHandler {
      * stale data, which is what would have happened without the gate.
      */
     setCatchUpGate(p: Promise<void> | null): void;
+    /**
+     * Await the catch-up gate, but no longer than the configured timeout (#905).
+     * If the reconcile settles first, we got the fully-reconciled answer. If the
+     * timeout wins, we serve the call now and let the reconcile finish in the
+     * background — it yields to the event loop (see SYNC_RECONCILE_YIELD_INTERVAL),
+     * so a concurrent read still runs against the same connection. Never throws:
+     * a failed reconcile is logged by the engine, and we serve best-effort over
+     * the same potentially-stale data the un-gated path would have.
+     */
+    private awaitCatchUpGate;
     /**
      * Record the directory the server tried to resolve the default project from.
      * Used only to make the "no default project" error actionable.
@@ -200,6 +219,17 @@ export declare class ToolHandler {
      * similar to how git finds .git/ directories.
      */
     private getCodeGraph;
+    /**
+     * Heal a long-lived connection whose `.codegraph/` was removed and recreated
+     * at the same path (a worktree recreated, or `rm -rf .codegraph` + re-init)
+     * before handing it to a tool. Otherwise the daemon keeps serving the
+     * pre-removal snapshot from its now-unlinked file handle until restart — and
+     * because the daemon registry is keyed by path, a same-path recreate routes
+     * new clients straight back to this same stale daemon (#925). The check is one
+     * stat() and a no-op unless the inode actually changed; it never throws into a
+     * tool call.
+     */
+    private freshen;
     /**
      * Close all cached project connections
      */
@@ -316,6 +346,26 @@ export declare class ToolHandler {
      * connected flow never reaches this method.
      */
     private buildDynamicBoundaries;
+    /**
+     * Interface/registry-dispatch announcement — #687 extended to GRAPH-visible
+     * polymorphism (the body-scan can't see it: `nodeType.execute()` is textually
+     * an ordinary call; the polymorphism lives in the `implements`/`extends` edges).
+     *
+     * A method the agent named that resolves to a large same-name family whose
+     * definers overwhelmingly implement/extend ONE supertype is a runtime dispatch:
+     * the concrete target is chosen at runtime from N implementations, so no single
+     * static edge is "the answer" — the implementations ARE the continuations. We
+     * announce the supertype, its TRUE implementer count, and a few concrete targets,
+     * then steer to codegraph_explore. Graph-only, query-time, zero mutation; the
+     * caller fires it ONLY for an UNCOVERED named token, so a connected flow is silent.
+     *
+     * Robust to FTS sampling bias: the same-name family is a capped FTS sample that
+     * over-represents whatever FTS ranks first (n8n: DB `TableOperation.execute`
+     * outnumbered `INodeType.execute` in the sample 7:6 even though INodeType has
+     * 611 implementers vs a handful). So candidate supertypes are ranked by their
+     * TRUE graph-wide implementer count, NOT their frequency in the sample.
+     */
+    private buildPolymorphicBoundaries;
     /**
      * Shortlist candidate runtime targets for a dispatch key surfaced by
      * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →

package/dist/project-config.d.ts

@@ -0,0 +1,36 @@
+import { Language } from './types';
+/** Filename of the project-scoped config, resolved relative to the project root. */
+export declare const PROJECT_CONFIG_FILENAME = "codegraph.json";
+export interface ProjectConfig {
+    /** Map of custom file extension (`.foo`) to a supported language id. */
+    extensions?: Record<string, string>;
+    /**
+     * Gitignore-style patterns naming gitignored directories whose embedded git
+     * repositories should be indexed anyway — the explicit opt-in to override
+     * `.gitignore` for nested-repo discovery (#622, #699). Absent/empty (the
+     * default) means `.gitignore` is fully respected: gitignored embedded repos
+     * are never discovered or indexed (#970, #976).
+     */
+    includeIgnored?: string[];
+}
+/**
+ * Load the validated extension overrides for a project, mtime-cached.
+ *
+ * Returns a map of `.ext` → supported language id. The result merges on top of
+ * the built-in extension map at the point of use (see `detectLanguage` /
+ * `isSourceFile`), with these user mappings taking precedence. Returns an empty
+ * map when there is no `codegraph.json` (the zero-config default).
+ */
+export declare function loadExtensionOverrides(rootDir: string): Record<string, Language>;
+/**
+ * Load the validated `includeIgnored` patterns for a project, mtime-cached.
+ *
+ * These name gitignored directories whose embedded git repositories should be
+ * indexed despite `.gitignore` (#622, #699). An empty result — the zero-config
+ * default — means `.gitignore` is fully respected: gitignored embedded repos
+ * are never discovered or indexed (#970, #976).
+ */
+export declare function loadIncludeIgnoredPatterns(rootDir: string): string[];
+/** Test/maintenance hook: forget cached config (e.g. after rewriting it in a test). */
+export declare function clearProjectConfigCache(): void;
+//# sourceMappingURL=project-config.d.ts.map

package/dist/reasoning/config.d.ts

@@ -0,0 +1,45 @@
+/** Managed tier ("CodeGraph AI") — the metered gateway used when logged in. */
+export declare const MANAGED_DEFAULT_URL = "https://ai.getcodegraph.com/v1";
+/** The gateway's public model id (it translates this to the upstream provider id). */
+export declare const MANAGED_DEFAULT_MODEL = "openai/gpt-oss-120b";
+export interface OffloadConfig {
+    /** Managed tier: route through CodeGraph AI (metered) with the logged-in org token. */
+    managed?: boolean;
+    /** OpenAI-compatible base URL ending in `/v1` (e.g. https://api.cerebras.ai/v1). */
+    url?: string;
+    /** Model id to request (default `gpt-oss-120b` BYO, `openai/gpt-oss-120b` managed). */
+    model?: string;
+    /** Name of the env var holding the provider API key (never persisted). BYO only. */
+    keyEnv?: string;
+    /** reasoning_effort: low | medium | high (default `low`). */
+    effort?: string;
+    /** Output style: plain | report (default `plain`). */
+    style?: string;
+}
+export interface ResolvedOffload {
+    /** True when the offload is usable (endpoint present; for managed, a token too). */
+    enabled: boolean;
+    /** Managed tier (CodeGraph AI, metered) vs BYO endpoint. */
+    managed: boolean;
+    url?: string;
+    model: string;
+    /** Resolved API key / org token (from env, the configured `keyEnv`, or login), if any. */
+    apiKey?: string;
+    /** Where the key/token came from (for `status` display) — never the secret itself. */
+    keySource?: string;
+    effort: string;
+    style: string;
+    timeoutMs: number;
+    maxTokens: number;
+    strip: boolean;
+    debug: boolean;
+    /** Where the endpoint came from — drives `codegraph offload status`. */
+    origin: 'env' | 'config' | 'none';
+}
+/** The persisted offload block (empty object if none). */
+export declare function readOffloadConfig(): OffloadConfig;
+/** Persist (or, with `null`, clear) the offload block, leaving other config keys intact. */
+export declare function writeOffloadConfig(offload: OffloadConfig | null): void;
+/** Merge the persisted config with `CODEGRAPH_OFFLOAD_*` env overrides (env wins). */
+export declare function resolveOffload(env?: NodeJS.ProcessEnv): ResolvedOffload;
+//# sourceMappingURL=config.d.ts.map

package/dist/reasoning/credentials.d.ts

@@ -0,0 +1,5 @@
+/** The stored managed-offload org token, if the machine is logged in. */
+export declare function readOffloadToken(): string | undefined;
+/** Persist (or, with `null`, clear) the managed-offload org token at `0600`. */
+export declare function writeOffloadToken(token: string | null): void;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/reasoning/login.d.ts

@@ -0,0 +1,21 @@
+/** Dashboard base for the device-login endpoints; override for testing via CODEGRAPH_LOGIN_URL. */
+export declare function loginBaseUrl(): string;
+/** The dashboard's response to a device-authorization start request. */
+export interface DeviceStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    /** Same URL with the code prefilled, for one-click open. */
+    verification_uri_complete?: string;
+    /** Seconds the CLI should wait between polls. */
+    interval?: number;
+    /** Seconds until the request expires. */
+    expires_in?: number;
+}
+/** Begin a device-authorization request. */
+export declare function startDeviceLogin(): Promise<DeviceStart>;
+/** Poll until the user approves in the browser; resolves with the org token. */
+export declare function pollForToken(deviceCode: string, intervalSec: number, expiresInSec: number): Promise<string>;
+/** Best-effort: open a URL in the default browser. Never throws — the URL is also printed. */
+export declare function openBrowser(url: string): Promise<void>;
+//# sourceMappingURL=login.d.ts.map

package/dist/reasoning/reasoner.d.ts

@@ -0,0 +1,43 @@
+interface SynthArgs {
+    query: string;
+    context: string;
+}
+/** True when a reasoning offload endpoint is configured (env or `~/.codegraph/config.json`). */
+export declare function isOffloadEnabled(): boolean;
+export interface OffloadUsage {
+    plan?: string;
+    allowance?: number;
+    used?: number;
+    overage?: number;
+    remaining?: number;
+    periodEnd?: number;
+    unlimited?: boolean;
+    banned?: boolean;
+    tokensLast30?: number;
+    callsLast30?: number;
+    creditsLast30?: number;
+    models?: string[];
+}
+/**
+ * GET `/v1/usage` from the configured (managed) endpoint → the org's credit
+ * balance/usage, or null on any failure. Drives `codegraph offload status`.
+ */
+export declare function fetchUsage(): Promise<OffloadUsage | null>;
+/**
+ * Strip sections of the explore output addressed to the AGENT (not useful to a
+ * reasoning model): the "Not shown above" pointer list, the completeness signal,
+ * the explore-budget note, the trimmed/truncation notices, and the redundant
+ * "## Exploration:/Found N symbols" header (the query is sent separately). Left
+ * in, some models regurgitate them ("We have 2 explore calls. Let's explore…")
+ * and they add noise. Source code, blast radius, relationships, and flow stay.
+ * Opt-in (`CODEGRAPH_OFFLOAD_STRIP=1`) — default off (it also removes the "Not
+ * shown above" pointers, which can be useful navigation).
+ */
+export declare function stripAgentDirectives(context: string): string;
+/**
+ * Offload reasoning over the retrieved `context` to the configured model and
+ * return its synthesized answer, or null to signal "fall back to local source".
+ */
+export declare function synthesizeOffload({ query, context }: SynthArgs): Promise<string | null>;
+export {};
+//# sourceMappingURL=reasoner.d.ts.map

package/dist/resolution/c-fnptr-synthesizer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * C/C++ function-pointer dispatch synthesis (#932).
+ *
+ * C/C++ polymorphism is the function pointer: a struct carries a fn-pointer
+ * field (`int (*fn)(int)`, or a fn-pointer-typedef field `hook_func func`),
+ * concrete functions are *registered* into it through a table
+ * (`static struct cmd cmds[] = {{"add", cmd_add}, …}`, a designated
+ * `.fn = cmd_add`, or `x->fn = cmd_add`), and the dispatcher calls through it
+ * indirectly (`p->fn(argv)`). Static extraction captures neither the
+ * registration→field binding nor the indirect call, so the dispatcher→handler
+ * edge is missing and `git`'s `run_builtin` looks like it calls nothing, the
+ * hooks in `hook_demo.c` are unreachable, etc.
+ *
+ * This bridges it, keyed by **(struct type, fn-pointer field)**:
+ *   • registrations — a function bound to `S.field` via a positional
+ *     initializer (matched by field index), a designated `.field = fn`, or a
+ *     direct `x.field = fn` / `x->field = fn` assignment;
+ *   • dispatch — `recv->field(…)` / `recv.field(…)` where `recv` resolves to a
+ *     value of struct type `S` (from the enclosing function's params / locals),
+ *     falling back to the field name when it is unique to one struct;
+ *   • field←field propagation — `a->f = b->g` merges `B.g`'s handlers into
+ *     `A.f`, so a generic single-slot hook that is reassigned from a registry
+ *     (the `hook_demo.c` shape: `h->func = found->fn`) still resolves.
+ *
+ * Whole-graph pass after base resolution; all edges are `provenance:'heuristic'`
+ * (`synthesizedBy:'fn-pointer-dispatch'`). High precision via the (type, field)
+ * key + a real-function gate; a project with no fn-pointer dispatch is a no-op.
+ */
+import type { Edge } from '../types';
+import type { QueryBuilder } from '../db/queries';
+import type { ResolutionContext } from './types';
+export declare function cFnPointerDispatchEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[];
+//# sourceMappingURL=c-fnptr-synthesizer.d.ts.map

package/dist/resolution/callback-synthesizer.d.ts

@@ -3,7 +3,12 @@ import type { ResolutionContext } from './types';
 /**
  * Synthesize dispatcher→callback edges (field observers + EventEmitters +
  * React re-render + JSX children + Vue templates + SvelteKit load + RN event
- * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain).
+ * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain +
+ * Redux-thunk dispatch chain + object-literal registry dispatch + RTK Query
+ * generated-hook → endpoint + Pinia useStore().action() + Vuex string dispatch +
+ * Celery task .delay()/.apply_async() → task body + Spring publishEvent → @EventListener +
+ * MediatR Send/Publish → IRequestHandler/INotificationHandler +
+ * Sidekiq Worker.perform_async → #perform + Laravel event(new X) → listener handle).
  * Returns the count added. Never throws into indexing — callers wrap in try/catch.
  */
 export declare function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): number;

package/dist/resolution/frameworks/goframe.d.ts

@@ -0,0 +1,41 @@
+/**
+ * GoFrame Framework Resolver (route metadata) — issue #747.
+ *
+ * GoFrame's "standard router" binds routes reflectively, so there is no literal
+ * path string at a `.GET("/x", handler)` call site and no static edge from a
+ * route to the controller method that serves it. The structural facts live in
+ * two places, joined only at runtime by GoFrame:
+ *
+ *   // api/user/v1/user_sign_in.go — the route lives in a struct tag on the request type
+ *   type SignInReq struct {
+ *       g.Meta `path:"/user/sign-in" method:"post" tags:"UserService" summary:"…"`
+ *       …
+ *   }
+ *   // internal/controller/user/user_v1_sign_in.go — the handler takes *that* request type
+ *   func (c *ControllerV1) SignIn(ctx context.Context, req *v1.SignInReq) (res *v1.SignInRes, err error)
+ *   // internal/cmd/cmd.go — reflective binding (no path, no handler name)
+ *   group.Bind(user.NewV1())
+ *
+ * This resolver handles the FIRST half: it reads the `g.Meta` struct tag on a
+ * request type into a `route` node (`POST /user/sign-in`). The route → handler
+ * EDGE is the genuinely reflective part — the method name is NOT derivable from
+ * the request type (`DeptSearchReq` is served by `List`, `DeptAddReq` by `Add`),
+ * so the only reliable join is the request type appearing in the method's
+ * parameter signature. That whole-graph join is done by the companion
+ * `goframeRouteEdges` synthesizer, which reads the request type back out of the
+ * route node's qualifiedName.
+ *
+ * Honesty note: the route node carries the `g.Meta` path verbatim. The group
+ * prefix from `s.Group("/api", …)` / nested `group.Group("/v1", …)` is applied
+ * by reflective `Bind` at runtime and is deliberately NOT reconstructed here —
+ * the discriminating, structural part is the per-route path + method.
+ */
+import { FrameworkResolver } from '../types';
+/** Marker embedded in a route node's qualifiedName so the synthesizer can read
+ *  back the request type to join on. The value after it is the package-qualified
+ *  request type (`cash.ListReq`) — the package disambiguates the many identical
+ *  bare names (`ListReq`, `GetReq`) a large app defines, one per module. Falls
+ *  back to the bare type when no `package` declaration is found. */
+export declare const GOFRAME_ROUTE_MARKER = "::goframe-route:";
+export declare const goframeResolver: FrameworkResolver;
+//# sourceMappingURL=goframe.d.ts.map

package/dist/resolution/frameworks/index.d.ts

@@ -39,6 +39,7 @@ export { railsResolver } from './ruby';
 export { springResolver } from './java';
 export { playResolver } from './play';
 export { goResolver } from './go';
+export { goframeResolver } from './goframe';
 export { rustResolver } from './rust';
 export { aspnetResolver } from './csharp';
 export { swiftUIResolver, uikitResolver, vaporResolver } from './swift';

package/dist/resolution/goframe-synthesizer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GoFrame route → controller-method dispatch synthesis (#747).
+ *
+ * GoFrame binds routes reflectively (`group.Bind(user.NewV1())`), so the route
+ * declared in a request type's `g.Meta` tag has no static edge to the method
+ * that serves it. The `goframeResolver` extract pass turns each `g.Meta` into a
+ * `route` node carrying its request type in the qualifiedName; this whole-graph
+ * pass closes the loop by joining each route to its handler.
+ *
+ * The join key is the REQUEST TYPE, not the method name — GoFrame method names
+ * are free (`DeptSearchReq` is served by `List`, `DeptAddReq` by `Add`), so the
+ * only reliable link is the request type appearing in the handler's parameter
+ * signature:
+ *
+ *   func (c *sysDeptController) Add(ctx context.Context, req *system.DeptAddReq) (…)
+ *                                                              ^^^^^^^^^^^^^^^^  the join
+ *
+ * Go method nodes already carry that signature, so no source re-read is needed.
+ * Each synthesized edge is `kind:'calls'`, `provenance:'heuristic'`,
+ * `metadata.synthesizedBy:'goframe-route'` — a reflective-dispatch bridge, so
+ * `codegraph_explore` surfaces it as a dynamic hop rather than a literal call,
+ * and the handler's callers list the route that reaches it. A project with no
+ * GoFrame routes is a no-op.
+ */
+import type { Edge } from '../types';
+import type { ResolutionContext } from './types';
+export declare function goframeRouteEdges(ctx: ResolutionContext): Edge[];
+//# sourceMappingURL=goframe-synthesizer.d.ts.map

package/dist/resolution/strip-comments.d.ts

@@ -22,6 +22,6 @@
  * `path(...)`, `Route::get(...)`, `app.get(...)` style patterns that
  * framework extractors scan for.
  */
-export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust';
+export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust' | 'c' | 'cpp';
 export declare function stripCommentsForRegex(content: string, lang: CommentLang): string;
 //# sourceMappingURL=strip-comments.d.ts.map