homegraph 1.5.0 → 1.5.2

package/dist/mcp/tools.js

@@ -31,6 +31,7 @@ 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");
+const diff_impact_1 = require("./diff-impact");
 /** ViewTree structural `references` vias — not UI event bindings. */
 const VIEWTREE_STRUCTURE_VIAS = new Set([
     'child-component',
@@ -73,6 +74,18 @@ const MAX_OUTPUT_LENGTH = 15000;
  * far beyond any realistic legitimate query.
  */
 const MAX_INPUT_LENGTH = 10_000;
+/** Example values for success-shaped bad-arg guidance (keyed by arg name). */
+const BAD_ARG_EXAMPLES = {
+    query: 'authenticate login',
+    symbol: 'authenticate',
+    filePath: 'src/auth.ts',
+    file: 'src/auth.ts',
+    path: 'src/components',
+    pattern: '*.ets',
+    projectPath: '/absolute/path/to/your/project',
+    repoPath: '/absolute/path/to/your/project',
+    diff: 'diff --git a/src/auth.ts b/src/auth.ts\n--- a/src/auth.ts\n+++ b/src/auth.ts\n@@ -10,3 +10,4 @@\n+export function authenticate() {}\n',
+};
 /**
  * Maximum length for path-like string inputs (projectPath, path
  * filter, glob pattern). Paths beyond a few thousand chars are
@@ -481,17 +494,19 @@ const READ_ONLY_ANNOTATIONS = {
 exports.tools = [
     {
         name: 'homegraph_search',
-        description: 'LAST RESORT spelling lookup — locations only, no source. Prefer homegraph_explore whenever the question already names a symbol/file/@kit. If you do call search with a bare name, HomeGraph may answer with a compact explore result instead of locations.',
+        description: 'LAST RESORT spelling lookup — locations only, no source. Required: `query` (e.g. "signIn"). ' +
+            'Prefer homegraph_explore when the question already names a symbol/file/@kit. ' +
+            'Bare-name search may return a compact explore result instead of locations.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Symbol name or partial name (e.g., "auth", "signIn", "UserService")',
+                    description: 'Required. Symbol name or partial name (e.g. "auth", "signIn", "UserService").',
                 },
                 kind: {
                     type: 'string',
-                    description: 'Filter by node kind',
+                    description: 'Optional filter by node kind',
                     enum: ['function', 'method', 'class', 'interface', 'type', 'variable', 'route', 'component'],
                 },
                 limit: {
@@ -507,17 +522,20 @@ exports.tools = [
     },
     {
         name: 'homegraph_callers',
-        description: 'Compact caller list for a NAMED in-repo symbol (no bodies). Use after you know the exact name. For full flows use homegraph_explore. DO NOT call for SDK catalogs, one-function semantics, or "what if X fails" hypothetics — Read that function instead. Prefer one explore over parallel callers+callees+node.',
+        description: 'Compact caller list for one NAMED in-repo symbol (no bodies). Required: `symbol` (e.g. "authenticate"). ' +
+            'Use after you know the exact name. For full flows use homegraph_explore. ' +
+            'DO NOT call for SDK catalogs, one-function semantics, or "what if X fails" hypothetics. ' +
+            'Prefer one explore over parallel callers+callees+node.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Name of the function, method, or class to find callers for',
+                    description: 'Required. Exact function/method/class name (e.g. "authenticate", "AuthService.login").',
                 },
                 file: {
                     type: 'string',
-                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist (e.g. one UserService per app in a monorepo)',
+                    description: 'Optional. Narrow to the definition in this file (path or suffix) when same-named symbols collide.',
                 },
                 limit: {
                     type: 'number',
@@ -532,17 +550,19 @@ exports.tools = [
     },
     {
         name: 'homegraph_callees',
-        description: 'Compact callee list for a NAMED in-repo symbol (no bodies). For full flows use homegraph_explore. DO NOT use for out-of-repo SDK internals or counterfactual analysis. Prefer one explore over parallel node+callers+callees.',
+        description: 'Compact callee list for one NAMED in-repo symbol (no bodies). Required: `symbol` (e.g. "authenticate"). ' +
+            'For full flows use homegraph_explore. DO NOT use for out-of-repo SDK internals or counterfactual analysis. ' +
+            'Prefer one explore over parallel node+callers+callees.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Name of the function, method, or class to find callees for',
+                    description: 'Required. Exact function/method/class name (e.g. "authenticate", "AuthService.login").',
                 },
                 file: {
                     type: 'string',
-                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+                    description: 'Optional. Narrow to the definition in this file (path or suffix) when same-named symbols collide.',
                 },
                 limit: {
                     type: 'number',
@@ -557,17 +577,19 @@ exports.tools = [
     },
     {
         name: 'homegraph_impact',
-        description: 'Blast radius for a NAMED in-repo symbol before a refactor. Not for SDK docs, permission judgments, or hypothetical failure effects — those need Read/Grep, not impact.',
+        description: 'Blast radius for one NAMED in-repo symbol before a refactor. Required: `symbol` (e.g. "authenticate"). ' +
+            'Not for SDK docs, permission judgments, or hypothetical failure effects — those need Read/Grep. ' +
+            'For PR/diff review use homegraph_diff_impact instead.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Name of the symbol to analyze impact for',
+                    description: 'Required. Exact symbol name to analyze (e.g. "authenticate", "CartRepository").',
                 },
                 file: {
                     type: 'string',
-                    description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+                    description: 'Optional. Narrow to the definition in this file (path or suffix) when same-named symbols collide.',
                 },
                 depth: {
                     type: 'number',
@@ -580,15 +602,64 @@ exports.tools = [
         },
         annotations: READ_ONLY_ANNOTATIONS,
     },
+    {
+        name: 'homegraph_diff_impact',
+        description: 'PR / code-review evidence pack from a unified diff (or explicit hunks). ' +
+            'Required: `diff` (unified diff text) OR `hunks` [{ path, startLine, endLine }]. ' +
+            'Intersects NEW-side changed lines with indexed symbol spans — does NOT dump every symbol in touched files. ' +
+            'Returns changedSymbols + capped callers + impactSummary + UI edges (viewtree/arkui-*); optional relatedSpecs. ' +
+            'Index should match the post-change tree. Does not write review text or judge Specs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                diff: {
+                    type: 'string',
+                    description: 'Unified diff text (preferred). New-side @@ +line ranges are used to find changed symbols. ' +
+                        'Example: output of `git diff` / PR patch for the files under review.',
+                },
+                hunks: {
+                    type: 'array',
+                    description: 'Alternative to `diff`: explicit changed ranges. Each item: { path, startLine, endLine } (1-based, inclusive, new-file lines).',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project-relative file path' },
+                            startLine: { type: 'number', description: '1-based start line (new file)' },
+                            endLine: { type: 'number', description: '1-based end line (new file)' },
+                        },
+                    },
+                },
+                depth: {
+                    type: 'number',
+                    description: 'Impact / caller traversal depth (default: 2, max: 5)',
+                    default: 2,
+                },
+                includeSpecs: {
+                    type: 'boolean',
+                    description: 'If true, attach related Commit4Spec hits for changed files/symbols (needs commit4spec.db). Default: false.',
+                    default: false,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: [],
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
     {
         name: 'homegraph_node',
-        description: 'Depth on ONE known in-repo symbol or indexed file — not a survey tool. (1) FILE: pass `file` alone → bounded line-numbered source + dependents. (2) SYMBOL: body (includeCode) + short trail; overloads return every body. USE after explore named the symbol and you still need one body. DO NOT call repeatedly to crawl a feature (prefer one explore). DO NOT call for: @kit/SDK catalogs, broad "how does X work", or after explore already returned that symbol\'s source. Treat returned source as already Read — do not grep/read the same path.',
+        description: 'Depth on ONE known in-repo symbol or indexed file — not a survey tool. ' +
+            'Required: pass `symbol` (symbol mode) OR `file` alone (file mode). ' +
+            'FILE: `file` only → line-numbered source + dependents. ' +
+            'SYMBOL: body via includeCode + short trail; overloads return every body. ' +
+            'USE after explore named the symbol and you still need one body. ' +
+            'DO NOT crawl a feature with repeated node calls (prefer one explore). ' +
+            'Treat returned source as already Read.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Name of the symbol to read (symbol mode). Omit it and pass `file` alone to read a whole file like Read.',
+                    description: 'Symbol mode (required unless `file` alone). Exact name (e.g. "authenticate").',
                 },
                 includeCode: {
                     type: 'boolean',
@@ -597,7 +668,8 @@ exports.tools = [
                 },
                 file: {
                     type: 'string',
-                    description: 'A file path or basename (e.g. "harness.rs", "src/auth/session.ts"). Pass it ALONE (no symbol) to READ the file like the Read tool — its full source with line numbers + which files depend on it. Or pass it WITH a symbol to disambiguate an overloaded name to the definition in this file.',
+                    description: 'File mode: pass ALONE (no symbol) to read like Read — e.g. "src/auth/session.ts". ' +
+                        'Or with `symbol` to disambiguate an overloaded name to that file.',
                 },
                 offset: {
                     type: 'number',
@@ -624,13 +696,16 @@ exports.tools = [
     },
     {
         name: 'homegraph_explore',
-        description: 'PRIMARY tool for THIS REPO\'s symbol graph (call paths + often line-numbered source). CALL when you need in-repo structure: how a named feature/component is wired, A→B path, callers/callees, Type.member → who uses it, click/handler flow, in-repo @kit import usages — put concrete symbol/file/@kit names in query; skip search. If the question does not need that graph, do not call. One explore; answer from returned Source + trail; treat as already Read; do not re-grep/search the same names. Busy/partial → retry same explore once.',
+        description: 'PRIMARY tool for THIS REPO\'s symbol graph (call paths + often line-numbered source). Required: `query` with concrete symbol/file/@kit names. ' +
+            'CALL for in-repo structure: feature wiring, A→B path, callers/callees, Type.member usage, click→handler, in-repo @kit usages. ' +
+            'Skip search when names are already known. One explore; answer from Source + trail; treat as already Read. Busy/partial → retry same explore once.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'In-repo symbols, file basenames, or @kit names for USAGE questions (import/call sites), not for asking the kit\'s official full API list. For flows, name both endpoints. Prefer concrete names from the question.',
+                    description: 'Required. In-repo symbols, file basenames, or @kit names (e.g. "ParentPage onClick build", "CartRepository.addItem"). ' +
+                        'For flows, name both endpoints. Not for official SDK API catalogs.',
                 },
                 maxFiles: {
                     type: 'number',
@@ -645,7 +720,7 @@ exports.tools = [
     },
     {
         name: 'homegraph_status',
-        description: 'Index health check (files / nodes / edges). Skip unless debugging.',
+        description: 'Index health check (files / nodes / edges). No required args when a default project is loaded. Skip unless debugging.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -656,17 +731,18 @@ exports.tools = [
     },
     {
         name: 'homegraph_files',
-        description: 'Indexed directory tree (paths and symbol counts only — NO source code). Do NOT use to answer where/what/how code questions; use homegraph_explore. Only for coarse folder layout when explore cannot help.',
+        description: 'Indexed directory tree (paths and symbol counts only — NO source). ' +
+            'Only for coarse folder layout when explore cannot help. For where/what/how code questions use homegraph_explore.',
         inputSchema: {
             type: 'object',
             properties: {
                 path: {
                     type: 'string',
-                    description: 'Filter to files under this directory path (e.g., "src/components"). Returns all files if not specified.',
+                    description: 'Optional directory prefix filter (e.g. "src/components"). Omit to list all indexed files.',
                 },
                 pattern: {
                     type: 'string',
-                    description: 'Filter files matching this glob pattern (e.g., "*.tsx", "**/*.test.ts")',
+                    description: 'Optional glob filter (e.g. "*.tsx", "**/*.ets").',
                 },
                 format: {
                     type: 'string',
@@ -690,19 +766,19 @@ exports.tools = [
     },
     {
         name: 'homegraph_spec_match',
-        description: 'Match a new spec/feature description against the Commit4Spec knowledge graph using FTS5 full-text search. ' +
-            'Returns the most similar historical specs with their associated commits and code fragments. ' +
-            'The database defaults to .homegraph/commit4spec/commit4spec.db under the repo path.',
+        description: 'Match a new feature/spec description against the Commit4Spec knowledge graph (FTS5). ' +
+            'Required: `query` (title + description text). Returns similar historical specs with commits/fragments. ' +
+            'Needs `.homegraph/commit4spec/commit4spec.db` (from `homegraph spec build` / `mine`).',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Spec text (title + description) to match against historical specs.',
+                    description: 'Required. Spec text (title + description) to match against historical specs.',
                 },
                 repoPath: {
                     type: 'string',
-                    description: 'Path to the repository root. Defaults to the current working directory.',
+                    description: 'Optional repository root (default: cwd). Spec DB lives under `.homegraph/commit4spec/`.',
                 },
                 topK: {
                     type: 'number',
@@ -721,20 +797,18 @@ exports.tools = [
     },
     {
         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.',
+        description: 'Find which Commit4Spec specs touch a file path. Required: `filePath` (e.g. "src/auth.ts"). ' +
+            'Needs `.homegraph/commit4spec/commit4spec.db`.',
         inputSchema: {
             type: 'object',
             properties: {
                 filePath: {
                     type: 'string',
-                    description: 'File path to look up (substring LIKE match). E.g. "src/auth.ts" or "src/auth".',
+                    description: 'Required. File path substring to match (e.g. "src/auth.ts" or "src/auth").',
                 },
                 repoPath: {
                     type: 'string',
-                    description: 'Path to the repository root. Defaults to the current working directory.',
+                    description: 'Optional repository root (default: cwd). Spec DB lives under `.homegraph/commit4spec/`.',
                 },
             },
             required: ['filePath'],
@@ -743,31 +817,26 @@ exports.tools = [
     },
     {
         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.',
+        description: 'Trace one code symbol back to related design Specs (Commit4Spec). Required: `symbol` (e.g. "authenticate"). ' +
+            'Optional `file`/`line` to disambiguate. Needs code index + `.homegraph/commit4spec/commit4spec.db`.',
         inputSchema: {
             type: 'object',
             properties: {
                 symbol: {
                     type: 'string',
-                    description: 'Symbol name (bare or qualified). E.g. "authenticate", "AuthService.login", "auth::validate".',
+                    description: 'Required. Symbol name (bare or qualified). E.g. "authenticate", "AuthService.login".',
                 },
                 file: {
                     type: 'string',
-                    description: 'File path for disambiguation when multiple symbols share the same name (optional).',
+                    description: 'Optional file path for disambiguation when multiple symbols share the same name.',
                 },
                 line: {
                     type: 'number',
-                    description: 'Line number for disambiguation (optional).',
+                    description: 'Optional line number for disambiguation.',
                 },
                 repoPath: {
                     type: 'string',
-                    description: 'Path to the repository root. Defaults to the current working directory.',
+                    description: 'Optional repository root (default: cwd).',
                 },
                 topK: {
                     type: 'number',
@@ -1017,6 +1086,7 @@ class ToolHandler {
                 'homegraph_explore',
                 'homegraph_search',
                 'homegraph_node',
+                'homegraph_diff_impact',
             ]);
             if (stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name));
@@ -1148,32 +1218,40 @@ class ToolHandler {
     /**
      * Validate that a value is a non-empty string within length bounds.
      *
-     * The `maxLength` cap protects against MCP clients that ship huge
-     * payloads (10MB+ query strings either by accident or maliciously).
-     * Without this, a single oversized input can pin the FTS5 index or
-     * exhaust memory before any real work runs.
+     * Bad / oversize args return SUCCESS-shaped guidance (no `isError`) with a
+     * retry example — same policy as {@link NotIndexedError}: early `isError`
+     * teaches agents to abandon the whole toolset. The length cap still blocks
+     * DoS before FTS/work runs.
      */
     validateString(value, name, maxLength = MAX_INPUT_LENGTH) {
         if (typeof value !== 'string' || value.length === 0) {
-            return this.errorResult(`${name} must be a non-empty string`);
+            const got = value === undefined || value === null
+                ? 'it was missing'
+                : typeof value !== 'string'
+                    ? `got ${typeof value}`
+                    : 'got an empty string';
+            return this.badArgResult(`\`${name}\` must be a non-empty string (${got}).`, name);
         }
         if (value.length > maxLength) {
-            return this.errorResult(`${name} exceeds maximum length of ${maxLength} characters (got ${value.length})`);
+            return this.badArgResult(`\`${name}\` exceeds maximum length of ${maxLength} characters (got ${value.length}). ` +
+                'Shorten it — pass a concrete symbol/file name, not a pasted dump.', name);
         }
         return value;
     }
     /**
      * Validate an optional path-like string input. Returns the value if
-     * valid (or undefined), or a ToolResult with the error.
+     * valid (or undefined), or SUCCESS-shaped guidance when the value is present
+     * but invalid (wrong type / oversize).
      */
     validateOptionalPath(value, name) {
         if (value === undefined || value === null)
             return undefined;
         if (typeof value !== 'string') {
-            return this.errorResult(`${name} must be a string`);
+            return this.badArgResult(`\`${name}\` must be a string when provided (got ${typeof value}).`, name);
         }
         if (value.length > MAX_PATH_LENGTH) {
-            return this.errorResult(`${name} exceeds maximum length of ${MAX_PATH_LENGTH} characters (got ${value.length})`);
+            return this.badArgResult(`\`${name}\` exceeds maximum length of ${MAX_PATH_LENGTH} characters (got ${value.length}). ` +
+                'Pass a normal project-relative or absolute path.', name);
         }
         return value;
     }
@@ -1600,6 +1678,7 @@ class ToolHandler {
             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_diff_impact': return await this.handleDiffImpact(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);
@@ -1901,6 +1980,147 @@ class ToolHandler {
         }
         return this.textResult(this.truncateOutput(sections.join('\n') + filterNote));
     }
+    /**
+     * Handle homegraph_diff_impact — diff line ranges ∩ symbol spans → evidence pack.
+     */
+    async handleDiffImpact(args) {
+        const resolved = (0, diff_impact_1.resolveDiffImpactHunks)({
+            diff: args.diff,
+            hunks: args.hunks,
+        });
+        if (resolved.error) {
+            return this.badArgResult(resolved.error, 'diff');
+        }
+        if (resolved.hunks.length === 0) {
+            return this.badArgResult('No file hunks found. Pass a unified `diff` with `+++` / `@@` headers, or `hunks: [{ path, startLine, endLine }]`.', 'diff');
+        }
+        const cg = this.getHomeGraph(args.projectPath);
+        const depthRaw = Number(args.depth);
+        const depth = Number.isFinite(depthRaw) ? depthRaw : 2;
+        const includeSpecs = args.includeSpecs === true;
+        const pack = (0, diff_impact_1.buildDiffImpactPack)(cg, resolved.hunks, {
+            depth,
+            notes: resolved.notes,
+        });
+        const relatedSpecs = [];
+        if (includeSpecs) {
+            const { resolveDbPath } = require('../spec/utils');
+            const { createDatabase } = require('../db/sqlite-adapter');
+            const { findSpecsByFilePath, findSpecsByCodeSymbol, } = require('../spec/graph/queries');
+            const projectRoot = (() => {
+                try {
+                    return cg.getProjectRoot();
+                }
+                catch {
+                    return args.projectPath || process.cwd();
+                }
+            })();
+            const dbPath = resolveDbPath(projectRoot);
+            let db = null;
+            try {
+                db = createDatabase(dbPath).db;
+            }
+            catch {
+                pack.notes.push(`includeSpecs was true but Commit4Spec DB is unavailable at ${dbPath} (run \`homegraph spec build\` / \`mine\` first).`);
+            }
+            if (db) {
+                try {
+                    const seenFileSpecs = new Set();
+                    for (const filePath of pack.changedFiles) {
+                        try {
+                            const found = findSpecsByFilePath(db, filePath);
+                            for (const r of found.results ?? []) {
+                                if (!r.id || seenFileSpecs.has(r.id))
+                                    continue;
+                                seenFileSpecs.add(r.id);
+                                relatedSpecs.push({
+                                    specId: r.id,
+                                    title: r.title,
+                                    via: 'file',
+                                    filePath,
+                                });
+                            }
+                        }
+                        catch {
+                            /* ignore per-file */
+                        }
+                    }
+                    const forTrace = pack.changedSymbols.slice(0, diff_impact_1.DIFF_IMPACT_LIMITS.maxSpecSymbols);
+                    if (pack.changedSymbols.length > forTrace.length) {
+                        pack.notes.push(`Spec symbol-trace limited to ${diff_impact_1.DIFF_IMPACT_LIMITS.maxSpecSymbols} of ${pack.changedSymbols.length} changed symbols.`);
+                    }
+                    const seenSymKeys = new Set();
+                    for (const sym of forTrace) {
+                        try {
+                            const traced = findSpecsByCodeSymbol(db, {
+                                name: sym.name,
+                                qualifiedName: sym.name,
+                                kind: sym.kind,
+                                filePath: sym.filePath,
+                                startLine: sym.startLine,
+                                endLine: sym.endLine,
+                            }, 5);
+                            for (const m of traced.matches ?? []) {
+                                const id = m.spec?.id;
+                                if (!id)
+                                    continue;
+                                const key = `${id}::${sym.name}`;
+                                if (seenSymKeys.has(key))
+                                    continue;
+                                seenSymKeys.add(key);
+                                relatedSpecs.push({
+                                    specId: id,
+                                    title: m.spec.title,
+                                    via: 'symbol',
+                                    symbol: sym.name,
+                                    score: typeof m.score === 'number' ? m.score : undefined,
+                                });
+                            }
+                        }
+                        catch {
+                            /* ignore per-symbol */
+                        }
+                    }
+                }
+                finally {
+                    try {
+                        db.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        }
+        const response = {
+            ...pack,
+            // Drop raw hunk ranges from default agent payload noise — keep changedFiles + symbols.
+            hunks: pack.hunks.map((h) => ({
+                path: h.path,
+                ranges: h.ranges,
+            })),
+            relatedSpecs: includeSpecs ? relatedSpecs : undefined,
+        };
+        const json = JSON.stringify(response, null, 2);
+        if (json.length <= MAX_OUTPUT_LENGTH) {
+            return this.textResult(json);
+        }
+        const slim = {
+            ...response,
+            callers: response.callers.slice(0, 20),
+            impactSummary: response.impactSummary.map((s) => ({
+                ...s,
+                sampleNames: s.sampleNames.slice(0, 3),
+            })),
+            uiEdges: response.uiEdges.slice(0, 15),
+            relatedSpecs: response.relatedSpecs?.slice(0, 15),
+            notes: [
+                ...response.notes,
+                'Output trimmed to fit MCP size limit — re-run with a smaller diff if you need full lists.',
+            ],
+        };
+        return this.textResult(this.truncateOutput(JSON.stringify(slim, null, 2)));
+    }
     /** Whether a graph edge may be traversed by homegraph_explore's main Flow BFS. */
     isExploreFlowEdge(edge) {
         if (edge.kind === 'calls')
@@ -2097,12 +2317,21 @@ class ToolHandler {
                 const hits = this.findAllSymbols(cg, t).nodes;
                 const cands = hits.filter((n) => CALLABLE.has(n.kind));
                 tokenFamily.set(t, cands);
+                // Prefer in-repo callables over attached OHOS SDK stubs (`ohos-sdk:…`).
+                // Lifecycle names like `aboutToAppear` / `build` collide with dozens of
+                // API defs; counting those as ambiguity empties co-naming and drops the
+                // project method the agent actually meant (ArkTS explore Flow regression).
+                // Do NOT fall back to the full pool when co-naming empties — that would
+                // pin a polymorphic name like `execute` (9+ impls) onto the Flow spine
+                // and silence the Interface-dispatch announcement.
+                const projectCands = cands.filter((n) => !(0, arkts_1.isOhosApiFilePath)(n.filePath));
+                const pool = projectCands.length > 0 ? projectCands : 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;
+                const specific = pool.length <= 3;
                 const pick = specific
-                    ? cands
-                    : cands.filter((n) => {
+                    ? pool
+                    : pool.filter((n) => {
                         const segs = (n.qualifiedName || '').toLowerCase().split(/::|\./).filter(Boolean);
                         const container = segs.length >= 2 ? segs[segs.length - 2] : '';
                         return !!container && segPool.has(container);
@@ -5946,6 +6175,12 @@ class ToolHandler {
         if (!symbolRaw && fileHint) {
             return this.handleFileView(cg, fileHint, { offset, limit, symbolsOnly });
         }
+        if (!symbolRaw && !fileHint) {
+            return this.badArgResult('`homegraph_node` needs either `symbol` (symbol mode) or `file` alone (file mode). Both were missing.', 'symbol', {
+                symbol: 'authenticate',
+                includeCode: true,
+            });
+        }
         const symbol = this.validateString(args.symbol, 'symbol');
         if (typeof symbol !== 'string')
             return symbol;
@@ -7111,6 +7346,21 @@ class ToolHandler {
             content: [{ type: 'text', text }],
         };
     }
+    /**
+     * Recoverable bad-argument guidance: SUCCESS-shaped (no `isError`) so agents
+     * retry with fixed args instead of abandoning HomeGraph for the session.
+     * Reserved `isError` cases stay in {@link errorResult} (security / real faults).
+     */
+    badArgResult(problem, argName, exampleOverride) {
+        const example = exampleOverride ??
+            { [argName]: BAD_ARG_EXAMPLES[argName] ?? '…' };
+        return this.textResult(`${problem}\n\n` +
+            'This is not a HomeGraph failure — fix the arguments and retry the same tool.\n' +
+            'Example:\n' +
+            '```json\n' +
+            `${JSON.stringify(example, null, 2)}\n` +
+            '```');
+    }
     errorResult(message) {
         return {
             content: [{ type: 'text', text: `Error: ${message}` }],