@aroman22/codegraph-vba 1.3.3

package/dist/mcp/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * CodeGraph MCP Server
+ *
+ * Model Context Protocol server that exposes CodeGraph functionality
+ * as tools for AI assistants like Claude.
+ *
+ * @module mcp
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer } from 'codegraph';
+ *
+ * const server = new MCPServer('/path/to/project');
+ * await server.start();
+ * ```
+ *
+ * Runtime modes (decided in {@link MCPServer.start}):
+ *
+ * - **Direct** — one process serves one MCP client over stdio. The pre-#411
+ *   behavior; used when the user opts out (`CODEGRAPH_NO_DAEMON=1`), no
+ *   `.codegraph/` is reachable, or the daemon machinery fails for any reason.
+ * - **Proxy** — what an MCP host actually talks to when sharing is on: a thin
+ *   stdio↔socket pipe to the shared daemon. The proxy carries the #277 PPID
+ *   watchdog, so a SIGKILL'd host reaps its proxy promptly. See {@link ./proxy.ts}.
+ * - **Daemon** — a *detached* background process (its own session/process
+ *   group) that serves N proxies over a Unix-domain socket / named pipe,
+ *   sharing one CodeGraph + watcher + SQLite handle. Spawned on demand; never a
+ *   child of any host, so it survives individual sessions and is reaped by
+ *   client-refcount + idle timeout. See {@link ./daemon.ts} and issue #411.
+ *
+ * The detached-daemon + always-proxy split is the fix for the review finding
+ * that the original in-process daemon (a) was the first host's child, so closing
+ * that terminal severed every other client, and (b) disabled the PPID watchdog,
+ * regressing #277 (orphaned daemons on host SIGKILL).
+ */
+/**
+ * MCP Server for CodeGraph
+ *
+ * Implements the Model Context Protocol to expose CodeGraph
+ * functionality as tools that can be called by AI assistants.
+ *
+ * Backwards-compatible constructor and `start()` signature with the
+ * pre-issue-#411 implementation: callers continue to do
+ * `new MCPServer(path).start()`. Internally we now pick from direct / proxy /
+ * daemon at start time.
+ */
+export declare class MCPServer {
+    private projectPath;
+    private session;
+    private engine;
+    private daemon;
+    private ppidWatchdog;
+    private livenessWatchdog;
+    private originalPpid;
+    private hostPpid;
+    private stopped;
+    private mode;
+    constructor(projectPath?: string);
+    /**
+     * Start the MCP server.
+     *
+     * Decision order:
+     *   1. `CODEGRAPH_NO_DAEMON=1` → direct mode (unchanged pre-#411 behavior).
+     *   2. `CODEGRAPH_DAEMON_INTERNAL=1` → we ARE the detached daemon; listen.
+     *   3. No `.codegraph/` reachable → direct mode (the daemon's lockfile and
+     *      socket both live under `.codegraph/`).
+     *   4. Otherwise connect to (or spawn) the shared daemon and proxy to it.
+     *
+     * On any unexpected failure in step 4 we transparently fall back to direct
+     * mode — a misbehaving daemon must never block a session from starting.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server. In daemon mode this triggers graceful shutdown of every
+     * connected session; in direct mode it mirrors the pre-#411 behavior (close
+     * cg, exit). Proxy mode never routes through here — the proxy exits itself.
+     */
+    stop(): void;
+    /** Single-process stdio MCP session — the pre-issue-#411 code path. */
+    private startDirect;
+    /**
+     * Run as the detached shared daemon (process spawned with
+     * `CODEGRAPH_DAEMON_INTERNAL=1`). Arbitrate the O_EXCL lock, then either
+     * become the daemon (bind the socket, serve forever) or — if a live daemon
+     * already holds the lock — exit so we don't leak a redundant process.
+     *
+     * No PPID watchdog and no stdin handlers: the daemon is detached on purpose
+     * and reaps itself via client-refcount + idle timeout (see {@link Daemon}).
+     */
+    private startDaemonProcess;
+    /**
+     * Proxy mode (the common case). Serve the MCP handshake LOCALLY for instant
+     * tool registration, forwarding tool calls to the shared daemon — which is
+     * connected in the background (probed, then spawned + polled if absent) so the
+     * handshake never waits ~600ms on it. Runs until the host disconnects; the
+     * proxy falls back to an in-process engine if the daemon never binds, so this
+     * never wedges a session.
+     */
+    private runProxyWithLocalHandshake;
+    /** Standard SIGINT/SIGTERM handlers that route to our `stop()` (direct mode). */
+    private installSignalHandlers;
+    /**
+     * PPID watchdog (#277) — direct mode only. Daemon mode is detached on purpose
+     * and reaps via idle timeout; proxy mode installs its own watchdog inside
+     * {@link runProxy}. So this only ever runs for an in-process direct session.
+     */
+    private installPpidWatchdog;
+}
+export { StdioTransport } from './transport';
+export { tools, ToolHandler } from './tools';
+export { Daemon } from './daemon';
+export { CodeGraphPackageVersion } from './version';
+//# sourceMappingURL=index.d.ts.map

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,62 @@
+/**
+ * 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;
+/** Default PPID poll cadence (ms). Shared by the MCP server and CLI commands. */
+export declare const DEFAULT_PPID_POLL_MS = 5000;
+/**
+ * Resolve the PPID watchdog poll interval from an env override
+ * (`CODEGRAPH_PPID_POLL_MS`). A value of `0` disables the watchdog entirely
+ * (escape hatch for embedded scenarios where the parent legitimately re-parents
+ * the process on purpose). Anything non-numeric or negative falls back to the
+ * default.
+ */
+export declare function parsePpidPollMs(raw: string | undefined): number;
+/**
+ * Parse the host PID propagated across the `--liftoff-only` re-exec
+ * (`CODEGRAPH_HOST_PPID`). Returns a positive integer PID, or null when
+ * unset/invalid — the direct-launch path, where the watchdog falls back to
+ * `process.ppid` divergence. PIDs of 0/1 are rejected (0 = unknown, 1 = init,
+ * i.e. already orphaned), so the watchdog doesn't latch onto init.
+ */
+export declare function parseHostPpid(raw: string | undefined): number | null;
+//# sourceMappingURL=ppid-watchdog.d.ts.map

package/dist/mcp/proxy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * MCP proxy mode — issue #411.
+ *
+ * The proxy is a near-transparent stdio↔socket pipe. Once it has verified
+ * the daemon's hello line (same major.minor.patch as ours), it does no
+ * protocol parsing of its own: every byte the MCP host writes to the proxy's
+ * stdin goes straight to the daemon socket, and every byte the daemon emits
+ * goes straight to the host's stdout. Server-initiated JSON-RPC requests
+ * (e.g. `roots/list`) flow through the same pipe transparently.
+ *
+ * Lifecycle expectations:
+ *   - The proxy exits when *either* stream closes (host stdin closed →
+ *     daemon socket end, or daemon-side socket close → host stdout end).
+ *   - Closing the socket on the proxy side is what tells the daemon to
+ *     decrement its connected-clients refcount.
+ *   - On a parent-process death we can't detect via stdin close (e.g. SIGKILL
+ *     of the MCP host), the proxy's PPID watchdog catches it — same logic
+ *     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
+     * stdio. The proxy stays alive until either end closes.
+     * `fallback-needed` — the daemon rejected us (version mismatch / unreachable
+     * socket) and the caller should run the server in direct mode.
+     */
+    outcome: 'proxied' | 'fallback-needed';
+    reason?: string;
+}
+/**
+ * Attempt to connect to the daemon at `socketPath` and pipe stdio through it.
+ *
+ * Returns a promise that resolves when either:
+ *   - the connection succeeded and one of stdin/socket has now closed
+ *     (after which the process should exit), or
+ *   - the connection failed early enough that the caller can still fall
+ *     back to direct mode.
+ *
+ * The `expectedVersion` param defaults to the package's own version — daemon
+ * and proxy MUST match exactly. Mismatch resolves with
+ * `outcome: 'fallback-needed'` so the caller can transparently start its own
+ * server. (We accept the cost of two concurrent servers in this case as the
+ * price of never silently running a stale daemon against newer client code.)
+ */
+export declare function runProxy(socketPath: string, expectedVersion?: string): Promise<ProxyResult>;
+/**
+ * Connect to a daemon at `socketPath` and verify its hello (exact version match).
+ * Returns the live socket (hello already consumed) or null if unreachable / stale
+ * / version-mismatched. Unlike {@link runProxy} it does NOT pipe — the caller
+ * owns the socket. Used by the local-handshake proxy's background connect.
+ */
+export declare function connectWithHello(socketPath: string, expectedVersion?: string): Promise<net.Socket | 'version-mismatch' | null>;
+/** Dependencies the local-handshake proxy needs, injected by MCPServer (which
+ *  owns the daemon-spawn machinery and the engine factory). */
+export interface LocalHandshakeDeps {
+    /** Probe → spawn → retry → hello-verify; resolves a connected daemon socket,
+     *  or null when the daemon path is genuinely unavailable (→ in-process fallback). */
+    getDaemonSocket(): Promise<net.Socket | null>;
+    /** Lazily create an in-process engine — used ONLY if the daemon never comes up,
+     *  preserving the "a broken daemon never wedges a session" guarantee. */
+    makeEngine(): MCPEngine;
+    /** Project root for the fallback engine's lazy init. */
+    root: string;
+}
+/**
+ * Local-handshake proxy (the cold-start fix).
+ *
+ * Answers `initialize` + `tools/list` from STATIC constants the instant the
+ * client asks — tools register in ~process-startup time instead of waiting
+ * ~600ms for the daemon to spawn+bind, which is what produced the "No such tool
+ * available" race that made headless agents flail into grep/Read. Tool CALLS are
+ * forwarded to the shared daemon (connected in the background); the daemon's
+ * response to the forwarded `initialize` is suppressed (the client already got
+ * the local one). If the daemon never comes up (version mismatch / spawn fail),
+ * a lazily-created in-process engine serves the calls — so the handshake speedup
+ * never costs the old fall-back-to-direct robustness.
+ */
+export declare function runLocalHandshakeProxy(deps: LocalHandshakeDeps): Promise<void>;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/mcp/query-pool.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Query pool — runs CPU-heavy read-tool calls on a pool of worker threads so
+ * the shared daemon's main event loop stays free for the MCP transport.
+ *
+ * Why this exists: see {@link ./query-worker}. One daemon, one event loop, one
+ * synchronous SQLite connection serializes every concurrent `codegraph_explore`
+ * AND starves the transport (a 10-way wave delivered 0 transport heartbeats in
+ * 25s — responses can't flush until the whole batch drains, so clients time
+ * out). Spreading the dispatch across worker threads (each its own WAL read
+ * connection) restores true multi-core parallelism and an idle main loop.
+ *
+ * Properties:
+ *   - lazy growth: one warm worker on construct, grows to `size` on demand, so a
+ *     single-agent session pays for one connection and a 10-subagent burst grows
+ *     to the core budget.
+ *   - crash recovery: a dead worker is respawned and its in-flight call retried
+ *     once; a poison call that keeps crashing fails gracefully (never wedges the
+ *     pool). A crash budget trips a circuit breaker (`healthy` → false) so the
+ *     caller falls back to in-process dispatch instead of thrashing respawns.
+ *   - graceful backstop: a call that can't be served within `softTimeoutMs`
+ *     resolves with SUCCESS-shaped "busy, retry" guidance — never `isError`, so
+ *     a momentary overload can't teach the agent to abandon codegraph — instead
+ *     of hanging past the client's hard timeout.
+ */
+import type { ToolResult } from './tools';
+/**
+ * Minimal worker surface the pool drives — satisfied by a real `worker_threads`
+ * Worker. Abstracted so tests can inject a fake worker and exercise the pool's
+ * queue / growth / crash-recovery / backstop logic without spawning threads or
+ * needing a built `dist/`.
+ */
+export interface PoolWorker {
+    postMessage(msg: unknown): void;
+    terminate(): Promise<number> | void;
+    on(event: 'message', cb: (m: unknown) => void): void;
+    on(event: 'error', cb: (e: Error) => void): void;
+    on(event: 'exit', cb: (code: number) => void): void;
+}
+export interface QueryPoolOptions {
+    /** Default project root each worker opens at spawn. */
+    root: string;
+    /** Max worker threads. Defaults to `clamp(cores-1, 1, 16)`. */
+    size?: number;
+    /** Linger before a queued call gets busy-guidance. Default 45s. */
+    softTimeoutMs?: number;
+    /** Retries for an in-flight call whose worker crashed. Default 1. */
+    maxRetries?: number;
+    /** Worker factory (tests inject a fake). Defaults to a real `worker_threads` Worker. */
+    createWorker?: () => PoolWorker;
+}
+/**
+ * Resolve the pool size from the `CODEGRAPH_QUERY_POOL_SIZE` override and the
+ * machine's core count. `0` (or a negative) explicitly disables the pool (the
+ * caller serves in-process — today's behavior). Unset → `clamp(cores-1, 1, 16)`:
+ * leave a core for the main loop + OS, but never zero, since even one worker
+ * frees the transport and lets responses flush incrementally.
+ */
+export declare function resolvePoolSize(envVal: string | undefined, cpuCount: number): number;
+export declare class QueryPool {
+    private idle;
+    private queue;
+    private inflight;
+    private workers;
+    private pendingWorkers;
+    private nextId;
+    private totalCrashes;
+    private destroyed;
+    private readonly root;
+    private readonly maxSize;
+    private readonly softTimeoutMs;
+    private readonly maxRetries;
+    private readonly createWorker;
+    constructor(opts: QueryPoolOptions);
+    /** Pool size cap (for logging/status). */
+    get size(): number;
+    /** Live worker count (for tests/status). */
+    get liveWorkers(): number;
+    /**
+     * False once the crash budget is exhausted (or after destroy). The ToolHandler
+     * checks this and falls back to in-process dispatch — a broken worker platform
+     * degrades to today's behavior instead of failing tool calls.
+     */
+    get healthy(): boolean;
+    private spawnOne;
+    private onMessage;
+    private onWorkerGone;
+    private drain;
+    private settle;
+    /** Run a read tool on the pool. Always resolves (never rejects). */
+    run(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** Terminate all workers and answer any outstanding calls gracefully. */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=query-pool.d.ts.map

package/dist/mcp/query-worker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Query worker thread — issue: concurrent MCP tool calls starve the daemon.
+ *
+ * The shared daemon serves every session on ONE event loop with synchronous
+ * `node:sqlite`. `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
+ * PageRank + impact + output building) stitched together by microtask `await`s,
+ * so N concurrent explores keep the microtask queue continuously full and
+ * starve the macrotask phases — timers AND socket I/O. The transport freezes:
+ * no response flushes, no request is read, until the whole batch drains. With
+ * ~10 subagents that routinely exceeds the MCP client's request timeout.
+ *
+ * This worker moves the heavy read-tool dispatch OFF the daemon's main loop.
+ * Each worker owns its OWN read connection (node:sqlite WAL allows N concurrent
+ * readers across connections — verified: a worker reader sees the main writer's
+ * committed catch-up/watcher writes), so {@link QueryPool} runs N tool calls in
+ * true parallel up to core count while the main loop stays free for the MCP
+ * transport. The worker runs {@link ToolHandler.executeReadTool} — validation +
+ * dispatch + error classification — and returns the raw {@link ToolResult}; the
+ * MAIN thread keeps the catch-up gate, the watcher-state notices (staleness /
+ * worktree), `codegraph_status`, and telemetry, none of which a watcher-less
+ * read connection can answer.
+ */
+export {};
+//# sourceMappingURL=query-worker.d.ts.map

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

@@ -0,0 +1,34 @@
+/**
+ * Server-level instructions emitted in the MCP `initialize` response.
+ *
+ * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
+ * SDK, …) surface this text in the agent's system prompt automatically,
+ * giving the agent a high-level playbook for the codegraph toolset
+ * before it sees individual tool descriptions.
+ *
+ * Goals when editing this:
+ *   - 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. 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## 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\n## Supported Languages\n\nThe indexer recognizes a fixed set of languages; if you ask about symbols in a\nfile with an unsupported extension, codegraph will report the project isn't\nindexed for that file and you should fall back to Read/Grep. The fork-specific\naddition beyond upstream codegraph is **VBA / Access** (Dysflow export\nformat):\n\n- **VBA / Access** - Dysflow exports Access/VBA source as `.bas`/`.cls`/\n  `.form.txt`/`.report.txt`. Codegraph extracts `.bas`/`.cls` as `module`/\n  `class`/`function` nodes with `calls`/`implements`/`references` edges\n  (procedural-level; regex-based, not full AST). Cross-module calls, qualified\n  `Dim As`, `WithEvents`, and SQL table references inside string literals\n  emit synthesized edges tagged `metadata.synthesizedBy` (`vba-name-resolution`,\n  `vba-withevents`, `vba-sql-table`). `.form.txt` and `.report.txt` are\n  extracted as a `module` plus one `property` per Access control - **no**\n  `function`/`sub`/`class` nodes come from form files; the canonical code\n  lives in the sibling `.cls`, parsed by the same extractor on that file.\n  Pass `projectPath` to a codegraph index that includes VBA files.\n";
+/**
+ * Instructions variant sent when the server's own root has NO codegraph index.
+ *
+ * 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_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/session.d.ts

@@ -0,0 +1,79 @@
+/**
+ * MCP per-connection session — speaks the JSON-RPC protocol (initialize,
+ * tools/list, tools/call) over a single {@link JsonRpcTransport}. It owns
+ * per-client state only (which protocol version the client asked for, whether
+ * it advertised `roots`, the one-shot roots/list latch); the heavyweight
+ * resources (CodeGraph, watcher, ToolHandler) live in the shared
+ * {@link MCPEngine} so daemon mode can collapse N inotify sets / DB handles
+ * to one.
+ *
+ * The state-machine itself mirrors what `MCPServer` used to do inline before
+ * issue #411 split it out — the same regression tests in
+ * `__tests__/mcp-initialize.test.ts` still drive this code path.
+ */
+import { JsonRpcTransport } from './transport';
+import { MCPEngine } from './engine';
+/**
+ * MCP Server Info — kept on the session because some clients log it. The
+ * version tracks the real package version (was a hard-coded '0.1.0').
+ */
+export declare const SERVER_INFO: {
+    name: string;
+    version: string;
+};
+/** MCP Protocol Version (latest the server claims). */
+export declare const PROTOCOL_VERSION = "2024-11-05";
+export interface MCPSessionOptions {
+    /**
+     * Explicit project path from the `--path` CLI flag. When set, the session
+     * will not bother asking the client for `roots/list` — we already know
+     * where the project lives.
+     */
+    explicitProjectPath?: string | null;
+}
+/**
+ * One MCP client's view of the server. Created fresh per stdio launch
+ * (direct mode) or per socket connection (daemon mode).
+ */
+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;
+    constructor(transport: JsonRpcTransport, engine: MCPEngine, opts?: MCPSessionOptions);
+    /**
+     * Start handling messages from the transport. Returns immediately — the
+     * session lives for as long as the transport is open.
+     */
+    start(): void;
+    /**
+     * Tear down the session. Does NOT touch the engine (the engine may serve
+     * other sessions) or call `process.exit` (the daemon decides when to exit).
+     */
+    stop(): void;
+    /** Underlying transport — exposed for daemon-side close hooks. */
+    getTransport(): JsonRpcTransport;
+    private handleMessage;
+    private handleInitialize;
+    private handleToolsList;
+    private handleToolsCall;
+    /**
+     * Lazy default-project resolution. Three layers:
+     *   1. await the in-flight init kicked off from `handleInitialize` (if any);
+     *   2. if still uninitialized and we never asked the client for its roots,
+     *      do so now (one-shot); fall back to cwd if the client lacks roots;
+     *   3. last-resort: re-walk from the best candidate — picks up projects
+     *      that were `codegraph init`'d *after* the server started.
+     */
+    private retryInitIfNeeded;
+    /**
+     * Ask the client for its workspace root via `roots/list` and open the
+     * first one. Falls back to `process.cwd()` on timeout or empty answer.
+     */
+    private initFromRoots;
+}
+//# sourceMappingURL=session.d.ts.map

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