homegraph 1.5.5 → 1.5.7

package/dist/mcp/tools.js

@@ -21,6 +21,8 @@ exports.queryAsBareSymbolInventory = queryAsBareSymbolInventory;
 exports.hasPositiveAnswerNowDirective = hasPositiveAnswerNowDirective;
 exports.reconcilePartialAnswerNow = reconcilePartialAnswerNow;
 const query_pool_1 = require("./query-pool");
+const evidence_rendering_1 = require("./evidence-rendering");
+const query_plan_1 = require("../search/query-plan");
 const memory_budget_1 = require("./memory-budget");
 const directory_1 = require("../directory");
 // Lazy-load the heavy HomeGraph chain off the MCP startup path — see the same
@@ -99,6 +101,20 @@ const MAX_OUTPUT_LENGTH = 15000;
  * far beyond any realistic legitimate query.
  */
 const MAX_INPUT_LENGTH = 10_000;
+// Server-owned, structured-clone-safe request context. Never accept these from MCP clients.
+const QUERY_PLAN_ARG = '__homegraphQueryPlan';
+const QUERY_DEADLINE_ARG = '__homegraphQueryDeadlineAt';
+const QUERY_STARTED_ARG = '__homegraphQueryStartedAt';
+const QUERY_INDEX_STATE_ARG = '__homegraphQueryIndexState';
+const QUERY_FAST_ATTEMPTED_ARG = '__homegraphQueryFastAttempted';
+function readQueryPlan(args) {
+    const plan = args[QUERY_PLAN_ARG];
+    return plan?.version === query_plan_1.QUERY_PLAN_VERSION && typeof plan.originalQuery === 'string'
+        && typeof plan.canonicalQuery === 'string' && Array.isArray(plan.steps) ? plan : undefined;
+}
+function planFeature(plan, name, query, fallback) {
+    return plan?.features[name] ?? fallback(query);
+}
 /** Example values for success-shaped bad-arg guidance (keyed by arg name). */
 const BAD_ARG_EXAMPLES = {
     query: 'authenticate login',
@@ -843,95 +859,107 @@ exports.tools = [
         annotations: READ_ONLY_ANNOTATIONS,
     },
     {
-        name: 'homegraph_explore',
-        description: 'PRIMARY entry for understanding THIS repo before you edit or answer structural questions. ' +
-            'Returns call paths + compact line-numbered source for the relevant symbols. Required: `query`. ' +
-            'CALL FIRST (alone, no parallel Grep/Read) when you will change an existing codebase — pass the user task or domain keywords ' +
-            '(page/module/feature/component words); locate where to edit before writing code. Also CALL FIRST for how/wired questions, ' +
-            'named Type/Component/Page/Dialog, Type.member, click→handler, inheritance/subtypes, declaration/attribute sites, ' +
-            'ALL_CAPS constant / field-mutex usages, path-module NAPI/exports or inter-deps, and in-repo @kit/@ohos *usages/dependencies* ' +
-            '(which files import a named export — not the SDK feature catalog). PascalCase names optional when domain keywords suffice. ' +
-            'Prefer callers/node when one named symbol is already enough. ' +
-            'DO NOT call for topic file-lists with no Type/file, literal copy hunts / pure existence compares with no anchors, ' +
-            'official-docs-only asks, empty-project-from-scratch scaffolds, git history, or media/binary asset inventories — those return Skip. ' +
-            '@kit / OHOS API questions ARE in scope when the SDK API graph is available — call explore (usages or API symbols). ' +
-            'Literal string/pattern hunts → Grep; media assets → Glob; git history → git. ' +
-            'One explore; then answer or edit from Source + trail — do not re-grep/node/read the same symbols. ' +
-            'Overlapping paraphrase explores are refused (name a new Type/file/@kit to continue). ' +
-            'Busy/partial → retry ONCE with the named Next anchor or ONE narrow Grep — not a Grep/node storm '
-            + '(session refuses further explore / depth fan-out after Partial).',
+        name: 'homegraph_usages',
+        description: 'PRIMARY first tool for a narrow WHERE-USED question about one named API, `.member`, ALL_CAPS constant, field, or mutex. ' +
+            'Choose this instead of homegraph_explore when the requested answer is usage/reference locations. ' +
+            'Required: `query`. Returns usage files/lines only; it does not build a general flow or source dump. ' +
+            '`homegraph_explore` auto-routes equivalent high-confidence queries here only for compatibility.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Required. For pre-edit orientation or how/mechanism: pass the user task or domain keywords (page/module/feature words). ' +
-                        'For named flows, include Type / Type.member / component names. For @kit, ask usages (depend/import sites), not SDK catalogs.',
-                },
-                maxFiles: {
-                    type: 'number',
-                    description: 'Maximum number of files to include source code from (default: 12)',
-                    default: 12,
+                    description: 'Required. Exact API/member/constant/field name, with or without where-used wording.',
                 },
                 projectPath: projectPathProperty,
             },
             required: ['query'],
         },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: { ...READ_ONLY_ANNOTATIONS, title: 'HomeGraph Where-used Inventory' },
     },
     {
-        name: 'homegraph_usages',
-        description: 'Focused in-repo usage inventory for one named API, `.member`, ALL_CAPS constant, field, or mutex. ' +
-            'Required: `query`. Returns usage files/lines only; it does not build a general flow or source dump. ' +
-            'Use directly for a narrow where-used question; `homegraph_explore` auto-routes equivalent high-confidence queries here.',
+        name: 'homegraph_modules',
+        description: 'PRIMARY first tool for a narrow DEPENDENCY/CYCLE question about named path modules or `*common` / `*service` / `*component` / `*constants` modules. ' +
+            'Choose this instead of homegraph_explore when the requested answer is module topology. ' +
+            'Required: `query`. It does not build a general code flow or scan unrelated survey families. ' +
+            '`homegraph_explore` auto-routes equivalent high-confidence dependency questions here only for compatibility.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Required. Exact API/member/constant/field name, with or without where-used wording.',
+                    description: 'Required. Dependency/cycle question containing the exact module names or paths.',
                 },
                 projectPath: projectPathProperty,
             },
             required: ['query'],
         },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: { ...READ_ONLY_ANNOTATIONS, title: 'HomeGraph Module Dependencies' },
     },
     {
-        name: 'homegraph_modules',
-        description: 'Focused dependency/cycle inventory for named path modules or `*common` / `*service` / `*component` / `*constants` modules. ' +
-            'Required: `query`. It does not build a general code flow or scan unrelated survey families. ' +
-            '`homegraph_explore` auto-routes equivalent high-confidence dependency questions here.',
+        name: 'homegraph_native',
+        description: 'PRIMARY first tool for a narrow NAPI/NATIVE EXPORT or registration question about one named path or Type. ' +
+            'Choose this instead of homegraph_explore when the requested answer is the ArkTS↔native export surface. Required: `query`. ' +
+            'Returns indexed export descriptors/registration sites without a general domain file dump. ' +
+            '`homegraph_explore` auto-routes equivalent high-confidence NAPI/export questions here only for compatibility.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Required. Dependency/cycle question containing the exact module names or paths.',
+                    description: 'Required. NAPI/native export question containing the exact path or Type name.',
                 },
                 projectPath: projectPathProperty,
             },
             required: ['query'],
         },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: { ...READ_ONLY_ANNOTATIONS, title: 'HomeGraph Native Exports' },
     },
     {
-        name: 'homegraph_native',
-        description: 'Focused NAPI/native export inventory for one named path or Type. Required: `query`. ' +
-            'Returns indexed export descriptors/registration sites without a general domain file dump. ' +
-            '`homegraph_explore` auto-routes equivalent high-confidence NAPI/export questions here.',
+        name: 'homegraph_explore',
+        description: 'GENERAL PRIMARY entry for understanding THIS repo before you edit or answer structural questions. ' +
+            'For an explicit narrow where-used, named module dependency/cycle, or NAPI/native export inventory, choose ' +
+            'homegraph_usages, homegraph_modules, or homegraph_native instead; this tool keeps conservative auto-routing only for compatibility. ' +
+            'Returns call paths + compact line-numbered source for the relevant symbols. Required: `query`. ' +
+            'CALL FIRST (alone, no parallel Grep/Read) when you will change an existing codebase — pass the user task or domain keywords ' +
+            '(page/module/feature/component words); locate where to edit before writing code. Also CALL FIRST for how/wired questions, ' +
+            'named Type/Component/Page/Dialog, Type.member, click→handler, inheritance/subtypes, declaration/attribute sites, ' +
+            'or a cross-symbol mechanism/flow. Use the named focused tools for exact usage, module-topology, or native-export inventories. ' +
+            'PascalCase names optional when domain keywords suffice. ' +
+            'For edits preserve the requested action, target product/module and exclusions; taskContext may carry the full task. ' +
+            'Prefer callers/node when one named symbol is already enough. ' +
+            'DO NOT call for topic file-lists with no Type/file, literal copy hunts / pure existence compares with no anchors, ' +
+            'official-docs-only asks, empty-project-from-scratch scaffolds, git history, or media/binary asset inventories — those return Skip. ' +
+            '@kit / OHOS API questions ARE in scope when the SDK API graph is available — exact where-used → homegraph_usages; ' +
+            'mechanism/API-symbol flow → homegraph_explore. ' +
+            'Literal string/pattern hunts → Grep; media assets → Glob; git history → git. ' +
+            'One explore; then answer or edit from Source + trail — do not re-grep/node/read the same symbols. ' +
+            'Overlapping paraphrase explores are refused (name a new Type/file/@kit to continue). ' +
+            'Busy/partial → retry ONCE with the named Next anchor or ONE narrow Grep — not a Grep/node storm '
+            + '(session refuses further explore / depth fan-out after Partial).',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'Required. NAPI/native export question containing the exact path or Type name.',
+                    description: 'Required. For pre-edit orientation or how/mechanism: pass the user task or domain keywords (page/module/feature words). ' +
+                        'For named flows, include Type / Type.member / component names. For @kit mechanism/flow, include module/export tokens; ' +
+                        'use homegraph_usages for a narrow import/usage inventory, not SDK catalogs.',
+                },
+                taskContext: {
+                    type: 'string',
+                    description: 'Optional original task, including requested changes, product/module scope, exclusions and acceptance requirements. Not source evidence; bounded to 4000 characters.',
+                },
+                maxFiles: {
+                    type: 'number',
+                    description: 'Maximum number of files to include source code from (default: 12)',
+                    default: 12,
                 },
                 projectPath: projectPathProperty,
             },
             required: ['query'],
         },
-        annotations: READ_ONLY_ANNOTATIONS,
+        annotations: { ...READ_ONLY_ANNOTATIONS, title: 'HomeGraph General Explore' },
     },
     {
         name: 'homegraph_status',
@@ -944,6 +972,27 @@ exports.tools = [
         },
         annotations: READ_ONLY_ANNOTATIONS,
     },
+    {
+        name: 'homegraph_project',
+        description: 'Shallow project map: modules + files per module (no symbols/call edges). ' +
+            'PRIMARY for engineering overview while the full index is still building; also useful after full index. ' +
+            'Optional `module` filters by name/path; `includeFiles` defaults true.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                module: {
+                    type: 'string',
+                    description: 'Optional module name or root path substring to filter.',
+                },
+                includeFiles: {
+                    type: 'boolean',
+                    description: 'Include per-module file lists (default true). Set false for module list only.',
+                },
+                projectPath: projectPathProperty,
+            },
+        },
+        annotations: READ_ONLY_ANNOTATIONS,
+    },
     {
         name: 'homegraph_arkui_migrate',
         description: 'ArkUI migrate / state-semantics snapshot in ONE call (components, state decorators + args, ' +
@@ -1256,10 +1305,15 @@ function reconcilePartialAnswerNow(text) {
     if (!/\*\*Partial locator\*\*/i.test(text))
         return text;
     let changed = false;
+    let fenced = false;
     const out = text
         .split('\n')
         .map((line) => {
-        if (!/ANSWER NOW/i.test(line))
+        if (/^\s*```/.test(line)) {
+            fenced = !fenced;
+            return line;
+        }
+        if (fenced || !/ANSWER NOW/i.test(line))
             return line;
         const stripped = stripPositiveAnswerNowFromLine(line);
         if (stripped.changed)
@@ -1270,7 +1324,7 @@ function reconcilePartialAnswerNow(text) {
         .join('\n');
     if (!changed)
         return text;
-    return `${out}\n\n> This survey is a **Partial locator**: the sections above are anchors, not a closed answer. Continue with the narrower lookup named above, or a text search, before answering.`;
+    return `${out}\n\n> This survey is a **Partial locator**: the sections above are anchors, not a closed answer. Inspect missing source with a focused lookup, continue the requested edits, and verify the resulting code.`;
 }
 class ToolHandler {
     cg;
@@ -1459,8 +1513,11 @@ class ToolHandler {
                 'homegraph_search',
                 'homegraph_node',
                 'homegraph_diff_impact',
+                'homegraph_project',
             ]);
-            if (stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
+            // An explicit host selection overrides the default size-based surface.
+            // Otherwise small ArkTS repos silently lose requested specialized tools.
+            if (!allow && stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name));
             }
             return visible.map(tool => {
@@ -1854,6 +1911,10 @@ class ToolHandler {
      * it (the CLI does) and explore behaves exactly as before, untracked.
      */
     async execute(toolName, args, sessionState) {
+        const requestStartedAt = Date.now();
+        args = { ...args };
+        for (const key of [QUERY_PLAN_ARG, QUERY_DEADLINE_ARG, QUERY_STARTED_ARG, QUERY_INDEX_STATE_ARG, QUERY_FAST_ATTEMPTED_ARG])
+            delete args[key];
         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
@@ -1894,13 +1955,37 @@ class ToolHandler {
                     return check;
             }
             const projectPath = args.projectPath;
+            if (toolName === 'homegraph_explore' && process.env.HOMEGRAPH_QUERY_PLANNER !== 'off') {
+                const query = this.validateString(args.query, 'query');
+                if (typeof query !== 'string')
+                    return query;
+                const cg = this.getHomeGraph(projectPath);
+                const gated = this.maybeDeepToolPhaseGate(cg, toolName);
+                if (gated)
+                    return gated;
+                // Refused repeats must not spend a model call or re-serve cached evidence.
+                if (sessionState) {
+                    const repeat = (0, explore_repeat_guard_1.decideExploreRepeat)(sessionState.forProject(cg.getProjectRoot()), query);
+                    if (this.shouldRefuseRepeatedEvidence(repeat, cg.getProjectRoot())) {
+                        return this.textResult((0, explore_repeat_guard_1.formatExploreRepeatRefuse)(repeat, query));
+                    }
+                }
+                args[QUERY_STARTED_ARG] = requestStartedAt;
+                args[QUERY_DEADLINE_ARG] = Date.now() + (0, query_pool_1.resolveToolDeadlineMs)();
+                args[QUERY_PLAN_ARG] = await (0, query_plan_1.planQuery)(query, {
+                    deadlineAt: args[QUERY_DEADLINE_ARG],
+                    taskContext: (0, query_plan_1.mergeQueryPlanTaskContext)(process.env.HOMEGRAPH_QUERY_TASK_CONTEXT, typeof args.taskContext === 'string' ? args.taskContext : undefined),
+                    validateAnchor: (anchor) => this.isExactPlanAnchor(cg, anchor),
+                });
+                args[QUERY_INDEX_STATE_ARG] = `${cg.getBuildPhase()}:${cg.getStats().nodeCount}:${cg.getLastIndexedAt() ?? 0}`;
+            }
             // Wrong question shapes → short Skip (before cache / graph work).
             if (toolName === 'homegraph_explore' || toolName === 'homegraph_search') {
                 const qEarly = typeof args.query === 'string' ? args.query : '';
                 if (qEarly) {
                     const deferKind = (0, query_utils_1.queryShouldDeferToBuiltinTools)(qEarly);
-                    if (deferKind) {
-                        return this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, qEarly));
+                    if (deferKind && readQueryPlan(args)?.source !== 'llm') {
+                        return this.withQueryPlanDiagnostics(this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, qEarly)), args);
                     }
                 }
             }
@@ -1917,7 +2002,9 @@ class ToolHandler {
             // Session-tracked explore must not hit the MCP query cache: a cache hit
             // would re-serve the first call's full source and defeat CG-18 dedup.
             const skipCacheForSession = toolName === 'homegraph_explore' && !!sessionState;
-            const cacheEnabled = !skipCacheForSession && (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
+            const requestPlan = readQueryPlan(args);
+            const cacheEnabled = !skipCacheForSession && requestPlan?.source !== 'llm'
+                && !requestPlan?.telemetry.fallbackReason && (0, query_cache_1.isMcpQueryCacheEnabled)() && (0, query_cache_1.isCacheableMcpTool)(toolName);
             let cacheKey;
             let cacheQueries;
             let cacheIndex;
@@ -1937,7 +2024,8 @@ class ToolHandler {
                     cacheKey = (0, query_cache_1.buildMcpQueryCacheKey)(toolName, args, fileCount);
                     const cached = cacheIndex.getEntry(cacheQueries, cacheKey);
                     if (cached) {
-                        const withWorktree = this.withWorktreeNotice(cached, projectPath);
+                        const diagnosed = this.withQueryPlanDiagnostics(cached, args, true);
+                        const withWorktree = this.withWorktreeNotice(diagnosed, projectPath);
                         return this.withStalenessNotice(withWorktree, projectPath);
                     }
                 }
@@ -1953,27 +2041,43 @@ class ToolHandler {
             if (toolName === 'homegraph_status') {
                 return await this.handleStatus(args);
             }
+            // While auto-init is still on the fast/indexing phases (no symbols yet),
+            // deep tools return guidance so the agent uses homegraph_project instead
+            // of abandoning HomeGraph after empty explore results.
+            if (toolName !== 'homegraph_project') {
+                try {
+                    const gated = this.maybeDeepToolPhaseGate(this.getHomeGraph(projectPath), toolName);
+                    if (gated)
+                        return gated;
+                }
+                catch {
+                    /* NotIndexed / sources disabled — fall through to normal handlers */
+                }
+            }
             // Every read tool races a deadline ≪ MCP client ~60s hard timeout and
             // Named-member / local-compact questions finish in tens of ms on the warm
             // main connection. Serving them here — before the query-pool offload —
             // avoids cold-worker / wedged-daemon paths that otherwise surface as empty
             // MCP client `-32001` (the handler itself is fine; the transport times out).
-            if (toolName === 'homegraph_explore' || toolName === 'homegraph_search') {
+            if ((toolName === 'homegraph_explore' || toolName === 'homegraph_search')
+                && (!requestPlan || (requestPlan.source === 'rules' && requestPlan.steps.length === 1
+                    && !requestPlan.telemetry.requestCount))) {
                 const q = typeof args.query === 'string' ? args.query : '';
                 if (q) {
                     try {
                         const cgFast = this.getHomeGraph(projectPath);
                         const rootFast = cgFast.getProjectRoot();
-                        const fast = (toolName === 'homegraph_explore'
-                            ? this.trySpecializedExploreRoute(cgFast, q, rootFast)
-                            : null)
-                            ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
-                                ? this.tryFastInventoryExplore(cgFast, q, rootFast)
-                                : null)
-                            ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
-                                ? this.tryLightMechanismExplore(cgFast, q, rootFast)
+                        const fast = requestPlan ? this.tryPlannedFastPath(cgFast, requestPlan, rootFast) :
+                            (toolName === 'homegraph_explore'
+                                ? this.trySpecializedExploreRoute(cgFast, q, rootFast)
                                 : null)
-                            ?? this.tryCompactLocalSymbolExplore(cgFast, q, rootFast);
+                                ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
+                                    ? this.tryFastInventoryExplore(cgFast, q, rootFast)
+                                    : null)
+                                ?? (toolName === 'homegraph_explore' || toolName === 'homegraph_search'
+                                    ? this.tryLightMechanismExplore(cgFast, q, rootFast)
+                                    : null)
+                                ?? this.tryCompactLocalSymbolExplore(cgFast, q, rootFast);
                         if (fast) {
                             // Fast explore must still file Partial/ANSWER meta into the session
                             // so explore + depth fuses see it (textResult-only paths used to skip).
@@ -1981,12 +2085,15 @@ class ToolHandler {
                             if (toolName === 'homegraph_explore' && sessionState) {
                                 served = this.takeExploreEmission(this.ensureExploreEmission(fast, rootFast, q), sessionState);
                             }
+                            served = this.withQueryPlanDiagnostics(served, args);
                             if (cacheEnabled && cacheKey && cacheQueries && cacheIndex && !served.isError) {
                                 cacheIndex.setEntry(cacheQueries, cacheKey, toolName, served);
                             }
                             const withWorktree = this.withWorktreeNotice(served, projectPath);
                             return this.withStalenessNotice(withWorktree, projectPath);
                         }
+                        if (requestPlan)
+                            args[QUERY_FAST_ATTEMPTED_ARG] = true;
                     }
                     catch {
                         // Not indexed / path issue — fall through to normal dispatch.
@@ -2002,7 +2109,7 @@ class ToolHandler {
             // (a frozen main loop prevents setTimeout deadlines from firing → empty
             // `-32001`). Fast-path surveys run inside the worker via executeReadTool.
             const raw = await this.runReadToolWithDeadline(toolName, dispatchArgs);
-            const result = this.takeExploreEmission(raw, sessionState);
+            const result = this.withQueryPlanDiagnostics(this.takeExploreEmission(raw, sessionState), args);
             if (sessionState
                 && !result.isError
                 && (toolName === 'homegraph_node'
@@ -2078,16 +2185,67 @@ class ToolHandler {
             return null;
         }
     }
+    /** A repeated query is duplicate evidence only while its source is unchanged. */
+    shouldRefuseRepeatedEvidence(decision, projectRoot) {
+        if (!decision.refuse)
+            return false;
+        // Source changes do not reset the total retrieval budget.
+        if (decision.reason !== 'overlap')
+            return true;
+        const files = decision.matched?.files.filter((file) => file.bytes > 0 && file.ranges.length > 0) ?? [];
+        if (files.length === 0 || files.length > 24)
+            return false;
+        let remainingBytes = 2 * 1024 * 1024;
+        for (const file of files) {
+            if (!file.fingerprint)
+                return false;
+            const absolute = (0, utils_1.validatePathWithinRoot)(projectRoot, file.path);
+            if (!absolute)
+                return false;
+            let descriptor;
+            try {
+                const stat = (0, fs_1.statSync)(absolute);
+                const limit = Math.min(1024 * 1024, remainingBytes);
+                if (!stat.isFile() || stat.size > limit)
+                    return false;
+                // Fixed-size reads also remain bounded if the file grows after stat.
+                descriptor = (0, fs_1.openSync)(absolute, 'r');
+                const buffer = Buffer.alloc(stat.size + 1);
+                let bytes = 0;
+                while (bytes < buffer.length) {
+                    const read = (0, fs_1.readSync)(descriptor, buffer, bytes, buffer.length - bytes, bytes);
+                    if (read === 0)
+                        break;
+                    bytes += read;
+                }
+                if (bytes !== stat.size)
+                    return false;
+                remainingBytes -= bytes;
+                if ((0, explore_dedup_1.fileFingerprint)(buffer.subarray(0, bytes).toString('utf8')) !== file.fingerprint)
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            finally {
+                if (descriptor !== undefined) {
+                    try {
+                        (0, fs_1.closeSync)(descriptor);
+                    }
+                    catch { /* bookkeeping only */ }
+                }
+            }
+        }
+        return true;
+    }
     /** Count a successful depth-tool call when the latest explore was Partial. */
     noteDepthToolUse(args, sessionState) {
         try {
             const cg = this.getHomeGraph(args.projectPath);
             const root = cg.getProjectRoot();
             const prior = sessionState.forProject(root);
-            const last = prior?.calls.length
-                ? [...prior.calls].reverse().find((c) => (c.responseBytes || 0) >= 400)
-                : undefined;
-            if (!last?.partial)
+            const last = prior?.calls[prior.calls.length - 1];
+            if (!last || (0, explore_session_state_1.inferExploreEvidenceStatus)(last) === 'complete')
                 return;
             sessionState.recordDepthTool(root);
         }
@@ -2107,17 +2265,22 @@ class ToolHandler {
         const emission = result?.[explore_session_state_1.EXPLORE_EMISSION_KEY];
         if (emission === undefined)
             return result;
+        emission.evidenceStatus = (0, explore_session_state_1.inferExploreEvidenceStatus)(emission);
+        emission.partial = emission.evidenceStatus !== 'complete';
+        result._meta = { ...result._meta, homegraphEvidence: { status: emission.evidenceStatus,
+                files: emission.files, locatedNodes: emission.locatedNodes, coveredObligations: emission.coveredObligations,
+                uncoveredObligations: emission.uncoveredObligations } };
         delete result[explore_session_state_1.EXPLORE_EMISSION_KEY];
         if (sessionState) {
             try {
                 const prior = sessionState.forProject(emission.projectRoot);
-                const priorPartials = (prior?.calls ?? []).filter((c) => c.partial === true && (c.responseBytes || 0) >= 400);
+                const priorPartials = (prior?.calls ?? []).filter((c) => (0, explore_session_state_1.inferExploreEvidenceStatus)(c) !== 'complete');
                 const metaPartial = emission.partial === true
                     || (emission.partial === undefined
                         && (0, explore_repeat_guard_1.inferExplorePartialMeta)(result.content?.[0]?.text ?? '').partial);
                 if (metaPartial && priorPartials.length >= 1) {
                     const text = result.content?.[0]?.text ?? '';
-                    if (text && !/Second Partial — stop HomeGraph/i.test(text)) {
+                    if (text && !/Second Partial/i.test(text)) {
                         const stop = (0, explore_repeat_guard_1.formatSecondPartialStopFooter)(emission.nextAnchor);
                         result = {
                             ...result,
@@ -2150,12 +2313,19 @@ class ToolHandler {
      * the success-shaped reply never flushed → empty client `-32001`.
      */
     async runReadToolWithDeadline(toolName, args) {
-        const deadlineMs = (0, query_pool_1.resolveToolDeadlineMs)();
+        const deadlineMs = typeof args[QUERY_DEADLINE_ARG] === 'number'
+            ? Math.max(0, Math.min((0, query_pool_1.resolveToolDeadlineMs)(), args[QUERY_DEADLINE_ARG] - Date.now()))
+            : (0, query_pool_1.resolveToolDeadlineMs)();
+        if (deadlineMs <= 0)
+            return this.deadlineBusyResult((0, query_pool_1.resolveToolDeadlineMs)(), args);
         const light = toolName === 'homegraph_search'
             || toolName === 'homegraph_node'
             || toolName === 'homegraph_callers'
             || toolName === 'homegraph_callees'
-            || toolName === 'homegraph_files';
+            || toolName === 'homegraph_files'
+            || toolName === 'homegraph_project'
+            // Project maps may be built on demand: never run them on a read worker.
+            || (readQueryPlan(args)?.steps.some((step) => step.intent === 'overview') ?? false);
         const work = () => {
             if (!light && this.queryPool && this.queryPool.healthy) {
                 return this.queryPool.run(toolName, args, {
@@ -2210,6 +2380,14 @@ class ToolHandler {
      */
     async executeReadTool(toolName, args) {
         try {
+            if (toolName !== 'homegraph_project' && toolName !== 'homegraph_status') {
+                const gate = this.maybeDeepToolPhaseGate(this.getHomeGraph(args.projectPath), toolName);
+                if (gate)
+                    return gate;
+            }
+            const plan = toolName === 'homegraph_explore' ? readQueryPlan(args) : undefined;
+            if (plan)
+                return await this.executeQueryPlan(args, plan);
             // Compact inventory / one-symbol surveys — safe on the worker (keeps the
             // daemon main loop free). Never run these unprotected on the MCP transport
             // thread: they can block long enough for the client to emit empty `-32001`.
@@ -2240,6 +2418,16 @@ class ToolHandler {
      * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
      */
     async dispatchTool(toolName, args) {
+        if (toolName !== 'homegraph_project' && toolName !== 'homegraph_status') {
+            try {
+                const gated = this.maybeDeepToolPhaseGate(this.getHomeGraph(args.projectPath), toolName);
+                if (gated)
+                    return gated;
+            }
+            catch {
+                /* fall through */
+            }
+        }
         switch (toolName) {
             case 'homegraph_search': return await this.handleSearch(args);
             case 'homegraph_callers': return await this.handleCallers(args);
@@ -2252,6 +2440,7 @@ class ToolHandler {
             case 'homegraph_native': return await this.handleSpecializedNative(args);
             case 'homegraph_node': return await this.handleNode(args);
             case 'homegraph_files': return await this.handleFiles(args);
+            case 'homegraph_project': return await this.handleProject(args);
             case 'homegraph_arkui_migrate': return await this.handleArkuiMigrate(args);
             case 'homegraph_spec_match': return await this.handleSpecMatch(args);
             case 'homegraph_spec_find': return await this.handleSpecFind(args);
@@ -2259,6 +2448,36 @@ class ToolHandler {
             default: return this.errorResult(`Unknown tool: ${toolName}`);
         }
     }
+    /**
+     * Gate symbol/graph tools while auto-init is still on the fast map or
+     * background full index (and no nodes exist yet). Success-shaped guidance —
+     * never isError — so agents keep using HomeGraph.
+     */
+    maybeDeepToolPhaseGate(cg, _toolName) {
+        const phase = cg.getBuildPhase();
+        if (phase === 'full')
+            return null;
+        try {
+            if (cg.getStats().nodeCount > 0)
+                return null;
+        }
+        catch {
+            /* ignore */
+        }
+        if (phase === 'fast' || phase === 'indexing') {
+            return this.textResult([
+                `Full symbol index is still building (phase=${phase}).`,
+                'Use `homegraph_project` for the module/file map now, then retry this tool once indexing finishes.',
+            ].join('\n'));
+        }
+        if (phase === 'building_fast' || phase === 'none') {
+            return this.textResult([
+                'HomeGraph is still preparing the project map.',
+                'Retry in a few seconds, or call `homegraph_project` once the fast build completes.',
+            ].join('\n'));
+        }
+        return null;
+    }
     async handleSearch(args) {
         const query = this.validateString(args.query, 'query');
         if (typeof query !== 'string')
@@ -5054,9 +5273,261 @@ class ToolHandler {
         lines.push('');
         return { section: lines.join('\n'), hitCount: locs.length + edges.length + extendsHits.length };
     }
-    /**
-     * Main-thread fast path for inventory surveys — skips the worker queue.
-     */
+    /** Exact validation for model-proposed names: a fuzzy hit is not proof. */
+    isExactPlanAnchor(cg, anchor) {
+        if (!anchor || anchor.length > 256)
+            return false;
+        try {
+            const matches = cg.searchNodes(anchor, { limit: 12 });
+            return matches.some(({ node }) => node.name === anchor || node.qualifiedName === anchor
+                || node.filePath.replace(/\\/g, '/') === anchor.replace(/\\/g, '/'));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Bind only declarations returned by this step, not input or global fuzzy hits. */
+    locatedPlanBindings(cg, result, inherited) {
+        const seen = new Set(inherited.map((binding) => binding.id));
+        const declarations = new Set(inherited.map((binding) => `${binding.filePath}:${binding.startLine}:${binding.name}`));
+        const located = [];
+        for (const receipt of (result[explore_session_state_1.EXPLORE_EMISSION_KEY]?.locatedNodes ?? []).slice(0, 32)) {
+            if (seen.has(receipt.id) || declarations.has(`${receipt.filePath}:${receipt.startLine}:${receipt.name}`))
+                continue;
+            const node = cg.getNode(receipt.id);
+            if (!node || ['file', 'import', 'export', 'parameter'].includes(node.kind)
+                || node.name === 'constructor' || node.name.startsWith('%AM') || node.filePath.includes('@dummy')
+                || node.name !== receipt.name || node.filePath !== receipt.filePath || node.startLine !== receipt.startLine
+                || node.qualifiedName !== receipt.qualifiedName)
+                continue;
+            seen.add(node.id);
+            declarations.add(`${node.filePath}:${node.startLine}:${node.name}`);
+            located.push({ id: node.id, name: node.name, qualifiedName: node.qualifiedName,
+                filePath: node.filePath, startLine: node.startLine });
+            if (located.length >= 8)
+                break;
+        }
+        return located;
+    }
+    withQueryPlanDiagnostics(result, args, cacheHit = false) {
+        const plan = readQueryPlan(args);
+        if (!plan)
+            return result;
+        const prior = result._meta?.homegraphQueryPlan;
+        const started = typeof args[QUERY_STARTED_ARG] === 'number' ? args[QUERY_STARTED_ARG] : Date.now();
+        return { ...result, _meta: { ...result._meta, homegraphQueryPlan: {
+                    ...prior, version: plan.version, source: plan.source, intent: plan.intent, route: plan.route,
+                    confidence: plan.confidence,
+                    plannerSeeds: { anchors: plan.anchors, searchTerms: plan.searchTerms, literalTexts: plan.literalTexts,
+                        sourceScope: plan.sourceScope, relation: plan.relation },
+                    hasTaskContext: !!plan.taskContext,
+                    matchedFeatures: Object.entries(plan.features).filter(([, matched]) => matched).map(([name]) => name).slice(0, 12),
+                    planningMs: plan.telemetry.durationMs, durationMs: Math.max(plan.telemetry.durationMs, Date.now() - started),
+                    modelRequests: plan.telemetry.requestCount ?? 0,
+                    planningEligible: plan.telemetry.decision?.eligible,
+                    planningReason: plan.telemetry.decision?.reason,
+                    skip_reason: plan.telemetry.decision?.eligible === false ? plan.telemetry.decision.reason : undefined,
+                    ruleRoute: plan.telemetry.decision?.ruleRoute,
+                    inputTokens: plan.telemetry.inputTokens ?? (plan.telemetry.requestCount ? null : 0),
+                    outputTokens: plan.telemetry.outputTokens ?? (plan.telemetry.requestCount ? null : 0),
+                    fallbackReason: plan.telemetry.fallbackReason, cacheHit,
+                    steps: cacheHit ? [] : prior?.steps ?? [{ id: plan.steps[0]?.id, intent: plan.intent,
+                            status: result.isError ? 'failed'
+                                : (0, explore_repeat_guard_1.inferExplorePartialMeta)(result.content[0]?.text ?? '').partial ? 'partial'
+                                    : /Status: (?:no_indexed_evidence|not_surveyed)|No relevant code|Skip HomeGraph/i.test(result.content[0]?.text ?? '')
+                                        ? 'no_evidence' : 'evidence', resolvedAnchors: [] }],
+                } } };
+    }
+    /** Select once; legacy section builders consume the same canonical query/features. */
+    tryPlannedFastPath(cg, plan, root) {
+        const query = plan.canonicalQuery;
+        if (plan.route === 'usages' || plan.route === 'modules' || plan.route === 'native') {
+            return this.runSpecializedExploreRoute(plan.route, cg, query, root, plan);
+        }
+        // These legacy paths re-extract seeds from text and cannot consume bound
+        // node identity / step hints. Model general/flow plans use full explore;
+        // rule/default and specialized routes retain their existing fast behavior.
+        if (plan.source === 'llm' && (plan.intent === 'general' || plan.intent === 'flow'))
+            return null;
+        return this.tryFastInventoryExplore(cg, query, root, plan)
+            ?? this.tryLightMechanismExplore(cg, query, root, plan)
+            ?? this.tryCompactLocalSymbolExplore(cg, query, root, plan);
+    }
+    /** Internal execution only: no recursive MCP calls, model requests or new deadline. */
+    async executePlannedStep(args, plan) {
+        const cg = this.getHomeGraph(args.projectPath);
+        if (plan.intent === 'overview') {
+            return this.handleProject({ projectPath: args.projectPath });
+        }
+        const gate = this.maybeDeepToolPhaseGate(cg, 'homegraph_explore');
+        if (gate)
+            return gate;
+        const query = plan.canonicalQuery;
+        const defer = (0, query_utils_1.queryShouldDeferToBuiltinTools)(query);
+        if (defer && plan.source === 'rules')
+            return this.textResult((0, query_utils_1.homegraphDeferGuidance)(defer, query));
+        // A typed relationship still needs a real target. Discover source from the
+        // same bounded hints first; do not turn an unanchored usage request into an
+        // empty survey or claim that its reference obligation has been covered.
+        if (plan.source === 'llm' && plan.route === 'usages'
+            && !plan.anchors.length && !plan.bindings?.length) {
+            const result = await this.handleExplore({ ...args, query, [QUERY_PLAN_ARG]: plan });
+            const served = this.ensureExploreEmission(result, cg.getProjectRoot(), plan.originalQuery);
+            const emission = served[explore_session_state_1.EXPLORE_EMISSION_KEY];
+            emission.partial = true;
+            emission.evidenceStatus = emission.sourceBytes > 0 ? 'partial' : 'empty';
+            emission.coveredObligations = [];
+            emission.uncoveredObligations = [plan.relation ?? 'incoming_references'];
+            if (served.content[0]?.type === 'text')
+                served.content[0].text =
+                    '**Reference target discovery — partial**\nSource candidates follow. Verify the relevant target before surveying its references; the reference obligation remains open.\n\n'
+                        + served.content[0].text;
+            return served;
+        }
+        const fast = args[QUERY_FAST_ATTEMPTED_ARG] === true && plan.source === 'rules'
+            ? null : this.tryPlannedFastPath(cg, plan, cg.getProjectRoot());
+        if (fast)
+            return fast;
+        return this.handleExplore({ ...args, query, [QUERY_PLAN_ARG]: plan });
+    }
+    async executeQueryPlan(args, plan) {
+        const cg = this.getHomeGraph(args.projectPath);
+        const root = cg.getProjectRoot();
+        const deadline = typeof args[QUERY_DEADLINE_ARG] === 'number'
+            ? args[QUERY_DEADLINE_ARG] : Date.now() + (0, query_pool_1.resolveToolDeadlineMs)();
+        const prior = (0, explore_session_state_1.viewForProject)((0, explore_session_state_1.readExploreSessionView)(args), root);
+        const repeat = (0, explore_repeat_guard_1.decideExploreRepeat)(prior, plan.originalQuery);
+        if (this.shouldRefuseRepeatedEvidence(repeat, root)) {
+            return this.textResult((0, explore_repeat_guard_1.formatExploreRepeatRefuse)(repeat, plan.originalQuery));
+        }
+        const multi = plan.steps.length > 1;
+        let outputBudget = Math.min(MAX_OUTPUT_LENGTH, getExploreOutputBudget(cg.getStats().fileCount).maxOutputChars);
+        if (!Number.isFinite(outputBudget))
+            outputBudget = MAX_OUTPUT_LENGTH;
+        const constraints = [plan.originalQuery, plan.taskContext].filter(Boolean).join('\n');
+        const constraintLimit = Math.min(2000, Math.floor(outputBudget / 5));
+        const constraintNotice = constraints.length > constraintLimit
+            ? constraints.slice(0, constraintLimit) + '\n[Constraint display shortened; the original task remains authoritative.]'
+            : constraints;
+        const preamble = [
+            '**Planned exploration — Partial locator**',
+            '> **Partial locator** — scoped subquestion evidence, not proof that every requirement in the original question is covered.',
+            '**Task constraints (not search seeds or verified source evidence)**\n' + constraintNotice,
+        ].join('\n\n');
+        const pieces = [];
+        const diagnostics = [];
+        const bindings = new Map();
+        const files = [];
+        const seenQueries = new Set();
+        let single;
+        let used = multi ? preamble.length + 400 : 400;
+        for (const step of plan.steps.slice(0, 3)) {
+            const started = Date.now();
+            const diagnostic = { id: step.id, intent: step.intent, status: 'pending', resolvedAnchors: [],
+                locatedNodes: [], durationMs: 0 };
+            diagnostics.push(diagnostic);
+            if (Date.now() >= deadline || used >= outputBudget) {
+                diagnostic.status = 'budget_exhausted';
+                pieces.push(`**Step ${step.id}: ${step.intent}** — not executed: shared request budget exhausted.`);
+                continue;
+            }
+            if (step.dependsOn.some((id) => !bindings.get(id)?.length)) {
+                diagnostic.status = 'dependency_unresolved';
+                pieces.push(`**Step ${step.id}: ${step.intent}** — not executed: predecessor supplied no resolved symbol anchors.`);
+                continue;
+            }
+            const resolved = step.dependsOn.flatMap((id) => bindings.get(id) ?? []);
+            // Keep rule-only single queries byte-compatible; only model subplans are adapted.
+            const compiled = plan.source === 'rules' && !multi ? plan : {
+                ...(0, query_plan_1.compileQueryPlanStep)(plan, step, resolved.map((node) => node.qualifiedName || node.name)), bindings: resolved,
+            };
+            if (seenQueries.has(`${compiled.intent}:${compiled.canonicalQuery}`)) {
+                diagnostic.status = 'duplicate_skipped';
+                pieces.push(`**Step ${step.id}: ${step.intent}** — duplicate query skipped.`);
+                continue;
+            }
+            seenQueries.add(`${compiled.intent}:${compiled.canonicalQuery}`);
+            try {
+                const result = await this.executePlannedStep({ ...args, [QUERY_DEADLINE_ARG]: deadline }, compiled);
+                const body = result.content.map((part) => part.text).join('\n');
+                const candidates = result.isError ? [] : this.locatedPlanBindings(cg, result, resolved);
+                const childEmission = result[explore_session_state_1.EXPLORE_EMISSION_KEY];
+                const hasLocalEvidence = candidates.length > 0 || (childEmission?.sourceBytes ?? 0) > 0;
+                diagnostic.status = result.isError ? 'failed'
+                    : childEmission?.evidenceStatus === 'complete' ? 'evidence'
+                        : hasLocalEvidence ? (childEmission?.partial ? 'partial' : 'evidence')
+                            : /HarmonyOS SDK API|ohos-sdk:/.test(body) ? 'sdk_only' : 'no_evidence';
+                if (!multi) {
+                    diagnostic.locatedNodes = candidates;
+                    diagnostic.resolvedAnchors = candidates.map((node) => node.name);
+                    single = result;
+                    break;
+                }
+                // A child cannot declare the original multi-part question answered.
+                let fenced = false;
+                const neutralBody = body.split('\n').filter((line) => {
+                    if (/^\s*```/.test(line)) {
+                        fenced = !fenced;
+                        return true;
+                    }
+                    return fenced || !/ANSWER NOW|Compact local explore complete|Do \*\*not\*\* (?:Read|Grep)|ONE tighter|ONE narrow/i.test(line);
+                }).join('\n');
+                const cap = Math.max(0, Math.floor((outputBudget - used) / Math.max(1, plan.steps.length - diagnostics.length + 1)) - 100);
+                // Keep the grounded location receipt before source trimming. Only the
+                // identities visibly delivered here may be consumed by the next step.
+                let receipt = '';
+                const visibleBindings = [];
+                const inline = (value) => value.replace(/[`\r\n]/g, ' ');
+                for (const candidate of candidates) {
+                    const next = (receipt ? '' : '**Located source candidates — relevance still needs verification**\n')
+                        + `- \`${inline(candidate.qualifiedName || candidate.name)}\` — \`${inline(candidate.filePath)}:${candidate.startLine}\`\n`;
+                    if (receipt.length + next.length > Math.min(1600, Math.floor(cap / 2)))
+                        break;
+                    receipt += next;
+                    visibleBindings.push(candidate);
+                }
+                diagnostic.locatedNodes = visibleBindings;
+                diagnostic.resolvedAnchors = visibleBindings.map((node) => node.name);
+                bindings.set(step.id, visibleBindings);
+                const bodyCap = Math.max(0, cap - receipt.length - 2);
+                const trimmed = neutralBody.length > bodyCap;
+                const kept = (0, evidence_rendering_1.trimEvidenceAtLine)(neutralBody, bodyCap);
+                if (trimmed)
+                    diagnostic.status = 'partial';
+                else
+                    files.push(...(result[explore_session_state_1.EXPLORE_EMISSION_KEY]?.files ?? []));
+                const piece = `**Step ${step.id}: ${step.intent}** (${diagnostic.status})\n${receipt}\n${kept}`;
+                pieces.push(piece);
+                used += piece.length;
+            }
+            catch (error) {
+                if (error instanceof PathRefusalError)
+                    throw error;
+                diagnostic.status = 'failed';
+                pieces.push(`**Step ${step.id}: ${step.intent}** — retrieval failed; other step evidence is retained.`);
+            }
+            finally {
+                diagnostic.durationMs = Date.now() - started;
+            }
+            // Yield between synchronous graph stages so deadlines and MCP I/O can run.
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        const result = single ?? this.textResult([preamble, ...pieces].join('\n\n').slice(0, outputBudget));
+        const served = this.ensureExploreEmission(result, root, plan.originalQuery);
+        const emission = served[explore_session_state_1.EXPLORE_EMISSION_KEY];
+        emission.query = plan.originalQuery;
+        if (multi) {
+            emission.partial = true;
+            emission.evidenceStatus = 'partial';
+            emission.coveredObligations = diagnostics.filter((step) => step.status === 'evidence').map((step) => step.id);
+            emission.uncoveredObligations = diagnostics.filter((step) => step.status !== 'evidence').map((step) => step.id);
+            emission.files = files;
+            emission.sourceBytes = files.reduce((sum, file) => sum + file.bytes, 0);
+        }
+        served._meta = { ...served._meta, homegraphQueryPlan: { steps: diagnostics } };
+        return served;
+    }
+    /** Main-thread fast path for inventory surveys — skips the worker queue. */
     tryFastPathResult(toolName, args) {
         const query = args.query;
         if (typeof query !== 'string')
@@ -5104,11 +5575,13 @@ class ToolHandler {
             : null;
     }
     /** Run exactly one bounded survey family and expose the selected route. */
-    runSpecializedExploreRoute(route, cg, query, projectRoot) {
+    runSpecializedExploreRoute(route, cg, query, projectRoot, plan) {
         let section = '';
         let status = 'no_indexed_evidence';
         let coverage = '';
         if (route === 'modules') {
+            if (plan?.relation === 'module_imports')
+                return this.renderModuleImports(cg, plan);
             const manifestResult = this.buildFocusedModuleManifestSection(projectRoot, query);
             const graphResult = manifestResult.manifestCount === 0
                 ? this.buildModuleDependencySurveySection(cg, query)
@@ -5126,10 +5599,10 @@ class ToolHandler {
             coverage = 'named path/Type NAPI export registrations only; no domain file dump was built';
         }
         else {
-            const apiUsage = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
+            const apiUsage = planFeature(plan, 'shouldBuildApiUsageSurvey', query, query_utils_1.shouldBuildApiUsageSurvey)
                 ? this.buildApiUsageSection(cg, query, projectRoot)
                 : { section: '', fileCount: 0 };
-            const memberUsage = (0, query_utils_1.shouldBuildMemberSurvey)(query)
+            const memberUsage = planFeature(plan, 'shouldBuildMemberSurvey', query, query_utils_1.shouldBuildMemberSurvey)
                 && !((0, query_utils_1.queryAsFieldUsageSurvey)(query) && apiUsage.fileCount > 0)
                 ? this.buildMemberSurveySection(cg, query, projectRoot)
                 : '';
@@ -5147,13 +5620,43 @@ class ToolHandler {
             || (status === 'not_surveyed'
                 ? '- No survey ran: this query carries no symbol name to scan. Re-run naming the symbol(s), or use `homegraph_explore`.'
                 : '- No matching evidence was found in the current index for this focused survey.');
-        return this.textResult(this.truncateOutput([
+        const text = this.truncateOutput([
             `**HomeGraph specialized route: ${route}**`,
             `Status: ${status}`,
             `Coverage: ${coverage}.`,
             '',
             body,
-        ].join('\n')));
+        ].join('\n'));
+        return this.exploreResult(text, { projectRoot, query, files: [], sourceBytes: 0,
+            responseBytes: text.length, evidenceStatus: status === 'complete' ? 'complete' : 'empty',
+            partial: status !== 'complete', coveredObligations: status === 'complete' ? [plan?.relation ?? route] : [],
+            uncoveredObligations: status !== 'complete' ? [plan?.relation ?? route] : [] });
+    }
+    /** Directed file import witnesses for an explicit module-import relation. */
+    renderModuleImports(cg, plan) {
+        const scope = [...new Set([...plan.anchors, ...(plan.bindings ?? []).map(node => node.filePath)])]
+            .map(value => value.replace(/\\/g, '/')).filter(Boolean);
+        const paths = cg.getFiles().map(file => file.path).filter(file => scope.some(anchor => file === anchor || file.startsWith(anchor + '/') || file.split('/').includes(anchor)));
+        const rows = [];
+        let scanned = 0;
+        for (const file of paths.slice(0, 120)) {
+            scanned++;
+            for (const target of cg.getFileDependencies(file)) {
+                rows.push(`- \`${file}\` imports → \`${target}\``);
+                if (rows.length >= 40)
+                    break;
+            }
+            if (rows.length >= 40)
+                break;
+        }
+        const partial = scanned < paths.length || rows.length >= 40;
+        const text = ['**Directed module imports**',
+            rows.length ? rows.join('\n') : 'No indexed import edges found for the supplied module paths.',
+            `Coverage: ${scanned} of ${paths.length} scoped files scanned; cycle analysis was not requested.`].join('\n\n');
+        return this.exploreResult(text, { projectRoot: cg.getProjectRoot(), query: plan.originalQuery,
+            files: [], sourceBytes: 0, responseBytes: text.length,
+            evidenceStatus: !rows.length ? 'empty' : partial ? 'partial' : 'complete',
+            partial: partial || !rows.length });
     }
     /** Usage sites for a bare symbol bag, including non-call textual references. */
     buildBareSymbolUsageSection(cg, query, projectRoot) {
@@ -5315,10 +5818,10 @@ class ToolHandler {
     /**
      * Fast inventory-only explore — skips findRelevantContext for survey/caller/dependency queries.
      */
-    tryFastInventoryExplore(cg, query, projectRoot) {
-        if (!(0, query_utils_1.shouldTryFastInventoryExplore)(query))
+    tryFastInventoryExplore(cg, query, projectRoot, plan) {
+        if (!planFeature(plan, 'shouldTryFastInventoryExplore', query, query_utils_1.shouldTryFastInventoryExplore))
             return null;
-        // Multi-Type dependency asks: inventory-only early exit (avoids fat compact / 25s busy).
+        // Multi-Type dependency asks: inventory-only early exit (avoids fat compact / busy timeout).
         if ((0, query_utils_1.queryAsMultiTypeDependencySurvey)(query)) {
             const multi = this.buildMultiTypeDependencySection(cg, query);
             if (multi.section) {
@@ -5720,8 +6223,8 @@ class ToolHandler {
      * findRelevantContext. Fast enough for MCP budget; complete enough to avoid
      * agent grep/read loops (token savings).
      */
-    tryLightMechanismExplore(cg, query, projectRoot) {
-        if (!(0, query_utils_1.shouldTryLightMechanismExplore)(query))
+    tryLightMechanismExplore(cg, query, projectRoot, plan) {
+        if (!planFeature(plan, 'shouldTryLightMechanismExplore', query, query_utils_1.shouldTryLightMechanismExplore))
             return null;
         const STRUCTURE_KINDS = new Set(['class', 'struct', 'interface', 'component', 'method', 'function']);
         const isTestPath = (p) => /(^|\/)(tests?|spec)\//i.test(p) || /\.(test|spec)\./i.test(p);
@@ -6358,7 +6861,7 @@ class ToolHandler {
      * Compact explore for local-symbol behavior questions — skips findRelevantContext
      * and caps to 1–2 defining files (avoids the ~24K related-file dump).
      */
-    tryCompactLocalSymbolExplore(cg, query, projectRoot) {
+    tryCompactLocalSymbolExplore(cg, query, projectRoot, plan) {
         // Inventory runs *before* this on the call sites. Do not refuse compact
         // merely because inventory *intent* matched — empty inventory must fall
         // through here (bare callbacks like OnSurfaceChangedCB).
@@ -6372,8 +6875,13 @@ class ToolHandler {
         // Light-mechanism owns domain howtos. Bare "how/如何" NL must NOT veto compact
         // when a local/flag/lifecycle shape already owns the query (flag impact was
         // falling through to a 20k Dynamic-dispatch dump).
-        if ((0, query_utils_1.shouldTryLightMechanismExplore)(query))
+        if (planFeature(plan, 'shouldTryLightMechanismExplore', query, query_utils_1.shouldTryLightMechanismExplore))
             return null;
+        // Explicit `…/Foo.ets` path asks need file-scoped full explore, not compact
+        // trails seeded from path-segment homonyms (`/order/` → `order` property).
+        if ((0, query_utils_1.shouldLimitToQueryNamedFile)(query, false, (0, query_utils_1.queryNamesMultipleExploreAnchors)(query))) {
+            return null;
+        }
         if ((0, query_utils_1.queryAsMechanismSurvey)(query)
             && !(0, query_utils_1.queryAsLocalSymbolDetail)(query)
             && !(0, query_utils_1.queryAsAssignedFlagImpactSurvey)(query)
@@ -8994,8 +9502,10 @@ class ToolHandler {
         // One normalization point so the flow-builder, relevance search, and
         // ranking all see the same canonical spelling (Erlang `mod:fn/arity`).
         const query = normalizeQuerySpelling(rawQuery);
+        const plan = readQueryPlan(args);
+        const feature = (name, fallback) => planFeature(plan, name, query, fallback);
         const deferKind = (0, query_utils_1.queryShouldDeferToBuiltinTools)(query);
-        if (deferKind) {
+        if (deferKind && plan?.source !== 'llm') {
             return this.textResult((0, query_utils_1.homegraphDeferGuidance)(deferKind, query));
         }
         const cg = this.getHomeGraph(args.projectPath);
@@ -9003,7 +9513,7 @@ class ToolHandler {
         // Same-bag / call-budget refuse (session view injected by execute).
         const sessionPrior = (0, explore_session_state_1.viewForProject)((0, explore_session_state_1.readExploreSessionView)(args), projectRoot);
         const repeat = (0, explore_repeat_guard_1.decideExploreRepeat)(sessionPrior, query);
-        if (repeat.refuse) {
+        if (!plan && this.shouldRefuseRepeatedEvidence(repeat, projectRoot)) {
             const text = (0, explore_repeat_guard_1.formatExploreRepeatRefuse)(repeat, query);
             return this.exploreResult(text, {
                 projectRoot,
@@ -9013,7 +9523,8 @@ class ToolHandler {
                 responseBytes: text.length,
             });
         }
-        const compactLocal = this.tryFastInventoryExplore(cg, query, projectRoot)
+        // A planned step already tried fast paths once, before entering full explore.
+        const compactLocal = plan ? null : this.tryFastInventoryExplore(cg, query, projectRoot)
             ?? this.tryLightMechanismExplore(cg, query, projectRoot)
             ?? this.tryCompactLocalSymbolExplore(cg, query, projectRoot);
         if (compactLocal)
@@ -9033,19 +9544,53 @@ class ToolHandler {
         const explicitMaxFiles = typeof args.maxFiles === 'number' && !Number.isNaN(args.maxFiles);
         let maxFiles = (0, utils_1.clamp)(args.maxFiles || budget.defaultMaxFiles, 1, 20);
         const queryFileBasenames = (0, query_utils_1.extractFileBasenamesFromQuery)(query);
-        const interpretationQuery = (0, query_utils_1.queryAsInterpretationSurvey)(query);
-        const testOnlyInterpretation = (0, query_utils_1.queryAsTestOnlyInterpretation)(query);
-        const crossModuleFlow = (0, query_utils_1.queryAsCrossModuleFlowSurvey)(query);
+        const interpretationQuery = feature('queryAsInterpretationSurvey', query_utils_1.queryAsInterpretationSurvey);
+        const testOnlyInterpretation = feature('queryAsTestOnlyInterpretation', query_utils_1.queryAsTestOnlyInterpretation);
+        const crossModuleFlow = feature('queryAsCrossModuleFlowSurvey', query_utils_1.queryAsCrossModuleFlowSurvey) || plan?.intent === 'flow';
         // Step 1: Find relevant context with generous parameters.
         const contextOpts = interpretationQuery && queryFileBasenames.length === 1
             ? { searchLimit: 6, traversalDepth: 2, maxNodes: 60, minScore: 0.25 }
             : { searchLimit: 8, traversalDepth: 3, maxNodes: 200, minScore: 0.2 };
         const contextQuery = interpretationQuery && queryFileBasenames.length === 1
             ? `${queryFileBasenames[0]} ${query}`
-            : query;
-        const subgraph = await cg.findRelevantContext(contextQuery, contextOpts);
+            : queryFileBasenames.length === 1
+                ? `${queryFileBasenames[0]} ${query}`
+                : query;
+        const subgraph = await cg.findRelevantContext(contextQuery, {
+            ...contextOpts,
+            ...(plan && (plan.source === 'llm' || plan.literalTexts?.length) ? { retrievalHints: {
+                    symbols: plan.anchors.filter((anchor) => !(plan.bindings ?? []).some((node) => anchor === node.name || anchor === node.qualifiedName)),
+                    searchTerms: plan.searchTerms, literalTexts: plan.literalTexts, sourceScope: plan.sourceScope, nodeIds: (plan.bindings ?? []).map((node) => node.id),
+                } } : {}),
+        });
+        // Path-first: always seed nodes from an explicit `Foo.ets` basename so a
+        // CJK-only ask + path (or a shared prop like showSearchIcon) cannot leave
+        // the named file out of the subgraph / digests.
+        if (queryFileBasenames.length > 0 && plan?.sourceScope !== 'sdk') {
+            for (const base of queryFileBasenames.slice(0, 3)) {
+                let hits = [];
+                try {
+                    hits = cg.searchNodes(base, { limit: 50 });
+                }
+                catch {
+                    continue;
+                }
+                for (const r of hits) {
+                    if (!(0, query_utils_1.fileMatchesQueryBasename)(r.node.filePath, [base]))
+                        continue;
+                    if (!subgraph.nodes.has(r.node.id)) {
+                        subgraph.nodes.set(r.node.id, r.node);
+                        subgraph.roots.push(r.node.id);
+                    }
+                }
+            }
+        }
+        const literalSource = this.renderLiteralSource(cg, subgraph);
         if (subgraph.nodes.size === 0) {
-            return this.textResult(`No relevant code found for "${query}"`);
+            const text = literalSource.text || `No relevant code found for "${query}"`;
+            return this.exploreResult(text, { projectRoot, query, files: literalSource.files,
+                sourceBytes: literalSource.files.reduce((sum, file) => sum + file.bytes, 0), responseBytes: text.length,
+                locatedNodes: literalSource.nodes, partial: true, evidenceStatus: literalSource.text ? 'partial' : 'empty' });
         }
         // Seed import nodes for @kit.* / *Kit names (and named symbols like taskpool).
         const importTerms = (0, query_utils_1.extractImportSearchTerms)(query);
@@ -9184,8 +9729,8 @@ class ToolHandler {
                     namedParts.push(m[3]);
             }
             const tokens = [...new Set([
-                    ...namedParts,
-                    ...query.split(/[\s,()[\]]+/)
+                    ...(plan?.source === 'llm' ? plan.anchors : namedParts),
+                    ...(plan?.source === 'llm' ? plan.anchors.join(' ') : 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);
@@ -9212,7 +9757,8 @@ class ToolHandler {
                 const isQual = /[.\/]|::/.test(t);
                 const raw = isQual ? this.findAllSymbols(cg, t).nodes : cg.getNodesByName(t);
                 let cands = raw
-                    .filter((n) => SEED_KINDS.has(n.kind) && !isTestPath(n.filePath))
+                    .filter((n) => SEED_KINDS.has(n.kind) && !isTestPath(n.filePath)
+                    && !(plan?.sourceScope === 'local' && (0, arkts_1.isOhosApiFilePath)(n.filePath)))
                     .sort((a, b) => {
                     // Prefer callables over types when both share a name, then body size.
                     const ac = CALLABLE.has(a.kind) ? 1 : 0;
@@ -9427,6 +9973,8 @@ class ToolHandler {
             }
             fileGroups.set(node.filePath, group);
         }
+        for (const group of fileGroups.values())
+            group.nodes = (0, evidence_rendering_1.canonicalSourceDeclarations)(group.nodes);
         if (testOnlyInterpretation) {
             for (const [, group] of fileGroups) {
                 const fp = group.nodes[0]?.filePath ?? '';
@@ -9622,6 +10170,15 @@ class ToolHandler {
         const sortedFiles = relevantFiles.sort((a, b) => {
             const aPath = a[0].toLowerCase();
             const bPath = b[0].toLowerCase();
+            if (plan?.sourceScope === 'local') {
+                const sdkOrder = Number((0, arkts_1.isOhosApiFilePath)(a[0])) - Number((0, arkts_1.isOhosApiFilePath)(b[0]));
+                if (sdkOrder)
+                    return sdkOrder;
+            }
+            const literalOrder = Number((subgraph.literalEvidence?.hits ?? []).some((hit) => hit.filePath === b[0]))
+                - Number((subgraph.literalEvidence?.hits ?? []).some((hit) => hit.filePath === a[0]));
+            if (literalOrder)
+                return literalOrder;
             // Query-named file (LocationController.ets in the question) before partial
             // substring matches (control.ets matching "Controller" inside LocationController).
             const aExactBase = (0, query_utils_1.fileMatchesQueryBasename)(a[0], queryFileBasenames) ? 1 : 0;
@@ -9681,6 +10238,8 @@ class ToolHandler {
             '',
         ];
         const summaryLineIdx = 2;
+        if (literalSource.text)
+            lines.push(literalSource.text);
         if (testOnlyInterpretation) {
             lines.push('> **Test-file scope only** — answer from the named `.test.ets` file below; ' +
                 'production handlers are out of scope unless explicitly referenced in the test.');
@@ -9705,30 +10264,30 @@ class ToolHandler {
             : { section: '', symbolCount: 0 };
         if (kitUsageResult.section)
             lines.push(kitUsageResult.section);
-        const domainFileResult = (0, query_utils_1.shouldBuildDomainFileSurvey)(query)
+        const domainFileResult = feature('shouldBuildDomainFileSurvey', query_utils_1.shouldBuildDomainFileSurvey)
             ? this.buildDomainFileSurveySection(cg, query)
             : { section: '', fileCount: 0 };
         if (domainFileResult.section)
             lines.push(domainFileResult.section);
-        const apiUsageResult = (0, query_utils_1.shouldBuildApiUsageSurvey)(query)
-            && !(0, query_utils_1.shouldBuildKitModuleUsageSurvey)(query)
+        const apiUsageResult = feature('shouldBuildApiUsageSurvey', query_utils_1.shouldBuildApiUsageSurvey)
+            && !feature('shouldBuildKitModuleUsageSurvey', query_utils_1.shouldBuildKitModuleUsageSurvey)
             ? this.buildApiUsageSection(cg, query, projectRoot)
             : { section: '', fileCount: 0 };
         if (apiUsageResult.section)
             lines.push(apiUsageResult.section);
-        const dataSourceResult = (0, query_utils_1.queryAsDataSourceSurvey)(query)
+        const dataSourceResult = feature('queryAsDataSourceSurvey', query_utils_1.queryAsDataSourceSurvey)
             ? this.buildDataSourceSection(cg, query)
             : { section: '', edgeCount: 0, sdkImportCount: 0, strongCount: 0 };
         if (dataSourceResult.section)
             lines.push(dataSourceResult.section);
-        const eventDispatchResult = (0, query_utils_1.queryAsEventDispatchSurvey)(query)
+        const eventDispatchResult = feature('queryAsEventDispatchSurvey', query_utils_1.queryAsEventDispatchSurvey)
             ? this.buildEventDispatchSection(cg, query, projectRoot)
             : { section: '', hitCount: 0, eventCount: 0, handlerCount: 0, memberCount: 0, complete: false };
         if (eventDispatchResult.section)
             lines.push(eventDispatchResult.section);
         const importInventoryFilter = (0, query_utils_1.hasImportInventoryFilter)(query);
         const multiAnchor = (0, query_utils_1.queryNamesMultipleExploreAnchors)(query) || crossModuleFlow;
-        const mechanismSurvey = (0, query_utils_1.queryAsMechanismSurvey)(query);
+        const mechanismSurvey = feature('queryAsMechanismSurvey', query_utils_1.queryAsMechanismSurvey);
         // Flow path — computed before omit-source so graph connectivity drives the decision,
         // not question-text keyword matching. Mechanism/cross-module surveys augment the
         // query with seeded entry symbol names so buildFlowFromNamedSymbols can connect them.
@@ -9959,6 +10518,17 @@ class ToolHandler {
         const priorCalls = (0, explore_session_state_1.viewForProject)((0, explore_session_state_1.readExploreSessionView)(args), projectRoot);
         const dedupEnabled = (0, explore_dedup_1.exploreDedupEnabled)() && (priorCalls?.calls.length ?? 0) > 0;
         const emittedByFile = new Map();
+        // Session emissions may include prior-call coverage or skeleton envelopes.
+        // Dependency receipts instead require *fresh*, actually printed source and
+        // a whole surviving file section (never the tail cut by the hard ceiling).
+        const freshRangesByFile = new Map();
+        const sourceEndByFile = new Map();
+        const noteFreshSource = (fp, ranges) => {
+            if (plan?.source !== 'llm' || !ranges.length)
+                return;
+            freshRangesByFile.set(fp, [...(freshRangesByFile.get(fp) ?? []), ...ranges]);
+            sourceEndByFile.set(fp, lines.join('\n').length);
+        };
         const noteEmitted = (fp, ranges, bytes, fingerprint) => {
             const existing = emittedByFile.get(fp);
             if (existing) {
@@ -10130,6 +10700,7 @@ class ToolHandler {
                 }
                 if (body.length > 0) {
                     lines.push('```' + lang, body, '```', '');
+                    noteFreshSource(filePath, ranges);
                     totalChars += body.length + lang.length + 11;
                     noteEmitted(filePath, [...ranges, ...opts.covered], body.length, fingerprint);
                     renderedFilePaths.push(filePath);
@@ -10216,6 +10787,7 @@ class ToolHandler {
                 // signature line (capped, with a "+N more" tail so the structure map of a
                 // god-file doesn't itself bloat the budget).
                 const skel = [];
+                const freshSkelRanges = [];
                 let coveredUntil = 0; // skip symbols already inside an emitted body
                 let sigCount = 0, sigDropped = 0;
                 const SIG_MAX = Math.max(12, budget.maxSymbolsInFileHeader * 2);
@@ -10226,6 +10798,7 @@ class ToolHandler {
                         const end = n.endLine;
                         const body = fileLines.slice(n.startLine - 1, end).join('\n');
                         skel.push(exploreLineNumbersEnabled() ? numberSourceLines(body, n.startLine) : body);
+                        freshSkelRanges.push({ start: n.startLine, end });
                         coveredUntil = end;
                     }
                     else {
@@ -10248,6 +10821,7 @@ class ToolHandler {
                         if (sig) {
                             skel.push(exploreLineNumbersEnabled() ? `${lineNo}\t${sig}` : sig);
                             sigCount++;
+                            freshSkelRanges.push({ start: lineNo, end: lineNo });
                         }
                     }
                 }
@@ -10285,6 +10859,7 @@ class ToolHandler {
                         return n ? { start: n.startLine, end: n.endLine || n.startLine } : null;
                     }).filter((r) => !!r);
                     lines.push(skelHeader, '', '```' + lang, skelBody, '```', '');
+                    noteFreshSource(filePath, freshSkelRanges);
                     totalChars += skelBody.length + 120;
                     noteEmitted(filePath, bodyRanges.length > 0 ? bodyRanges : [wholeRange], skelBody.length, fingerprint);
                     renderedFilePaths.push(filePath);
@@ -10317,7 +10892,15 @@ class ToolHandler {
                 ? Math.min(Math.max(0, budget.maxOutputChars - totalChars - 200), Math.round(budget.maxCharsPerFile * 1.5))
                 : budget.maxCharsPerFile * 3;
             if (fileLines.length <= WHOLE_FILE_MAX_LINES && fileContent.length <= WHOLE_FILE_MAX_CHARS) {
-                const wholeRange = { start: 1, end: Math.max(1, fileLines.length) };
+                let sourceStart = 0;
+                if (fileLines[0]?.trim().startsWith('/*')) {
+                    const endComment = fileLines.findIndex((line) => line.includes('*/'));
+                    if (endComment >= 0 && endComment < 40)
+                        sourceStart = endComment + 1;
+                }
+                while (sourceStart < fileLines.length - 1 && !fileLines[sourceStart]?.trim())
+                    sourceStart++;
+                const wholeRange = { start: sourceStart + 1, end: Math.max(1, fileLines.length) };
                 const dd = (0, explore_dedup_1.dedupeRange)(wholeRange, served);
                 const uniqSymbols = [...new Set(group.nodes
                         .filter(n => n.kind !== 'import' && n.kind !== 'export')
@@ -10778,6 +11361,7 @@ class ToolHandler {
         const output = flow.text + lines.join('\n');
         const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
         let finalText;
+        let sourceCutoff = output.length;
         if (output.length > hardCeiling) {
             // Prefer dropping trailing notes ("Not shown above", completeness, budget)
             // over dropping a whole file's source — notes are recoverable, source isn't.
@@ -10792,8 +11376,10 @@ class ToolHandler {
                 if (trimmed.length <= hardCeiling)
                     break;
                 const at = trimmed.lastIndexOf(marker);
-                if (at > hardCeiling * 0.4)
+                if (at > hardCeiling * 0.4) {
                     trimmed = trimmed.slice(0, at).replace(/\n+$/, '');
+                    sourceCutoff = Math.min(sourceCutoff, trimmed.length);
+                }
             }
             if (trimmed.length > hardCeiling) {
                 // Cut at a FILE-SECTION boundary so we drop whole trailing file-sections
@@ -10822,6 +11408,7 @@ class ToolHandler {
                     boundary = lastSection > hardCeiling * 0.5 ? lastSection : cut.lastIndexOf('\n');
                 }
                 const safe = boundary > 0 ? cut.slice(0, boundary) : cut;
+                sourceCutoff = Math.min(sourceCutoff, safe.length);
                 finalText = safe + '\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For uncovered files/symbols, run another homegraph_explore with their exact names — not grep/read/node for symbols already shown.)';
             }
             else {
@@ -10872,14 +11459,85 @@ class ToolHandler {
             });
             sourceBytes += emitted.bytes;
         }
+        // Do not promote unseen subgraph hits or a large parent's unshown header.
+        // The declaration's starting line must be in a surviving, fresh source span.
+        const rootIds = new Set(subgraph.roots);
+        for (const file of literalSource.files) {
+            if (!finalText.includes(literalSource.text))
+                break;
+            emittedFiles.push(file);
+            sourceBytes += file.bytes;
+        }
+        const locatedNodes = plan?.source === 'llm' ? [...(finalText.includes(literalSource.text) ? literalSource.nodes : []), ...emittedFiles.flatMap((file) => staleRendered.includes(file.path) || flow.text.length + (sourceEndByFile.get(file.path) ?? Infinity) > sourceCutoff
+                ? [] : (fileGroups.get(file.path)?.nodes ?? []).filter((node) => !['file', 'import', 'export', 'parameter'].includes(node.kind)
+                && (freshRangesByFile.get(file.path) ?? []).some((range) => node.startLine >= range.start && node.startLine <= range.end)))]
+            .sort((a, b) => Number(rootIds.has(b.id)) - Number(rootIds.has(a.id)))
+            .filter((node, i, nodes) => nodes.findIndex((other) => other.id === node.id) === i)
+            .slice(0, 32).map((node) => ({ id: node.id, name: node.name, qualifiedName: node.qualifiedName,
+            filePath: node.filePath, startLine: node.startLine })) : undefined;
         return this.exploreResult(finalText, {
             projectRoot,
             query,
             files: emittedFiles,
             sourceBytes,
+            evidenceStatus: sourceBytes > 0 ? (anyFileTrimmed || subgraph.confidence === 'low' || sourceCutoff < output.length
+                || (plan?.source === 'llm' && !(locatedNodes?.length)) ? 'partial' : 'complete')
+                : filesIncluded > 0 && /HarmonyOS SDK API/.test(finalText) ? 'sdk-only' : 'empty',
             responseBytes: finalText.length,
+            ...(locatedNodes ? { locatedNodes } : {}),
         });
     }
+    /** Render literal witnesses before graph-heavy sections, including unindexed UI. */
+    renderLiteralSource(cg, subgraph) {
+        const sections = [];
+        const files = [];
+        const nodes = [];
+        const seen = new Set();
+        let chars = 0;
+        for (const hit of subgraph.literalEvidence?.hits ?? []) {
+            if (files.length >= 2 || seen.has(hit.filePath))
+                continue;
+            const absolute = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), hit.filePath);
+            if (!absolute)
+                continue;
+            let source;
+            try {
+                source = (0, fs_1.readFileSync)(absolute, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const lines = source.split('\n');
+            // Never serve an earlier witness against a changed file.
+            if (lines.slice(hit.startLine - 1, hit.endLine).join('\n') !== hit.text)
+                continue;
+            const containing = this.isFileStaleOnDisk(cg, hit.filePath, source) ? undefined
+                : (0, evidence_rendering_1.canonicalSourceDeclarations)(cg.getNodesInFile(hit.filePath))
+                    .filter(node => !['file', 'import', 'export', 'parameter'].includes(node.kind)
+                    && !node.name.startsWith('%') && node.name !== 'constructor'
+                    && node.startLine <= hit.line && node.endLine >= hit.line)
+                    .sort((a, b) => (a.endLine - a.startLine) - (b.endLine - b.startLine))[0];
+            const ranges = [{ start: hit.startLine, end: hit.endLine }];
+            if (containing && containing.startLine < hit.startLine) {
+                ranges.unshift({ start: containing.startLine, end: Math.min(containing.startLine + 2, hit.startLine - 1) });
+            }
+            const body = ranges.map(range => lines.slice(range.start - 1, range.end)
+                .map((line, index) => `${range.start + index}\t${line}`).join('\n')).join('\n... (gap) ...\n');
+            const resource = hit.resource
+                ? `\nResource: \`${hit.resource.filePath}:${hit.resource.line}\` — ${JSON.stringify(hit.resource.value)} → \`${hit.resource.key}\`.` : '';
+            const section = `**Literal source witness: \`${hit.filePath}:${hit.line}\`**${resource}\n\n\`\`\`\n${body}\n\`\`\``;
+            if (chars + section.length > 3000)
+                continue;
+            sections.push(section);
+            chars += section.length;
+            seen.add(hit.filePath);
+            files.push({ path: hit.filePath, ranges, bytes: body.length, fingerprint: (0, explore_dedup_1.fileFingerprint)(source) });
+            if (containing)
+                nodes.push({ id: containing.id, name: containing.name,
+                    qualifiedName: containing.qualifiedName, filePath: containing.filePath, startLine: containing.startLine });
+        }
+        return { text: sections.join('\n\n'), files, nodes };
+    }
     /**
      * An explore response plus the record of what it emitted (CG-17). The record
      * rides the result only as far as {@link execute}, which files it into the
@@ -10890,7 +11548,8 @@ class ToolHandler {
         const result = this.textResult(text);
         result[explore_session_state_1.EXPLORE_EMISSION_KEY] = {
             ...emission,
-            partial: emission.partial ?? meta.partial,
+            evidenceStatus: emission.evidenceStatus ?? (emission.sourceBytes > 0 ? (meta.partial ? 'partial' : 'complete') : 'partial'),
+            partial: emission.partial ?? (emission.evidenceStatus && emission.evidenceStatus !== 'complete' ? true : meta.partial),
             nextAnchor: emission.nextAnchor ?? meta.nextAnchor,
         };
         return result;
@@ -10916,7 +11575,8 @@ class ToolHandler {
             files: [],
             sourceBytes: 0,
             responseBytes: text.length,
-            partial: meta.partial,
+            partial: true,
+            evidenceStatus: /HarmonyOS SDK API|ohos-sdk:/.test(text) ? 'sdk-only' : /No relevant code|No matching evidence|No survey ran/.test(text) ? 'empty' : 'partial',
             nextAnchor: meta.nextAnchor,
         };
         return result;
@@ -10951,7 +11611,7 @@ class ToolHandler {
         const symbol = this.validateString(args.symbol, 'symbol');
         if (typeof symbol !== 'string')
             return symbol;
-        let matches = this.findSymbolMatches(cg, symbol);
+        let matches = (0, evidence_rendering_1.canonicalSourceDeclarations)(this.findSymbolMatches(cg, symbol));
         if (matches.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
@@ -11317,7 +11977,7 @@ class ToolHandler {
         if (mismatch) {
             lines.push(`> ⚠ ${(0, worktree_1.worktreeMismatchWarning)(mismatch).replace(/\n/g, '\n> ')}`, '');
         }
-        lines.push(`**Files indexed:** ${stats.fileCount}`, `**Total nodes:** ${stats.nodeCount}`, `**Total edges:** ${stats.edgeCount}`, `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`, ...(stats.walSizeBytes > 0
+        lines.push(`**Build phase:** ${cg.getBuildPhase()}`, `**Files indexed:** ${stats.fileCount}`, `**Total nodes:** ${stats.nodeCount}`, `**Total edges:** ${stats.edgeCount}`, `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`, ...(stats.walSizeBytes > 0
             ? [`**WAL size:** ${(stats.walSizeBytes / 1024 / 1024).toFixed(2)} MB`]
             : []), `**Graph sources:** ${cg.getGraphSources()}`);
         // Surface the active SQLite backend: node:sqlite → better-sqlite3 → wasm.
@@ -11382,6 +12042,64 @@ class ToolHandler {
         }
         return this.textResult(lines.join('\n'));
     }
+    /**
+     * Handle homegraph_project — shallow module → file map (fast build).
+     */
+    async handleProject(args) {
+        const cg = this.getHomeGraph(args.projectPath);
+        const phase = cg.getBuildPhase();
+        if (phase === 'building_fast') {
+            return this.textResult('Fast project map is still building — retry in a few seconds.');
+        }
+        let map = cg.getProjectMap({
+            module: typeof args.module === 'string' ? args.module : undefined,
+            includeFiles: args.includeFiles !== false,
+        });
+        // On-demand build for indexes that never ran the fast path (legacy / CLI init).
+        if (map.modules.length === 0) {
+            try {
+                cg.buildProjectMap();
+                if (phase === 'none') {
+                    cg.setBuildPhase(cg.getStats().nodeCount > 0 ? 'full' : 'fast');
+                }
+                map = cg.getProjectMap({
+                    module: typeof args.module === 'string' ? args.module : undefined,
+                    includeFiles: args.includeFiles !== false,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return this.textResult(`Failed to build project map: ${message}`);
+            }
+        }
+        if (map.modules.length === 0) {
+            return this.textResult('No modules found in the project map.');
+        }
+        const FILE_CAP = 80;
+        const lines = [
+            `**Project map** (phase=${map.phase})`,
+            `modules: ${map.modules.length} · files: ${map.fileCount}`,
+            '',
+        ];
+        if (map.phase === 'fast' || map.phase === 'indexing') {
+            lines.push('_Full symbol index still building — this map has modules/files only (no call graph)._', '');
+        }
+        for (const m of map.modules) {
+            const rootLabel = m.rootPath || '.';
+            lines.push(`### ${m.name} (\`${rootLabel}\`) · ${m.kind} · ${m.fileCount} files`);
+            if (m.files && m.files.length > 0) {
+                const shown = m.files.slice(0, FILE_CAP);
+                for (const f of shown) {
+                    lines.push(`- ${f.path}`);
+                }
+                if (m.files.length > FILE_CAP) {
+                    lines.push(`- … +${m.files.length - FILE_CAP} more`);
+                }
+            }
+            lines.push('');
+        }
+        return this.textResult(lines.join('\n').trimEnd());
+    }
     /**
      * Handle homegraph_arkui_migrate — one-shot ArkUI migrate / state snapshot (spec 0007).
      */
@@ -12269,7 +12987,7 @@ class ToolHandler {
         return {
             // Single choke point for every tool's text, so no section builder can ship
             // a stop-searching directive on an output that declares itself partial.
-            content: [{ type: 'text', text: reconcilePartialAnswerNow(text) }],
+            content: [{ type: 'text', text: (0, evidence_rendering_1.neutralRetrievalGuidance)(reconcilePartialAnswerNow(text)) }],
         };
     }
     /**