homegraph 0.9.10 → 1.1.1

package/dist/mcp/tools.js

@@ -2,27 +2,50 @@
 /**
  * MCP Tool Definitions
  *
- * Defines the tools exposed by the CodeGraph MCP server.
+ * Defines the tools exposed by the HomeGraph MCP server.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolHandler = exports.tools = void 0;
+exports.ToolHandler = exports.tools = exports.PathRefusalError = exports.NotIndexedError = void 0;
 exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
 exports.formatStaleBanner = formatStaleBanner;
 exports.formatStaleFooter = formatStaleFooter;
+exports.formatDegradedBanner = formatDegradedBanner;
 exports.getStaticTools = getStaticTools;
 const directory_1 = require("../directory");
-// Lazy-load the heavy CodeGraph chain off the MCP startup path — see the same
+// Lazy-load the heavy HomeGraph chain off the MCP startup path — see the same
 // helper in engine.ts. ToolHandler must load to answer tools/list (static
 // schemas), but it must NOT drag in sqlite/query layers before the daemon binds;
-// CodeGraph is pulled in only when a tool actually opens a project. require() is
+// HomeGraph is pulled in only when a tool actually opens a project. require() is
 // sync + cached (CommonJS build).
-const loadCodeGraph = () => require('../index').default;
+const loadHomeGraph = () => require('../index').default;
 const worktree_1 = require("../sync/worktree");
 const query_utils_1 = require("../search/query-utils");
 const fs_1 = require("fs");
 const utils_1 = require("../utils");
 const generated_detection_1 = require("../extraction/generated-detection");
+const dynamic_boundaries_1 = require("./dynamic-boundaries");
+/**
+ * An expected, recoverable "homegraph 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 homegraph 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.
+ */
+class NotIndexedError extends Error {
+}
+exports.NotIndexedError = NotIndexedError;
+/**
+ * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
+ * retry guidance — abandoning this path is the desired agent reaction.
+ */
+class PathRefusalError extends Error {
+}
+exports.PathRefusalError = PathRefusalError;
 const path_1 = require("path");
 /** Maximum output length to prevent context bloat (characters) */
 const MAX_OUTPUT_LENGTH = 15000;
@@ -206,6 +229,28 @@ function exploreLineNumbersEnabled() {
 function adaptiveExploreEnabled() {
     return process.env.HOMEGRAPH_ADAPTIVE_EXPLORE !== '0' && process.env.HOMEGRAPH_ADAPTIVE_EXPLORE !== 'false';
 }
+/**
+ * How long the FIRST tool call waits on the post-open catch-up reconcile before
+ * giving up and serving anyway (issue #905). On a normal repo the reconcile
+ * finishes in well under this, so the gate is fully honored and nothing changes.
+ * On a very large repo (~100k files) the reconcile takes minutes — blocking the
+ * first call on all of it presents as a multi-minute hang — so we wait briefly
+ * for a clean answer, then serve and let the reconcile finish in the background
+ * (it yields to the event loop, so a concurrent read still runs).
+ *
+ * `HOMEGRAPH_CATCHUP_GATE_TIMEOUT_MS` overrides the default; `0` restores the
+ * old unbounded-wait behavior (always block until the reconcile completes).
+ */
+const DEFAULT_CATCHUP_GATE_TIMEOUT_MS = 3000;
+function resolveCatchUpGateTimeoutMs() {
+    const raw = process.env.HOMEGRAPH_CATCHUP_GATE_TIMEOUT_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_CATCHUP_GATE_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_CATCHUP_GATE_TIMEOUT_MS;
+    return Math.floor(n);
+}
 /**
  * Prefix each line of a source slice with its 1-based line number, matching
  * the Read tool's `cat -n` convention (number + tab) so the agent treats it
@@ -222,6 +267,22 @@ function numberSourceLines(slice, firstLineNumber) {
     }
     return out.join('\n');
 }
+/**
+ * Unique line-prefix for a per-file source section in homegraph_explore output.
+ * Issue #778: tool results dropped ATX headings (`####`, `##`, `###`) for bold
+ * labels so Markdown-rendering MCP clients (e.g. the Claude Code VSCode
+ * extension) stop blowing every header up to H1–H4. The path is bold + a code
+ * span so it still reads as a header, and the leading ``**` `` stays a UNIQUE,
+ * greppable marker — no other explore line begins with it — that the explore
+ * truncation boundary (`handleExplore`) and the offload chunker
+ * (`reasoning/reasoner.ts`) both key off to cut on whole file sections.
+ */
+const FILE_SECTION_PREFIX = '**`';
+function fileSectionHeader(filePath, suffix) {
+    return suffix
+        ? `${FILE_SECTION_PREFIX}${filePath}\`** — ${suffix}`
+        : `${FILE_SECTION_PREFIX}${filePath}\`**`;
+}
 /**
  * Per-file staleness banner emitted at the top of a tool response when the
  * file watcher has pending events for files referenced by the response.
@@ -236,7 +297,7 @@ function formatStaleBanner(stale) {
         return `  - ${p.path} (edited ${ageMs}ms ago, ${label})`;
     });
     return ('⚠️ Some files referenced below were edited since the last index sync — ' +
-        'their codegraph entries may be stale:\n' +
+        'their homegraph entries may be stale:\n' +
         lines.join('\n') +
         '\nFor accurate content of those specific files, Read them directly. ' +
         'The rest of this response is fresh.');
@@ -258,15 +319,29 @@ function formatStaleFooter(stale) {
     return (`(Note: ${stale.length} file(s) elsewhere in this project are pending index ` +
         `sync but were not referenced above:\n${lines.join('\n')}${more})`);
 }
+/**
+ * Whole-index degradation banner (issue #876). Emitted at the top of a read
+ * tool response when live watching has permanently stopped — at which point
+ * `getPendingFiles()` is empty, so the per-file banner above can't fire even
+ * though the index is now FROZEN and silently drifting stale. Leads with the
+ * agent-actionable instruction (Read directly) and carries the reason, which
+ * already names the operator remedy (`homegraph sync` / git hooks).
+ */
+function formatDegradedBanner(reason) {
+    return ('⚠️ HomeGraph auto-sync is DISABLED — live file watching stopped, so the index is ' +
+        'frozen and any file edited since then is stale here. Read files directly to confirm ' +
+        'current content before relying on it.' +
+        (reason ? `\n  Reason: ${reason}` : ''));
+}
 /**
  * Common projectPath property for cross-project queries
  */
 const projectPathProperty = {
     type: 'string',
-    description: 'Path to a different project with .homegraph/ initialized. If omitted, uses current project. Use this to query other codebases.',
+    description: 'Absolute path to the project to query (or any directory inside it) — homegraph uses the nearest .homegraph/ index at or above that path. Omit to use this session\'s default project. Pass it to query a second codebase, or when the server root has no index of its own (e.g. a monorepo where only sub-projects are indexed, so there is no default project).',
 };
 /**
- * All CodeGraph MCP tools
+ * All HomeGraph MCP tools
  *
  * Designed for minimal context usage - use homegraph_explore as the primary tool
  * (one call usually answers the whole question), and only use other tools for
@@ -310,6 +385,10 @@ exports.tools = [
                     type: 'string',
                     description: 'Name of the function, method, or class to find callers for',
                 },
+                file: {
+                    type: 'string',
+                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist (e.g. one UserService per app in a monorepo)',
+                },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of callers to return (default: 20)',
@@ -330,6 +409,10 @@ exports.tools = [
                     type: 'string',
                     description: 'Name of the function, method, or class to find callees for',
                 },
+                file: {
+                    type: 'string',
+                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+                },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of callees to return (default: 20)',
@@ -350,6 +433,10 @@ exports.tools = [
                     type: 'string',
                     description: 'Name of the symbol to analyze impact for',
                 },
+                file: {
+                    type: 'string',
+                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+                },
                 depth: {
                     type: 'number',
                     description: 'How many levels of dependencies to traverse (default: 2)',
@@ -362,41 +449,54 @@ exports.tools = [
     },
     {
         name: 'homegraph_node',
-        description: 'SECONDARY (after homegraph_explore): get ONE symbol in full — its location, signature, callers/callees trail, and verbatim body (includeCode=true). When the name is AMBIGUOUS (an overloaded method, or the same method name on different types), it returns EVERY matching definition\'s full body in a single call — so you never need to Read a file to find the specific overload you want. For a heavily-overloaded name, pass `file` (and/or `line`) to pin the exact definition — e.g. the `file:line` a trail or another tool already showed you. Reach for this when explore trimmed a body you need. Use homegraph_explore for several related symbols or the full flow.',
+        description: 'Two modes. (1) READ A FILE — use INSTEAD of the Read tool: pass `file` (a path or basename) with no `symbol` and it returns that file\'s current on-disk source with line numbers, exactly the shape Read gives you (`<n>\\t<line>`, safe to Edit from), narrowable with `offset`/`limit` just 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 whenever you would Read a source file. (2) ONE SYMBOL you can name — its location, signature, verbatim source (includeCode=true) and caller/callee trail in one call, so before changing it you see what calls it and what your edit would break. 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); pass `file`/`line` to pin one. Use homegraph_explore for several related symbols or the full flow.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Name of the symbol to get details for',
+                    description: 'Name of the symbol to read (symbol mode). Omit it and pass `file` alone to read a whole file like Read.',
                 },
                 includeCode: {
                     type: 'boolean',
-                    description: 'Include full source code (default: false to minimize context)',
+                    description: 'Symbol mode: include the symbol\'s full body (default: false). Ignored in file mode, which always returns source unless `symbolsOnly` is set.',
                     default: false,
                 },
                 file: {
                     type: 'string',
-                    description: 'Optional: disambiguate an overloaded name to the definition in this file (path or basename, e.g. "harness.rs").',
+                    description: 'A file path or basename (e.g. "harness.rs", "src/auth/session.ts"). Pass it ALONE (no symbol) to READ the file like the Read tool — its full source with line numbers + which files depend on it. Or pass it WITH a symbol to disambiguate an overloaded name to the definition in this file.',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'File mode: 1-based line to start reading from, exactly like Read\'s offset. Defaults to the start of the file.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'File mode: maximum number of lines to return, exactly like Read\'s limit. Defaults to the whole file (capped at 2000 lines, like Read).',
+                },
+                symbolsOnly: {
+                    type: 'boolean',
+                    description: 'File mode: return just the file\'s symbol map + dependents (a cheap structural overview) instead of its source.',
+                    default: false,
                 },
                 line: {
                     type: 'number',
-                    description: 'Optional: disambiguate to the definition at/around this line (use with the file:line a trail showed you).',
+                    description: 'Symbol mode only: disambiguate to the definition at/around this line (use with the file:line a trail showed you).',
                 },
                 projectPath: projectPathProperty,
             },
-            required: ['symbol'],
+            required: [],
         },
     },
     {
         name: 'homegraph_explore',
-        description: 'PRIMARY TOOL — call FIRST for almost any question: how does X work, architecture, a bug, where/what is X, or surveying an area. Returns the verbatim source of the relevant symbols grouped by file in ONE capped call (Read-equivalent — do NOT re-open shown files). Query can be a natural-language question OR a bag of symbol/file names. Usually the ONLY call you need — answers without further search/node/Read/Grep.',
+        description: 'PRIMARY TOOL — call FIRST for almost any question OR before an edit: how does X work, architecture, a bug, where/what is X, surveying an area, or the symbols you are about to change. Returns the verbatim source of the relevant symbols grouped by file in ONE capped call (Read-equivalent — treat the shown source as already Read; do NOT re-open those files), plus the call path among them. Query can be a natural-language question OR a bag of symbol/file names. Usually the ONLY call you need — more accurate context, in far fewer tokens and round-trips than a search/Read/Grep loop.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). Use homegraph_search first to find relevant names.',
+                    description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). For a flow question, name the symbols spanning the flow (e.g. "mutateElement renderScene"). A natural-language question works too — no prior homegraph_search needed.',
                 },
                 maxFiles: {
                     type: 'number',
@@ -455,25 +555,38 @@ exports.tools = [
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
- * `ToolHandler.getTools()` in the no-CodeGraph case (the dynamic per-repo budget
+ * `ToolHandler.getTools()` in the no-HomeGraph case (the dynamic per-repo budget
  * note in a description only adds once `cg` is loaded; the schemas are static).
  */
 function getStaticTools() {
-    const raw = process.env.HOMEGRAPH_MCP_TOOLS;
-    if (!raw || !raw.trim())
-        return exports.tools;
-    const allow = new Set(raw.split(',').map(s => s.trim().replace(/^homegraph_/, '')).filter(Boolean));
+    const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
+    if (!raw || !raw.trim()) {
+        return exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^homegraph_/, '')));
+    }
+    const allow = new Set(raw.split(',').map(s => s.trim().replace(/^homegraph_/, '').replace(/^homegraph_/, '')).filter(Boolean));
     return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, ''))) : exports.tools;
 }
 /**
- * Tool handler that executes tools against a CodeGraph instance
+ * The MCP tools served by DEFAULT (short names). Pared to ONLY `homegraph_explore`
+ * — the single tool that reliably earns its place: one capped call returns the
+ * verbatim source of the relevant symbols grouped by file. Every other tool is a
+ * narrower slice of what explore already does, and presence itself steers
+ * mis-picks, so they are no longer LISTED to agents.
+ *
+ * The other defined tools (`node`, `search`, `callers`, plus callees/impact/files/
+ * status) remain fully functional — handlers stay, the library API and CLI are
+ * untouched, and `HOMEGRAPH_MCP_TOOLS=explore,node,...` re-enables any of them.
+ */
+const DEFAULT_MCP_TOOLS = new Set(['explore']);
+/**
+ * Tool handler that executes tools against a HomeGraph instance
  *
  * Supports cross-project queries via the projectPath parameter.
  * Other projects are opened on-demand and cached for performance.
  */
 class ToolHandler {
     cg;
-    // Cache of opened CodeGraph instances for cross-project queries
+    // Cache of opened HomeGraph instances for cross-project queries
     projectCache = new Map();
     // The directory the server last searched for a default project. Surfaced in
     // the "not initialized" error so users can see why detection missed.
@@ -489,16 +602,18 @@ class ToolHandler {
     // this, a tool call that races past `catchUpSync()` serves rows for files
     // that were deleted (or edited) while no MCP server was running — and the
     // per-file staleness banner can't help, because `getPendingFiles()` is
-    // populated by the watcher, not by catch-up. Cleared on first await so
+    // populated by the watcher, not by catch-up. The wait is time-boxed
+    // (see {@link resolveCatchUpGateTimeoutMs}) so a minutes-long reconcile on a
+    // huge repo can't hang the first call (#905); cleared on first await so
     // subsequent calls don't pay any cost.
     catchUpGate = null;
     constructor(cg) {
         this.cg = cg;
     }
     /**
-     * Update the default CodeGraph instance (e.g. after lazy initialization)
+     * Update the default HomeGraph instance (e.g. after lazy initialization)
      */
-    setDefaultCodeGraph(cg) {
+    setDefaultHomeGraph(cg) {
         this.cg = cg;
     }
     /**
@@ -511,6 +626,45 @@ class ToolHandler {
     setCatchUpGate(p) {
         this.catchUpGate = p;
     }
+    /**
+     * Await the catch-up gate, but no longer than the configured timeout (#905).
+     * If the reconcile settles first, we got the fully-reconciled answer. If the
+     * timeout wins, we serve the call now and let the reconcile finish in the
+     * background — it yields to the event loop (see SYNC_RECONCILE_YIELD_INTERVAL),
+     * so a concurrent read still runs against the same connection. Never throws:
+     * a failed reconcile is logged by the engine, and we serve best-effort over
+     * the same potentially-stale data the un-gated path would have.
+     */
+    async awaitCatchUpGate(gate) {
+        const timeoutMs = resolveCatchUpGateTimeoutMs();
+        if (timeoutMs <= 0) {
+            // 0 = opt back into the original unbounded wait.
+            try {
+                await gate;
+            }
+            catch { /* engine already logged */ }
+            return;
+        }
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            const outcome = await Promise.race([
+                gate.then(() => 'done', () => 'done'),
+                timedOut,
+            ]);
+            if (outcome === 'timeout') {
+                process.stderr.write(`[HomeGraph MCP] Catch-up reconcile still running after ${timeoutMs}ms; serving this tool call now and finishing the reconcile in the background (#905). ` +
+                    `Set HOMEGRAPH_CATCHUP_GATE_TIMEOUT_MS=0 to always wait for it.\n`);
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     /**
      * Record the directory the server tried to resolve the default project from.
      * Used only to make the "no default project" error actionable.
@@ -519,9 +673,9 @@ class ToolHandler {
         this.defaultProjectHint = searchedPath;
     }
     /**
-     * Whether a default CodeGraph instance is available
+     * Whether a default HomeGraph instance is available
      */
-    hasDefaultCodeGraph() {
+    hasDefaultHomeGraph() {
         return this.cg !== null;
     }
     /**
@@ -533,7 +687,7 @@ class ToolHandler {
      * Matching is on the short form, so "node" and "homegraph_node" both work.
      */
     toolAllowlist() {
-        const raw = process.env.HOMEGRAPH_MCP_TOOLS;
+        const raw = process.env.HOMEGRAPH_MCP_TOOLS ?? process.env.HOMEGRAPH_MCP_TOOLS;
         if (!raw || !raw.trim())
             return null;
         const short = (s) => s.trim().replace(/^homegraph_/, '');
@@ -553,18 +707,22 @@ class ToolHandler {
      */
     getTools() {
         const allow = this.toolAllowlist();
+        // No explicit allowlist → the default 4-tool surface (see
+        // DEFAULT_MCP_TOOLS for the evidence). An allowlist replaces the
+        // default entirely, so any defined tool can be re-enabled.
         let visible = allow
             ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, '')))
-            : exports.tools;
+            : exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^homegraph_/, '')));
         if (!this.cg)
             return visible;
         try {
             const stats = this.cg.getStats();
             const budget = getExploreBudget(stats.fileCount);
             // Tiny-repo tool gating: on projects under TINY_REPO_FILE_THRESHOLD
-            // files, only expose the 5 core tools (search, context, node,
-            // explore, trace). The 5 omitted tools (callers, callees, impact,
-            // status, files) reduce to one grep at this scale.
+            // files, only expose the core trio (search, node, explore) — one
+            // below even the 4-tool default: at this scale callers, too, reduces
+            // to one grep. (Historical note: the audit below ran when context and
+            // trace still existed; its "5 core tools" are today's trio.)
             //
             // n=2 audits ruled out cutting below 5 tools:
             // - 3-tool gate (search + context + trace): cost regressed on
@@ -607,31 +765,32 @@ class ToolHandler {
         }
     }
     /**
-     * Get CodeGraph instance for a project
+     * Get HomeGraph instance for a project
      *
-     * If projectPath is provided, opens that project's CodeGraph (cached).
-     * Otherwise returns the default CodeGraph instance.
+     * If projectPath is provided, opens that project's HomeGraph (cached).
+     * Otherwise returns the default HomeGraph instance.
      *
      * Walks up parent directories to find the nearest .homegraph/ folder,
      * similar to how git finds .git/ directories.
      */
-    getCodeGraph(projectPath) {
+    getHomeGraph(projectPath) {
         if (!projectPath) {
             if (!this.cg) {
                 const searched = this.defaultProjectHint ?? process.cwd();
-                throw new Error('No CodeGraph project is loaded for this session.\n' +
+                throw new NotIndexedError('No HomeGraph project is loaded for this session.\n' +
                     `Searched for a .homegraph/ directory starting from: ${searched}\n` +
-                    'The index is likely fine — this is a working-directory detection issue: ' +
-                    "the MCP client launched the server outside your project and didn't report the " +
-                    'workspace root. Fix it either way:\n' +
-                    '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project"\n' +
-                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]');
+                    'Either the server root has no index of its own (e.g. a monorepo where only ' +
+                    "sub-projects are indexed), or the MCP client launched the server outside your " +
+                    'project without reporting the workspace root. Either way, target the project ' +
+                    'explicitly:\n' +
+                    '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project" ' +
+                    '(any project that has a .homegraph/ — including a sub-project of a monorepo)\n' +
+                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]\n' +
+                    'If a project simply has no index, use your built-in tools (Read/Grep/Glob) for THAT ' +
+                    "project (the user can run 'homegraph init' there to enable it) — you can still query " +
+                    'other indexed projects by projectPath in the same session.');
             }
-            return this.cg;
-        }
-        // Check cache first (using original path as key)
-        if (this.projectCache.has(projectPath)) {
-            return this.projectCache.get(projectPath);
+            return this.freshen(this.cg);
         }
         // Reject sensitive system directories before opening. Only validate a
         // path that actually exists — a nested or not-yet-created sub-path of a
@@ -641,36 +800,66 @@ class ToolHandler {
         if ((0, fs_1.existsSync)(projectPath)) {
             const pathError = (0, utils_1.validateProjectPath)(projectPath);
             if (pathError) {
-                throw new Error(pathError);
+                throw new PathRefusalError(pathError);
             }
         }
-        // Walk up parent directories to find nearest .homegraph/
-        const resolvedRoot = (0, directory_1.findNearestCodeGraphRoot)(projectPath);
+        // Always RE-RESOLVE the nearest .homegraph/ from the input path. The walk
+        // is cheap (a few existsSync up the tree) and is the only thing that
+        // notices a path whose index root CHANGED since it was first seen — most
+        // importantly a git worktree that gained its own .homegraph/ after the
+        // (long-lived) server first resolved it up to the parent checkout. We used
+        // to short-circuit on a `projectCache[projectPath]` entry before resolving,
+        // which pinned that first resolution for the server's whole lifetime, so a
+        // worktree kept being served the parent checkout's index until restart
+        // (#926). The DB connection itself is still cached (by resolved root,
+        // below), so re-resolving costs only the stat walk, never a reopen.
+        const resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(projectPath);
         if (!resolvedRoot) {
-            throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'homegraph init' in that project first.`);
+            throw new NotIndexedError(`The project at ${projectPath} isn't indexed with homegraph (no .homegraph/ directory found ` +
+                'walking up from it), so homegraph cannot query it. Use your built-in tools (Read/Grep/Glob) ' +
+                "for that codebase instead, and don't call homegraph for it again this session. " +
+                "Indexing is the user's decision — they can run 'homegraph init' in that project to enable it.");
         }
         // If the path resolves to the default project, reuse the already-open
         // default instance rather than opening a SECOND connection to the same DB.
         // A duplicate connection serializes reads against the watcher's auto-sync
-        // writes; on the wasm backend (no WAL) that surfaces as intermittent
-        // "database is locked" on concurrent tool calls. See issue #238. Deliberately
-        // not cached under projectPath — the server owns and closes the default
-        // instance, so routing it through projectCache.closeAll() would double-close it.
+        // writes; when WAL isn't in effect (e.g. a filesystem without shared-memory
+        // support) that surfaces as intermittent
+        // "database is locked" on concurrent tool calls. See issue #238. The
+        // default instance is owned/closed by the server, so it's never cached.
         if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
-            return this.cg;
-        }
-        // Check if we already have this resolved root cached (different path, same project)
-        if (this.projectCache.has(resolvedRoot)) {
-            const cg = this.projectCache.get(resolvedRoot);
-            // Cache under original path too for faster future lookups
-            this.projectCache.set(projectPath, cg);
-            return cg;
+            return this.freshen(this.cg);
         }
-        // Open and cache under both paths
-        const cg = loadCodeGraph().openSync(resolvedRoot);
+        // Cache the open DB connection by RESOLVED ROOT only — never by the input
+        // path. One key per instance means closeAll() closes each exactly once, and
+        // a changed resolution maps to a different entry instead of a stale hit.
+        const cached = this.projectCache.get(resolvedRoot);
+        if (cached)
+            return this.freshen(cached);
+        const cg = loadHomeGraph().openSync(resolvedRoot);
         this.projectCache.set(resolvedRoot, cg);
-        if (projectPath !== resolvedRoot) {
-            this.projectCache.set(projectPath, cg);
+        return cg;
+    }
+    /**
+     * Heal a long-lived connection whose `.homegraph/` was removed and recreated
+     * at the same path (a worktree recreated, or `rm -rf .homegraph` + re-init)
+     * before handing it to a tool. Otherwise the daemon keeps serving the
+     * pre-removal snapshot from its now-unlinked file handle until restart — and
+     * because the daemon registry is keyed by path, a same-path recreate routes
+     * new clients straight back to this same stale daemon (#925). The check is one
+     * stat() and a no-op unless the inode actually changed; it never throws into a
+     * tool call.
+     */
+    freshen(cg) {
+        try {
+            if (cg.reopenIfReplaced()) {
+                process.stderr.write('[HomeGraph MCP] The index was replaced on disk (e.g. a git worktree ' +
+                    'recreated at the same path); reopened the live database in place.\n');
+            }
+        }
+        catch {
+            // Best-effort self-heal — a failed reopen must never break the tool call;
+            // the (still stale) handle keeps serving and the next call retries.
         }
         return cg;
     }
@@ -728,18 +917,29 @@ class ToolHandler {
      */
     worktreeMismatchFor(projectPath) {
         const startPath = projectPath ?? this.defaultProjectHint ?? process.cwd();
-        const cached = this.worktreeMismatchCache.get(startPath);
-        if (cached !== undefined)
-            return cached;
-        let mismatch = null;
+        // The verdict depends on BOTH the start path AND the index root it resolves
+        // to, so the cache must be keyed on the pair. Resolve the index root first
+        // (cheap — getHomeGraph re-walks to the nearest .homegraph/, no git), then
+        // key on `(startPath, indexRoot)`. The moment that root changes — most
+        // importantly when a git worktree gains its own index and the walk-up stops
+        // there instead of at the parent checkout — the key changes and the verdict
+        // is recomputed, instead of serving the stale "borrowed the parent's index"
+        // warning for the server's whole lifetime. Keying on startPath alone pinned
+        // that first verdict until restart (#926).
+        let indexRoot;
         try {
-            mismatch = (0, worktree_1.detectWorktreeIndexMismatch)(startPath, this.getCodeGraph(projectPath).getProjectRoot());
+            indexRoot = this.getHomeGraph(projectPath).getProjectRoot();
         }
         catch {
             // No resolvable project (or any other resolution error) → nothing to warn.
-            mismatch = null;
+            return null;
         }
-        this.worktreeMismatchCache.set(startPath, mismatch);
+        const cacheKey = `${startPath}\u0000${indexRoot}`;
+        const cached = this.worktreeMismatchCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const mismatch = (0, worktree_1.detectWorktreeIndexMismatch)(startPath, indexRoot);
+        this.worktreeMismatchCache.set(cacheKey, mismatch);
         return mismatch;
     }
     /**
@@ -781,12 +981,12 @@ class ToolHandler {
             return result;
         let cg;
         try {
-            cg = this.getCodeGraph(projectPath);
+            cg = this.getHomeGraph(projectPath);
         }
         catch {
             return result; // no default project — leave as is
         }
-        // Cross-project `projectPath` calls open a cached CodeGraph WITHOUT a
+        // Cross-project `projectPath` calls open a cached HomeGraph WITHOUT a
         // watcher (watchers are only attached to the default session project).
         // When the cross-project path happens to be the same project as the
         // default cg, the cached instance is the wrong one — its pendingFiles is
@@ -803,7 +1003,35 @@ class ToolHandler {
                 /* getProjectRoot may throw on a closed instance — leave cg as is */
             }
         }
-        // Defensive: some test fakes inject a partial CodeGraph stub without the
+        // Whole-index degradation (#876): once live watching has permanently
+        // stopped, getPendingFiles() is empty so the per-file banner below can't
+        // fire — but the index is now FROZEN and silently drifting stale. Surface
+        // one global notice instead, so the agent Reads for current content rather
+        // than trusting a response off a no-longer-updating index. (Cross-project
+        // calls open a watcher-less HomeGraph, so this is false there — correct: we
+        // only know degraded state for the default session project.)
+        let degraded = false;
+        try {
+            degraded = cg.isWatcherDegraded?.() ?? false;
+        }
+        catch {
+            degraded = false;
+        }
+        if (degraded) {
+            const [head, ...tail] = result.content;
+            if (!head || head.type !== 'text')
+                return result;
+            let reason = null;
+            try {
+                reason = cg.getWatcherDegradedReason?.() ?? null;
+            }
+            catch {
+                reason = null;
+            }
+            const composed = `${formatDegradedBanner(reason)}\n\n${head.text}`;
+            return { ...result, content: [{ type: 'text', text: composed }, ...tail] };
+        }
+        // Defensive: some test fakes inject a partial HomeGraph stub without the
         // newer pending-files API. Treat missing/throwing as "no pending files."
         let pending = [];
         try {
@@ -822,7 +1050,7 @@ class ToolHandler {
         const elsewhere = [];
         for (const p of pending) {
             // Substring match against the project-relative POSIX path — that's
-            // exactly the format both the watcher and every codegraph response
+            // exactly the format both the watcher and every homegraph response
             // emit, so a plain includes() is sufficient and avoids regex pitfalls.
             if (text.includes(p.path))
                 inResponse.push(p);
@@ -849,16 +1077,16 @@ class ToolHandler {
         try {
             // Block the first tool call on the engine's post-open reconcile so we
             // never serve rows for files deleted/edited while no MCP server was
-            // running. The gate is cleared after first await — subsequent calls
-            // pay nothing. Catch-up failures are logged by the engine; we
-            // proceed regardless so a transient sync error never breaks tools.
+            // running. The wait is time-boxed (#905): a huge-repo reconcile takes
+            // minutes, and blocking the first call on all of it reads as a hang, so
+            // we wait briefly then serve and let it finish in the background. The
+            // gate is cleared after first await — subsequent calls pay nothing.
+            // Catch-up failures are logged by the engine; we proceed regardless so a
+            // transient sync error never breaks tools.
             if (this.catchUpGate) {
                 const gate = this.catchUpGate;
                 this.catchUpGate = null;
-                try {
-                    await gate;
-                }
-                catch { /* engine already logged */ }
+                await this.awaitCatchUpGate(gate);
             }
             // Honor the optional tool allowlist (HOMEGRAPH_MCP_TOOLS): a trimmed
             // surface rejects ablated tools defensively even if a client cached them.
@@ -926,7 +1154,19 @@ class ToolHandler {
             return this.withStalenessNotice(withWorktree, args.projectPath);
         }
         catch (err) {
-            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
+            // Expected condition, not a malfunction: answer as a SUCCESS so the
+            // agent keeps trusting the toolset for projects that ARE indexed.
+            // (An isError here teaches session-long abandonment — see NotIndexedError.)
+            if (err instanceof NotIndexedError) {
+                return this.textResult(err.message);
+            }
+            // Security refusal: a clean error, no retry encouragement.
+            if (err instanceof PathRefusalError) {
+                return this.errorResult(err.message);
+            }
+            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+                'This is an internal homegraph error — retry the call once; if it persists, ' +
+                'continue without homegraph for this task.');
         }
     }
     /**
@@ -936,8 +1176,12 @@ class ToolHandler {
         const query = this.validateString(args.query, 'query');
         if (typeof query !== 'string')
             return query;
-        const cg = this.getCodeGraph(args.projectPath);
-        const kind = args.kind;
+        const cg = this.getHomeGraph(args.projectPath);
+        const rawKind = args.kind;
+        // The schema enum says 'type' (what agents naturally reach for); the
+        // NodeKind is 'type_alias'. Without the mapping, kind: "type" silently
+        // matched nothing — a filter value we advertise must work.
+        const kind = rawKind === 'type' ? 'type_alias' : rawKind;
         const rawLimit = Number(args.limit) || 10;
         const limit = (0, utils_1.clamp)(rawLimit, 1, 100);
         const results = cg.searchNodes(query, {
@@ -958,6 +1202,43 @@ class ToolHandler {
         const formatted = this.formatSearchResults(ranked);
         return this.textResult(this.truncateOutput(formatted));
     }
+    /**
+     * 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.
+     */
+    groupDefinitions(nodes, fileFilter) {
+        let pool = nodes;
+        let filteredOut = false;
+        if (fileFilter) {
+            const wanted = fileFilter.replace(/^\.\//, '');
+            const narrowed = pool.filter((n) => n.filePath === wanted || n.filePath.endsWith(wanted) || n.filePath.endsWith(`/${wanted}`));
+            if (narrowed.length > 0) {
+                pool = narrowed;
+            }
+            else {
+                filteredOut = true;
+            }
+        }
+        const byDef = new Map();
+        for (const n of pool) {
+            const key = `${n.filePath}|${n.qualifiedName}`;
+            const group = byDef.get(key);
+            if (group)
+                group.push(n);
+            else
+                byDef.set(key, [n]);
+        }
+        return { groups: [...byDef.values()], filteredOut };
+    }
+    /** Section heading for one distinct definition in grouped output. */
+    definitionHeading(group) {
+        const head = group[0];
+        const line = head.startLine ? `:${head.startLine}` : '';
+        return `**${head.qualifiedName}** (${head.kind}) — ${head.filePath}${line}`;
+    }
     /**
      * Handle homegraph_callers
      */
@@ -965,28 +1246,66 @@ class ToolHandler {
         const symbol = this.validateString(args.symbol, 'symbol');
         if (typeof symbol !== 'string')
             return symbol;
-        const cg = this.getCodeGraph(args.projectPath);
+        const cg = this.getHomeGraph(args.projectPath);
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const fileFilter = typeof args.file === 'string' ? args.file : undefined;
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        // Aggregate callers across all matching symbols
-        const seen = new Set();
-        const allCallers = [];
-        for (const node of allMatches.nodes) {
-            for (const c of cg.getCallers(node.id)) {
-                if (!seen.has(c.node.id)) {
-                    seen.add(c.node.id);
-                    allCallers.push(c.node);
+        const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+        const filterNote = filteredOut
+            ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+            : '';
+        const collect = (defNodes) => {
+            const seen = new Set();
+            const callers = [];
+            const labels = new Map();
+            for (const node of defNodes) {
+                for (const c of cg.getCallers(node.id)) {
+                    if (!seen.has(c.node.id)) {
+                        seen.add(c.node.id);
+                        callers.push(c.node);
+                        const label = this.edgeLabel(c.edge);
+                        if (label)
+                            labels.set(c.node.id, label);
+                    }
                 }
             }
+            return { callers, labels };
+        };
+        // Single definition (or same-file overloads): the familiar flat list.
+        if (groups.length === 1) {
+            const { callers, labels } = collect(groups[0]);
+            if (callers.length === 0) {
+                return this.textResult(`No callers found for "${symbol}"${allMatches.note}${filterNote}`);
+            }
+            // A successful `file` narrowing makes the multi-symbol aggregation note
+            // stale — suppress it.
+            const note = fileFilter && !filteredOut ? '' : allMatches.note;
+            const formatted = this.formatNodeList(callers.slice(0, limit), `Callers of ${symbol}`, labels) + note + filterNote;
+            return this.textResult(this.truncateOutput(formatted));
         }
-        if (allCallers.length === 0) {
-            return this.textResult(`No callers found for "${symbol}"${allMatches.note}`);
+        // Multiple DISTINCT definitions (#764): one section per definition so an
+        // agent never mistakes one app's callers for another's. Narrow with
+        // `file` to focus a single definition.
+        const lines = [
+            `**Callers of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)**`,
+        ];
+        for (const group of groups) {
+            const { callers, labels } = collect(group);
+            lines.push('', this.definitionHeading(group));
+            if (callers.length === 0) {
+                lines.push('- (no callers)');
+                continue;
+            }
+            for (const node of callers.slice(0, limit)) {
+                const location = node.startLine ? `:${node.startLine}` : '';
+                const label = labels.get(node.id);
+                lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
+            }
         }
-        const formatted = this.formatNodeList(allCallers.slice(0, limit), `Callers of ${symbol}`) + allMatches.note;
-        return this.textResult(this.truncateOutput(formatted));
+        return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
     }
     /**
      * Handle homegraph_callees
@@ -995,28 +1314,63 @@ class ToolHandler {
         const symbol = this.validateString(args.symbol, 'symbol');
         if (typeof symbol !== 'string')
             return symbol;
-        const cg = this.getCodeGraph(args.projectPath);
+        const cg = this.getHomeGraph(args.projectPath);
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const fileFilter = typeof args.file === 'string' ? args.file : undefined;
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        // Aggregate callees across all matching symbols
-        const seen = new Set();
-        const allCallees = [];
-        for (const node of allMatches.nodes) {
-            for (const c of cg.getCallees(node.id)) {
-                if (!seen.has(c.node.id)) {
-                    seen.add(c.node.id);
-                    allCallees.push(c.node);
+        const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+        const filterNote = filteredOut
+            ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+            : '';
+        const collect = (defNodes) => {
+            const seen = new Set();
+            const callees = [];
+            const labels = new Map();
+            for (const node of defNodes) {
+                for (const c of cg.getCallees(node.id)) {
+                    if (!seen.has(c.node.id)) {
+                        seen.add(c.node.id);
+                        callees.push(c.node);
+                        const label = this.edgeLabel(c.edge);
+                        if (label)
+                            labels.set(c.node.id, label);
+                    }
                 }
             }
+            return { callees, labels };
+        };
+        if (groups.length === 1) {
+            const { callees, labels } = collect(groups[0]);
+            if (callees.length === 0) {
+                return this.textResult(`No callees found for "${symbol}"${allMatches.note}${filterNote}`);
+            }
+            // A successful `file` narrowing makes the multi-symbol aggregation note
+            // stale — suppress it.
+            const note = fileFilter && !filteredOut ? '' : allMatches.note;
+            const formatted = this.formatNodeList(callees.slice(0, limit), `Callees of ${symbol}`, labels) + note + filterNote;
+            return this.textResult(this.truncateOutput(formatted));
         }
-        if (allCallees.length === 0) {
-            return this.textResult(`No callees found for "${symbol}"${allMatches.note}`);
+        // Multiple DISTINCT definitions (#764): per-definition sections.
+        const lines = [
+            `**Callees of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)**`,
+        ];
+        for (const group of groups) {
+            const { callees, labels } = collect(group);
+            lines.push('', this.definitionHeading(group));
+            if (callees.length === 0) {
+                lines.push('- (no callees)');
+                continue;
+            }
+            for (const node of callees.slice(0, limit)) {
+                const location = node.startLine ? `:${node.startLine}` : '';
+                const label = labels.get(node.id);
+                lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
+            }
         }
-        const formatted = this.formatNodeList(allCallees.slice(0, limit), `Callees of ${symbol}`) + allMatches.note;
-        return this.textResult(this.truncateOutput(formatted));
+        return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
     }
     /**
      * Handle homegraph_impact
@@ -1025,36 +1379,53 @@ class ToolHandler {
         const symbol = this.validateString(args.symbol, 'symbol');
         if (typeof symbol !== 'string')
             return symbol;
-        const cg = this.getCodeGraph(args.projectPath);
+        const cg = this.getHomeGraph(args.projectPath);
         const depth = (0, utils_1.clamp)(args.depth || 2, 1, 10);
+        const fileFilter = typeof args.file === 'string' ? args.file : undefined;
         const allMatches = this.findAllSymbols(cg, symbol);
         if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        // Aggregate impact across all matching symbols
-        const mergedNodes = new Map();
-        const mergedEdges = [];
-        const seenEdges = new Set();
-        for (const node of allMatches.nodes) {
-            const impact = cg.getImpactRadius(node.id, depth);
-            for (const [id, n] of impact.nodes) {
-                mergedNodes.set(id, n);
-            }
-            for (const e of impact.edges) {
-                const key = `${e.source}->${e.target}:${e.kind}`;
-                if (!seenEdges.has(key)) {
-                    seenEdges.add(key);
-                    mergedEdges.push(e);
+        const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+        const filterNote = filteredOut
+            ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+            : '';
+        const impactOf = (defNodes) => {
+            const mergedNodes = new Map();
+            const mergedEdges = [];
+            const seenEdges = new Set();
+            for (const node of defNodes) {
+                const impact = cg.getImpactRadius(node.id, depth);
+                for (const [id, n] of impact.nodes) {
+                    mergedNodes.set(id, n);
+                }
+                for (const e of impact.edges) {
+                    const key = `${e.source}->${e.target}:${e.kind}`;
+                    if (!seenEdges.has(key)) {
+                        seenEdges.add(key);
+                        mergedEdges.push(e);
+                    }
                 }
             }
-        }
-        const mergedImpact = {
-            nodes: mergedNodes,
-            edges: mergedEdges,
-            roots: allMatches.nodes.map(n => n.id),
+            return { nodes: mergedNodes, edges: mergedEdges, roots: defNodes.map((n) => n.id) };
         };
-        const formatted = this.formatImpact(symbol, mergedImpact) + allMatches.note;
-        return this.textResult(this.truncateOutput(formatted));
+        // Single definition (or same-file overloads): the familiar merged report.
+        if (groups.length === 1) {
+            const formatted = this.formatImpact(symbol, impactOf(groups[0])) + (fileFilter && !filteredOut ? "" : allMatches.note) + filterNote;
+            return this.textResult(this.truncateOutput(formatted));
+        }
+        // Multiple DISTINCT definitions (#764): a blast radius PER definition —
+        // merging unrelated same-named classes (one UserService per monorepo app)
+        // overstated impact and confused agents. Narrow with `file`.
+        const sections = [
+            `**Impact of ${symbol} — ${groups.length} distinct definitions (each with its own blast radius; narrow with \`file\`)**`,
+        ];
+        for (const group of groups) {
+            const head = group[0];
+            const line = head.startLine ? `:${head.startLine}` : '';
+            sections.push('', this.formatImpact(`${head.qualifiedName} (${head.filePath}${line})`, impactOf(group)));
+        }
+        return this.textResult(this.truncateOutput(sections.join('\n') + filterNote));
     }
     /**
      * Describe a synthesized (dynamic-dispatch) edge for human output: how the
@@ -1123,6 +1494,29 @@ class ToolHandler {
                 registeredAt,
             };
         }
+        if (m?.synthesizedBy === 'fn-pointer-dispatch') {
+            const via = m.via ? `\`${String(m.via)}\`` : 'a function pointer';
+            return {
+                label: `function-pointer dispatch via ${via} (dynamic dispatch)`,
+                compact: `dynamic: fn-pointer ${m.via ? String(m.via) : ''}${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'goframe-route') {
+            const route = m.route ? `\`${String(m.route)}\`` : 'a route';
+            return {
+                label: `GoFrame route ${route} — reflective Bind → controller method (dynamic dispatch)`,
+                compact: `dynamic: GoFrame route ${m.route ? String(m.route) : ''}${at}`,
+                registeredAt,
+            };
+        }
+        // Generic fallback for any other synthesizer (redux-thunk, gin-middleware-chain,
+        // flutter-build, …): a synthesized hop must never read as a bare static `calls`.
+        // It's a dynamic-dispatch bridge — label it as one and keep its wiring site.
+        if (typeof m?.synthesizedBy === 'string') {
+            const kind = m.synthesizedBy.replace(/-/g, ' ');
+            return { label: `${kind} (dynamic dispatch)`, compact: `dynamic: ${kind}${at}`, registeredAt };
+        }
         return null;
     }
     /**
@@ -1140,14 +1534,17 @@ class ToolHandler {
      * dropping unrelated `OmsOrderService::list`.
      */
     buildFlowFromNamedSymbols(cg, query) {
-        const EMPTY = { text: '', pathNodeIds: new Set(), namedNodeIds: new Set(), uniqueNamedNodeIds: new Set() };
+        // spineCallSites: for each spine node, the line where it CALLS the next hop —
+        // lets the source assembler window an oversize spine method (e.g. n8n's 962-line
+        // processRunExecutionData) to the call site instead of dumping the whole body.
+        const EMPTY = { text: '', pathNodeIds: new Set(), namedNodeIds: new Set(), uniqueNamedNodeIds: new Set(), spineCallSites: new Map() };
         try {
             const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
             // Strip only a REAL file extension (Create.cs → Create); KEEP qualified
             // names (Class.method / Class::method) — the agent's most precise input,
             // resolved exactly by findAllSymbols. (The old strip mangled Class.method
             // into Class, throwing the method away.)
-            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
             const tokens = [...new Set(query.split(/[\s,()[\]]+/)
                     .map((t) => t.replace(FILE_EXT, '').trim())
                     .filter((t) => t.length >= 3 && /^[A-Za-z_$][\w$]*(?:(?:::|\.)[\w$]+)*$/.test(t)))].slice(0, 16);
@@ -1168,8 +1565,28 @@ class ToolHandler {
             // (`as_sql`, 110 defs across every Expression/Compiler subclass) is NOT here,
             // so naming it doesn't keep every backend variant full and flood the budget.
             const uniqueNamedNodeIds = new Set();
+            // token → resolved node ids: drives the token-coverage check that gates
+            // the dynamic-boundary scan (a token is covered when ANY of its nodes
+            // lands on the main chain — overloads off the chain don't count against).
+            const tokenNodes = new Map();
+            // token → its full same-name callable family (before the container filter).
+            // A LARGE family that fails to connect on the chain is a polymorphic
+            // interface/registry dispatch — surfaced by buildPolymorphicBoundaries below.
+            const tokenFamily = new Map();
+            // Non-callable endpoints (CONSTANT/VARIABLE/FIELD) connected by a SYNTHESIZED
+            // edge. RTK thunks are `const X = createAsyncThunk(...)`, so a thunk→thunk hop
+            // is constant→constant — the CALLABLE-only `named` set can't hold it, and
+            // without this the hop is invisible to the Flow path at every tier (the
+            // Relationships section catches it only on repos ≥500 files). Kept SEPARATE
+            // from `named` (which drives the call-chain + source sizing, callable-only);
+            // fed only to the dynamic-dispatch-links scan below.
+            const dynNamed = new Map();
+            const DYN_KINDS = new Set(['constant', 'variable', 'field', 'property']);
+            const hasHeuristicEdge = (id) => [...cg.getCallers(id), ...cg.getCallees(id)].some(({ edge }) => edge.provenance === 'heuristic');
             for (const t of tokens) {
-                const cands = this.findAllSymbols(cg, t).nodes.filter((n) => CALLABLE.has(n.kind));
+                const hits = this.findAllSymbols(cg, t).nodes;
+                const cands = hits.filter((n) => CALLABLE.has(n.kind));
+                tokenFamily.set(t, cands);
                 // A qualified or otherwise-specific name (<=3 hits) keeps all; an
                 // ambiguous simple name keeps only candidates whose container is named.
                 const specific = cands.length <= 3;
@@ -1180,16 +1597,75 @@ class ToolHandler {
                         const container = segs.length >= 2 ? segs[segs.length - 2] : '';
                         return !!container && segPool.has(container);
                     });
-                for (const n of pick.slice(0, 6)) {
+                const kept = pick.slice(0, 6);
+                tokenNodes.set(t, kept.map((n) => n.id));
+                for (const n of kept) {
                     named.set(n.id, n);
                     if (specific)
                         uniqueNamedNodeIds.add(n.id);
                 }
+                // Same token, non-callable synth endpoints (capped, precision-gated on an
+                // actual heuristic edge so plain config constants never qualify).
+                if (dynNamed.size < 12) {
+                    for (const n of hits) {
+                        if (CALLABLE.has(n.kind) || !DYN_KINDS.has(n.kind) || dynNamed.has(n.id))
+                            continue;
+                        if (hasHeuristicEdge(n.id))
+                            dynNamed.set(n.id, n);
+                        if (dynNamed.size >= 12)
+                            break;
+                    }
+                }
                 if (named.size > 40)
                     break;
             }
-            if (named.size < 2)
-                return EMPTY;
+            // Surface synthesized (heuristic) edges incident to a named symbol — INCLUDING
+            // the non-callable CONSTANT endpoints in `dynNamed`. `skipInChain` drops a hop
+            // already shown in the rendered main chain (a 2-node chain renders nothing, so a
+            // direct named→named synth hop still surfaces — #687).
+            const collectSynthLinks = (skipInChain) => {
+                const synthLines = [];
+                const synthSeen = new Set();
+                for (const n of [...named.values(), ...dynNamed.values()]) {
+                    if (synthLines.length >= 6)
+                        break;
+                    for (const { node: other, edge } of [...cg.getCallers(n.id), ...cg.getCallees(n.id)]) {
+                        if (synthLines.length >= 6)
+                            break;
+                        if (edge.provenance !== 'heuristic' || other.id === n.id)
+                            continue;
+                        if (skipInChain && skipInChain(edge))
+                            continue;
+                        const src = edge.source === n.id ? n : other;
+                        const tgt = edge.source === n.id ? other : n;
+                        const key = `${src.name}>${tgt.name}`;
+                        if (synthSeen.has(key))
+                            continue;
+                        synthSeen.add(key);
+                        const note = this.synthEdgeNote(edge);
+                        synthLines.push(`- ${src.name} → ${tgt.name}   [${note ? note.compact : edge.kind}]`);
+                    }
+                }
+                return synthLines;
+            };
+            if (named.size < 2) {
+                // <2 CALLABLES resolved. Two recoveries before giving up: (1) synthesized
+                // edges among named CONSTANT/VARIABLE endpoints — RTK thunk→thunk is
+                // constant→constant, so `named` can be empty while `dynNamed` holds the
+                // whole chain; (2) the one resolved callable's body may hold the
+                // dynamic-dispatch site that EXPLAINS a half-connected flow.
+                const synthLines = collectSynthLinks(null);
+                const boundaries = named.size === 0 ? '' : (this.buildDynamicBoundaries(cg, [...named.values()], named) || '');
+                if (synthLines.length === 0 && !boundaries)
+                    return EMPTY;
+                const out = [];
+                if (synthLines.length)
+                    out.push('**Dynamic-dispatch links among your symbols**', '(synthesized — the indirect hops grep/Read would reconstruct; the `@file:line` is the wiring site)', '', ...synthLines, '');
+                if (boundaries)
+                    out.push(boundaries);
+                out.push('> Full source for these symbols is below.\n');
+                return { text: out.join('\n'), pathNodeIds: new Set(), namedNodeIds: new Set([...named.keys(), ...dynNamed.keys()]), uniqueNamedNodeIds, spineCallSites: new Map() };
+            }
             const MAX_HOPS = 7;
             let best = null;
             // BFS the full call graph (incl. synth edges) from each named seed, but
@@ -1237,41 +1713,90 @@ class ToolHandler {
             }
             const hasMain = !!best && best.length >= 3;
             const pathIds = new Set((best ?? []).map((s) => s.node.id));
-            // Supplementary: dynamic-dispatch (synthesized) edges incident to a NAMED
-            // symbol — the indirect hops an agent would otherwise grep/Read to
-            // reconstruct ("where do the appended `validators` actually run?"). The
-            // synth edge IS that answer, so surface it even when the OTHER end wasn't
-            // named (e.g. the agent names `validate` but not the `didCompleteTask`
-            // that drains the collection). On-topic by construction: only heuristic
-            // edges touching a symbol the agent named; skipped when the hop already
-            // shows in the main chain.
-            const synthLines = [];
-            const synthSeen = new Set();
-            for (const n of named.values()) {
-                if (synthLines.length >= 6)
-                    break;
-                for (const { node: other, edge } of [...cg.getCallers(n.id), ...cg.getCallees(n.id)]) {
-                    if (synthLines.length >= 6)
-                        break;
-                    if (edge.provenance !== 'heuristic' || other.id === n.id)
-                        continue;
-                    if (pathIds.has(edge.source) && pathIds.has(edge.target))
-                        continue; // already in the main chain
-                    const src = edge.source === n.id ? n : other;
-                    const tgt = edge.source === n.id ? other : n;
-                    const key = `${src.name}>${tgt.name}`;
-                    if (synthSeen.has(key))
+            // Where each spine node calls the NEXT hop (best[i+1].edge is the edge from
+            // best[i] → best[i+1]; its line is the call site inside best[i]'s body). Lets
+            // the assembler window an oversize spine method to the call instead of dumping it.
+            const spineCallSites = new Map();
+            if (best)
+                for (let i = 0; i < best.length - 1; i++) {
+                    const ln = best[i + 1]?.edge?.line;
+                    if (ln && ln > 0 && !spineCallSites.has(best[i].node.id))
+                        spineCallSites.set(best[i].node.id, ln);
+                }
+            // Dynamic-boundary scan (#687) — fires ONLY when the flow the agent
+            // asked about did not fully connect: some token resolved to nodes but
+            // none of them sit on the main chain (or there is no chain at all). A
+            // healthy flow skips this entirely. Scan order: the chain's dead end
+            // first (where the partial flow stops), then the disconnected symbols,
+            // agent-specific (unique-named) ones first.
+            let boundaryText = '';
+            {
+                const uncovered = [];
+                if (!hasMain) {
+                    // No rendered chain — but a 2-node chain still CONNECTS its two
+                    // endpoints (e.g. via one synthesized hop, surfaced below as a
+                    // dynamic-dispatch link). Only nodes off that short chain are
+                    // unexplained breaks worth scanning.
+                    for (const n of named.values())
+                        if (!pathIds.has(n.id))
+                            uncovered.push(n);
+                }
+                else {
+                    for (const ids of tokenNodes.values()) {
+                        if (ids.length === 0 || ids.some((id) => pathIds.has(id)))
+                            continue;
+                        for (const id of ids) {
+                            const n = named.get(id);
+                            if (n)
+                                uncovered.push(n);
+                        }
+                    }
+                }
+                if (uncovered.length > 0) {
+                    const scanList = [];
+                    if (hasMain)
+                        scanList.push(best[best.length - 1].node);
+                    scanList.push(...uncovered.sort((a, b) => (uniqueNamedNodeIds.has(b.id) ? 1 : 0) - (uniqueNamedNodeIds.has(a.id) ? 1 : 0)));
+                    boundaryText = this.buildDynamicBoundaries(cg, scanList, named);
+                }
+            }
+            // Interface/registry-dispatch announcement (extends #687 to GRAPH-visible
+            // polymorphism). A method the agent NAMED that resolves to a large same-name
+            // family AND did not land on the main chain is almost always a runtime
+            // dispatch (plugin/strategy/handler interface): the concrete target is chosen
+            // at runtime from N implementations, so no single static edge is the answer.
+            // The body-scan above can't see this — `nodeType.execute()` is textually an
+            // ordinary call; the polymorphism lives in the graph (implements edges), so
+            // detect it there. Fires ONLY for an uncovered named token; a connected flow
+            // stays silent.
+            let polyText = '';
+            {
+                const POLY_MIN_FAMILY = 8; // smaller families are overload sets, not dispatch
+                const polyCands = [];
+                for (const [t, fam] of tokenFamily) {
+                    if (fam.length < POLY_MIN_FAMILY)
                         continue;
-                    synthSeen.add(key);
-                    const note = this.synthEdgeNote(edge);
-                    synthLines.push(`- ${src.name} → ${tgt.name}   [${note ? note.compact : edge.kind}]`);
+                    const ids = tokenNodes.get(t) || [];
+                    if (ids.some((id) => pathIds.has(id)))
+                        continue; // covered by the flow — silent
+                    polyCands.push({ token: t, family: fam });
                 }
+                if (polyCands.length)
+                    polyText = this.buildPolymorphicBoundaries(cg, polyCands, named);
             }
-            if (!hasMain && synthLines.length === 0)
+            // Supplementary: dynamic-dispatch (synthesized) edges incident to a named
+            // symbol (incl. the non-callable CONSTANT endpoints in `dynNamed`) — the
+            // indirect hops an agent would otherwise grep/Read to reconstruct ("where do
+            // the appended `validators` actually run?"). Surfaced even when the OTHER end
+            // wasn't named. The skip drops a hop already in the rendered main chain; a
+            // 2-node chain renders nothing (hasMain false) so a direct named→named synth
+            // hop still surfaces — too short for Flow, but #687-visible here.
+            const synthLines = collectSynthLinks(hasMain ? (e) => pathIds.has(e.source) && pathIds.has(e.target) : null);
+            if (!hasMain && synthLines.length === 0 && !boundaryText && !polyText)
                 return EMPTY;
             const out = [];
             if (hasMain) {
-                out.push('## Flow (call path among the symbols you queried)', '');
+                out.push('**Flow (call path among the symbols you queried)**', '');
                 for (let i = 0; i < best.length; i++) {
                     const step = best[i];
                     if (step.edge) {
@@ -1283,20 +1808,288 @@ class ToolHandler {
                 out.push('');
             }
             if (synthLines.length) {
-                out.push('## Dynamic-dispatch links among your symbols', '(synthesized — the indirect hops grep/Read would reconstruct; the `@file:line` is the wiring site)', '', ...synthLines, '');
+                out.push('**Dynamic-dispatch links among your symbols**', '(synthesized — the indirect hops grep/Read would reconstruct; the `@file:line` is the wiring site)', '', ...synthLines, '');
             }
+            if (boundaryText)
+                out.push(boundaryText);
+            if (polyText)
+                out.push(polyText);
             out.push('> Full source for these symbols is below — the call flow among them, followed by their bodies.', '');
             // namedNodeIds = every callable the agent explicitly named (a superset of
             // the spine). A file holding one is something the agent asked to SEE, so it
             // must keep full source even if it's an off-spine polymorphic sibling — the
             // agent named `getResponseWithInterceptorChain` / `SQLCompiler.execute_sql`
             // as the mechanism, not as an interchangeable leaf. See the skeleton gate.
-            return { text: out.join('\n'), pathNodeIds: pathIds, namedNodeIds: new Set(named.keys()), uniqueNamedNodeIds };
+            return { text: out.join('\n'), pathNodeIds: pathIds, namedNodeIds: new Set([...named.keys(), ...dynNamed.keys()]), uniqueNamedNodeIds, spineCallSites };
         }
         catch {
             return EMPTY;
         }
     }
+    /**
+     * 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.
+     */
+    buildDynamicBoundaries(cg, scanList, named) {
+        const MAX_NOTES = 4; // boundary bullets per explore
+        const MAX_SCAN = 8; // bodies scanned
+        const MAX_TOTAL_CHARS = 200_000;
+        let projectRoot;
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch {
+            return '';
+        }
+        const notes = [];
+        const seenNode = new Set();
+        const seenSite = new Set();
+        let scanned = 0, charsScanned = 0;
+        for (const node of scanList) {
+            if (notes.length >= MAX_NOTES || scanned >= MAX_SCAN || charsScanned > MAX_TOTAL_CHARS)
+                break;
+            if (seenNode.has(node.id) || !node.startLine || !node.endLine)
+                continue;
+            seenNode.add(node.id);
+            const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, node.filePath);
+            if (!absPath || !(0, fs_1.existsSync)(absPath))
+                continue;
+            let content;
+            try {
+                content = (0, fs_1.readFileSync)(absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const body = content.split('\n').slice(node.startLine - 1, node.endLine).join('\n');
+            scanned++;
+            charsScanned += body.length;
+            for (const m of (0, dynamic_boundaries_1.scanDynamicDispatch)(body, node.language || '', node.startLine)) {
+                if (notes.length >= MAX_NOTES)
+                    break;
+                const siteKey = `${node.filePath}:${m.line}:${m.form}`;
+                if (seenSite.has(siteKey))
+                    continue;
+                seenSite.add(siteKey);
+                const more = m.moreSites ? ` (+${m.moreSites} more such site${m.moreSites > 1 ? 's' : ''} in this body)` : '';
+                notes.push(`- \`${node.name}\` (${node.filePath}:${m.line}) — ${m.label}: \`${m.snippet}\`${more}`);
+                if (m.key) {
+                    const cand = this.boundaryCandidates(cg, m.key, !!m.keyIsType, named, node.id);
+                    if (cand)
+                        notes.push(`  ${cand}`);
+                }
+            }
+        }
+        if (notes.length === 0)
+            return '';
+        return [
+            '**Dynamic boundaries (the static path ends at runtime dispatch)**',
+            '',
+            ...notes,
+            '',
+            '> These sites choose their call target at runtime (registry / bus / reflection) — the site shown IS where the flow continues. To follow it, run homegraph_explore or homegraph_node on a candidate; source for the sites above is included below.',
+            '',
+        ].join('\n');
+    }
+    /**
+     * Interface/registry-dispatch announcement — #687 extended to GRAPH-visible
+     * polymorphism (the body-scan can't see it: `nodeType.execute()` is textually
+     * an ordinary call; the polymorphism lives in the `implements`/`extends` edges).
+     *
+     * A method the agent named that resolves to a large same-name family whose
+     * definers overwhelmingly implement/extend ONE supertype is a runtime dispatch:
+     * the concrete target is chosen at runtime from N implementations, so no single
+     * static edge is "the answer" — the implementations ARE the continuations. We
+     * announce the supertype, its TRUE implementer count, and a few concrete targets,
+     * then steer to homegraph_explore. Graph-only, query-time, zero mutation; the
+     * caller fires it ONLY for an UNCOVERED named token, so a connected flow is silent.
+     *
+     * Robust to FTS sampling bias: the same-name family is a capped FTS sample that
+     * over-represents whatever FTS ranks first (n8n: DB `TableOperation.execute`
+     * outnumbered `INodeType.execute` in the sample 7:6 even though INodeType has
+     * 611 implementers vs a handful). So candidate supertypes are ranked by their
+     * TRUE graph-wide implementer count, NOT their frequency in the sample.
+     */
+    buildPolymorphicBoundaries(cg, candidates, named) {
+        const CLASSY = new Set(['class', 'struct', 'interface', 'trait', 'protocol', 'abstract']);
+        const MIN_IMPL = 8; // a supertype needs >= this many implementers to count as "polymorphic"
+        const MIN_SUPPORT = 2; // >= this many sampled definers must share the supertype (ties it to the token)
+        const SAMPLE = 40; // family members inspected per token
+        const MAX_NOTES = 3;
+        const rel = (p) => p.replace(/\\/g, '/');
+        const containerOf = (m) => {
+            try {
+                const ce = cg.getIncomingEdges(m.id).find((e) => e.kind === 'contains');
+                return ce ? cg.getNode(ce.source) : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const notes = [];
+        const seenSuper = new Set();
+        for (const { token, family } of candidates) {
+            if (notes.length >= MAX_NOTES)
+                break;
+            // supertype id → how many sampled definers share it + a few example definers
+            const supers = new Map();
+            for (const m of family.slice(0, SAMPLE)) {
+                const container = containerOf(m);
+                if (!container || !CLASSY.has(container.kind))
+                    continue;
+                let sups = [];
+                try {
+                    sups = cg.getOutgoingEdges(container.id)
+                        .filter((e) => e.kind === 'implements' || e.kind === 'extends')
+                        .map((e) => { try {
+                        return cg.getNode(e.target);
+                    }
+                    catch {
+                        return null;
+                    } })
+                        .filter((n) => !!n && CLASSY.has(n.kind) && (n.name?.length || 0) >= 3);
+                }
+                catch { /* no supertypes — free function or unresolved */ }
+                for (const s of sups) {
+                    const e = supers.get(s.id) || { node: s, count: 0, targets: [] };
+                    e.count++;
+                    if (e.targets.length < 6)
+                        e.targets.push(m);
+                    supers.set(s.id, e);
+                }
+            }
+            // Pick the supertype with the most TRUE implementers (graph-wide), among
+            // those genuinely shared by the token's definers.
+            let best = null;
+            for (const { node, count, targets } of supers.values()) {
+                if (count < MIN_SUPPORT)
+                    continue;
+                let impl = 0;
+                try {
+                    impl = cg.getIncomingEdges(node.id).filter((e) => e.kind === 'implements' || e.kind === 'extends').length;
+                }
+                catch { /* leave 0 — gated out below */ }
+                if (impl < MIN_IMPL)
+                    continue;
+                if (!best || impl > best.impl)
+                    best = { node, impl, targets };
+            }
+            if (!best || seenSuper.has(best.node.id))
+                continue;
+            seenSuper.add(best.node.id);
+            const namedNames = new Set([...named.values()].map((n) => n.name));
+            const eg = best.targets.slice(0, 4).map((m) => {
+                const cont = containerOf(m);
+                const disp = cont ? `${cont.name}.${m.name}` : (m.qualifiedName || m.name);
+                const mark = cont && namedNames.has(cont.name) ? ' ← you named this' : '';
+                return `\`${disp}\` (${rel(m.filePath)}:${m.startLine})${mark}`;
+            });
+            const more = best.impl > eg.length ? ` +${best.impl - eg.length} more` : '';
+            notes.push(`- \`${token}\` → runtime dispatch to **${best.impl}** types implementing \`${best.node.name}\` — the static path ends here, the target is chosen at runtime. e.g. ${eg.join(', ')}${more}`);
+        }
+        if (notes.length === 0)
+            return '';
+        return [
+            '**Interface dispatch (a named method has many implementations)**',
+            '',
+            ...notes,
+            '',
+            '> The method above is dispatched at runtime to one of the listed implementations (a registry / plugin / strategy interface) — there is no single static caller→callee edge; the implementations ARE the continuations. To follow one, run homegraph_explore on a listed target.',
+            '',
+        ].join('\n');
+    }
+    /**
+     * 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.
+     */
+    boundaryCandidates(cg, key, keyIsType, named, selfId) {
+        const CALLABLE = new Set(['method', 'function', 'component', 'constructor', 'class']);
+        const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const keyNorm = norm(key);
+        if (keyNorm.length < 3)
+            return '';
+        const cands = new Map();
+        const consider = (n) => {
+            if (!n || n.id === selfId || !CALLABLE.has(n.kind) || cands.has(n.id))
+                return;
+            const nameNorm = norm(n.name || '');
+            if (nameNorm.length < 3)
+                return;
+            if (!nameNorm.includes(keyNorm) && !keyNorm.includes(nameNorm))
+                return;
+            cands.set(n.id, n);
+        };
+        const cap = key.charAt(0).toUpperCase() + key.slice(1);
+        const probes = keyIsType
+            ? [`${key}Handler`, key]
+            : [key, `on${cap}`, `handle${cap}`, `${key}Handler`, `handle_${key}`];
+        for (const p of probes) {
+            try {
+                for (const n of cg.getNodesByName(p))
+                    consider(n);
+            }
+            catch { /* exact probe miss is fine */ }
+        }
+        let raw = 0;
+        try {
+            const results = cg.searchNodes(key, { limit: 12 });
+            raw = results.length;
+            for (const r of results)
+                consider(r.node);
+        }
+        catch { /* FTS syntax edge — exact probes already ran */ }
+        if (cands.size === 0) {
+            return raw >= 12 && key.length < 5 ? `key \`${key}\` is too generic to shortlist (${raw}+ matches)` : '';
+        }
+        // A constructor candidate duplicates its class: extractors emit ctors as
+        // METHOD nodes named like the class (C#/Java `Foo::Foo`) — keep the class.
+        const all = [...cands.values()];
+        const classKey = new Set(all.filter((n) => n.kind === 'class').map((n) => `${n.name}|${n.filePath}`));
+        const namedNames = new Set([...named.values()].map((n) => n.name));
+        const isNamed = (n) => named.has(n.id) || namedNames.has(n.name); // the flow's named set holds callables only — transfer the mark to the class
+        const list = all
+            .filter((n) => !(n.kind !== 'class' && classKey.has(`${n.name}|${n.filePath}`)))
+            .sort((a, b) => (isNamed(b) ? 1 : 0) - (isNamed(a) ? 1 : 0))
+            .slice(0, 4)
+            .map((n) => {
+            // Typed-bus convention: the runtime target is the candidate class's
+            // Handle/Execute/Consume method — name the exact node, not just the class.
+            let display = n.qualifiedName || n.name;
+            let at = `${n.filePath}:${n.startLine}`;
+            if (keyIsType && n.kind === 'class') {
+                try {
+                    const HANDLER_METHODS = /^(handle|handleAsync|execute|executeAsync|consume|consumeAsync|run|__invoke)$/i;
+                    const method = cg.getOutgoingEdges(n.id)
+                        .filter((e) => e.kind === 'contains')
+                        .map((e) => { try {
+                        return cg.getNode(e.target);
+                    }
+                    catch {
+                        return null;
+                    } })
+                        .find((c) => !!c && c.kind === 'method' && HANDLER_METHODS.test(c.name));
+                    if (method) {
+                        display = `${n.name}.${method.name}`;
+                        at = `${method.filePath}:${method.startLine}`;
+                    }
+                }
+                catch { /* class without resolvable members — show the class itself */ }
+            }
+            return `\`${display}\` (${at})${isNamed(n) ? ' ← you named this' : ''}`;
+        });
+        return `candidates for key \`${key}\`: ${list.join(', ')}`;
+    }
     /**
      * Compact "blast radius" for the entry symbols of an explore result: who
      * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
@@ -1350,7 +2143,7 @@ class ToolHandler {
         if (entries.length === 0)
             return '';
         return [
-            '### Blast radius — what depends on these (update/verify before editing)',
+            '**Blast radius — what depends on these (update/verify before editing)**',
             '',
             ...entries,
             '',
@@ -1361,7 +2154,7 @@ class ToolHandler {
      * 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
+     * homegraph'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`
@@ -1453,7 +2246,7 @@ class ToolHandler {
         const query = this.validateString(args.query, 'query');
         if (typeof query !== 'string')
             return query;
-        const cg = this.getCodeGraph(args.projectPath);
+        const cg = this.getHomeGraph(args.projectPath);
         const projectRoot = cg.getProjectRoot();
         // Resolve adaptive output budget from project size. Falls back to the
         // largest-tier defaults if stats aren't available, which preserves
@@ -1527,7 +2320,7 @@ class ToolHandler {
         // agent explicitly named is in the subgraph and its file is scored.
         const namedSeedIds = new Set();
         {
-            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
             const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
             const isTestPath = (p) => /(^|\/)(tests?|specs?|__tests__|testdata|mocks?|fixtures?)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
             const bodyLines = (n) => Math.max(0, (n.endLine ?? n.startLine) - n.startLine);
@@ -1538,8 +2331,12 @@ class ToolHandler {
             // agent writes "DataRequest task validate", the `task`/`validate` it wants
             // are DataRequest's, NOT the same-named overloads in Validation.swift /
             // Concurrency.swift / the abstract base. Used below to bias overloaded
-            // names toward the file/class the query also names.
-            const typeTokens = tokens.filter((o) => /^[A-Z][A-Za-z0-9]{3,}/.test(o));
+            // names toward the file/class the query also names. EXCLUDE the project
+            // name (a PascalCase token a user naturally includes) — it names the whole
+            // repo, so biasing toward it just pulls overloads to whichever stack
+            // embeds it, re-burying the rest (#720).
+            const projectNameTokens = cg.getProjectNameTokens();
+            const typeTokens = tokens.filter((o) => /^[A-Z][A-Za-z0-9]{3,}/.test(o) && !projectNameTokens.has((0, query_utils_1.normalizeNameToken)(o)));
             const inNamedContext = (n) => typeTokens.some((ct) => {
                 const lc = ct.toLowerCase();
                 return n.filePath.toLowerCase().includes(lc) || n.qualifiedName.toLowerCase().includes(lc);
@@ -1596,6 +2393,12 @@ class ToolHandler {
             // Skip import/export nodes — they add noise without information
             if (node.kind === 'import' || node.kind === 'export')
                 continue;
+            // SECURITY (#383): never render the on-disk source of a config-leaf
+            // (Spring application.{yml,properties} key) — its line is `key = <secret>`,
+            // so whole-file/cluster rendering here would push secrets into context
+            // unbidden. The key still appears in the flow/symbol listing above.
+            if ((0, utils_1.isConfigLeafNode)(node))
+                continue;
             const group = fileGroups.get(node.filePath) || { nodes: [], score: 0 };
             group.nodes.push(node);
             // Score: a NAMED-SEED node (a symbol the agent named that FTS missed, now
@@ -1740,6 +2543,25 @@ class ToolHandler {
             if (n)
                 namedSeedFiles.add(n.filePath);
         }
+        // Multi-term corroboration tier: a file that is BOTH (a) an entry/central file
+        // (a search root, named seed, or graph-central hub — i.e. structurally part of
+        // the answer) AND (b) matched by ≥2 DISTINCT query terms must not be buried by
+        // graph-centrality mass that accrued to a denser-but-off-topic cluster. In a
+        // cross-layer monorepo (an API server alongside a much larger, internally dense
+        // frontend that mirrors the same domain words) the Random-Walk-with-Restart mass
+        // — seeded from text matches that skew to the bigger layer — floats hits=0
+        // frontend files above the hits=2/3 backend service that IS the answer (its many
+        // callers don't help: it's call-isolated from the frontend seed cluster). The
+        // entry/central GUARD keeps this safe: an INCIDENTAL multi-term file that is
+        // neither entry nor central (a type/util file that matches "element"+x but isn't
+        // the flow) is NOT promoted, so it can't displace the graph-central answer file
+        // (hits=1) the way a blunt hits-only tier would. Single-layer repos with one
+        // cluster are unaffected (no competing mass). Set HOMEGRAPH_RANK_NO_MULTITERM=1
+        // to disable.
+        const MULTITERM_OFF = process.env.HOMEGRAPH_RANK_NO_MULTITERM === '1';
+        const isCorroborated = (fp) => !MULTITERM_OFF &&
+            (fileTermHits.get(fp) ?? 0) >= 2 &&
+            (entryFiles.has(fp) || centralFiles.has(fp));
         const sortedFiles = relevantFiles.sort((a, b) => {
             const aPath = a[0].toLowerCase();
             const bPath = b[0].toLowerCase();
@@ -1748,6 +2570,11 @@ class ToolHandler {
             const bNamed = namedSeedFiles.has(b[0]) ? 1 : 0;
             if (aNamed !== bNamed)
                 return bNamed - aNamed;
+            // Corroborated (entry/central + ≥2 terms) tier, above the graph signal.
+            const aCorr = isCorroborated(a[0]) ? 1 : 0;
+            const bCorr = isCorroborated(b[0]) ? 1 : 0;
+            if (aCorr !== bCorr)
+                return bCorr - aCorr;
             // Graph connectivity is the next key (small epsilon so near-ties fall
             // through to the text signal rather than coin-flipping on float noise).
             const aG = fileGraphScore.get(a[0]) ?? 0;
@@ -1778,7 +2605,7 @@ class ToolHandler {
         });
         // Step 3: Build relationship map
         const lines = [
-            `## Exploration: ${query}`,
+            `**Exploration: ${query}**`,
             '',
             `Found ${subgraph.nodes.size} symbols across ${fileGroups.size} files.`,
             '',
@@ -1793,7 +2620,7 @@ class ToolHandler {
         const significantEdges = subgraph.edges.filter(e => e.kind !== 'contains' // skip contains — it's implied by file grouping
         );
         if (budget.includeRelationships && significantEdges.length > 0) {
-            lines.push('### Relationships');
+            lines.push('**Relationships**');
             lines.push('');
             // Group edges by kind for readability
             const byKind = new Map();
@@ -1878,7 +2705,7 @@ class ToolHandler {
             }
             return false;
         };
-        lines.push('### Source Code');
+        lines.push('**Source Code**');
         lines.push('');
         lines.push('> The code below is the **verbatim, current on-disk source** of these files — re-read from disk on this call and line-numbered, byte-for-byte identical to what the Read tool returns. It is NOT a summary, outline, or stale cache. Treat each block as a Read you have already performed: do not Read a file shown here.');
         lines.push('');
@@ -2033,7 +2860,7 @@ class ToolHandler {
                     const tag = bodyIds.size > 0
                         ? 'focused (the methods you named in full, the rest as signatures — homegraph_explore a signature by name for its body; do NOT Read)'
                         : 'skeleton (signatures only — homegraph_explore a name for its full body; do NOT Read)';
-                    lines.push(`#### ${filePath} — ${names} · ${tag}`, '', '```' + lang, skel.join('\n'), '```', '');
+                    lines.push(fileSectionHeader(filePath, `${names} · ${tag}`), '', '```' + lang, skel.join('\n'), '```', '');
                     totalChars += skel.join('\n').length + 120;
                     filesIncluded++;
                     continue;
@@ -2071,7 +2898,7 @@ class ToolHandler {
                         .map(n => `${n.name}(${n.kind})`))];
                 const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader);
                 const omitted = uniqSymbols.length - headerNames.length;
-                const wholeHeader = `#### ${filePath} — ${omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')}`;
+                const wholeHeader = fileSectionHeader(filePath, omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', '));
                 if (!fileNecessary && totalChars + wholeSection.length + 200 > budget.maxOutputChars) {
                     // Don't slice a whole file mid-method: an incidental file that doesn't
                     // fit is skipped; a necessary one (below) renders in full. Half a file
@@ -2135,7 +2962,12 @@ class ToolHandler {
                     importance = 6; // bridging caller/callee of an entry
                 else if (connectedToEntry.has(n.id))
                     importance = 3;
-                return { start: n.startLine, end: n.endLine, name: n.name, kind: n.kind, importance };
+                // On the rendered call-path spine? That IS the flow answer — its cluster
+                // must never be dropped by the per-file budget (n8n's huge workflow-execute.ts:
+                // processRunExecutionData, the named flow ENTRY at L1562, is a large
+                // low-density method that lost the budget to denser blocks and got cut, so
+                // the agent Read it back — the very thing explore exists to prevent).
+                return { start: n.startLine, end: n.endLine, name: n.name, kind: n.kind, importance, spine: flow.pathNodeIds.has(n.id), spineCallLine: flow.spineCallSites.get(n.id) };
             });
             // Add edge source locations in this file — captures template references
             // (component usages, event handlers) that aren't nodes themselves.
@@ -2154,7 +2986,7 @@ class ToolHandler {
                     // Look up target name from subgraph first, fall back to edge kind
                     const targetNode = subgraph.nodes.get(edge.target);
                     const targetName = targetNode?.name ?? edge.kind;
-                    ranges.push({ start: edge.line, end: edge.line, name: targetName, kind: edge.kind, importance: 2 });
+                    ranges.push({ start: edge.line, end: edge.line, name: targetName, kind: edge.kind, importance: 2, spine: false });
                 }
             }
             ranges.sort((a, b) => a.start - b.start);
@@ -2168,6 +3000,8 @@ class ToolHandler {
                 symbols: [`${ranges[0].name}(${ranges[0].kind})`],
                 score: ranges[0].importance,
                 maxImportance: ranges[0].importance,
+                hasSpine: ranges[0].spine,
+                spineCallLine: ranges[0].spineCallLine,
             };
             for (let i = 1; i < ranges.length; i++) {
                 const r = ranges[i];
@@ -2176,6 +3010,8 @@ class ToolHandler {
                     current.symbols.push(`${r.name}(${r.kind})`);
                     current.score += r.importance;
                     current.maxImportance = Math.max(current.maxImportance, r.importance);
+                    current.hasSpine = current.hasSpine || r.spine;
+                    current.spineCallLine = current.spineCallLine ?? r.spineCallLine;
                 }
                 else {
                     clusters.push(current);
@@ -2185,6 +3021,8 @@ class ToolHandler {
                         symbols: [`${r.name}(${r.kind})`],
                         score: r.importance,
                         maxImportance: r.importance,
+                        hasSpine: r.spine,
+                        spineCallLine: r.spineCallLine,
                     };
                 }
             }
@@ -2198,16 +3036,40 @@ class ToolHandler {
             // get tail-trimmed with a marker.
             const contextPadding = 3;
             const withLineNumbers = exploreLineNumbersEnabled();
+            // Language-neutral separator (no `//` — not a comment in Python, Ruby,
+            // etc.). With line numbers on, the line-number jump also signals the gap.
+            const GAP_MARKER = '\n\n... (gap) ...\n\n';
+            // An oversize spine method (the call path runs THROUGH a god-method — n8n's
+            // processRunExecutionData is 962 lines) is windowed to its next-hop CALL site
+            // plus the signature head, NOT dumped whole. Without this the cluster is too big
+            // for any per-file cap and gets dropped, so the agent Reads the method back —
+            // the exact gap this closes. Bounded, so a god-method can't blow the budget yet
+            // the spine's call still appears in context.
+            const OVERSIZE_SPINE_LINES = 200;
+            const SPINE_WINDOW = 28; // lines each side of the next-hop call site
             const buildSection = (c) => {
+                if (c.hasSpine && c.spineCallLine && (c.end - c.start + 1) > OVERSIZE_SPINE_LINES) {
+                    const call = c.spineCallLine;
+                    const winStart = Math.max(c.start, call - SPINE_WINDOW);
+                    const winEnd = Math.min(c.end, call + SPINE_WINDOW);
+                    const parts = [];
+                    // Signature head, only when it sits clearly above the window (else the
+                    // window already covers the method opening).
+                    const headEnd = Math.min(c.start + 4, winStart - 2);
+                    if (headEnd >= c.start) {
+                        const head = fileLines.slice(c.start - 1, headEnd).join('\n');
+                        parts.push(withLineNumbers ? numberSourceLines(head, c.start) : head);
+                    }
+                    const win = fileLines.slice(winStart - 1, winEnd).join('\n');
+                    parts.push(withLineNumbers ? numberSourceLines(win, winStart) : win);
+                    return parts.join(GAP_MARKER);
+                }
                 const startIdx = Math.max(0, c.start - 1 - contextPadding);
                 const endIdx = Math.min(fileLines.length, c.end + contextPadding);
                 const slice = fileLines.slice(startIdx, endIdx).join('\n');
                 // startIdx is 0-based, so the slice's first line is line startIdx + 1.
                 return withLineNumbers ? numberSourceLines(slice, startIdx + 1) : slice;
             };
-            // Language-neutral separator (no `//` — not a comment in Python, Ruby,
-            // etc.). With line numbers on, the line-number jump also signals the gap.
-            const GAP_MARKER = '\n\n... (gap) ...\n\n';
             // Rank clusters for inclusion under the per-file cap. Entry-point
             // clusters come first: a cluster containing a query entry point
             // (importance 10) must outrank a dense block of mere declarations,
@@ -2221,6 +3083,12 @@ class ToolHandler {
             const rankedClusters = clusters
                 .map((c, i) => ({ idx: i, span: c.end - c.start + 1, c }))
                 .sort((a, b) => {
+                // Spine clusters first — the rendered call path IS the flow answer, so it
+                // outranks any denser block of peripheral declarations (a low-density entry
+                // method must not lose the budget to them). Within spine / within non-spine,
+                // the existing importance → density → score → span order holds.
+                if (a.c.hasSpine !== b.c.hasSpine)
+                    return (b.c.hasSpine ? 1 : 0) - (a.c.hasSpine ? 1 : 0);
                 if (b.c.maxImportance !== a.c.maxImportance)
                     return b.c.maxImportance - a.c.maxImportance;
                 const densityA = a.c.score / a.span;
@@ -2238,6 +3106,11 @@ class ToolHandler {
             // That source-order slice is what cut Django's `_fetch_all` (L2237, importance
             // 9 — agent-named) when query.py was the last of four big files to be emitted.
             const fileBudget = Math.min(budget.maxCharsPerFile, Math.max(0, budget.maxOutputChars - totalChars - 200));
+            // Spine ceiling: a flow-path cluster may exceed the per-file cap (the call
+            // path is the answer), but bounded — at most ~2.5× the per-file cap and never
+            // past what's left of the total output cap — so a pathological long in-file
+            // spine can't run away or starve co-flow files entirely.
+            const SPINE_CEILING = Math.min(budget.maxCharsPerFile * 2.5, Math.max(0, budget.maxOutputChars - totalChars - 200));
             const chosenIndices = new Set();
             let projectedChars = 0;
             for (const rc of rankedClusters) {
@@ -2250,7 +3123,12 @@ class ToolHandler {
                     projectedChars += sectionLen;
                     continue;
                 }
-                if (projectedChars + sectionLen > fileBudget)
+                // A spine cluster (the rendered call path) is the flow answer — include it
+                // past the per-file budget up to the spine ceiling; non-spine clusters obey
+                // the normal per-file budget.
+                const fits = projectedChars + sectionLen <= fileBudget;
+                const spineFits = rc.c.hasSpine && projectedChars + sectionLen <= SPINE_CEILING;
+                if (!fits && !spineFits)
                     continue;
                 chosenIndices.add(rc.idx);
                 projectedChars += sectionLen;
@@ -2293,7 +3171,7 @@ class ToolHandler {
             const headerSuffix = omittedCount > 0
                 ? `${headerSymbols.join(', ')}, +${omittedCount} more`
                 : headerSymbols.join(', ');
-            const fileHeader = `#### ${filePath} — ${headerSuffix}`;
+            const fileHeader = fileSectionHeader(filePath, headerSuffix);
             // The total cap bounds INCIDENTAL files only. A file that DEFINES a symbol
             // the agent named (or that's on the flow spine) renders even when the
             // nominal total is used up — it's the answer, and the set is bounded by
@@ -2330,7 +3208,7 @@ class ToolHandler {
                 .sort((a, b) => b[1].score - a[1].score);
             const remainingFiles = [...remainingRelevant, ...peripheralFiles];
             if (remainingFiles.length > 0) {
-                lines.push('### Not shown above — explore these names for their source');
+                lines.push('**Not shown above — explore these names for their source**');
                 lines.push('');
                 for (const [filePath, group] of remainingFiles.slice(0, 10)) {
                     const symbols = group.nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
@@ -2377,13 +3255,13 @@ class ToolHandler {
         const output = flow.text + lines.join('\n');
         const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
         if (output.length > hardCeiling) {
-            // Cut at a FILE-SECTION boundary (the last `#### ` header before the
+            // Cut at a FILE-SECTION boundary (the last ``**` `` file header before the
             // ceiling) so we drop whole trailing file-sections rather than slicing
             // through a method body — a half-rendered method just forces the Read this
             // tool exists to prevent. Fall back to a line boundary only if no section
             // header sits in the back half (degenerate single-giant-section case).
             const cut = output.slice(0, hardCeiling);
-            const lastSection = cut.lastIndexOf('\n#### ');
+            const lastSection = cut.lastIndexOf('\n' + FILE_SECTION_PREFIX);
             const boundary = lastSection > hardCeiling * 0.5 ? lastSection : cut.lastIndexOf('\n');
             const safe = boundary > 0 ? cut.slice(0, boundary) : cut;
             return this.textResult(safe + '\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For any area not covered, run another homegraph_explore with the specific names — do NOT Read these files.)');
@@ -2394,14 +3272,26 @@ class ToolHandler {
      * Handle homegraph_node
      */
     async handleNode(args) {
-        const symbol = this.validateString(args.symbol, 'symbol');
-        if (typeof symbol !== 'string')
-            return symbol;
-        const cg = this.getCodeGraph(args.projectPath);
+        const cg = this.getHomeGraph(args.projectPath);
         // Default to false to minimize context usage
         const includeCode = args.includeCode === true;
         const fileHint = typeof args.file === 'string' && args.file.trim() ? args.file.trim() : undefined;
         const lineHint = typeof args.line === 'number' && args.line > 0 ? args.line : undefined;
+        const offset = typeof args.offset === 'number' && args.offset > 0 ? Math.floor(args.offset) : undefined;
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.floor(args.limit) : undefined;
+        const symbolsOnly = args.symbolsOnly === true;
+        const symbolRaw = typeof args.symbol === 'string' ? args.symbol.trim() : '';
+        // FILE READ MODE: a `file` with no `symbol` reads that file like the Read
+        // tool — its current on-disk source with line numbers, narrowable with
+        // `offset`/`limit` exactly as Read does — PLUS a one-line blast-radius
+        // header (which files depend on it). `symbolsOnly` returns just the
+        // structural map instead. Backed by the index: same bytes Read gives you.
+        if (!symbolRaw && fileHint) {
+            return this.handleFileView(cg, fileHint, { offset, limit, symbolsOnly });
+        }
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
         let matches = this.findSymbolMatches(cg, symbol);
         if (matches.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
@@ -2480,13 +3370,147 @@ class ToolHandler {
         if (listed.length) {
             const LIST_CAP = 20;
             const shownList = listed.slice(0, LIST_CAP);
-            out.push('', '### Other definitions', ...shownList.map((n) => `- \`${n.name}\` (${n.kind}) — ${n.filePath}:${n.startLine}`));
+            out.push('', '**Other definitions**', ...shownList.map((n) => `- \`${n.name}\` (${n.kind}) — ${n.filePath}:${n.startLine}`));
             if (listed.length > LIST_CAP)
                 out.push(`- … +${listed.length - LIST_CAP} more`);
             out.push('', `> Need one of these in full? Call homegraph_node again with \`file\` (e.g. \`"${listed[0].filePath.split('/').pop()}"\`) or \`line\` — do NOT Read it.`);
         }
         return this.textResult(this.truncateOutput(out.join('\n')));
     }
+    /**
+     * 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).
+     */
+    async handleFileView(cg, fileArg, opts = {}) {
+        const normalize = (p) => p.replace(/\\/g, '/').replace(/^(?:\.?\/+)+/, '').replace(/\/+$/, '');
+        const wantLower = normalize(fileArg).toLowerCase();
+        const allFiles = cg.getFiles();
+        if (allFiles.length === 0)
+            return this.textResult('No files indexed. Run `homegraph index` first.');
+        let resolved = allFiles.find((f) => f.path.toLowerCase() === wantLower);
+        let candidates = [];
+        if (!resolved) {
+            candidates = allFiles.filter((f) => f.path.toLowerCase().endsWith('/' + wantLower));
+            if (candidates.length === 1)
+                resolved = candidates[0];
+        }
+        if (!resolved && candidates.length === 0) {
+            candidates = allFiles.filter((f) => f.path.toLowerCase().includes(wantLower));
+            if (candidates.length === 1)
+                resolved = candidates[0];
+        }
+        if (!resolved && candidates.length > 1) {
+            return this.textResult([`"${fileArg}" matches ${candidates.length} indexed files — pass a longer path:`, '',
+                ...candidates.slice(0, 25).map((f) => `- ${f.path}`)].join('\n'));
+        }
+        if (!resolved) {
+            return this.textResult(`No indexed file matches "${fileArg}". Codegraph indexes source files; configs/docs it doesn't parse won't appear — Read those directly.`);
+        }
+        const filePath = resolved.path;
+        const nodes = cg.getNodesInFile(filePath)
+            .filter((n) => n.kind !== 'file' && n.kind !== 'import' && n.kind !== 'export')
+            .sort((a, b) => a.startLine - b.startLine);
+        const dependents = cg.getFileDependents(filePath);
+        // Compact, one-line blast radius (homegraph's value-add over a plain Read).
+        const depSummary = dependents.length
+            ? `used by ${dependents.length} file${dependents.length === 1 ? '' : 's'}: ${dependents.slice(0, 8).join(', ')}${dependents.length > 8 ? `, +${dependents.length - 8} more` : ''}`
+            : 'no other indexed file depends on it';
+        // Symbol-map renderer — for symbolsOnly, the config fallback, and read errors.
+        const symbolMap = (heading, limit = 200) => {
+            const lines = [heading];
+            for (const n of nodes.slice(0, limit)) {
+                const sig = n.signature ? ` ${n.signature.replace(/\s+/g, ' ').trim()}` : '';
+                lines.push(`- \`${n.name}\` (${n.kind})${sig} — :${n.startLine}`);
+            }
+            if (nodes.length > limit)
+                lines.push(`- … +${nodes.length - limit} more`);
+            return lines;
+        };
+        // symbolsOnly → the cheap structural overview, no source.
+        if (opts.symbolsOnly) {
+            const out = [`**${filePath}** — ${nodes.length} symbol${nodes.length === 1 ? '' : 's'}, ${depSummary}`, ''];
+            if (nodes.length)
+                out.push(...symbolMap('**Symbols**'));
+            else
+                out.push('_No indexed symbols in this file._');
+            out.push('', '> Drop `symbolsOnly` (or pass `offset`/`limit`) to read the source, like Read.');
+            return this.textResult(this.truncateOutput(out.join('\n')));
+        }
+        // SECURITY (#383): never dump a raw config/data file — a yaml/properties
+        // line is `key: <secret>`. Summarize by key and point to a real Read.
+        if (utils_1.CONFIG_LEAF_LANGUAGES.has(resolved.language)) {
+            const out = [`**${filePath}** — configuration/data file, ${depSummary}`, ''];
+            if (nodes.length)
+                out.push(...symbolMap('**Keys (values withheld for safety)**'));
+            out.push('', '> Values may be secrets, so homegraph indexes keys only. Read the file directly if you need a value.');
+            return this.textResult(this.truncateOutput(out.join('\n')));
+        }
+        // Read the current bytes from disk through the security chokepoint
+        // (validatePathWithinRoot: blocks `../` traversal and symlink escapes, #527).
+        const abs = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), filePath);
+        let content = null;
+        if (abs) {
+            try {
+                content = (0, fs_1.readFileSync)(abs, 'utf-8');
+            }
+            catch {
+                content = null;
+            }
+        }
+        if (content === null) {
+            const out = [`**${filePath}** — could not read from disk (it may have moved since indexing). ${depSummary}`, ''];
+            if (nodes.length)
+                out.push(...symbolMap('**Symbols**'));
+            out.push('', `> Read \`${filePath}\` directly for its current content.`);
+            return this.textResult(this.truncateOutput(out.join('\n')));
+        }
+        // Split exactly as Read does — keep the trailing empty line a final newline
+        // produces (Read numbers it too), so line numbers line up byte-for-byte.
+        const fileLines = content.split('\n');
+        const total = fileLines.length;
+        // Read-parity windowing: `offset`/`limit` mean exactly what they do on Read
+        // (1-based start line; max line count). Default: the whole file, capped like
+        // Read at 2000 lines and bounded by a char budget that tracks explore's
+        // proven-safe ~38k response ceiling. Overflow is stated explicitly (Read
+        // paginates too) — never the silent 15k truncateOutput chop.
+        const CHAR_BUDGET = 38000;
+        const DEFAULT_LIMIT = 2000;
+        const offset = Math.max(1, opts.offset ?? 1);
+        if (offset > total) {
+            return this.textResult(`**${filePath}** has ${total} line${total === 1 ? '' : 's'} — offset ${offset} is past the end. ${depSummary}`);
+        }
+        const maxLines = Math.max(1, opts.limit ?? DEFAULT_LIMIT);
+        const start = offset - 1; // 0-based
+        const header = `**${filePath}** — ${total} lines, ${nodes.length} symbol${nodes.length === 1 ? '' : 's'} · ${depSummary}`;
+        // Numbered lines, byte-for-byte Read's shape: `<n>\t<line>`, no left-pad.
+        const numbered = [];
+        let used = header.length + 8;
+        let i = start;
+        for (; i < total && numbered.length < maxLines; i++) {
+            const ln = `${i + 1}\t${fileLines[i]}`;
+            if (used + ln.length + 1 > CHAR_BUDGET && numbered.length > 0)
+                break;
+            numbered.push(ln);
+            used += ln.length + 1;
+        }
+        const shownEnd = start + numbered.length;
+        const complete = offset === 1 && shownEnd >= total;
+        const out = [header, '', ...numbered];
+        if (!complete) {
+            out.push('', `(lines ${offset}–${shownEnd} of ${total} — pass \`offset\`/\`limit\` for another range, or \`homegraph_node <symbol>\` for one symbol in full)`);
+        }
+        // Self-bounded to CHAR_BUDGET — do NOT route through truncateOutput (15k).
+        return this.textResult(out.join('\n'));
+    }
     /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
     async renderNodeSection(cg, node, includeCode) {
         let code = null;
@@ -2536,7 +3560,7 @@ class ToolHandler {
         const callers = collect(cg.getCallers(node.id));
         if (callees.length === 0 && callers.length === 0)
             return '';
-        const lines = ['', '### Trail — homegraph_node any of these to follow it (no Read needed)'];
+        const lines = ['', '**Trail — homegraph_node any of these to follow it (no Read needed)**'];
         if (callees.length > 0) {
             lines.push(`**Calls →** ${callees.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callees.length > TRAIL_CAP ? `, +${callees.length - TRAIL_CAP} more` : ''}`);
         }
@@ -2549,7 +3573,7 @@ class ToolHandler {
      * Handle homegraph_status
      */
     async handleStatus(args) {
-        let cg = this.getCodeGraph(args.projectPath);
+        let cg = this.getHomeGraph(args.projectPath);
         // Same trick as withStalenessNotice — when an explicit projectPath
         // resolves to the same project as the default session cg, prefer the
         // default so getPendingFiles() (only populated by the default's watcher)
@@ -2570,7 +3594,7 @@ class ToolHandler {
         // one-liner via withWorktreeNotice. Both share the cached detection.
         const mismatch = this.worktreeMismatchFor(args.projectPath);
         const lines = [
-            '## CodeGraph Status',
+            '**HomeGraph Status**',
             '',
         ];
         if (mismatch) {
@@ -2592,25 +3616,32 @@ class ToolHandler {
             lines.push(`**Journal mode:** ⚠ ${journalMode || 'unknown'} — WAL not active, so reads ` +
                 `can block on a concurrent write (WAL appears unsupported on this filesystem)`);
         }
-        lines.push('', '### Nodes by Kind:');
+        lines.push('', '**Nodes by Kind:**');
         for (const [kind, count] of Object.entries(stats.nodesByKind)) {
             if (count > 0) {
                 lines.push(`- ${kind}: ${count}`);
             }
         }
-        lines.push('', '### Languages:');
+        lines.push('', '**Languages:**');
         for (const [lang, count] of Object.entries(stats.filesByLanguage)) {
             if (count > 0) {
                 lines.push(`- ${lang}: ${count}`);
             }
         }
+        // Whole-index degradation (#876): when live watching has permanently
+        // stopped, getPendingFiles() is empty (so no "Pending sync" section below)
+        // but the index is frozen — call that out explicitly here, the one place an
+        // agent asks "is the index caught up?".
+        if (cg.isWatcherDegraded()) {
+            lines.push('', '**Auto-sync disabled:**', `- ${cg.getWatcherDegradedReason() ?? 'live file watching stopped'}`, '- The index is frozen; Read files directly for current content.');
+        }
         // Per-file freshness — the inverse of the auto-prepended staleness banner
         // (issue #403). Surfacing it inside `status` gives the agent a single
         // place to ask "is the index caught up?" rather than inferring from
         // banners on other tool calls.
         const pending = cg.getPendingFiles();
         if (pending.length > 0) {
-            lines.push('', '### Pending sync:');
+            lines.push('', '**Pending sync:**');
             const now = Date.now();
             for (const p of pending) {
                 const ageMs = Math.max(0, now - p.lastSeenMs);
@@ -2624,7 +3655,7 @@ class ToolHandler {
      * Handle homegraph_files - get project file structure from the index
      */
     async handleFiles(args) {
-        const cg = this.getCodeGraph(args.projectPath);
+        const cg = this.getHomeGraph(args.projectPath);
         const pathFilter = args.path;
         const pattern = args.pattern;
         const format = args.format || 'tree';
@@ -2690,7 +3721,7 @@ class ToolHandler {
      * Format files as a flat list
      */
     formatFilesFlat(files, includeMetadata) {
-        const lines = [`## Files (${files.length})`, ''];
+        const lines = [`**Files (${files.length})**`, ''];
         for (const file of files.sort((a, b) => a.path.localeCompare(b.path))) {
             if (includeMetadata) {
                 lines.push(`- ${file.path} (${file.language}, ${file.nodeCount} symbols)`);
@@ -2711,11 +3742,11 @@ class ToolHandler {
             existing.push(file);
             byLang.set(file.language, existing);
         }
-        const lines = [`## Files by Language (${files.length} total)`, ''];
+        const lines = [`**Files by Language (${files.length} total)**`, ''];
         // Sort languages by file count (descending)
         const sortedLangs = [...byLang.entries()].sort((a, b) => b[1].length - a[1].length);
         for (const [lang, langFiles] of sortedLangs) {
-            lines.push(`### ${lang} (${langFiles.length})`);
+            lines.push(`**${lang} (${langFiles.length})**`);
             for (const file of langFiles.sort((a, b) => a.path.localeCompare(b.path))) {
                 if (includeMetadata) {
                     lines.push(`- ${file.path} (${file.nodeCount} symbols)`);
@@ -2751,7 +3782,7 @@ class ToolHandler {
             }
         }
         // Render tree
-        const lines = [`## Project Structure (${files.length} files)`, ''];
+        const lines = [`**Project Structure (${files.length} files)**`, ''];
         const renderNode = (node, prefix, isLast, depth) => {
             if (maxDepth !== undefined && depth > maxDepth)
                 return;
@@ -2942,12 +3973,12 @@ class ToolHandler {
     // Formatting helpers (compact by default to reduce context usage)
     // =========================================================================
     formatSearchResults(results) {
-        const lines = [`## Search Results (${results.length} found)`, ''];
+        const lines = [`**Search Results (${results.length} found)**`, ''];
         for (const result of results) {
             const { node } = result;
             const location = node.startLine ? `:${node.startLine}` : '';
             // Compact format: one line per result with key info
-            lines.push(`### ${node.name} (${node.kind})`);
+            lines.push(`**${node.name}** (${node.kind})`);
             lines.push(`${node.filePath}${location}`);
             if (node.signature)
                 lines.push(`\`${node.signature}\``);
@@ -2955,20 +3986,41 @@ class ToolHandler {
         }
         return lines.join('\n');
     }
-    formatNodeList(nodes, title) {
-        const lines = [`## ${title} (${nodes.length} found)`, ''];
+    formatNodeList(nodes, title, labels) {
+        const lines = [`**${title} (${nodes.length} found)**`, ''];
         for (const node of nodes) {
             const location = node.startLine ? `:${node.startLine}` : '';
-            // Compact: just name, kind, location
-            lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}`);
+            // Compact: just name, kind, location — plus the relationship when it
+            // isn't a plain call (callback registration, instantiation, …).
+            const label = labels?.get(node.id);
+            lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
         }
         return lines.join('\n');
     }
+    /**
+     * 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.
+     */
+    edgeLabel(edge) {
+        if (edge.kind === 'calls')
+            return null;
+        if (edge.metadata?.fnRef === true)
+            return 'callback registration';
+        if (edge.kind === 'instantiates')
+            return 'instantiation';
+        if (edge.kind === 'imports')
+            return 'import';
+        if (edge.kind === 'references')
+            return 'reference';
+        return edge.kind;
+    }
     formatImpact(symbol, impact) {
         const nodeCount = impact.nodes.size;
         // Compact format: just list affected symbols grouped by file
         const lines = [
-            `## Impact: "${symbol}" affects ${nodeCount} symbols`,
+            `**Impact: "${symbol}" affects ${nodeCount} symbols**`,
             '',
         ];
         // Group by file
@@ -3011,7 +4063,7 @@ class ToolHandler {
     formatNodeDetails(node, code, outline) {
         const location = node.startLine ? `:${node.startLine}` : '';
         const lines = [
-            `## ${node.name} (${node.kind})`,
+            `**${node.name}** (${node.kind})`,
             '',
             `**Location:** ${node.filePath}${location}`,
         ];