@colbymchenry/codegraph 0.9.9 → 1.0.1

package/dist/extraction/vue-extractor.d.ts

@@ -32,5 +32,20 @@ export declare class VueExtractor {
      * Process a script block by delegating to TreeSitterExtractor
      */
     private processScriptBlock;
+    /**
+     * Extract component usages from the Vue `<template>`.
+     *
+     * PascalCase tags (`<Modal>`, `<Button />`) and kebab-case tags
+     * (`<my-button>`) both represent component instantiations — analogous to
+     * function calls in imperative code. Capturing them creates parent→child
+     * component edges and lets `callers` / `impact` see a component that is
+     * only ever used in markup. Vue's extractor previously parsed only the
+     * `<script>` block, so these usages produced no edge at all (#629).
+     *
+     * HTML elements (lowercase, no hyphen) and Vue built-ins are skipped.
+     * Unmatched names create no edge during resolution, so converting
+     * kebab-case is safe even for native custom elements.
+     */
+    private extractTemplateComponents;
 }
 //# sourceMappingURL=vue-extractor.d.ts.map

package/dist/index.d.ts

@@ -158,8 +158,8 @@ export declare class CodeGraph {
      */
     getPendingFiles(): PendingFile[];
     /**
-     * Resolves once the file watcher has finished its initial chokidar scan.
-     * Useful for tests that need a deterministic boundary before asserting on
+     * Resolves once the file watcher has installed its watch set. Useful for
+     * tests that need a deterministic boundary before asserting on
      * `getPendingFiles()`. Resolves immediately when no watcher is active.
      */
     waitUntilWatcherReady(timeoutMs?: number): Promise<void>;
@@ -171,6 +171,30 @@ export declare class CodeGraph {
         modified: string[];
         removed: string[];
     };
+    /**
+     * Most recent index timestamp (ms since epoch) across all tracked files, or
+     * null when nothing is indexed yet. Lets library consumers check index
+     * freshness without shelling out to `codegraph status --json`. (#329)
+     */
+    getLastIndexedAt(): number | null;
+    /**
+     * Which engine built the current index: the package version + extraction
+     * version stamped at the last full `indexAll`. Either field is null for an
+     * index built before stamping existed (treated as stale). See
+     * `extraction-version.ts` and `isIndexStale()`.
+     */
+    getIndexBuildInfo(): {
+        version: string | null;
+        extractionVersion: number | null;
+    };
+    /**
+     * True when the on-disk index was built by an engine whose extraction is
+     * older than the one now running — i.e. a re-index would add data a migration
+     * can't backfill. False when there's no index yet (nothing to refresh) or the
+     * stamp is current. This is the signal behind `codegraph status`'s re-index
+     * hint and `codegraph upgrade`'s reminder.
+     */
+    isIndexStale(): boolean;
     /**
      * Extract nodes and edges from source code (without storing)
      */
@@ -237,6 +261,14 @@ export declare class CodeGraph {
      * Search nodes by text
      */
     searchNodes(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Normalized project-name tokens (go.mod / package.json / repo dir) used to
+     * down-weight the non-discriminative project name in search ranking (#720).
+     * Exposed so explore can exclude it from the PascalCase type-disambiguation
+     * bias, which would otherwise pull overloaded tokens toward whichever stack
+     * embeds the project name.
+     */
+    getProjectNameTokens(): Set<string>;
     /**
      * Find the project's "primary route file" — the file with the densest
      * concentration of framework-emitted `route` nodes (≥3 routes, ≥30%

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

@@ -1,18 +1,41 @@
 /**
- * Marker constants for the legacy agent-instructions block.
+ * The marker-fenced agent-instructions block the installer writes into each
+ * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md).
  *
- * Codegraph used to write a `## CodeGraph` usage guide into each
- * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md /
- * codegraph.mdc / Kiro steering doc). That duplicated the guidance the
- * MCP server already emits in its `initialize` response — every agent
- * read the same playbook twice each turn (issue #529). The installer no
- * longer writes an instructions file; the MCP server instructions in
- * `mcp/server-instructions.ts` are the single source of truth.
+ * History: pre-#529 the installer wrote a full usage playbook here, which
+ * duplicated the MCP `initialize` instructions for the main agent — so it
+ * was removed and `mcp/server-instructions.ts` became the single source of
+ * truth. A much smaller block returned for #704, because the MCP
+ * instructions cannot reach two audiences that the instructions FILE does
+ * reach:
  *
- * These markers are retained so install (self-heal on upgrade) and
- * uninstall can find and strip the block a previous install wrote.
+ *  - **Task-tool subagents** — they receive the project instructions file
+ *    in their context but NOT the MCP initialize instructions. They hold
+ *    the codegraph MCP tools only as deferred names and rarely think to
+ *    load them: measured on a forced-delegation flow question (excalidraw,
+ *    sonnet, high effort), subagents loaded + used codegraph in ~1 of 9
+ *    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.
+ *
+ * Keep this block SHORT. The main agent reads it every turn on top of the
+ * server instructions — the #529 duplication-cost argument still bounds
+ * its size. Command names and the two surfaces, nothing more.
  */
-/** Markers used by the marker-based section removal. */
+/** Markers used by the marker-based section write/removal. */
 export declare const CODEGRAPH_SECTION_START = "<!-- CODEGRAPH_START -->";
 export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
+/**
+ * The full block, markers included, exactly as written to disk.
+ *
+ * The wording is deliberately CONDITIONAL ("in repositories indexed by…"):
+ * a global install writes this into a user-scope file (~/.claude/CLAUDE.md,
+ * ~/.codex/AGENTS.md) that applies to every project the user opens —
+ * including unindexed ones, where an unconditional "this repository is
+ * 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 -->";
 //# sourceMappingURL=instructions-template.d.ts.map

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

@@ -2,10 +2,18 @@
  * opencode target.
  *
  *   - MCP server entry to `~/.config/opencode/opencode.jsonc` (global,
- *     XDG-style; `%APPDATA%/opencode/opencode.jsonc` on Windows) or
+ *     XDG-style on EVERY platform, Windows included — see below) or
  *     `./opencode.jsonc` (local). Falls back to `opencode.json` when a
  *     `.json` file already exists; defaults new installs to `.jsonc`
  *     because that's what opencode itself creates on first run.
+ *
+ *     opencode resolves its config dir with the `xdg-basedir` package
+ *     (sst/opencode `packages/core/src/global.ts`): `XDG_CONFIG_HOME`
+ *     if set, else `~/.config` — unconditionally, on all platforms. It
+ *     never reads `%APPDATA%`; that layout belonged to the discontinued
+ *     Go fork. We previously wrote there on Windows, so opencode never
+ *     saw the entry (#535) — install/uninstall now also sweep a stale
+ *     codegraph entry out of the legacy `%APPDATA%/opencode` location.
  *   - Instructions to `~/.config/opencode/AGENTS.md` (global) or
  *     `./AGENTS.md` (local). opencode reads AGENTS.md for agent
  *     instructions — same convention Codex CLI uses.

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

@@ -64,6 +64,20 @@ export declare function jsonDeepEqual(a: unknown, b: unknown): boolean;
  * existing block already matches `body`.
  */
 export declare function replaceOrAppendMarkedSection(filePath: string, body: string, startMarker: string, endMarker: string): 'created' | 'updated' | 'appended' | 'unchanged';
+/**
+ * Upsert the CodeGraph instructions block into an agent instructions
+ * file (CLAUDE.md / AGENTS.md / GEMINI.md). The one write shared by
+ * every target: self-heals a stale pre-#529 long block (markers match →
+ * replaced by the current short one), appends after existing user
+ * content otherwise, and reports `unchanged` on byte-equal re-runs so
+ * install stays idempotent. See `instructions-template.ts` for why this
+ * block exists (#704: subagents + non-MCP harnesses never see the MCP
+ * initialize instructions).
+ */
+export declare function upsertInstructionsEntry(file: string): {
+    path: string;
+    action: 'created' | 'updated' | 'unchanged';
+};
 /**
  * Inverse of `replaceOrAppendMarkedSection`. Strips the marker
  * block from `filePath` if present. If the file becomes empty after

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

@@ -54,6 +54,20 @@ export interface DaemonHello {
     socketPath: string;
     protocol: 1;
 }
+/**
+ * Optional reverse-handshake line a proxy sends right after it verifies the
+ * daemon hello, carrying its own pids so the daemon can reap the client if its
+ * process dies WITHOUT the socket ever signalling close (the Windows named-pipe
+ * hazard behind #692). Entirely optional and fail-safe: a connection that never
+ * sends it (a legacy/direct client) just falls back to the socket-close
+ * lifecycle. The `codegraph_client` marker is what tells it apart from the
+ * client's first JSON-RPC message.
+ */
+export interface DaemonClientHello {
+    codegraph_client: 1;
+    pid: number;
+    hostPid: number | null;
+}
 export interface DaemonStartResult {
     /** Always-non-null for a successfully-started daemon. */
     socketPath: string;
@@ -75,14 +89,21 @@ export declare class Daemon {
     private projectRoot;
     private server;
     private clients;
+    /** Per-client peer pids from the optional client-hello, for the liveness sweep. */
+    private clientPeers;
     private idleTimer;
     private idleTimeoutMs;
+    private maxIdleMs;
+    private lastActivityAt;
+    private maxIdleTimer;
+    private clientSweepTimer;
     private engine;
     private stopping;
     private socketPath;
     private pidPath;
     constructor(projectRoot: string, opts?: {
         idleTimeoutMs?: number;
+        maxIdleMs?: number;
     });
     /**
      * Bind the socket, kick off engine init, and register signal handlers. The
@@ -101,6 +122,26 @@ export declare class Daemon {
     private dropClient;
     private armIdleTimer;
     private disarmIdleTimer;
+    /**
+     * Defense-in-depth against a daemon that outlives its clients (#692), for the
+     * cases the refcount + idle timer miss because a socket close never arrives:
+     *   - **Inactivity backstop:** exit if no inbound traffic for `maxIdleMs` while
+     *     clients are still (nominally) connected. A phantom client sends nothing,
+     *     so it can't pin the daemon past this window.
+     *   - **Liveness sweep:** drop any client whose peer process has died (per the
+     *     client-hello pids), which re-arms the idle timer once the last real
+     *     client is gone. Catches a dead peer within one sweep instead of waiting
+     *     out the whole backstop.
+     * Both timers are unref'd — the listening server keeps the loop alive, and
+     * neither should hold it open on its own.
+     */
+    private startLivenessTimers;
+    /**
+     * Drop every connected client whose peer process is gone. Returns the count
+     * reaped. `isAlive` is injected for testing. Clients with unknown pids (no
+     * client-hello) are skipped — they rely on the socket-close path.
+     */
+    reapDeadClients(isAlive: (pid: number) => boolean): number;
     private cleanupLockfile;
 }
 /**
@@ -128,7 +169,7 @@ export type AcquireResult = {
  * the file existed but was empty; under concurrent daemon startup a third
  * candidate could read that empty file, decode it as `null`, and `unlink` the
  * winner's lock → two daemons (two watchers, two writers). The window was
- * normally too small to hit, but the chokidar watcher's extra startup time made
+ * normally too small to hit, but the file watcher's extra startup time made
  * concurrent daemons overlap enough to reproduce it reliably.
  *
  * The fix writes the complete record to a private temp file, then hard-links it
@@ -156,6 +197,24 @@ export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?:
  * mistake a live daemon for a dead one and clear its lock.
  */
 export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Parse one client-hello line. Returns the peer pids if `line` is a well-formed
+ * client-hello (carries the `codegraph_client` marker), or null otherwise — in
+ * which case the caller treats the bytes as ordinary JSON-RPC.
+ */
+export declare function parseClientHelloLine(line: string): {
+    pid: number;
+    hostPid: number | null;
+} | null;
+/**
+ * A client's peer is dead when its proxy process is gone, or when its known
+ * host process is gone. Unknown pid (no client-hello) is never "dead" on this
+ * basis — those clients rely on the socket-close path. Exported for testing.
+ */
+export declare function peerIsDead(peers: {
+    pid: number | null;
+    hostPid: number | null;
+}, isAlive: (pid: number) => boolean): boolean;
 /** Exported for test stubs that need to bound the hello-line read. */
 export { MAX_HELLO_LINE_BYTES };
 //# sourceMappingURL=daemon.d.ts.map

package/dist/mcp/dynamic-boundaries.d.ts

@@ -0,0 +1,41 @@
+export interface BoundaryMatch {
+    /** Stable form id, e.g. 'computed-call' — used for per-form dedupe. */
+    form: string;
+    /** Human label for the dispatch form, e.g. 'computed member call'. */
+    label: string;
+    /** One-line source snippet of the site (from the original, untrimmed text). */
+    snippet: string;
+    /** 1-based line within the scanned body's FILE (absolute, ready to print). */
+    line: number;
+    /**
+     * Statically-visible dispatch key, when one exists: the string literal in
+     * `handlers['save']`, the `:symbol` in ruby `send`, the type name in
+     * `Send(new CreateCmd(...))`. Drives candidate lookup. Undefined when the
+     * key is a runtime value (variable, computed expression).
+     */
+    key?: string;
+    /** For typed-bus matches the key is a TYPE name (candidates ~ `${key}Handler`). */
+    keyIsType?: boolean;
+    /** Additional sites of the same form+key in this body beyond the reported one. */
+    moreSites?: number;
+}
+/**
+ * Blank the CONTENTS of string literals (quotes preserved, offsets preserved)
+ * so dispatch-shaped prose — docs, error messages, template text — can't fire
+ * a matcher. Run AFTER comment stripping (comments are already spaces).
+ * Backslash escapes are honored; `'`/`"` strings end at a newline (treated as
+ * unterminated, matching the comment stripper); backticks span lines, and
+ * `${...}` interpolations inside them are blanked too — missing a dispatch
+ * inside a template literal is acceptable, false-firing on prose is not.
+ */
+export declare function blankStringContents(text: string): string;
+/**
+ * Scan one symbol's body for dynamic-dispatch sites.
+ *
+ * @param body       the symbol's source text (sliced from the file)
+ * @param language   Node.language of the symbol
+ * @param fileStartLine 1-based line where `body` starts in its file — returned
+ *                      line numbers are absolute file lines.
+ */
+export declare function scanDynamicDispatch(body: string, language: string, fileStartLine: number): BoundaryMatch[];
+//# sourceMappingURL=dynamic-boundaries.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/ppid-watchdog.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared decision logic for the PPID watchdog (#277, #692).
+ *
+ * The watchdog's job: notice that the process we depend on — our parent, or the
+ * MCP host reached past an intermediate launcher — has died, so an orphaned
+ * proxy / direct server shuts itself down instead of leaking forever.
+ *
+ * Parent death surfaces differently per OS, and getting this wrong is what
+ * caused the unbounded daemon/proxy leak on Windows (#692, #576):
+ *
+ *   - **POSIX** reparents an orphan to init (pid 1), so `process.ppid` *changes*
+ *     the instant the parent dies. That divergence is the classic #277 signal.
+ *   - **Windows** never reparents: `process.ppid` keeps reporting the original
+ *     (now-dead) parent forever, so the change-check can never fire. There we
+ *     must poll the original parent's *liveness* instead.
+ *
+ * The liveness fallback is deliberately gated to Windows. On POSIX a
+ * double-forked grandparent can legitimately outlive the reparent, so a dead
+ * `originalPpid` is not proof of orphaning there — the change-check is the
+ * correct and sufficient POSIX signal, and using liveness too would risk a
+ * false-positive shutdown.
+ */
+export interface SupervisionState {
+    /** `process.ppid` captured at startup. */
+    originalPpid: number;
+    /** `process.ppid` right now. */
+    currentPpid: number;
+    /**
+     * The MCP host pid threaded past an intermediate launcher
+     * (`CODEGRAPH_HOST_PPID`), or null when unknown — e.g. the standalone bundle,
+     * which pre-bakes `--liftoff-only` and so never runs the relaunch that sets it.
+     */
+    hostPpid: number | null;
+    /** Liveness probe — `process.kill(pid, 0)` in production, stubbed in tests. */
+    isAlive: (pid: number) => boolean;
+    /** Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Returns a human-readable reason string when the process has lost its
+ * supervisor and should shut down, or null while it is still supervised.
+ */
+export declare function supervisionLostReason(state: SupervisionState): string | null;
+//# sourceMappingURL=ppid-watchdog.d.ts.map

package/dist/mcp/proxy.d.ts

@@ -18,7 +18,13 @@
  *     the direct-mode server uses; see issue #277.
  */
 import * as net from 'net';
+import { DaemonHello } from './daemon';
 import type { MCPEngine } from './engine';
+/**
+ * Log a successful daemon attach — gated behind {@link LOG_ATTACH_ENV} so it is
+ * silent by default (see #618). Exported for tests.
+ */
+export declare function logAttachedDaemon(socketPath: string, hello: DaemonHello): void;
 export interface ProxyResult {
     /**
      * `proxied` — successfully attached to a same-version daemon and piped

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

@@ -15,5 +15,16 @@
  * burn tokens. Reference only tools that exist on `main`; gate any
  * conditional tools behind feature checks if/when they ship.
  */
-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\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Answer directly \u2014 don't delegate exploration\n\nFor \"how does X work\", architecture, trace, or where-is-X questions,\nanswer 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 does this call?\" / \"What would changing this break?\"** \u2192 `codegraph_callers` / `codegraph_callees` / `codegraph_impact`\n- **One specific symbol's full source (esp. a body `codegraph_explore` trimmed), or an OVERLOADED name** \u2192 `codegraph_node` (with `includeCode`): for an ambiguous name it returns EVERY matching definition's body in one call, so you never Read a file to find the right overload\n- **\"What's in directory X?\"** \u2192 `codegraph_files`\n- **\"Is the index ready / what's its size?\"** \u2192 `codegraph_status`\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_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call 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- **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. `codegraph_status` also lists pending files under \"Pending sync\".\n\n## Limitations\n\n- If a tool reports the project isn't initialized, `.codegraph/` doesn't exist yet \u2014 offer to run `codegraph init -i` to build the index.\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## 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";
+/**
+ * Instructions variant sent when the workspace 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.
+ */
+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";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/session.d.ts

@@ -39,6 +39,8 @@ export declare class MCPSession {
     private transport;
     private engine;
     private clientSupportsRoots;
+    /** From the initialize handshake — attributes usage rollups to the agent host. */
+    private clientInfo;
     private rootsAttempted;
     private resolvePromise;
     private explicitProjectPath;

package/dist/mcp/stdin-teardown.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Treat a stdin failure as a shutdown signal — issue #799.
+ *
+ * An MCP stdio server's lifeline is its stdin: when the host/client goes away,
+ * stdin should end and the server should exit. The server paths listened for
+ * `'end'` and `'close'` — but NOT `'error'`.
+ *
+ * That gap bites with a socket-backed stdin, which is the shape VS Code /
+ * Claude Code use (a socketpair, not a pipe). When the client dies, the socket
+ * can surface as an `'error'` (ECONNRESET / hangup) rather than a clean
+ * `'close'`. With no `'error'` listener, Node escalates it to the process-wide
+ * `uncaughtException` handler, which logs and keeps running — so the server
+ * orphans instead of exiting. Worse, on Linux a `POLLHUP` socket fd left
+ * registered in epoll wakes the event loop continuously, pinning a core at
+ * 100% CPU (the spin reported in #799); once the main thread spins, the
+ * `setInterval` PPID watchdog can't even fire, so the orphan runs forever.
+ *
+ * Fix: listen for `'error'` as well, and DESTROY the stdin stream on any
+ * terminal event so the fd leaves epoll and can't keep churning, then run the
+ * caller's shutdown. Fires `onTerminal` at most once — callers' shutdowns are
+ * already re-entry-guarded, but the single-shot guard also keeps `destroy()`'s
+ * follow-on `'close'` from re-invoking it.
+ *
+ * `stream` is injectable for tests; it defaults to `process.stdin`.
+ */
+export declare function treatStdinFailureAsShutdown(onTerminal: () => void, stream?: NodeJS.ReadableStream): void;
+//# sourceMappingURL=stdin-teardown.d.ts.map