@colbymchenry/codegraph 1.0.0 → 1.1.0

package/dist/extraction/tree-sitter.d.ts

@@ -16,12 +16,19 @@ export declare class TreeSitterExtractor {
     private nodes;
     private edges;
     private unresolvedReferences;
+    private static readonly VALUE_REF_LANGS;
+    private static readonly MAX_VALUE_REF_NODES;
+    private readonly valueRefsEnabled;
+    private fileScopeValues;
+    private fileScopeValueCounts;
+    private valueRefScopes;
     private errors;
     private extractor;
     private nodeStack;
     private methodIndex;
     private fnRefSpec;
     private fnRefCandidates;
+    private vueStoreFile;
     constructor(filePath: string, source: string, language?: Language);
     /**
      * Parse and extract from the source code
@@ -59,6 +66,21 @@ export declare class TreeSitterExtractor {
      * callback + same-file ops struct) — is.
      */
     private flushFnRefCandidates;
+    /**
+     * Record value-reference bookkeeping as nodes are created: file-scope const/var symbols with
+     * distinctive names become reference targets; function/method/const/var symbols become reader
+     * scopes whose bodies flushValueRefs scans.
+     */
+    private captureValueRefScope;
+    /**
+     * Emit same-file `references` edges from a symbol to the file-scope const/var it reads (TS/JS).
+     * The engine doesn't edge const→consumer, so impact analysis misses "change this table, affect
+     * its readers" (the ReScript-PR false positive). Same-file only (resolution is unambiguous),
+     * distinctive target names only (dodges the local-shadowing precision trap documented on
+     * function_ref), deduped per (reader, target). Default on (CODEGRAPH_VALUE_REFS=0 disables) +
+     * additive. Shadowed targets are pruned — see below.
+     */
+    private flushValueRefs;
     /**
      * Visit a node and extract information
      */
@@ -92,10 +114,41 @@ export declare class TreeSitterExtractor {
      * (class, struct, interface, trait). File nodes do not count as class-like.
      */
     private isInsideClassLikeNode;
+    /**
+     * Ruby `CONST = …` assignment whose LHS is a `constant` node — a class/module
+     * (or top-level) constant worth extracting as a symbol even inside a class.
+     * Other languages don't give an assignment a `constant`-typed LHS, so this
+     * gate is effectively Ruby-only.
+     */
+    private isClassScopeConstantAssignment;
     /**
      * Extract a function
      */
     private extractFunction;
+    /**
+     * Detect a React component declared via an HOC wrapper whose result is itself a
+     * component: `forwardRef(...)`, `memo(...)`, `React.forwardRef/memo(...)`, and
+     * styled-components / emotion `styled.tag\`…\`` / `styled(Base)\`…\``. These
+     * initializers are a call / tagged-template (not a bare arrow), so the const is
+     * otherwise classified `constant` — and a constant is skipped by both the
+     * JSX-render edge synthesizer and component resolution, so `<Button/>` usages
+     * get no edge and callers/impact silently return empty (#841).
+     *
+     * Returns `{ inner }` — the inline render function to extract as the component
+     * body, or `null` when the wrapper has no inline function (`memo(Imported)`,
+     * `styled.button\`…\``) and only a bodyless component node is minted — or
+     * `undefined` when this initializer is not a recognized component wrapper.
+     */
+    private reactComponentHoc;
+    /**
+     * Emit a `component` node for an HOC-wrapped React component declaration (see
+     * reactComponentHoc). Named by the declarator (`Button`) and located at it so
+     * the node range spans the body. When the wrapper has an inline render
+     * function, its body is walked so the component's callees (hooks, helpers) are
+     * captured under the component node — matching how a plain
+     * `const Foo = () => …` arrow component already behaves.
+     */
+    private extractReactComponentNode;
     /**
      * Extract a class
      */
@@ -157,6 +210,72 @@ export declare class TreeSitterExtractor {
      * `=> { return {...} }` block. Returns null for any other body shape.
      */
     private functionReturnedObject;
+    /**
+     * RTK Query: from a `createApi({ ..., endpoints: build => ({...}) })` or a
+     * `baseApi.injectEndpoints({ endpoints: build => ({...}) })` call initializer,
+     * return the object literal of endpoint definitions (the object the `endpoints`
+     * arrow returns). Returns null for any other call — the common case — so this
+     * stays cheap and silent. Keyed on the RTK entry-point names (`createApi` /
+     * `injectEndpoints`) like the framework extractors key on their library APIs.
+     */
+    private findRtkEndpointsObject;
+    /**
+     * Extract each RTK Query endpoint (`getX: build.query({...})` / `build.mutation`)
+     * as a function node named by the endpoint key, spanning its primary handler
+     * (the `queryFn`/`query` arrow) so the fetch logic's calls attribute to the
+     * endpoint. Without this an endpoint exists only as an object-literal property —
+     * never a node — so the generated `useXQuery` hook can't be bridged to it.
+     */
+    private extractRtkEndpoints;
+    /**
+     * The primary handler arrow of a `build.query({ queryFn|query: (…) => … })`
+     * endpoint — prefers `queryFn`, then `query`, else the first function-valued
+     * property. Returns null when the endpoint is config-only (no handler arrow).
+     */
+    private rtkEndpointHandler;
+    /**
+     * RTK Query generated-hook bindings. `export const { useGetXQuery,
+     * useUpdateYMutation } = someApi` destructures the hooks RTK generates per
+     * endpoint off a createApi result. They are real exported symbols that
+     * components import, but destructured bindings aren't otherwise extracted —
+     * mint a function node per binding matching the RTK hook convention so the hook
+     * resolves and the synthesizer can bridge it to its endpoint. Gated tight by the
+     * caller (object-pattern off a bare identifier) + the name convention here, so
+     * ordinary destructures stay unextracted.
+     */
+    private extractRtkHookBindings;
+    /** Cheap per-file heuristic: the file carries ≥2 distinct Vue-store signals
+     *  (defineStore/createStore/Vuex, or the actions/mutations/getters/namespaced
+     *  vocabulary). Gates the non-exported `const actions = {…}` Vuex-module form so
+     *  a stray `const actions` in unrelated code is never mistaken for a store. */
+    private looksLikeVueStoreFile;
+    /** True if an object literal has ≥1 inline function member (`key: () => …` /
+     *  `method(){}`) — distinguishes an inline action map (zustand/SvelteKit form
+     *  actions) from a Pinia SETUP store's all-shorthand `return { foo, bar }`
+     *  (whose functions are body-local consts, walked normally instead). */
+    private objectHasInlineFunctions;
+    /** Vue store action/mutation/getter collections defined INLINE in a store call:
+     *  `defineStore({ actions: {…}, getters: {…} })` (Pinia options form),
+     *  `defineStore('id', { actions: {…} })`, `createStore({ mutations: {…} })`,
+     *  `new Vuex.Store({ actions: {…} })`. Returns the object literals under those
+     *  keys so their methods become nodes. Gated on the store-factory callee. */
+    private findVueStoreCollectionObjects;
+    /** Extract the methods of a store-config object's `actions`/`mutations`/`getters`
+     *  properties. Used for the canonical Vuex MODULE shape `export default {
+     *  namespaced, actions: {…}, mutations: {…} }` — object-literal methods aren't
+     *  otherwise extracted, so the actions/mutations would never be nodes. */
+    private extractStoreCollectionMethods;
+    /** The SETUP function of a Pinia setup store (`defineStore('id', () => {…})`)
+     *  — an arrow/function arg with a block body. Returns null for the options form
+     *  (`defineStore({…})`) and for any non-defineStore call. The setup body's local
+     *  function consts are the store's actions; the generic body walk doesn't reach
+     *  them (nested functions are separate scopes), so they're extracted explicitly. */
+    private findPiniaSetupFn;
+    /** Extract a Pinia setup store's actions: the body-local `const foo = () => …`
+     *  / `function foo(){}` declarations, named by the binding. (State refs and other
+     *  consts are left to the normal value-extraction; only the functions matter as
+     *  the store's callable surface.) */
+    private extractPiniaSetupBody;
     /**
      * Extract a variable declaration (const, let, var, etc.)
      *

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/daemon-manager.d.ts

@@ -0,0 +1,42 @@
+import type { DaemonRecord, StopResult } from './daemon-registry';
+/** Sentinel option values (not real roots, so they can't collide with a project path). */
+export declare const STOP_ALL = "__stop_all__";
+export declare const CANCEL = "__cancel__";
+export interface PickItem {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/** Compact uptime: `45s`, `12m`, `3h 5m`. */
+export declare function formatUptime(ms: number): string;
+/**
+ * Build the ordered, UI-ready option list: the current project's daemon first
+ * (so it's the auto-selected default), the rest newest-first, then "Stop all"
+ * (only when there's more than one) and "Cancel".
+ */
+export declare function buildPickItems(daemons: DaemonRecord[], cwdRoot: string | null, now: number): PickItem[];
+export interface PickerDeps {
+    list: () => DaemonRecord[];
+    stop: (root: string) => Promise<StopResult>;
+    stopAll: () => Promise<StopResult[]>;
+    /** Realpath'd root of the current project's daemon, or null. */
+    cwdRoot: string | null;
+    now: () => number;
+    /** Render the picker; returns the chosen value or a cancel sentinel. */
+    select: (opts: {
+        message: string;
+        options: PickItem[];
+        initialValue: string;
+    }) => Promise<unknown>;
+    isCancel: (v: unknown) => boolean;
+    /** Per-action note (e.g. "Stopped daemon …"). */
+    note: (msg: string) => void;
+    /** Final line + teardown (clack outro). */
+    done: (msg: string) => void;
+}
+/**
+ * Pick a daemon → stop it → re-prompt with what's left, until the user cancels
+ * (Esc / Ctrl-C / "Cancel"), picks "Stop all", or nothing remains.
+ */
+export declare function runDaemonPicker(deps: PickerDeps): Promise<void>;
+//# sourceMappingURL=daemon-manager.d.ts.map

package/dist/mcp/daemon-registry.d.ts

@@ -0,0 +1,47 @@
+export interface DaemonRecord {
+    /** Realpath'd project root the daemon serves. */
+    root: string;
+    pid: number;
+    version: string;
+    socketPath: string;
+    /** Epoch ms when the daemon bound its socket. */
+    startedAt: number;
+}
+/**
+ * `~/.codegraph/daemons` — GLOBAL, keyed off the home install dir. (The
+ * `CODEGRAPH_DIR` env var only renames the per-project index dir, not this.)
+ */
+export declare function getRegistryDir(): string;
+/**
+ * Is `pid` a live process? `kill(pid, 0)` sends no signal — it just probes:
+ * ESRCH ⇒ dead, EPERM ⇒ alive but not ours (still alive). Same liveness check
+ * the PPID watchdog (#277) and daemon lock arbitration use.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/** Best-effort: record this daemon so `list`/`stop --all` can find it. */
+export declare function registerDaemon(rec: DaemonRecord): void;
+/** Best-effort: drop this daemon's record on graceful shutdown. */
+export declare function deregisterDaemon(root: string): void;
+/**
+ * All registered daemons whose process is still alive, newest first. Dead/garbage
+ * records are deleted as a side effect (self-healing) unless `prune` is false.
+ */
+export declare function listDaemons(opts?: {
+    prune?: boolean;
+}): DaemonRecord[];
+export interface StopResult {
+    root: string;
+    pid: number | null;
+    /** 'term' graceful, 'kill' force, 'not-running' stale lock, 'no-daemon' none found. */
+    outcome: 'term' | 'kill' | 'not-running' | 'no-daemon';
+}
+/**
+ * Stop the daemon serving `root`: SIGTERM, wait, then SIGKILL if it won't go,
+ * then sweep its artifacts. `root` must be realpath'd (match how the daemon
+ * keys its socket/lockfile). Resolves the pid from the authoritative lockfile,
+ * falling back to the registry.
+ */
+export declare function stopDaemonAt(root: string): Promise<StopResult>;
+/** Stop every registered, live daemon. */
+export declare function stopAllDaemons(): Promise<StopResult[]>;
+//# sourceMappingURL=daemon-registry.d.ts.map

package/dist/mcp/index.d.ts

@@ -50,6 +50,7 @@ export declare class MCPServer {
     private engine;
     private daemon;
     private ppidWatchdog;
+    private livenessWatchdog;
     private originalPpid;
     private hostPpid;
     private stopped;

package/dist/mcp/liveness-watchdog.d.ts

@@ -0,0 +1,18 @@
+/** Default: 60s — ~300× shorter than the 5h #850 wedge, far longer than any real main-thread block. */
+export declare const DEFAULT_WATCHDOG_TIMEOUT_MS = 60000;
+/** Parse the timeout env, falling back to the default for missing/invalid values. */
+export declare function parseWatchdogTimeoutMs(raw: string | undefined, fallback?: number): number;
+/** Derive a heartbeat cadence that emits several beats inside the timeout window. */
+export declare function deriveCheckIntervalMs(timeoutMs: number): number;
+export interface WatchdogHandle {
+    /** Stop heartbeating and shut the watchdog child down. Idempotent. */
+    stop(): void;
+}
+/**
+ * Install the main-thread liveness watchdog for a long-lived process. Returns a
+ * handle to stop it, or `null` when disabled or when the child can't be spawned
+ * (degraded, never throws — a missing watchdog must never keep a process from
+ * starting).
+ */
+export declare function installMainThreadWatchdog(): WatchdogHandle | null;
+//# sourceMappingURL=liveness-watchdog.d.ts.map

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,19 @@
+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>;
+}
+/**
+ * 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>;
+/** 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