@colbymchenry/codegraph 0.9.9 → 1.0.0

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.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/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

package/dist/mcp/tools.d.ts

@@ -5,6 +5,25 @@
  */
 import type CodeGraph from '../index';
 import type { PendingFile } from '../sync';
+/**
+ * An expected, recoverable "codegraph can't serve this" condition — most
+ * importantly a project with no index. The dispatch catch converts these to
+ * SUCCESS-shaped responses (guidance text, NO isError): an `isError: true`
+ * early in a session teaches the agent the toolset is broken and it stops
+ * calling codegraph entirely (observed repeatedly), which is exactly wrong
+ * for conditions the agent can simply work around (use built-in tools for
+ * that codebase / pass projectPath). isError is reserved for "stop trying"
+ * cases: security refusals ({@link PathRefusalError}) and genuine
+ * malfunctions.
+ */
+export declare class NotIndexedError extends Error {
+}
+/**
+ * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
+ * retry guidance — abandoning this path is the desired agent reaction.
+ */
+export declare class PathRefusalError extends Error {
+}
 /**
  * Calculate the recommended number of codegraph_explore calls based on project size.
  * Larger codebases need more exploration calls to cover their surface area,
@@ -241,6 +260,16 @@ export declare class ToolHandler {
      * Handle codegraph_search
      */
     private handleSearch;
+    /**
+     * Group symbol matches into DISTINCT DEFINITIONS — one group per
+     * (filePath, qualifiedName), so same-file overloads stay together while
+     * unrelated same-named classes across a monorepo's apps (#764: one
+     * `UserService` per NestJS app) are kept apart. Optionally narrowed by a
+     * `file` path/suffix first.
+     */
+    private groupDefinitions;
+    /** Section heading for one distinct definition in grouped output. */
+    private definitionHeading;
     /**
      * Handle codegraph_callers
      */
@@ -275,6 +304,27 @@ export declare class ToolHandler {
      * dropping unrelated `OmsOrderService::list`.
      */
     private buildFlowFromNamedSymbols;
+    /**
+     * Dynamic-boundary surfacing (#687): when the flow among the agent's named
+     * symbols does not fully connect, scan the disconnected symbols' bodies for
+     * dynamic-dispatch sites (computed member calls, getattr, reflection, typed
+     * message buses, runtime-keyed emits) and ANNOUNCE the boundary — the exact
+     * site, the form, and (when a key is statically visible) candidate targets —
+     * instead of guessing edges. The answer to "how does A reach B" when no
+     * static path exists IS the dispatch site: that's where the flow continues
+     * at runtime. Query-time, deterministic, zero graph mutation; a fully
+     * connected flow never reaches this method.
+     */
+    private buildDynamicBoundaries;
+    /**
+     * Shortlist candidate runtime targets for a dispatch key surfaced by
+     * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
+     * `onSave`/`handleSave`; `CreateCmd` → `CreateCmdHandler`), then FTS, with a
+     * normalized-containment post-filter (FTS camel-splitting is fuzzier than a
+     * candidate list should be). Symbols the agent already named sort first and
+     * are marked — that's the "you were right, here's the wiring" case.
+     */
+    private boundaryCandidates;
     /**
      * Compact "blast radius" for the entry symbols of an explore result: who
      * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
@@ -317,6 +367,20 @@ export declare class ToolHandler {
      * Handle codegraph_node
      */
     private handleNode;
+    /**
+     * FILE READ MODE: resolve `fileArg` (path or basename) to an indexed file and
+     * read it like the Read tool — its current on-disk source with line numbers,
+     * narrowable with `offset`/`limit` exactly as Read's are — preceded by a
+     * one-line blast-radius header (which files depend on it). `symbolsOnly`
+     * returns just the structural map (symbols + dependents) instead of source.
+     *
+     * Parity goal: the numbered source block is byte-for-byte the shape Read
+     * returns (`<n>\t<line>`, no padding), so the agent treats it as a Read — only
+     * faster (served from the index) and with the blast radius attached. Security:
+     * yaml/properties files are summarized by key, never dumped (#383); reads go
+     * through validatePathWithinRoot (#527).
+     */
+    private handleFileView;
     /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
     private renderNodeSection;
     /**
@@ -396,6 +460,13 @@ export declare class ToolHandler {
     private truncateOutput;
     private formatSearchResults;
     private formatNodeList;
+    /**
+     * Relationship label for a non-`calls` edge in callers/callees lists. A
+     * function-as-value edge (#756) is the high-signal one: `callers(cb)`
+     * showing "via callback registration" tells the agent this is where the
+     * callback is WIRED, not where it's invoked.
+     */
+    private edgeLabel;
     private formatImpact;
     /**
      * Build a compact structural outline of a container symbol from its

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

@@ -2,9 +2,9 @@ import type { QueryBuilder } from '../db/queries';
 import type { ResolutionContext } from './types';
 /**
  * Synthesize dispatcher→callback edges (field observers + EventEmitters +
- * React re-render + JSX children + Vue templates + RN event channel +
- * Fabric native-impl + MyBatis Java↔XML + Gin middleware chain). Returns the
- * count added. Never throws into indexing — callers wrap in try/catch.
+ * React re-render + JSX children + Vue templates + SvelteKit load + RN event
+ * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain).
+ * Returns the count added. Never throws into indexing — callers wrap in try/catch.
  */
 export declare function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): number;
 //# sourceMappingURL=callback-synthesizer.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * Astro Framework Resolver
+ *
+ * Handles Astro component references, the `Astro` global, `astro:*` virtual
+ * module imports, and Astro's `src/pages/` file-based routing.
+ */
+import { FrameworkResolver } from '../types';
+export declare const astroResolver: FrameworkResolver;
+//# sourceMappingURL=astro.d.ts.map

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

@@ -33,6 +33,7 @@ export { nestjsResolver } from './nestjs';
 export { reactResolver } from './react';
 export { svelteResolver } from './svelte';
 export { vueResolver } from './vue';
+export { astroResolver } from './astro';
 export { djangoResolver, flaskResolver, fastapiResolver } from './python';
 export { railsResolver } from './ruby';
 export { springResolver } from './java';

package/dist/resolution/import-resolver.d.ts

@@ -27,6 +27,16 @@ export declare function clearCppIncludeDirCache(): void;
  * Returns paths relative to projectRoot.
  */
 export declare function loadCppIncludeDirs(projectRoot: string): string[];
+/**
+ * Is this reference a PHP include/require PATH (vs a namespace `use` symbol)?
+ *
+ * include/require emit a file path ("lib.php", "inc/db.php", "../x.php"),
+ * whereas namespace use is an FQN (App\Foo\Bar) or a bare class symbol
+ * (Closure). PHP identifiers contain neither '/' nor '.', so a slash or dot
+ * marks a path-shaped include. Such references resolve to files only — never
+ * to a same-named symbol — so callers must not fall back to the name-matcher.
+ */
+export declare function isPhpIncludePathRef(ref: UnresolvedRef): boolean;
 /**
  * Extract import mappings from a file
  */

package/dist/resolution/index.d.ts

@@ -17,6 +17,9 @@ export declare class ReferenceResolver {
     private queries;
     private context;
     private frameworks;
+    private deferredChainRefs;
+    private deferredThisMemberRefs;
+    private razorUsingsCache;
     private nodeCache;
     private fileCache;
     private importMappingCache;
@@ -29,6 +32,7 @@ export declare class ReferenceResolver {
     private cachesWarmed;
     private projectAliases;
     private goModule;
+    private workspacePackages;
     constructor(projectRoot: string, queries: QueryBuilder);
     /**
      * Initialize the resolver (detect frameworks, etc.)
@@ -86,6 +90,20 @@ export declare class ReferenceResolver {
      * Resolve and persist edges to database
      */
     resolveAndPersist(unresolvedRefs: UnresolvedReference[], onProgress?: (current: number, total: number) => void): ResolutionResult;
+    /**
+     * Second resolution pass for chained static-factory / fluent calls whose
+     * chained method is defined on a SUPERTYPE the receiver's type conforms to —
+     * a protocol-extension / inherited / default-interface method (#750). The
+     * first pass can't resolve these because `implements`/`extends` edges aren't
+     * built yet; this runs AFTER edges are persisted, so `context.getSupertypes`
+     * (and the conformance fallback in resolveMethodOnType) can walk them.
+     *
+     * Operates only on the leftover unresolved refs that have the `inner().method`
+     * chain shape, for the dotted-chain languages — a small set — and is idempotent
+     * (re-resolving an already-resolved ref is a no-op since it's been deleted).
+     * Returns the number of newly-created edges.
+     */
+    resolveChainedCallsViaConformance(): number;
     /**
      * Resolve and persist in batches to keep memory bounded.
      * Processes unresolved references in chunks, persisting edges and cleaning
@@ -108,6 +126,68 @@ export declare class ReferenceResolver {
      * Get language from node ID
      */
     private getLanguageFromNodeId;
+    /**
+     * Drop an import/name-strategy resolution that crosses a language family.
+     * Two regimes (mirrors `applyLanguageGate`'s candidate filter):
+     *  - `references` (type usage): STRICT — a `Type.member` static read names a
+     *    same-family type, never a coincidentally same-named symbol in another
+     *    language. Drops any non-same-family target.
+     *  - `imports` (import binding / `#include`): both-known — a C++ `#include
+     *    "X.h"` must not resolve to a same-named ObjC header on another platform
+     *    (basename collision), but a singleton-family / SFC language (`vue` →
+     *    `.ts`) importing across is left alone.
+     * Applies to the import (strategy 2) + name-match (strategy 3) results.
+     */
+    /**
+     * Collect the `@using` namespaces in scope for a `.razor`/`.cshtml` file: its
+     * own `@using` directives plus every `_Imports.razor` from the file's folder up
+     * to the project root (Razor `_Imports` cascade). Cached per file.
+     */
+    private getRazorUsings;
+    /**
+     * Resolve a Razor/Blazor simple type ref through the file's `@using`
+     * namespaces: `CatalogBrand` + `@using BlazorShared.Models` → the node whose
+     * qualified name is `BlazorShared.Models::CatalogBrand`. Only resolves when the
+     * `@using` set yields exactly ONE type (otherwise it stays ambiguous and falls
+     * through to name-matching).
+     */
+    private resolveRazorUsing;
+    /**
+     * Resolve a `this.<member>` function-as-value reference (#756/#808) to the
+     * ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The
+     * registration idiom (`btn.on('click', this.handleClick)`) names a member
+     * of the class being defined, so the only valid target shares the
+     * from-symbol's qualified-name scope. Function/method targets only — a
+     * property (a data field, post-#808 classification) yields no edge — same
+     * file required, no fallback of any kind.
+     */
+    private resolveThisMemberFnRef;
+    /**
+     * Second pass for `this.<member>` refs whose member wasn't on the enclosing
+     * class itself (#808): once implements/extends edges exist, walk the
+     * class's supertypes (transitively, depth-capped) and resolve the member on
+     * the nearest one that declares it — `this.handleSubmit` registered in a
+     * subclass resolves to `FormBase::handleSubmit`. Validated targets only
+     * (function/method kind, same language family); no match → no edge.
+     * Mirrors resolveChainedCallsViaConformance's lifecycle. Returns the number
+     * of newly-created edges.
+     */
+    resolveDeferredThisMemberRefs(): number;
+    private gateLanguage;
+    /**
+     * Drop a FRAMEWORK-strategy resolution that crosses two *known* language
+     * families for a type-usage (`references`) or import-binding (`imports`)
+     * edge. The framework strategy is intentionally ungated for cross-language
+     * bridges, but those legitimate bridges are either `calls` edges (RN/Expo
+     * JS → native) or config↔code edges whose config side (`yaml`/`blade`/…) is
+     * not a known programming-language family. A `references`/`imports` edge
+     * between two *known* families is always a coincidental name collision — the
+     * React/Svelte/Vue PascalCase component resolvers name-match `getNodesByName`
+     * without a language check, so a TS `<TestRunner>` ref happily matched a
+     * Kotlin `class TestRunner`. Gating only the both-known-cross-family case
+     * lets config bridges and `calls` bridges through untouched.
+     */
+    private gateFrameworkLanguage;
 }
 /**
  * Create a reference resolver instance