@colbymchenry/codegraph 0.9.8 → 1.0.0

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 using 2-3 codegraph calls: `codegraph_context` first,\nthen ONE `codegraph_explore` for the source of the symbols it surfaces.\nCodegraph IS the pre-built search index \u2014 so delegating the lookup to a\nseparate file-reading sub-task/agent, or running your own grep + read\nloop, repeats work codegraph already did and costs more for the same\nanswer. Reach for raw Read/Grep only to confirm a specific detail\ncodegraph didn't cover. A direct codegraph answer is typically a handful\nof calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **\"What is the symbol named X?\"** \u2192 `codegraph_search`\n- **\"What's the deal with this task / feature / area?\"** \u2192 `codegraph_context` (PRIMARY \u2014 composes search + node + callers + callees in one call)\n- **\"How does X reach/become Y? / trace the flow / the path from X to Y\"** \u2192 `codegraph_trace` (ONE call returns the whole call path, including dynamic-dispatch hops \u2014 callbacks, React re-render, JSX children \u2014 that grep can't follow)\n- **\"What calls this?\"** \u2192 `codegraph_callers`\n- **\"What does this call?\"** \u2192 `codegraph_callees`\n- **\"What would changing this break?\"** \u2192 `codegraph_impact`\n- **\"Show me this symbol's source / signature / docstring.\"** \u2192 `codegraph_node`\n- **\"Show me several related symbols' source / survey an area.\"** \u2192 `codegraph_explore` (ONE capped call; prefer over many codegraph_node/Read)\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\"**: `codegraph_trace` from\u2192to FIRST \u2014 one call returns the entire path with dynamic-dispatch hops bridged. Then ONE `codegraph_explore` for the hop bodies if you need them. Do NOT reconstruct the path with `codegraph_search` + `codegraph_callers` \u2014 that's exactly what trace does in a single call.\n- **Onboarding**: `codegraph_context` first. If still unclear, `codegraph_explore` for breadth, then `codegraph_node` on specific symbols.\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`** when you just want context \u2014 `codegraph_context` is one 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,
@@ -105,8 +124,9 @@ export interface ToolResult {
 /**
  * All CodeGraph MCP tools
  *
- * Designed for minimal context usage - use codegraph_context as the primary tool,
- * and only use other tools for targeted follow-up queries.
+ * Designed for minimal context usage - use codegraph_explore as the primary tool
+ * (one call usually answers the whole question), and only use other tools for
+ * targeted follow-up queries.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
  */
@@ -158,7 +178,7 @@ export declare class ToolHandler {
      * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
      * trim the tool surface without rebuilding the client config; the ablated
      * tool is then truly absent from ListTools rather than merely denied on call.
-     * Matching is on the short form, so "trace" and "codegraph_trace" both work.
+     * Matching is on the short form, so "node" and "codegraph_node" both work.
      */
     private toolAllowlist;
     /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
@@ -241,26 +261,15 @@ export declare class ToolHandler {
      */
     private handleSearch;
     /**
-     * Handle codegraph_context
+     * 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 handleContext;
-    /**
-     * Detect a flow-style task ("how does X reach Y", "trace the path from A to B")
-     * and pre-run trace between the most likely endpoints, returning the trace
-     * body to splice into the context response. Returns '' for non-flow queries
-     * or when no plausible endpoint pair can be extracted.
-     *
-     * Conservative by design: only fires when the task has both a clear flow
-     * keyword AND at least two distinct PascalCase / camelCase identifiers.
-     * False positives waste a graph query; false negatives just fall back to
-     * the agent calling trace itself (existing path-proximity wiring handles
-     * disambiguation either way).
-     */
-    private maybeInlineFlowTrace;
-    /**
-     * Heuristic to detect if a query looks like a feature request
-     */
-    private looksLikeFeatureRequest;
+    private groupDefinitions;
+    /** Section heading for one distinct definition in grouped output. */
+    private definitionHeading;
     /**
      * Handle codegraph_callers
      */
@@ -273,18 +282,6 @@ export declare class ToolHandler {
      * Handle codegraph_impact
      */
     private handleImpact;
-    /**
-     * Handle codegraph_trace — shortest CALL PATH between two symbols.
-     *
-     * Exposes GraphTraverser.findPath: the chain of functions from `from` to `to`,
-     * each hop annotated with file:line and the call-site line. This is the
-     * capability grep/Read structurally cannot provide. When no static path
-     * exists, the chain has almost certainly broken at dynamic dispatch
-     * (callbacks, descriptors, metaclasses) — we say so and surface the start
-     * symbol's outgoing calls so the agent bridges the one missing hop with
-     * codegraph_node rather than blindly reading.
-     */
-    private handleTrace;
     /**
      * Describe a synthesized (dynamic-dispatch) edge for human output: how the
      * callback was wired up — the bridge static parsing can't see. Returns null
@@ -292,19 +289,6 @@ export declare class ToolHandler {
      * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
      */
     private synthEdgeNote;
-    /**
-     * Read one trimmed source line at "relpath:line" (relative to the project
-     * root). `cache` holds split file contents so a multi-hop trace reads each
-     * file at most once. Returns null if the file/line can't be resolved.
-     */
-    private sourceLineAt;
-    /**
-     * Read a hop's body — filePath lines [startLine..endLine] — for inlining into
-     * a trace, capped (lines + chars) so the whole path stays path-scoped even on
-     * a 7-hop chain. Dedents to the body's own indentation and marks truncation.
-     * Shares `cache` with sourceLineAt so each file is read at most once per trace.
-     */
-    private sourceRangeAt;
     /**
      * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
      * symbol names that usually spans the flow it's investigating (e.g.
@@ -320,6 +304,53 @@ 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,
+     * no source, so the agent knows what to update / re-verify before editing
+     * without reaching for a separate impact call. Always-on, but skips symbols
+     * that have no dependents (nothing to warn about), and returns '' when none
+     * qualify so a leaf-only exploration stays clean.
+     */
+    private buildBlastRadiusSection;
+    /**
+     * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
+     * PageRank) from the query's matched SEED nodes over the call/reference graph.
+     *
+     * This is the ranking signal text search (FTS/bm25) CANNOT provide, and it's
+     * codegraph's home turf: relevance by STRUCTURE, not words. A file whose
+     * symbols are call-connected to the matched cluster accrues walk mass and
+     * ranks high; a lone TEXT match — e.g. `LensSwitcher.swift` matched the word
+     * "switch" from `switchOrganization`, but calls none of `setUser`/`fetchUser`
+     * — gets only its own restart probability and ranks ~0. Immune to the
+     * tokenization trap that fools term matching, deterministic, no embeddings.
+     *
+     * Undirected adjacency (reachability both ways), restart α=0.25 to the seeds,
+     * power iteration to convergence. Bounded to the already-relevant subgraph, so
+     * it's a few hundred nodes × ~25 iterations — negligible cost.
+     */
+    private computeGraphRelevance;
     /**
      * Handle codegraph_explore — deep exploration in a single call
      *
@@ -336,6 +367,22 @@ 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;
     /**
      * Build the "trail" for a symbol: its direct callees (what it calls) and
      * callers (what calls it), each with file:line — so codegraph_node doubles as
@@ -393,7 +440,15 @@ export declare class ToolHandler {
      *      Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
      */
     private matchesSymbol;
-    private findSymbol;
+    /**
+     * Find ALL definitions matching a name, ranked, so codegraph_node can return
+     * every overload instead of guessing one (the wrong guess → a Read). Keepers
+     * rank before generated stubs (.pb.go etc.); stable within a group preserves
+     * FTS order. Returns [] when nothing matches; a qualified lookup that finds no
+     * exact match returns [] rather than a misleading fuzzy file hit (#173); a
+     * bare name with no exact match falls back to the single top fuzzy result.
+     */
+    private findSymbolMatches;
     /**
      * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
      * results across all matching symbols (e.g., multiple classes with an `execute` method).
@@ -405,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
@@ -415,7 +477,6 @@ export declare class ToolHandler {
      */
     private buildContainerOutline;
     private formatNodeDetails;
-    private formatTaskContext;
     private textResult;
     private errorResult;
 }

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

package/dist/resolution/name-matcher.d.ts

@@ -9,6 +9,36 @@ import { UnresolvedRef, ResolvedRef, ResolutionContext } from './types';
  * by matching the filename against file nodes.
  */
 export declare function matchByFilePath(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+export declare function sameLanguageFamily(a: string, b: string): boolean;
+/**
+ * True when `lang` belongs to a known multi-language family (jvm/apple/web/c).
+ * Languages not listed (php, python, go, ruby, rust, dart, …) and config
+ * formats (yaml/xml/blade) form their own singleton families and return
+ * `false` — used to leave config↔code framework bridges (whose config side is
+ * never a known programming-language family) out of the cross-family gate.
+ */
+export declare function isKnownLanguageFamily(lang: string): boolean;
+/**
+ * True when `a` and `b` are two DIFFERENT *known* language families — the
+ * signature of a coincidental cross-language name collision (a TS `import
+ * React` matching a Swift `import React`, a C++ `#include "X.h"` matching a
+ * same-named ObjC header on another platform). The both-*known* test is
+ * deliberately weaker than {@link sameLanguageFamily}'s negation: a
+ * single-file-component language that carries its own tag (`vue`/`svelte`)
+ * importing a `.ts` module, or any singleton-family language (php/go/ruby/…),
+ * returns `false` here and is left alone.
+ */
+export declare function crossesKnownFamily(a: string, b: string): boolean;
+/**
+ * Resolve a function-as-value reference (#756) — a function name used as a
+ * callback/function-pointer value (`register(handler)`, `o->cb = handler`,
+ * `{ .cb = handler }`, `signal(SIGINT, handler)`). The ONLY strategy allowed
+ * for `function_ref` refs: exact name, function/method targets only, same
+ * language family, same-file first, and cross-file only when the match is
+ * UNIQUE. No fuzzy fallback, no qualified-name walking — a wrong callback
+ * edge is worse than none.
+ */
+export declare function matchFunctionRef(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 /**
  * Try to resolve a reference by exact name match
  */
@@ -17,6 +47,37 @@ export declare function matchByExactName(ref: UnresolvedRef, context: Resolution
  * Try to resolve by qualified name
  */
 export declare function matchByQualifiedName(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a C++ chained call whose receiver is itself a call — encoded by the
+ * extractor as `<innerCallee>().<method>` (#645). The receiver's type is what
+ * the inner call returns; the outer method is then resolved and VALIDATED on it
+ * (resolveMethodOnType requires `cls::method` to exist), so a wrong inference
+ * produces no edge rather than a wrong one.
+ */
+export declare function matchCppCallChain(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a `::`-scoped factory chain whose receiver is a scoped/static call —
+ * PHP `Cls::for($x)->method()` (#608, the per-credential Laravel client idiom) or
+ * Rust `Foo::new().bar()` (an associated-function call) — both encoded by the
+ * extractor as `Cls::factory().method`. The receiver's type is what `Cls::factory`
+ * returns: a `self` marker (PHP `: self`/`: static`, Rust `-> Self`) resolves to
+ * the factory's own type, a concrete return type to that type. The outer method is
+ * then resolved and VALIDATED on it (resolveMethodOnType requires the method to
+ * exist on the type or a supertype it conforms to), so a wrong inference yields no
+ * edge rather than a wrong one. Shared by the `::`-receiver languages (PHP, Rust).
+ */
+export declare function matchScopedCallChain(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a dotted chained call whose receiver is a static factory / fluent call —
+ * `Foo.getInstance().bar()`, encoded by the extractor as `Foo.getInstance().bar`
+ * (#645/#608 mechanism). The receiver's type is what `Foo.getInstance` returns
+ * (its declared return type); the outer method is then resolved and VALIDATED on
+ * it (resolveMethodOnType requires `Type::method` to exist), so a wrong inference
+ * yields no edge rather than a wrong one (e.g. a same-named `bar()` on an
+ * unrelated class is never matched). Shared by the dot-notation languages
+ * (Java, Kotlin, C#, Swift) — same receiver shape, same `Class::method` qualified names.
+ */
+export declare function matchDottedCallChain(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 /**
  * Try to resolve by method name on a class/object
  */