@colbymchenry/codegraph-darwin-x64 1.0.0 → 1.1.0

package/lib/dist/mcp/tools.js

@@ -10,6 +10,7 @@ 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
@@ -228,6 +229,28 @@ function exploreLineNumbersEnabled() {
 function adaptiveExploreEnabled() {
     return process.env.CODEGRAPH_ADAPTIVE_EXPLORE !== '0' && process.env.CODEGRAPH_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).
+ *
+ * `CODEGRAPH_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.CODEGRAPH_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
@@ -244,6 +267,22 @@ function numberSourceLines(slice, firstLineNumber) {
     }
     return out.join('\n');
 }
+/**
+ * Unique line-prefix for a per-file source section in codegraph_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.
@@ -280,12 +319,26 @@ 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 (`codegraph sync` / git hooks).
+ */
+function formatDegradedBanner(reason) {
+    return ('⚠️ CodeGraph 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 .codegraph/ 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) — codegraph uses the nearest .codegraph/ 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
@@ -514,28 +567,17 @@ function getStaticTools() {
     return allow.size ? exports.tools.filter(t => allow.has(t.name.replace(/^codegraph_/, ''))) : exports.tools;
 }
 /**
- * The MCP tools served by DEFAULT (short names). The other defined tools
- * (callees, impact, files, status) remain fully functional — handlers stay,
- * the library API and CLI are untouched, and `CODEGRAPH_MCP_TOOLS` re-enables
- * any of them — they just aren't LISTED to agents anymore.
+ * The MCP tools served by DEFAULT (short names). Pared to ONLY `codegraph_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.
  *
- * Evidence for the cut (the "adapt the tool to the agent" principle —
- * fewer tools = fewer mis-picks, and presence itself steers):
- * - `codegraph_impact` appears in ZERO recorded eval runs ever — its
- *   blast-radius info already arrives inline on explore (the "Blast radius"
- *   section) and node (the dependents note), so agents never need the
- *   standalone tool.
- * - `codegraph_callees` is redundant by construction: a symbol's body (which
- *   node returns) IS its callee list, plus the caller/callee trail.
- * - `codegraph_files` / `codegraph_status`: the tiny-repo audit (see
- *   getTools) found they "reduce to one grep"; staleness banners already
- *   inline the pending-sync info on every read tool, and the CLI covers
- *   diagnostics.
- * - `codegraph_callers` stays: exhaustive call-site enumeration (every
- *   caller with file:line, callback registrations labeled, one section per
- *   same-named definition) is the one job explore/node don't replicate.
+ * 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 `CODEGRAPH_MCP_TOOLS=explore,node,...` re-enables any of them.
  */
-const DEFAULT_MCP_TOOLS = new Set(['explore', 'node', 'search', 'callers']);
+const DEFAULT_MCP_TOOLS = new Set(['explore']);
 /**
  * Tool handler that executes tools against a CodeGraph instance
  *
@@ -560,7 +602,9 @@ 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) {
@@ -582,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(`[CodeGraph MCP] Catch-up reconcile still running after ${timeoutMs}ms; serving this tool call now and finishing the reconcile in the background (#905). ` +
+                    `Set CODEGRAPH_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.
@@ -696,19 +779,18 @@ class ToolHandler {
                 const searched = this.defaultProjectHint ?? process.cwd();
                 throw new NotIndexedError('No CodeGraph project is loaded for this session.\n' +
                     `Searched for a .codegraph/ directory starting from: ${searched}\n` +
-                    'If this project IS indexed, 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' +
+                    '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 .codegraph/ — 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 the project simply has no index, continue with your built-in tools (Read/Grep/Glob) ' +
-                    "and don't call codegraph again this session — the user can run 'codegraph init' to enable it.");
+                    'If a project simply has no index, use your built-in tools (Read/Grep/Glob) for THAT ' +
+                    "project (the user can run 'codegraph 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
@@ -721,7 +803,16 @@ class ToolHandler {
                 throw new PathRefusalError(pathError);
             }
         }
-        // Walk up parent directories to find nearest .codegraph/
+        // Always RE-RESOLVE the nearest .codegraph/ 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 .codegraph/ 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.findNearestCodeGraphRoot)(projectPath);
         if (!resolvedRoot) {
             throw new NotIndexedError(`The project at ${projectPath} isn't indexed with codegraph (no .codegraph/ directory found ` +
@@ -732,25 +823,43 @@ class ToolHandler {
         // 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;
-        }
-        // Open and cache under both paths
+            return this.freshen(this.cg);
+        }
+        // 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 = loadCodeGraph().openSync(resolvedRoot);
         this.projectCache.set(resolvedRoot, cg);
-        if (projectPath !== resolvedRoot) {
-            this.projectCache.set(projectPath, cg);
+        return cg;
+    }
+    /**
+     * Heal a long-lived connection whose `.codegraph/` was removed and recreated
+     * at the same path (a worktree recreated, or `rm -rf .codegraph` + 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('[CodeGraph 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;
     }
@@ -808,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 — getCodeGraph re-walks to the nearest .codegraph/, 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.getCodeGraph(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;
     }
     /**
@@ -883,6 +1003,34 @@ class ToolHandler {
                 /* getProjectRoot may throw on a closed instance — leave cg as is */
             }
         }
+        // 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 CodeGraph, 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 CodeGraph stub without the
         // newer pending-files API. Treat missing/throwing as "no pending files."
         let pending = [];
@@ -929,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 (CODEGRAPH_MCP_TOOLS): a trimmed
             // surface rejects ablated tools defensively even if a client cached them.
@@ -1089,7 +1237,7 @@ class ToolHandler {
     definitionHeading(group) {
         const head = group[0];
         const line = head.startLine ? `:${head.startLine}` : '';
-        return `### ${head.qualifiedName} (${head.kind}) — ${head.filePath}${line}`;
+        return `**${head.qualifiedName}** (${head.kind}) — ${head.filePath}${line}`;
     }
     /**
      * Handle codegraph_callers
@@ -1142,7 +1290,7 @@ class ToolHandler {
         // 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\`)`,
+            `**Callers of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)**`,
         ];
         for (const group of groups) {
             const { callers, labels } = collect(group);
@@ -1207,7 +1355,7 @@ class ToolHandler {
         }
         // Multiple DISTINCT definitions (#764): per-definition sections.
         const lines = [
-            `## Callees of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)`,
+            `**Callees of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)**`,
         ];
         for (const group of groups) {
             const { callees, labels } = collect(group);
@@ -1270,7 +1418,7 @@ class ToolHandler {
         // 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\`)`,
+            `**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];
@@ -1346,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;
     }
     /**
@@ -1363,7 +1534,10 @@ 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
@@ -1395,8 +1569,24 @@ class ToolHandler {
             // 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;
@@ -1414,21 +1604,67 @@ class ToolHandler {
                     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;
             }
+            // 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) {
-                // The agent named a flow but only one side resolved (the other end is
-                // anonymous / runtime-registered / not extracted). The resolved side's
-                // body may still hold the dynamic-dispatch site that EXPLAINS the gap —
-                // surface that instead of silently returning nothing.
-                if (named.size === 0)
-                    return EMPTY;
-                const boundaries = this.buildDynamicBoundaries(cg, [...named.values()], named);
-                if (!boundaries)
+                // <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 text = boundaries + '> Full source for these symbols is below.\n';
-                return { text, pathNodeIds: new Set(), namedNodeIds: new Set(named.keys()), uniqueNamedNodeIds };
+                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;
@@ -1477,6 +1713,16 @@ class ToolHandler {
             }
             const hasMain = !!best && best.length >= 3;
             const pathIds = new Set((best ?? []).map((s) => s.node.id));
+            // 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
@@ -1514,46 +1760,43 @@ class ToolHandler {
                     boundaryText = this.buildDynamicBoundaries(cg, scanList, named);
                 }
             }
-            // 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;
-                    // "Already in the main chain" only applies when a chain RENDERS
-                    // (hasMain). A 2-node chain populates pathIds but renders nothing,
-                    // so a direct synthesized hop between two named symbols (custom
-                    // EventBus emit→handler, #687) was invisible — too short for Flow,
-                    // skipped here as in-chain. Surface it.
-                    if (hasMain && pathIds.has(edge.source) && pathIds.has(edge.target))
-                        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))
+            // 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 && !boundaryText)
+            // 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) {
@@ -1565,17 +1808,19 @@ 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;
@@ -1645,7 +1890,7 @@ class ToolHandler {
         if (notes.length === 0)
             return '';
         return [
-            '## Dynamic boundaries (the static path ends at runtime dispatch)',
+            '**Dynamic boundaries (the static path ends at runtime dispatch)**',
             '',
             ...notes,
             '',
@@ -1653,6 +1898,113 @@ class ToolHandler {
             '',
         ].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 codegraph_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 codegraph_explore on a listed target.',
+            '',
+        ].join('\n');
+    }
     /**
      * Shortlist candidate runtime targets for a dispatch key surfaced by
      * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
@@ -1791,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,
             '',
@@ -2191,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 CODEGRAPH_RANK_NO_MULTITERM=1
+        // to disable.
+        const MULTITERM_OFF = process.env.CODEGRAPH_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();
@@ -2199,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;
@@ -2229,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.`,
             '',
@@ -2244,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();
@@ -2329,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('');
@@ -2484,7 +2860,7 @@ class ToolHandler {
                     const tag = bodyIds.size > 0
                         ? 'focused (the methods you named in full, the rest as signatures — codegraph_explore a signature by name for its body; do NOT Read)'
                         : 'skeleton (signatures only — codegraph_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;
@@ -2522,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
@@ -2586,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.
@@ -2605,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);
@@ -2619,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];
@@ -2627,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);
@@ -2636,6 +3021,8 @@ class ToolHandler {
                         symbols: [`${r.name}(${r.kind})`],
                         score: r.importance,
                         maxImportance: r.importance,
+                        hasSpine: r.spine,
+                        spineCallLine: r.spineCallLine,
                     };
                 }
             }
@@ -2649,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,
@@ -2672,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;
@@ -2689,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) {
@@ -2701,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;
@@ -2744,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
@@ -2781,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(', ');
@@ -2828,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 codegraph_explore with the specific names — do NOT Read these files.)');
@@ -2943,7 +3370,7 @@ 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 codegraph_node again with \`file\` (e.g. \`"${listed[0].filePath.split('/').pop()}"\`) or \`line\` — do NOT Read it.`);
@@ -3012,7 +3439,7 @@ class ToolHandler {
         if (opts.symbolsOnly) {
             const out = [`**${filePath}** — ${nodes.length} symbol${nodes.length === 1 ? '' : 's'}, ${depSummary}`, ''];
             if (nodes.length)
-                out.push(...symbolMap('### Symbols'));
+                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.');
@@ -3023,7 +3450,7 @@ class ToolHandler {
         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(...symbolMap('**Keys (values withheld for safety)**'));
             out.push('', '> Values may be secrets, so codegraph indexes keys only. Read the file directly if you need a value.');
             return this.textResult(this.truncateOutput(out.join('\n')));
         }
@@ -3042,7 +3469,7 @@ class ToolHandler {
         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(...symbolMap('**Symbols**'));
             out.push('', `> Read \`${filePath}\` directly for its current content.`);
             return this.textResult(this.truncateOutput(out.join('\n')));
         }
@@ -3133,7 +3560,7 @@ class ToolHandler {
         const callers = collect(cg.getCallers(node.id));
         if (callees.length === 0 && callers.length === 0)
             return '';
-        const lines = ['', '### Trail — codegraph_node any of these to follow it (no Read needed)'];
+        const lines = ['', '**Trail — codegraph_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` : ''}`);
         }
@@ -3167,7 +3594,7 @@ class ToolHandler {
         // one-liner via withWorktreeNotice. Both share the cached detection.
         const mismatch = this.worktreeMismatchFor(args.projectPath);
         const lines = [
-            '## CodeGraph Status',
+            '**CodeGraph Status**',
             '',
         ];
         if (mismatch) {
@@ -3189,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);
@@ -3287,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)`);
@@ -3308,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)`);
@@ -3348,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;
@@ -3539,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}\``);
@@ -3553,7 +3987,7 @@ class ToolHandler {
         return lines.join('\n');
     }
     formatNodeList(nodes, title, labels) {
-        const lines = [`## ${title} (${nodes.length} found)`, ''];
+        const lines = [`**${title} (${nodes.length} found)**`, ''];
         for (const node of nodes) {
             const location = node.startLine ? `:${node.startLine}` : '';
             // Compact: just name, kind, location — plus the relationship when it
@@ -3586,7 +4020,7 @@ class ToolHandler {
         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
@@ -3629,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}`,
         ];