@colbymchenry/codegraph 0.9.7 → 0.9.9

package/dist/mcp/daemon.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * One detached `codegraph serve --mcp` daemon process per project root,
+ * accepting N concurrent MCP clients over a Unix-domain socket (or named pipe
+ * on Windows). Each incoming connection gets its own {@link MCPSession}; all
+ * sessions share a single {@link MCPEngine}, which means a single file watcher
+ * (one inotify set), a single SQLite connection (one WAL writer), and a single
+ * tree-sitter warm-up — paid once, amortized across every agent talking to the
+ * project.
+ *
+ * Lifecycle (see also `./index.ts` and `./proxy.ts`):
+ *   - The daemon is spawned **detached** (its own session/process group, stdio
+ *     decoupled) by the first launcher that finds no daemon running. It is NOT
+ *     a child of any MCP host, so closing one terminal / Ctrl-C'ing one session
+ *     can't take it down and sever the others. That's why this process has no
+ *     PPID watchdog: it deliberately outlives every individual client.
+ *   - Every MCP host talks to the daemon through a thin `proxy` process (the
+ *     thing the host actually spawned). The proxy keeps the #277 PPID watchdog,
+ *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
+ *     close then decrements the daemon's refcount.
+ *   - When the last client disconnects the daemon lingers for
+ *     `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
+ *     runs in the same project don't repay startup, then exits cleanly. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *
+ * What this file owns:
+ *   - Listening on the daemon socket and spawning per-connection sessions.
+ *   - The handshake "hello" line that lets a proxy verify it found a
+ *     same-version daemon before piping any JSON-RPC through it.
+ *   - The lockfile (`.codegraph/daemon.pid`) competing daemons arbitrate
+ *     against — atomic `O_EXCL` create with the full record written in the same
+ *     breath (no empty-file window) + cleanup on exit.
+ *   - Reference counting + idle timeout.
+ *   - Graceful shutdown on SIGTERM/SIGINT and idle exit.
+ *
+ * What this file does NOT own:
+ *   - The proxy side (`./proxy.ts`).
+ *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
+ *   - The MCP protocol state machine — that's `./session.ts`.
+ */
+import { DaemonLockInfo } from './daemon-paths';
+/** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
+declare const MAX_HELLO_LINE_BYTES = 4096;
+/**
+ * Wire format for the one-shot hello line the daemon emits on every new
+ * connection. Versioned with the package's own semver so a 0.9.x proxy never
+ * pipes through a 0.10.x daemon (or vice-versa) — the proxy falls back to
+ * direct mode on mismatch rather than risk subtle wire incompatibilities.
+ */
+export interface DaemonHello {
+    codegraph: string;
+    pid: number;
+    socketPath: string;
+    protocol: 1;
+}
+export interface DaemonStartResult {
+    /** Always-non-null for a successfully-started daemon. */
+    socketPath: string;
+    /** Lockfile contents as written. */
+    lock: DaemonLockInfo;
+}
+/**
+ * Run as the shared daemon for `projectRoot`. Resolves once the socket is
+ * listening. The Daemon owns the socket, the engine, and the lockfile until
+ * `stop()` is called or it exits on idle/signal.
+ *
+ * Race-safe: callers must first call `tryAcquireDaemonLock(projectRoot)` and
+ * only construct a Daemon if they got the lock (`kind: 'acquired'`). The atomic
+ * `O_EXCL` create inside the acquire helper — which now also writes the full
+ * record before returning — is the only synchronization between competing
+ * daemons.
+ */
+export declare class Daemon {
+    private projectRoot;
+    private server;
+    private clients;
+    private idleTimer;
+    private idleTimeoutMs;
+    private engine;
+    private stopping;
+    private socketPath;
+    private pidPath;
+    constructor(projectRoot: string, opts?: {
+        idleTimeoutMs?: number;
+    });
+    /**
+     * Bind the socket, kick off engine init, and register signal handlers. The
+     * lockfile body was already written atomically by `tryAcquireDaemonLock`, so
+     * there is nothing to write here. The promise resolves once the server is
+     * listening — the daemon then sticks around until idle/shutdown.
+     */
+    start(): Promise<DaemonStartResult>;
+    /** Currently-connected client count. Exposed for tests / status output. */
+    getClientCount(): number;
+    /** The socket path the daemon is (or will be) listening on. */
+    getSocketPath(): string;
+    /** Graceful shutdown: close all sessions, the engine, and clean up the lock. */
+    stop(reason?: string): Promise<void>;
+    private handleConnection;
+    private dropClient;
+    private armIdleTimer;
+    private disarmIdleTimer;
+    private cleanupLockfile;
+}
+/**
+ * Result of `tryAcquireDaemonLock`. Either we got the lockfile (caller becomes
+ * the daemon), or it already existed (caller should connect to the existing
+ * daemon as a proxy, or — if the holder is dead — clear it and retry).
+ */
+export type AcquireResult = {
+    kind: 'acquired';
+    pidPath: string;
+    info: DaemonLockInfo;
+} | {
+    kind: 'taken';
+    existing: DaemonLockInfo | null;
+    pidPath: string;
+};
+/**
+ * Atomically create the daemon pidfile with its full record already in place.
+ * Returns either an `acquired` result (the caller is the daemon-elect and may
+ * construct a {@link Daemon}) or a `taken` result.
+ *
+ * must-fix 1 (issue #411 review): the lockfile must appear in ONE atomic step,
+ * already complete — never empty, even momentarily. The first attempt at this
+ * (`O_EXCL` create then a separate `writeSync`) left a microsecond window where
+ * 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
+ * concurrent daemons overlap enough to reproduce it reliably.
+ *
+ * The fix writes the complete record to a private temp file, then hard-links it
+ * into place: `link()` is atomic AND exclusive (EEXIST if the target exists), so
+ * the pidfile becomes visible in one step already containing a full record.
+ * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
+ * There is no empty-file window at all.
+ */
+export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+/**
+ * Remove a stale pidfile, but only if it still names a dead process. Re-reads
+ * the file immediately before unlinking so we never delete a lock that a live
+ * daemon (re)acquired in the meantime.
+ *
+ * must-fix 1 (issue #411 review): the original unconditionally `unlink`'d,
+ * which let a racing candidate delete a healthy daemon's lock. Passing
+ * `expectedDeadPid` (the pid the caller believed was dead) makes the clear a
+ * compare-and-delete: bail if the file now holds a different pid, or any live
+ * pid. Returns true when the stale lock is gone (or was already gone).
+ */
+export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?: number): boolean;
+/**
+ * Probe whether `pid` is currently alive (signal-0). Treats EPERM as alive on
+ * every platform (the process exists, it's just not ours to signal) so we never
+ * mistake a live daemon for a dead one and clear its lock.
+ */
+export declare function isProcessAlive(pid: number): 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/engine.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link CodeGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+import { ToolHandler } from './tools';
+export interface MCPEngineOptions {
+    /**
+     * Whether to start the file watcher when initializing. Daemon and direct
+     * modes both want this true; tests may set it false to keep the engine
+     * cheap. Honors {@link watchDisabledReason} regardless.
+     */
+    watch?: boolean;
+}
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+export declare class MCPEngine {
+    private cg;
+    private toolHandler;
+    private projectPath;
+    private initPromise;
+    private watcherStarted;
+    private opts;
+    private closed;
+    constructor(opts?: MCPEngineOptions);
+    /**
+     * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+     * project path (from the `--path` CLI flag) without yet opening it. This
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath: string): void;
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath(): string | null;
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler(): ToolHandler;
+    /** Whether the default project's CodeGraph is open. */
+    hasDefaultCodeGraph(): boolean;
+    /**
+     * Walk up from `searchFrom` to find the nearest `.codegraph/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    ensureInitialized(searchFrom: string): Promise<void>;
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom: string): void;
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop(): void;
+    private doInitialize;
+    /**
+     * Start file watching on the active CodeGraph instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    private startWatching;
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    private catchUpSync;
+}
+/**
+ * Parse and clamp the CODEGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+export declare function parseDebounceEnv(raw: string | undefined): number | undefined;
+//# sourceMappingURL=engine.d.ts.map

package/dist/mcp/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 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/proxy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 type { MCPEngine } from './engine';
+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/server-instructions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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:
+ *   - 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)
+ *
+ * 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.
+ */
+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";
+//# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/session.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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;
+    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