homegraph 1.1.3 → 1.2.0

package/dist/mcp/tools.js

@@ -24,12 +24,15 @@ 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 arkts_1 = require("../extraction/languages/arkts");
 const dynamic_boundaries_1 = require("./dynamic-boundaries");
+const query_cache_1 = require("./query-cache");
 /** ViewTree structural `references` vias — not UI event bindings. */
 const VIEWTREE_STRUCTURE_VIAS = new Set([
     'child-component',
     'state-binding',
-    'prop-transfer',
+    'Prop',
+    'Link',
     'builder',
     'builder-param',
 ]);
@@ -275,6 +278,29 @@ function numberSourceLines(slice, firstLineNumber) {
     }
     return out.join('\n');
 }
+/** Primary signature line (first line when overloads are stored newline-separated). */
+function primarySignatureLine(signature) {
+    return signature.split('\n')[0]?.trim() ?? signature.trim();
+}
+/** Render a stored signature (single line or newline-separated overloads) for MCP output. */
+function formatNodeSignatureBlock(signature) {
+    const lines = signature.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length <= 1) {
+        return lines.length ? [`**Signature:** \`${lines[0]}\``] : [];
+    }
+    return [
+        '**Signature:**',
+        `- \`${lines[0]}\` (primary)`,
+        ...lines.slice(1).map((l) => `- \`${l}\` (overload)`),
+    ];
+}
+function formatInlineSignature(signature) {
+    const primary = primarySignatureLine(signature);
+    const overloadCount = signature.split('\n').filter((l) => l.trim()).length - 1;
+    if (overloadCount <= 0)
+        return primary;
+    return `${primary} (+${overloadCount} overload${overloadCount === 1 ? '' : 's'})`;
+}
 /**
  * Unique line-prefix for a per-file source section in homegraph_explore output.
  * Issue #778: tool results dropped ATX headings (`####`, `##`, `###`) for bold
@@ -286,6 +312,12 @@ function numberSourceLines(slice, firstLineNumber) {
  * (`reasoning/reasoner.ts`) both key off to cut on whole file sections.
  */
 const FILE_SECTION_PREFIX = '**`';
+// Placeholder for codegraph_explore's "Found N symbols across M files." line.
+// The honest N/M can only be known after the final truncation drops trailing
+// sections (#1046), so the header is emitted as this sentinel and substituted
+// at the very end. This bracketed token never occurs in rendered source or a
+// file path, so the final string-replace can't collide.
+const SUMMARY_SENTINEL = '[[codegraph-explore-summary]]';
 function fileSectionHeader(filePath, suffix) {
     return suffix
         ? `${FILE_SECTION_PREFIX}${filePath}\`** — ${suffix}`
@@ -348,6 +380,23 @@ const projectPathProperty = {
     type: 'string',
     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).',
 };
+/**
+ * EVERY homegraph tool is query-only: it reads the pre-built index and never
+ * mutates the workspace (indexing is the user's explicit CLI call, never the
+ * agent's). Advertising this read-only contract lets clients that gate on it run
+ * the tools where a possibly-mutating tool would be blocked — most concretely,
+ * Cursor's Ask mode, which rejects any MCP tool lacking `readOnlyHint: true`
+ * (issue #1018). `idempotentHint`: a repeated query has no additional effect.
+ * `openWorldHint: false`: the domain is the closed local index, not an open
+ * external world. Shared so the contract is declared once; a hypothetical
+ * mutating tool would simply not reference it.
+ */
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 /**
  * All HomeGraph MCP tools
  *
@@ -382,6 +431,7 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_callers',
@@ -406,6 +456,7 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_callees',
@@ -430,6 +481,7 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_impact',
@@ -454,6 +506,7 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_node',
@@ -495,6 +548,7 @@ exports.tools = [
             },
             required: [],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_explore',
@@ -515,6 +569,7 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_status',
@@ -525,6 +580,7 @@ exports.tools = [
                 projectPath: projectPathProperty,
             },
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_files',
@@ -558,6 +614,7 @@ exports.tools = [
                 projectPath: projectPathProperty,
             },
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'homegraph_spec_match',
@@ -592,8 +649,108 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
+    {
+        name: 'homegraph_spec_find',
+        description: 'Find which specs are related to the given file path by matching against code-fragment file paths ' +
+            'in the Commit4Spec knowledge graph. Traverses code_fragment_nodes → commit_fragment_relations ' +
+            '→ spec_commit_relations → spec_nodes. Useful for answering "which specs does this file affect?" ' +
+            'The database defaults to .homegraph/commit4spec/commit4spec.db under the repo path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'File path to look up (substring LIKE match). E.g. "src/auth.ts" or "src/auth".',
+                },
+                repoPath: {
+                    type: 'string',
+                    description: 'Path to the repository root. Defaults to the current working directory.',
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Explicit path to the Commit4Spec database. Overrides repoPath-based resolution.',
+                },
+            },
+            required: ['filePath'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
+    {
+        name: 'homegraph_spec_trace',
+        description: 'Trace a code symbol (function, method, class) back to its associated design Specs in the Commit4Spec ' +
+            'knowledge graph. Resolves the symbol via the HomeGraph code index, then matches against code-fragment ' +
+            'records in the Spec database using five-dimensional scoring: file-path match, code-diff content search ' +
+            '(FTS5), Spec title/subtitle name match, Spec recency, and line-range overlap. ' +
+            'Returns ranked Specs with score breakdowns even when exact line overlap is absent — code drifts over ' +
+            'time, so recency and content matching compensate. ' +
+            'The Spec DB defaults to .homegraph/commit4spec/commit4spec.db under the repo path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Symbol name (bare or qualified). E.g. "authenticate", "AuthService.login", "auth::validate".',
+                },
+                file: {
+                    type: 'string',
+                    description: 'File path for disambiguation when multiple symbols share the same name (optional).',
+                },
+                line: {
+                    type: 'number',
+                    description: 'Line number for disambiguation (optional).',
+                },
+                repoPath: {
+                    type: 'string',
+                    description: 'Path to the repository root. Defaults to the current working directory.',
+                },
+                topK: {
+                    type: 'number',
+                    description: 'Maximum number of matching Specs to return (default: 10).',
+                    default: 10,
+                },
+                dbPath: {
+                    type: 'string',
+                    description: 'Explicit path to the Commit4Spec database. Overrides repoPath-based resolution.',
+                },
+            },
+            required: ['symbol'],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
 ];
+/**
+ * Return `defs` with `projectPath` marked `required` in each tool's inputSchema.
+ *
+ * Used for the NO-DEFAULT-PROJECT tool surface (issue #993): when the MCP server
+ * has no default project to fall back to — a gateway server started outside any
+ * repo, or a monorepo root whose `.codegraph/` indexes live only in sub-projects
+ * — every call MUST carry an explicit `projectPath`, so the schema should say so.
+ * A `required` field is a HIGH-salience channel (MCP clients surface and often
+ * validate it), unlike the instructions text the reporter found too weak to stop
+ * the agent omitting the param. When a default project IS open, callers leave
+ * projectPath optional and never call this.
+ *
+ * Pure: clones each tool's schema rather than mutating the shared module-level
+ * `tools` array (reused by every session and the static surface). A tool that
+ * doesn't expose projectPath, or already requires it, is returned untouched;
+ * explore's `['query']` becomes `['query', 'projectPath']`, and a tool with no
+ * `required` list (status/files) gains `['projectPath']`.
+ */
+function withRequiredProjectPath(defs) {
+    return defs.map((tool) => {
+        if (!tool.inputSchema.properties.projectPath)
+            return tool;
+        const required = tool.inputSchema.required ?? [];
+        if (required.includes('projectPath'))
+            return tool;
+        return {
+            ...tool,
+            inputSchema: { ...tool.inputSchema, required: [...required, 'projectPath'] },
+        };
+    });
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -637,9 +794,23 @@ class ToolHandler {
     // huge repo can't hang the first call (#905); cleared on first await so
     // subsequent calls don't pay any cost.
     catchUpGate = null;
+    // Optional worker-thread pool for off-loop read-tool dispatch (daemon mode).
+    // When set + healthy, the heavy read tools run on a worker so the daemon's
+    // main loop stays free for the MCP transport under concurrent load. Null in
+    // direct/in-process mode (one client, no concurrency to parallelize).
+    queryPool = null;
     constructor(cg) {
         this.cg = cg;
     }
+    /**
+     * Engine-only: attach (or detach with null) the worker-thread query pool. The
+     * shared daemon sets this once its default project is open; the workers each
+     * hold their own WAL read connection and run {@link executeReadTool}. A
+     * worker's own ToolHandler never has a pool, so there is no nested off-loading.
+     */
+    setQueryPool(pool) {
+        this.queryPool = pool;
+    }
     /**
      * Update the default HomeGraph instance (e.g. after lazy initialization)
      */
@@ -743,8 +914,18 @@ class ToolHandler {
         let visible = allow
             ? exports.tools.filter(t => allow.has(t.name.replace(/^homegraph_/, '')))
             : exports.tools;
+        // No default project loaded → no-root-index case (#993): a gateway server
+        // started outside any repo, or a monorepo root whose indexes live in
+        // sub-projects. With nothing to fall back to, EVERY call needs an explicit
+        // projectPath, so mark it required in the schema — a high-salience nudge the
+        // agent acts on, where SERVER_INSTRUCTIONS_NO_ROOT_INDEX's prose alone
+        // wasn't enough (the reporter had to add an AGENTS.md note). `this.cg` is
+        // settled by `retryInitIfNeeded()` before `handleToolsList` calls us, so a
+        // null here means "genuinely no default", not a startup race. When a default
+        // IS open we leave projectPath optional (below): a bare call falls back to
+        // it, exactly as in the common single-project launch.
         if (!this.cg)
-            return visible;
+            return withRequiredProjectPath(visible);
         try {
             const stats = this.cg.getStats();
             const budget = getExploreBudget(stats.fileCount);
@@ -1143,48 +1324,58 @@ class ToolHandler {
                 if (typeof check === 'object' && check !== undefined)
                     return check;
             }
-            // Read tools resolve through a single result variable so cross-cutting
-            // notices — worktree-index mismatch (issue #155) and per-file
-            // staleness (issue #403) — can be applied in one place. status embeds
-            // its own verbose worktree warning but still flows through the
-            // staleness wrapper so its pending-files section stays consistent
-            // with what the read tools surface.
-            let result;
-            switch (toolName) {
-                case 'homegraph_search':
-                    result = await this.handleSearch(args);
-                    break;
-                case 'homegraph_callers':
-                    result = await this.handleCallers(args);
-                    break;
-                case 'homegraph_callees':
-                    result = await this.handleCallees(args);
-                    break;
-                case 'homegraph_impact':
-                    result = await this.handleImpact(args);
-                    break;
-                case 'homegraph_explore':
-                    result = await this.handleExplore(args);
-                    break;
-                case 'homegraph_node':
-                    result = await this.handleNode(args);
-                    break;
-                case 'homegraph_status':
-                    // status embeds the pending-files list as a first-class section
-                    // (see handleStatus), so we skip the auto-banner wrapper here to
-                    // avoid duplicating the same info at the top of the response.
-                    return await this.handleStatus(args);
-                case 'homegraph_files':
-                    result = await this.handleFiles(args);
-                    break;
-                case 'homegraph_spec_match':
-                    result = await this.handleSpecMatch(args);
-                    break;
-                default:
-                    return this.errorResult(`Unknown tool: ${toolName}`);
+            const projectPath = args.projectPath;
+            const cacheEnabled = (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
+            let cacheKey;
+            let cacheQueries;
+            if (cacheEnabled) {
+                try {
+                    const cacheCg = this.getHomeGraph(projectPath);
+                    cacheQueries = cacheCg.getQueryBuilder();
+                    (0, query_cache_1.ensureMcpQueryCacheValid)(cacheQueries, () => cacheCg.getLastIndexedAt());
+                    let fileCount;
+                    try {
+                        fileCount = cacheCg.getStats().fileCount;
+                    }
+                    catch {
+                        fileCount = undefined;
+                    }
+                    cacheKey = (0, query_cache_1.buildMcpQueryCacheKey)(toolName, args, fileCount);
+                    const cached = (0, query_cache_1.getMcpQueryCacheEntry)(cacheQueries, cacheKey);
+                    if (cached) {
+                        const withWorktree = this.withWorktreeNotice(cached, projectPath);
+                        return this.withStalenessNotice(withWorktree, projectPath);
+                    }
+                }
+                catch {
+                    // No indexed project — fall through; handler returns guidance.
+                }
             }
-            const withWorktree = this.withWorktreeNotice(result, args.projectPath);
-            return this.withStalenessNotice(withWorktree, args.projectPath);
+            // homegraph_status reports watcher state (pending files, degraded mode,
+            // worktree warning) and embeds its own sections — it must run on the MAIN
+            // thread against the watched default instance, so it is NEVER off-loaded to
+            // a worker (whose read connection has no watcher). It also skips the
+            // auto-banner wrapper to avoid duplicating its own pending-files section.
+            if (toolName === 'homegraph_status') {
+                return await this.handleStatus(args);
+            }
+            // Read tools: off-load the CPU-heavy dispatch to the worker pool when one
+            // is attached and healthy (daemon mode), so the daemon's single event loop
+            // stays free for the MCP transport under concurrent load — otherwise N
+            // concurrent explores serialize AND starve the transport until the whole
+            // batch drains (clients then time out). With no pool (direct mode) or a
+            // degraded one, dispatch runs in-process exactly as before. Either way the
+            // result flows through the cross-cutting notices — worktree-index mismatch
+            // (#155) and per-file staleness (#403) — which need the watched MAIN
+            // instance and so are always applied here, never in the worker.
+            const result = (this.queryPool && this.queryPool.healthy)
+                ? await this.queryPool.run(toolName, args)
+                : await this.executeReadTool(toolName, args);
+            if (cacheEnabled && cacheKey && cacheQueries && !result.isError) {
+                (0, query_cache_1.setMcpQueryCacheEntry)(cacheQueries, cacheKey, toolName, result);
+            }
+            const withWorktree = this.withWorktreeNotice(result, projectPath);
+            return this.withStalenessNotice(withWorktree, projectPath);
         }
         catch (err) {
             // Expected condition, not a malfunction: answer as a SUCCESS so the
@@ -1202,6 +1393,56 @@ class ToolHandler {
                 'continue without homegraph for this task.');
         }
     }
+    /**
+     * Run a single read tool to completion and return its raw {@link ToolResult},
+     * classifying expected failures the same way {@link execute}'s catch does so
+     * the SHAPE is identical whether dispatch runs in-process or on a worker:
+     * NotIndexed → success-shaped guidance, PathRefusal → clean error, anything
+     * else → internal-error-with-retry. Never throws.
+     *
+     * This is the worker thread's entry point (see {@link ./query-worker}) and the
+     * in-process fallback for {@link execute}. It deliberately does NOT run the
+     * catch-up gate or the staleness/worktree notices — those need the daemon's
+     * watched main instance and stay on the main thread. Cross-cutting allowlist +
+     * path validation already ran in {@link execute} before routing here.
+     */
+    async executeReadTool(toolName, args) {
+        try {
+            return await this.dispatchTool(toolName, args);
+        }
+        catch (err) {
+            if (err instanceof NotIndexedError) {
+                return this.textResult(err.message);
+            }
+            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.');
+        }
+    }
+    /**
+     * Pure dispatch over the read tools — the switch, with no gate, no notices, no
+     * allowlist/validation (the caller owns those). `homegraph_status` is handled
+     * on the main thread in {@link execute} and never reaches here. May throw
+     * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
+     */
+    async dispatchTool(toolName, args) {
+        switch (toolName) {
+            case 'homegraph_search': return await this.handleSearch(args);
+            case 'homegraph_callers': return await this.handleCallers(args);
+            case 'homegraph_callees': return await this.handleCallees(args);
+            case 'homegraph_impact': return await this.handleImpact(args);
+            case 'homegraph_explore': return await this.handleExplore(args);
+            case 'homegraph_node': return await this.handleNode(args);
+            case 'homegraph_files': return await this.handleFiles(args);
+            case 'homegraph_spec_match': return await this.handleSpecMatch(args);
+            case 'homegraph_spec_find': return await this.handleSpecFind(args);
+            case 'homegraph_spec_trace': return await this.handleSpecTrace(args);
+            default: return this.errorResult(`Unknown tool: ${toolName}`);
+        }
+    }
     /**
      * Handle homegraph_search
      */
@@ -1215,8 +1456,8 @@ class ToolHandler {
         // 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 rawLimit = Number(args.limit);
+        const limit = (0, utils_1.clamp)(isNaN(rawLimit) ? 10 : rawLimit, 1, 100);
         const results = cg.searchNodes(query, {
             limit,
             kinds: kind ? [kind] : undefined,
@@ -1526,6 +1767,20 @@ class ToolHandler {
         }
         if (m?.synthesizedBy === 'viewtree') {
             const via = typeof m.via === 'string' ? m.via : '';
+            if (via === 'Prop') {
+                return {
+                    label: `@Prop one-way state transfer (parent → child)`,
+                    compact: `state: @Prop one-way${at}`,
+                    registeredAt,
+                };
+            }
+            if (via === 'Link') {
+                return {
+                    label: `@Link two-way state transfer (parent ↔ child)`,
+                    compact: `state: @Link two-way${at}`,
+                    registeredAt,
+                };
+            }
             if (via && !VIEWTREE_STRUCTURE_VIAS.has(via)) {
                 return {
                     label: `ArkUI event \`.${via}\` — bound handler (dynamic dispatch)`,
@@ -2374,11 +2629,24 @@ class ToolHandler {
         // trace endpoint picker uses) and inject it as an entry, so every symbol the
         // agent explicitly named is in the subgraph and its file is scored.
         const namedSeedIds = new Set();
+        // The subset of named seeds that earns the named-FIRST sort tier. We still
+        // SEED every ≤3-def name (so RWR / flow ranking is unchanged), but only the
+        // most-substantive def is tiered — a bare name's unrelated namesakes (Go's
+        // `NewClient` = real client + test fake + xds pool) must not fill the tier
+        // and crowd out the real answer file (grpc's `dialoptions.go`). Corroborated
+        // overloads (the query also named the type) all earn it. (#1064)
+        const tierSeedIds = 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|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);
+            const callerCount = (n) => { try {
+                return cg.getCallers(n.id).length;
+            }
+            catch {
+                return 0;
+            } };
             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);
@@ -2414,12 +2682,23 @@ class ToolHandler {
                 // capped; else fall back to the single most-substantive def. This is the
                 // explore-side mirror of homegraph_node's overload disambiguation.
                 let picks;
+                let tierPicks; // subset that earns the named-first tier (#1064)
                 if (cands.length <= 3) {
                     picks = cands;
+                    // Centrality de-noise: tier the most-substantive def PLUS any co-named
+                    // def of comparable centrality (a real overload/wrapper — excalidraw's
+                    // `mutateElement` lives in mutateElement.ts, App.tsx AND Scene.ts, all
+                    // within ~2x callers). EXCLUDE a vastly-less-central namesake (Go's
+                    // `NewClient`: real client 492 callers vs xds-pool 11, test-fake 3 →
+                    // ratio <0.025) so it doesn't fill the tier and crowd out the answer.
+                    const counts = new Map(cands.map((c) => [c.id, callerCount(c)]));
+                    const maxCallers = Math.max(1, ...counts.values());
+                    tierPicks = cands.filter((c, i) => i === 0 || (counts.get(c.id) ?? 0) >= maxCallers * 0.25);
                 }
                 else {
                     const ctx = cands.filter(inNamedContext);
                     picks = ctx.length > 0 ? ctx.slice(0, 4) : cands.slice(0, 1);
+                    tierPicks = picks; // corroborated overloads (or the single fallback) all earn it
                 }
                 for (const n of picks) {
                     if (!subgraph.nodes.has(n.id))
@@ -2431,6 +2710,8 @@ class ToolHandler {
                     // so a named symbol FTS already gathered never sorted to the top.)
                     namedSeedIds.add(n.id);
                 }
+                for (const n of tierPicks)
+                    tierSeedIds.add(n.id);
             }
         }
         // Step 2: Group nodes by file, score by relevance
@@ -2444,6 +2725,46 @@ class ToolHandler {
             if (entryNodeIds.has(edge.target))
                 connectedToEntry.add(edge.source);
         }
+        // CHANGE SURFACE (#1064): a named method's signature types — its parameter
+        // and return types — are part of what you'd edit to "add a parameter to X",
+        // yet they can be lexically dissimilar to the query ("add a parameter to
+        // NewClient" shares no words with `dialoptions.go`, which defines NewClient's
+        // `DialOption`) and sit a hop away. COLLECT them here from each named-seed
+        // callable's outgoing signature edges (full graph — the type is often not in
+        // the subgraph); the decision to surface one is DEFERRED to the buried-rescue
+        // pass below, which fires only when the type's file would otherwise be
+        // dropped — so a well-connected type (excalidraw's element types, Alamofire's
+        // `DataRequest` on a flow query) is left to rank on its own and never
+        // displaces a flow-central file. Bounded: only the few named seeds, only the
+        // types in their signatures.
+        const CALLABLE_KINDS = new Set(['method', 'function', 'component', 'constructor']);
+        const TYPE_KINDS = new Set(['class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'type_alias']);
+        const SIG_EDGE = new Set(['references', 'type_of', 'returns']);
+        const changeSurfaceCandidates = [];
+        const seenChangeSurface = new Set();
+        for (const seedId of tierSeedIds) {
+            const seedNode = subgraph.nodes.get(seedId);
+            if (!seedNode || !CALLABLE_KINDS.has(seedNode.kind))
+                continue;
+            let outs = [];
+            try {
+                outs = cg.getOutgoingEdges(seedId);
+            }
+            catch {
+                continue;
+            }
+            for (const e of outs) {
+                if (!SIG_EDGE.has(e.kind))
+                    continue;
+                const tgt = cg.getNode(e.target);
+                if (!tgt || !TYPE_KINDS.has(tgt.kind) || namedSeedIds.has(tgt.id))
+                    continue;
+                if (seenChangeSurface.has(tgt.id))
+                    continue;
+                seenChangeSurface.add(tgt.id);
+                changeSurfaceCandidates.push(tgt);
+            }
+        }
         for (const node of subgraph.nodes.values()) {
             // Skip import/export nodes — they add noise without information
             if (node.kind === 'import' || node.kind === 'export')
@@ -2563,6 +2884,36 @@ class ToolHandler {
             if (n)
                 entryFiles.add(n.filePath);
         }
+        // Buried-rescue pass (#1064): surface a named method's signature type ONLY
+        // when its file is genuinely buried — near-zero graph mass AND not lexically
+        // matched. That is the invisible case (grpc's `DialOption` → `dialoptions.go`,
+        // g≈0, 0 term hits): reachable but ranked nowhere, so the agent greps. A
+        // well-connected type file (excalidraw element types, Alamofire `DataRequest`)
+        // is NOT buried and is left alone — rescuing it would displace a flow-central
+        // file (App.tsx, Validation.swift). Buried is judged on the PRE-rescue graph,
+        // so injecting the type below can't make it look connected. A rescued file is
+        // injected (so it renders), force-kept (gate + relevantFiles), and tiered.
+        const changeSurfaceFiles = new Set();
+        for (const t of changeSurfaceCandidates) {
+            const fp = t.filePath;
+            const buried = (fileGraphScore.get(fp) ?? 0) < maxGraph * 0.06
+                && (fileTermHits.get(fp) ?? 0) < 2;
+            if (!buried)
+                continue;
+            changeSurfaceFiles.add(fp);
+            if (!subgraph.nodes.has(t.id))
+                subgraph.nodes.set(t.id, t);
+            let group = fileGroups.get(fp);
+            if (!group) {
+                group = { nodes: [], score: 0 };
+                fileGroups.set(fp, group);
+            }
+            if (!group.nodes.some((n) => n.id === t.id))
+                group.nodes.push(t);
+            group.score = Math.max(group.score, 45);
+            if (!relevantFiles.some(([f]) => f === fp))
+                relevantFiles.push([fp, group]);
+        }
         // Relevance gate (so the generous budget is a CEILING, not a target): keep a
         // file only if it is STRUCTURALLY relevant by ANY of:
         //   - graph score within a fraction of the top (it's on/near the flow), OR
@@ -2579,6 +2930,7 @@ class ToolHandler {
             const gated = relevantFiles.filter(([fp]) => (fileGraphScore.get(fp) ?? 0) >= maxGraph * 0.06
                 || centralFiles.has(fp)
                 || entryFiles.has(fp)
+                || changeSurfaceFiles.has(fp)
                 || (fileTermHits.get(fp) ?? 0) >= 2);
             if (gated.length >= 2)
                 relevantFiles = gated;
@@ -2593,11 +2945,16 @@ class ToolHandler {
         // in other files (`Validation.swift`), falls outside the budget, and the
         // agent Reads it. The named file is the answer — rank it at the top.
         const namedSeedFiles = new Set();
-        for (const id of namedSeedIds) {
+        for (const id of tierSeedIds) {
             const n = subgraph.nodes.get(id);
             if (n)
                 namedSeedFiles.add(n.filePath);
         }
+        // A rescued change-surface file (only the genuinely-buried ones — see the
+        // buried-rescue pass) is the lexically-dissimilar answer; give it the named
+        // tier so it isn't buried under files that merely share surface words (#1064).
+        for (const fp of changeSurfaceFiles)
+            namedSeedFiles.add(fp);
         // 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
@@ -2662,9 +3019,16 @@ class ToolHandler {
         const lines = [
             `**Exploration: ${query}**`,
             '',
-            `Found ${subgraph.nodes.size} symbols across ${fileGroups.size} files.`,
+            // Curated summary — filled in after the source loop (see below). We do NOT
+            // report `subgraph.nodes.size` / `fileGroups.size` here: that's the raw
+            // candidate gather, which a broad natural-language query inflates wildly
+            // (260 symbols / 124 files on a 636-file repo) even though only a handful
+            // render. Reporting the pool read as "260 results to wade through" when the
+            // real, correctly-ranked answer is the few files below (#1046).
+            '',
             '',
         ];
+        const summaryLineIdx = 2;
         // Blast radius (always-on, compact): for the entry symbols, who depends on
         // them + which tests cover them — locations only, no source — so the agent
         // knows what to update/verify before editing without a separate call.
@@ -2766,6 +3130,9 @@ class ToolHandler {
         lines.push('');
         let totalChars = lines.join('\n').length;
         let filesIncluded = 0;
+        // Paths we actually render source for below. Drives the curated header count
+        // (#1046) — it must reflect what we show, not the raw candidate gather.
+        const renderedFilePaths = [];
         let anyFileTrimmed = false;
         for (const [filePath, group] of sortedFiles) {
             if (filesIncluded >= maxFiles)
@@ -2779,6 +3146,24 @@ class ToolHandler {
             const fileNecessary = group.nodes.some(n => entryNodeIds.has(n.id) || flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id));
             if (!fileNecessary && totalChars > budget.maxOutputChars * 0.9)
                 continue;
+            if ((0, arkts_1.isOhosApiFilePath)(filePath)) {
+                const rel = filePath.slice(arkts_1.OHOS_API_FILE_PREFIX.length);
+                const syms = group.nodes
+                    .filter((n) => n.kind !== 'import' && n.kind !== 'export')
+                    .sort((a, b) => a.startLine - b.startLine);
+                if (syms.length === 0)
+                    continue;
+                lines.push(fileSectionHeader(rel, 'HarmonyOS SDK API (prebuilt db)'));
+                lines.push('');
+                for (const n of syms) {
+                    const sig = n.signature || n.docstring || `${n.kind} ${n.qualifiedName || n.name}`;
+                    lines.push(`\`${sig}\``);
+                }
+                lines.push('');
+                totalChars = lines.join('\n').length;
+                filesIncluded++;
+                continue;
+            }
             const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, filePath);
             if (!absPath || !(0, fs_1.existsSync)(absPath))
                 continue;
@@ -2917,6 +3302,7 @@ class ToolHandler {
                         : 'skeleton (signatures only — homegraph_explore a name for its full body; do NOT Read)';
                     lines.push(fileSectionHeader(filePath, `${names} · ${tag}`), '', '```' + lang, skel.join('\n'), '```', '');
                     totalChars += skel.join('\n').length + 120;
+                    renderedFilePaths.push(filePath);
                     filesIncluded++;
                     continue;
                 }
@@ -2963,6 +3349,7 @@ class ToolHandler {
                 }
                 lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
                 totalChars += wholeSection.length + 200;
+                renderedFilePaths.push(filePath);
                 filesIncluded++;
                 continue;
             }
@@ -3251,8 +3638,14 @@ class ToolHandler {
             lines.push('```');
             lines.push('');
             totalChars += fileSection.length + 200;
+            renderedFilePaths.push(filePath);
             filesIncluded++;
         }
+        // The curated header count is computed from the files that SURVIVE the final
+        // truncation (see end of method) — `filesIncluded` can over-count when the
+        // hard ceiling drops trailing sections — so leave a sentinel here and fill it
+        // in once the output is final.
+        lines[summaryLineIdx] = SUMMARY_SENTINEL;
         // Add remaining files as references (from both relevant and peripheral files).
         // Small projects (per budget) skip this — the relevant story already fits
         // in the source section, and a trailing pointer list is pure overhead.
@@ -3309,6 +3702,7 @@ class ToolHandler {
         // externalize territory.
         const output = flow.text + lines.join('\n');
         const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
+        let finalText;
         if (output.length > hardCeiling) {
             // Cut at a FILE-SECTION boundary (the last ``**` `` file header before the
             // ceiling) so we drop whole trailing file-sections rather than slicing
@@ -3319,9 +3713,30 @@ class ToolHandler {
             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.)');
+            finalText = 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.)';
         }
-        return this.textResult(output);
+        else {
+            finalText = output;
+        }
+        // Curated header (#1046): substitute the sentinel with the count of files
+        // whose source SURVIVES in the final text — not `subgraph`/`fileGroups` (the
+        // raw gather a broad query inflates) and not `filesIncluded` (which can
+        // over-count when the ceiling above drops trailing sections). A file counts
+        // only if its section header is still present; its relevant (non-import)
+        // symbols are summed for N. Files we couldn't fit are still named under "Not
+        // shown above" + the budget note, so nothing is silently dropped.
+        const survivors = renderedFilePaths.filter((fp) => finalText.includes(`${FILE_SECTION_PREFIX}${fp}\``));
+        const shownSymbols = survivors.reduce((sum, fp) => {
+            const g = fileGroups.get(fp);
+            if (!g)
+                return sum;
+            return sum + new Set(g.nodes.filter((n) => n.kind !== 'import' && n.kind !== 'export').map((n) => n.id)).size;
+        }, 0);
+        const summaryLine = survivors.length > 0
+            ? `Found ${shownSymbols} symbol${shownSymbols === 1 ? '' : 's'} across ${survivors.length} file${survivors.length === 1 ? '' : 's'}.`
+            : `Found ${subgraph.nodes.size} symbol${subgraph.nodes.size === 1 ? '' : 's'} across ${fileGroups.size} file${fileGroups.size === 1 ? '' : 's'}.`;
+        finalText = finalText.replace(SUMMARY_SENTINEL, summaryLine);
+        return this.textResult(finalText);
     }
     /**
      * Handle homegraph_node
@@ -3483,7 +3898,7 @@ class ToolHandler {
         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()}` : '';
+                const sig = n.signature ? ` ${formatInlineSignature(n.signature)}` : '';
                 lines.push(`- \`${n.name}\` (${n.kind})${sig} — :${n.startLine}`);
             }
             if (nodes.length > limit)
@@ -3886,12 +4301,12 @@ class ToolHandler {
             return query;
         const repoPath = args.repoPath;
         const explicitDbPath = args.dbPath;
-        const topK = Math.max(1, Math.min(Number(args.topK) || 5, 50));
+        const topKRaw = Number(args.topK);
+        const topK = Math.max(1, Math.min(isNaN(topKRaw) ? 5 : topKRaw, 50));
         const includeFragments = args.includeFragments !== false;
         // Lazily require spec modules so the MCP startup path stays lean.
         const { resolveDbPath } = require('../spec/utils');
         const { createDatabase } = require('../db/sqlite-adapter');
-        const { initSpecSchema } = require('../spec/db/schema');
         const { searchAndGetContext } = require('../spec/graph/queries');
         const { truncateCodeDiff, truncateSubtitles, computeBudgetProfile, } = require('../spec/utils');
         // Resolve the database path.
@@ -3906,8 +4321,6 @@ class ToolHandler {
                 `${err instanceof Error ? err.message : String(err)}`);
         }
         try {
-            // Ensure the schema exists (idempotent).
-            initSpecSchema(db);
             // Search and traverse.
             const contexts = searchAndGetContext(db, query, topK, includeFragments);
             if (contexts.length === 0) {
@@ -3975,15 +4388,238 @@ class ToolHandler {
                     return this.textResult(`(Fragments elided — output exceeded ${MAX_OUTPUT_LENGTH} chars)\n\n` + slim);
                 }
             }
-            // Fallback: hard-truncate the JSON.
-            const truncated = json.slice(0, MAX_OUTPUT_LENGTH - 3) + '...';
-            return this.textResult(truncated);
+            // Fallback: truncate at a newline to avoid broken JSON.
+            return this.textResult(this.truncateOutput(json));
         }
         finally {
             db.close();
         }
     }
     // =========================================================================
+    // handleSpecFind — file-path based spec lookup
+    // =========================================================================
+    /**
+     * Find which specs are related to the given file path by matching against
+     * code-fragment file paths in the Commit4Spec knowledge graph.
+     *
+     * Traverses: filePath → code_fragment_nodes → commit_fragment_relations
+     * → spec_commit_relations → spec_nodes.
+     */
+    async handleSpecFind(args) {
+        const filePath = this.validateString(args.filePath, 'filePath');
+        if (typeof filePath !== 'string')
+            return filePath;
+        const repoPath = args.repoPath;
+        const explicitDbPath = args.dbPath;
+        // Lazily require spec modules so the MCP startup path stays lean.
+        const { resolveDbPath } = require('../spec/utils');
+        const { createDatabase } = require('../db/sqlite-adapter');
+        const { findSpecsByFilePath } = require('../spec/graph/queries');
+        // Resolve the database path.
+        const dbPath = resolveDbPath(repoPath || process.cwd(), explicitDbPath);
+        // Open the database.
+        let db;
+        try {
+            db = createDatabase(dbPath).db;
+        }
+        catch (err) {
+            return this.errorResult(`Failed to open Commit4Spec database at "${dbPath}": ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            const result = findSpecsByFilePath(db, filePath);
+            const response = {
+                filePath,
+                matched_count: result.matched_count,
+                truncated: result.truncated,
+                results: result.results,
+            };
+            const json = JSON.stringify(response, null, 2);
+            if (json.length <= MAX_OUTPUT_LENGTH) {
+                return this.textResult(json);
+            }
+            // Truncate: reduce results
+            const slim = {
+                ...response,
+                results: response.results.slice(0, Math.max(1, Math.floor(response.results.length / 2))),
+            };
+            const slimJson = JSON.stringify(slim, null, 2);
+            if (slimJson.length <= MAX_OUTPUT_LENGTH) {
+                return this.textResult(`(Results trimmed to fit output limit)\n\n${slimJson}`);
+            }
+            return this.textResult(this.truncateOutput(json));
+        }
+        finally {
+            db.close();
+        }
+    }
+    // =========================================================================
+    // handleSpecTrace — code symbol → Spec reverse trace
+    // =========================================================================
+    /**
+     * Trace a code symbol back to its associated Specs.
+     *
+     * Uses the HomeGraph code index to resolve the symbol to AST-level node(s),
+     * then queries the Commit4Spec knowledge graph for associated Specs via
+     * five-dimensional scoring (file-path, content FTS5, name FTS5, recency,
+     * line overlap).
+     *
+     * This bridges the two databases: homegraph.db (code entities) →
+     * commit4spec.db (Spec knowledge graph).
+     */
+    async handleSpecTrace(args) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const fileRaw = this.validateOptionalPath(args.file, 'file');
+        if (typeof fileRaw === 'object')
+            return fileRaw;
+        const file = fileRaw;
+        const line = typeof args.line === 'number' ? args.line : undefined;
+        const repoPath = args.repoPath;
+        const explicitDbPath = args.dbPath;
+        const topKRaw = Number(args.topK);
+        const topK = Math.max(1, Math.min(isNaN(topKRaw) ? 10 : topKRaw, 50));
+        // Lazily require all needed modules
+        const HomeGraph = loadHomeGraph();
+        const { resolveDbPath } = require('../spec/utils');
+        const { createDatabase } = require('../db/sqlite-adapter');
+        const { findSpecsByCodeSymbol } = require('../spec/graph/queries');
+        const { initSpecSchema, runSpecMigrations, getCurrentSpecVersion, CURRENT_SPEC_SCHEMA_VERSION } = require('../spec/db/schema');
+        // Resolve project path for the code graph
+        const projectPath = repoPath || process.cwd();
+        // Open the HomeGraph code index
+        let cg;
+        try {
+            cg = await HomeGraph.open(projectPath);
+        }
+        catch (err) {
+            return this.errorResult(`Failed to open HomeGraph code index at "${projectPath}": ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            // Step 1: Resolve symbol to nodes via findSymbolMatches
+            let nodes = this.findSymbolMatches(cg, symbol);
+            if (nodes.length === 0) {
+                await cg.close();
+                return this.textResult(JSON.stringify({
+                    symbol,
+                    error: `No code entities found for symbol "${symbol}".`,
+                    matches: [],
+                }, null, 2));
+            }
+            // Disambiguate by file/line if provided
+            if (file) {
+                // Use endsWith for precise file path matching
+                nodes = nodes.filter((n) => n.filePath.endsWith(file));
+            }
+            if (line !== undefined && nodes.length > 1) {
+                const closest = nodes.reduce((best, n) => {
+                    const bestDist = Math.abs(best.startLine - line) + Math.abs(best.endLine - line);
+                    const curDist = Math.abs(n.startLine - line) + Math.abs(n.endLine - line);
+                    return curDist < bestDist ? n : best;
+                });
+                nodes = [closest];
+            }
+            // Take the best disambiguated node
+            const node = nodes[0];
+            if (!node) {
+                await cg.close();
+                return this.textResult(JSON.stringify({
+                    symbol,
+                    error: `Could not resolve symbol "${symbol}" to a specific code entity.`,
+                    matches: [],
+                }, null, 2));
+            }
+            // Step 2: Resolve the Spec database path
+            const dbPath = resolveDbPath(repoPath || process.cwd(), explicitDbPath);
+            // Step 3: Open the Spec database
+            let db;
+            try {
+                db = createDatabase(dbPath).db;
+            }
+            catch (err) {
+                await cg.close();
+                return this.errorResult(`Failed to open Commit4Spec database at "${dbPath}": ` +
+                    `${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                // Ensure schema is up to date
+                initSpecSchema(db);
+                const currentVersion = getCurrentSpecVersion(db);
+                if (currentVersion < CURRENT_SPEC_SCHEMA_VERSION) {
+                    runSpecMigrations(db, currentVersion);
+                }
+                // Step 4: Query Specs for the code entity
+                const result = findSpecsByCodeSymbol(db, {
+                    name: node.name,
+                    qualifiedName: node.qualifiedName,
+                    kind: node.kind,
+                    filePath: node.filePath,
+                    startLine: node.startLine,
+                    endLine: node.endLine,
+                }, topK);
+                // Step 5: Serialize the response
+                const response = {
+                    symbol,
+                    entity: {
+                        name: result.entity.name,
+                        qualifiedName: result.entity.qualifiedName,
+                        kind: result.entity.kind,
+                        filePath: result.entity.filePath,
+                        startLine: result.entity.startLine,
+                        endLine: result.entity.endLine,
+                    },
+                    matched_count: result.matches.length,
+                    total_candidates: result.totalCandidates,
+                    matches: result.matches.map((m) => ({
+                        spec_id: m.spec.id,
+                        title: m.spec.title,
+                        status: m.spec.status,
+                        version: m.spec.version,
+                        file_path: m.spec.filePath,
+                        score: Math.round(m.score * 1000) / 1000,
+                        score_detail: {
+                            file_path: Math.round(m.scoreDetail.filePathScore * 1000) / 1000,
+                            content: Math.round(m.scoreDetail.contentScore * 1000) / 1000,
+                            name: Math.round(m.scoreDetail.nameScore * 1000) / 1000,
+                            recency: Math.round(m.scoreDetail.recencyScore * 1000) / 1000,
+                            line_overlap: Math.round(m.scoreDetail.overlapScore * 1000) / 1000,
+                        },
+                        fragment_count: m.fragmentCount,
+                        commit_count: m.commitCount,
+                    })),
+                };
+                const json = JSON.stringify(response, null, 2);
+                if (json.length <= MAX_OUTPUT_LENGTH) {
+                    return this.textResult(json);
+                }
+                // Truncate: reduce matches
+                const slim = {
+                    ...response,
+                    matches: response.matches.slice(0, Math.max(1, Math.floor(topK / 2))),
+                };
+                const slimJson = JSON.stringify(slim, null, 2);
+                if (slimJson.length <= MAX_OUTPUT_LENGTH) {
+                    return this.textResult(`(Results trimmed to fit output limit)\n\n${slimJson}`);
+                }
+                return this.textResult(this.truncateOutput(json));
+            }
+            finally {
+                try {
+                    db.close();
+                }
+                catch { /* best effort */ }
+            }
+        }
+        finally {
+            try {
+                await cg.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    // =========================================================================
     // Symbol resolution helpers
     // =========================================================================
     /**
@@ -4151,7 +4787,7 @@ class ToolHandler {
             lines.push(`**${node.name}** (${node.kind})`);
             lines.push(`${node.filePath}${location}`);
             if (node.signature)
-                lines.push(`\`${node.signature}\``);
+                lines.push(`\`${formatInlineSignature(node.signature)}\``);
             lines.push('');
         }
         return lines.join('\n');
@@ -4225,7 +4861,7 @@ class ToolHandler {
         const lines = [`**Members (${children.length}):**`, ''];
         for (const c of children) {
             const loc = c.startLine ? `:${c.startLine}` : '';
-            const sig = c.signature ? ` — \`${c.signature}\`` : '';
+            const sig = c.signature ? ` — \`${formatInlineSignature(c.signature)}\`` : '';
             lines.push(`- ${c.name} (${c.kind})${loc}${sig}`);
         }
         return lines.join('\n');
@@ -4238,7 +4874,7 @@ class ToolHandler {
             `**Location:** ${node.filePath}${location}`,
         ];
         if (node.signature) {
-            lines.push(`**Signature:** \`${node.signature}\``);
+            lines.push(...formatNodeSignatureBlock(node.signature));
         }
         // Only include docstring if it's short and useful
         if (node.docstring && node.docstring.length < 200) {