homegraph 1.5.6 → 1.5.8

package/dist/mcp/tools.js

@@ -21,7 +21,13 @@ exports.queryAsBareSymbolInventory = queryAsBareSymbolInventory;
 exports.hasPositiveAnswerNowDirective = hasPositiveAnswerNowDirective;
 exports.reconcilePartialAnswerNow = reconcilePartialAnswerNow;
 const query_pool_1 = require("./query-pool");
+const source_slice_identity_1 = require("./source-slice-identity");
+const evidence_rendering_1 = require("./evidence-rendering");
+const arkts_evidence_packs_1 = require("./arkts-evidence-packs");
+const evidence_paths_1 = require("../graph/evidence-paths");
+const query_plan_1 = require("../search/query-plan");
 const memory_budget_1 = require("./memory-budget");
+const index_availability_1 = require("./index-availability");
 const directory_1 = require("../directory");
 // Lazy-load the heavy HomeGraph chain off the MCP startup path — see the same
 // helper in engine.ts. ToolHandler must load to answer tools/list (static
@@ -99,6 +105,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',
@@ -641,7 +661,7 @@ exports.tools = [
     {
         name: 'homegraph_search',
         description: 'LAST RESORT spelling lookup — locations only, no source. Required: `query` (e.g. "signIn"). ' +
-            'Prefer explore/callers/node when names are known. ' +
+            'Use ordinary scoped search/read when names or paths are known; use graph tools only for missing structural evidence. ' +
             'DO NOT call for topic file-lists, concept compares, or SDK/@kit feature catalogs (those return Skip guidance). ' +
             'Also skip literal string/pattern greps — use Grep instead. ' +
             'Bare-name search may return a compact explore result instead of locations.',
@@ -671,7 +691,7 @@ exports.tools = [
     {
         name: 'homegraph_callers',
         description: 'Compact caller list for one NAMED in-repo symbol (no bodies). Required: `symbol` (e.g. "authenticate"). ' +
-            'Cheaper than explore when you only need who-calls-X. For multi-file flows use homegraph_explore. ' +
+            'Cheaper than explore when you only need who-calls-X. For an unresolved cross-symbol flow, consider homegraph_explore. ' +
             'DO NOT call for SDK catalogs, topic file-lists, concept compares, or hypothetics.',
         inputSchema: {
             type: 'object',
@@ -698,7 +718,7 @@ exports.tools = [
     {
         name: 'homegraph_callees',
         description: 'Compact callee list for one NAMED in-repo symbol (no bodies). Required: `symbol` (e.g. "authenticate"). ' +
-            'Cheaper than explore when you only need what-X-calls. For multi-file flows use homegraph_explore. ' +
+            'Cheaper than explore when you only need what-X-calls. For an unresolved cross-symbol flow, consider homegraph_explore. ' +
             'DO NOT use for out-of-repo SDK catalogs or counterfactual analysis.',
         inputSchema: {
             type: 'object',
@@ -799,9 +819,9 @@ exports.tools = [
             'Cheaper than explore when you already know the name and only need one body. ' +
             'FILE: `file` only → line-numbered source + dependents. ' +
             'SYMBOL: body via includeCode + short trail; overloads return every body. ' +
-            'DO NOT call after explore already returned that symbol/file (multiplies tokens). ' +
-            'DO NOT crawl a feature with repeated node calls (prefer one explore for flows). ' +
-            'Treat returned source as already Read.',
+            'Reuse complete unchanged source ranges already returned by any tool; refresh missing, truncated or edited ranges. ' +
+            'Avoid repeated node calls over the same evidence; use explore only for an unresolved cross-symbol flow. ' +
+            'Treat complete returned source ranges as already Read, not an entire file inferred from an excerpt.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -843,95 +863,97 @@ 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: 'Optional focused tool for an unresolved 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: 'Optional focused tool for an unresolved 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: 'Optional focused tool for an unresolved 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: 'Optional graph evidence for a concrete unresolved cross-symbol mechanism in THIS repo. Required: `query`. ' +
+            'Use ordinary bash/search/read for paths, symbols, literal strings and local changes; continue editing when that evidence suffices. ' +
+            'Do not call for routine pre-edit orientation or merely because implementation is difficult. ' +
+            'For a missing usage, dependency/cycle or native-registration relation, use ' +
+            'homegraph_usages, homegraph_modules, or homegraph_native instead. ' +
+            'Returns call paths and compact line-numbered source. ArkTS symbol evidence uses complete declarations and bounded directed paths with intermediate source dependencies; explicit Gaps and stop reasons name omitted or unverified evidence. Qualify ambiguous symbols by owning type or file. State the missing relation with known anchors, requested action, scope and constraints; taskContext can carry the full task. ' +
+            'Reuse unchanged complete ranges; refresh missing, edited or truncated evidence. ' +
+            'No new evidence → change to a targeted source inspection, not a paraphrased explore. ' +
+            'Partial/busy → at most one focused recovery for the named gap; budgets are ceilings, not required calls. ' +
+            'Retrieval completion is not task completion: continue implementation and required validation.',
         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',
@@ -987,7 +1009,7 @@ exports.tools = [
     {
         name: 'homegraph_files',
         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.',
+            'Optional coarse folder inventory; prefer ordinary file listing for known paths. Use graph tools only for missing structural evidence.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1277,10 +1299,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)
@@ -1291,7 +1318,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;
@@ -1450,7 +1477,6 @@ class ToolHandler {
             return withRequiredProjectPath(visible);
         try {
             const stats = this.cg.getStats();
-            const budget = getExploreBudget(stats.fileCount);
             // Tiny-repo tool gating: on projects under TINY_REPO_FILE_THRESHOLD
             // files, only expose the core trio (search, node, explore) — one
             // below even the 4-tool default: at this scale callers, too, reduces
@@ -1482,14 +1508,16 @@ class ToolHandler {
                 '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 => {
                 if (tool.name === 'homegraph_explore') {
                     return {
                         ...tool,
-                        description: `${tool.description} Budget: make at most ${budget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).`,
+                        description: `${tool.description} ${this.exploreSuffix(stats.fileCount)}`,
                     };
                 }
                 return tool;
@@ -1499,6 +1527,53 @@ class ToolHandler {
             return visible;
         }
     }
+    /**
+     * Per-repo suffix appended to homegraph_explore's description (Spec 0027).
+     *
+     * fileCount === 0 must not read as "this project is empty": hosts snapshot
+     * tools/list once at connect (#964), and an auto-init that is still building
+     * reports 0 at that instant. Field evidence (DevEco Code bench, 3 sessions,
+     * zero homegraph calls): agents read "make at most 1 calls for this project
+     * (0 files indexed)" as terminal — "homegraph isn't indexed for this
+     * project" — and permanently fell back to Read/Grep even though the index
+     * completed seconds later. Mirror maybeDeepToolPhaseGate's success-shaped
+     * guidance so the frozen description and the live call-time response tell
+     * the same story: failed build → say so (indexing is the user's call, so
+     * the agent relays it); still building → point at homegraph_project and
+     * retry; genuinely empty → honest empty note. Only fileCount > 0 carries a
+     * call budget — there is nothing to budget over an unbuilt index.
+     */
+    exploreSuffix(fileCount) {
+        if (fileCount > 0) {
+            return `Budget: make at most ${getExploreBudget(fileCount)} calls for this project (${fileCount.toLocaleString()} files indexed).`;
+        }
+        const cg = this.cg;
+        if (cg) {
+            try {
+                // Failed check comes first: a failed full build rolls build_phase back
+                // to 'fast' (startBackgroundFullBuild catch), so the building branch
+                // below would otherwise mask the failure.
+                if (cg.getQueryBuilder().getMetadata('index_state') === 'failed') {
+                    return 'The last full index build for this project failed, so results will be empty. Tell the user to re-run `homegraph index`.';
+                }
+                const state = (0, index_availability_1.resolveProductIndexState)(cg);
+                if (state === 'empty') {
+                    return (0, index_availability_1.productIndexGuidance)('empty');
+                }
+                if (state === 'fast' || state === 'syncing') {
+                    // Keep the Spec 0027 "still building → homegraph_project" story for
+                    // frozen tools/list descriptions (hosts snapshot once at connect).
+                    return state === 'syncing'
+                        ? (0, index_availability_1.productIndexGuidance)('syncing')
+                        : "HomeGraph is still building this project's index. A call right now returns build-progress guidance; use `homegraph_project` for the module/file map, then retry once indexing finishes.";
+                }
+            }
+            catch {
+                /* metadata is advisory — fall through to the empty note */
+            }
+        }
+        return 'No files are indexed for this project; results will be empty until an index is built.';
+    }
     /**
      * Get HomeGraph instance for a project
      *
@@ -1876,6 +1951,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, '_hgEvidenceMaxChars'])
+            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
@@ -1916,13 +1995,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);
                     }
                 }
             }
@@ -1939,7 +2042,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;
@@ -1958,8 +2063,12 @@ 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 packMeta = cached?._meta?.homegraphEvidencePacks;
+                    const cachedFiles = cached?._meta?.homegraphEvidence?.files;
+                    if (cached && (!packMeta || (packMeta.status === 'complete'
+                        && this.areEvidenceFilesCurrent(cachedFiles ?? [], cacheCg.getProjectRoot())))) {
+                        const diagnosed = this.withQueryPlanDiagnostics(cached, args, true);
+                        const withWorktree = this.withWorktreeNotice(diagnosed, projectPath);
                         return this.withStalenessNotice(withWorktree, projectPath);
                     }
                 }
@@ -1993,35 +2102,41 @@ class ToolHandler {
             // 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).
                             let served = fast;
-                            if (toolName === 'homegraph_explore' && sessionState) {
-                                served = this.takeExploreEmission(this.ensureExploreEmission(fast, rootFast, q), sessionState);
+                            if ((toolName === 'homegraph_explore' && sessionState) || fast._meta?.homegraphEvidencePacks) {
+                                served = this.takeExploreEmission(this.ensureExploreEmission(fast, rootFast, q), toolName === 'homegraph_explore' ? sessionState : undefined);
                             }
+                            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.
@@ -2037,7 +2152,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'
@@ -2065,7 +2180,11 @@ class ToolHandler {
             if (err instanceof PathRefusalError) {
                 return this.errorResult(err.message);
             }
-            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+            const msg = err instanceof Error ? err.message : String(err);
+            if ((0, index_availability_1.isSqliteBusyMessage)(msg)) {
+                return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+            }
+            return this.errorResult(`Tool execution failed: ${msg}. ` +
                 'This is an internal homegraph error — retry the call once; if it persists, ' +
                 'continue without homegraph for this task.');
         }
@@ -2113,16 +2232,71 @@ 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) ?? [];
+        return this.areEvidenceFilesCurrent(files, projectRoot);
+    }
+    /** Same bounded fingerprint check for repeat protection and cached source packs. */
+    areEvidenceFilesCurrent(files, projectRoot) {
+        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);
         }
@@ -2142,17 +2316,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,
@@ -2185,13 +2364,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_project';
+            || 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, {
@@ -2246,6 +2431,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`.
@@ -2264,7 +2457,11 @@ class ToolHandler {
             if (err instanceof PathRefusalError) {
                 return this.errorResult(err.message);
             }
-            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+            const msg = err instanceof Error ? err.message : String(err);
+            if ((0, index_availability_1.isSqliteBusyMessage)(msg)) {
+                return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+            }
+            return this.errorResult(`Tool execution failed: ${msg}. ` +
                 'This is an internal homegraph error — retry the call once; if it persists, ' +
                 'continue without homegraph for this task.');
         }
@@ -2307,34 +2504,31 @@ class ToolHandler {
         }
     }
     /**
-     * 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.
+     * Gate symbol/graph tools by product index state (Spec 0032).
+     * Success-shaped guidance — never isError — so agents keep using HomeGraph.
      */
     maybeDeepToolPhaseGate(cg, _toolName) {
-        const phase = cg.getBuildPhase();
-        if (phase === 'full')
+        const state = (0, index_availability_1.resolveProductIndexState)(cg);
+        if (state === 'full')
             return null;
+        if (state === 'syncing') {
+            return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+        }
+        if (state === 'empty') {
+            return this.textResult((0, index_availability_1.productIndexGuidance)('empty'));
+        }
+        // fast: allow deep tools once some symbols exist (partial index).
         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'));
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if ((0, index_availability_1.isSqliteBusyMessage)(msg)) {
+                return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+            }
         }
-        return null;
+        return this.textResult((0, index_availability_1.productIndexGuidance)('fast'));
     }
     async handleSearch(args) {
         const query = this.validateString(args.query, 'query');
@@ -5131,9 +5325,273 @@ 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, evidenceMaxChars) {
+        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, evidenceMaxChars)
+            ?? this.tryCompactLocalSymbolExplore(cg, query, root, plan, evidenceMaxChars);
+    }
+    /** 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(), args._hgEvidenceMaxChars);
+        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 stepCap = Math.max(0, Math.floor((outputBudget - used) / Math.max(1, plan.steps.length - diagnostics.length + 1)) - 100);
+                const result = await this.executePlannedStep({ ...args, [QUERY_DEADLINE_ARG]: deadline,
+                    ...(multi ? { _hgEvidenceMaxChars: Math.max(0, stepCap - Math.min(1600, Math.floor(stepCap / 2)) - 2) } : {}),
+                }, 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 atomic = !!result._meta?.homegraphEvidencePacks;
+                const kept = atomic && trimmed
+                    ? '[Partial source: complete evidence pack omitted by the shared output budget.]'.slice(0, bodyCap)
+                    : atomic ? neutralBody : (0, evidence_rendering_1.trimEvidenceAtLine)(neutralBody, bodyCap);
+                if (atomic && trimmed) {
+                    receipt = '';
+                    diagnostic.locatedNodes = [];
+                    diagnostic.resolvedAnchors = [];
+                    bindings.set(step.id, []);
+                }
+                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')
@@ -5181,11 +5639,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)
@@ -5203,10 +5663,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)
                 : '';
@@ -5224,13 +5684,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) {
@@ -5392,8 +5882,8 @@ 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 / busy timeout).
         if ((0, query_utils_1.queryAsMultiTypeDependencySurvey)(query)) {
@@ -5759,9 +6249,29 @@ class ToolHandler {
         }
         return finishCompact('Inventory sections above are complete for this query. **ANSWER NOW.**');
     }
-    /**
-     * Render a compact symbol-bounded slice of one file (lightweight mechanism path).
-     */
+    /** Pack already-located ArkTS evidence before legacy windowing can cut it. */
+    tryArktsEvidenceExplore(cg, query, projectRoot, nodes, focusIds, maxChars, maxFiles, plan) {
+        if (process.env.HOMEGRAPH_ARKTS_EVIDENCE_PACKS === '0')
+            return null;
+        if (!nodes.some(n => /\.ets$/i.test(n.filePath) && !n.filePath.startsWith('ohos-sdk:')))
+            return null;
+        const budget = getExploreOutputBudget(cg.getStats().fileCount);
+        const queryPaths = process.env.HOMEGRAPH_ARKTS_QUERY_PATHS !== '0';
+        if (queryPaths)
+            nodes = (0, evidence_paths_1.completeEvidencePathCandidates)(query, nodes, (name, limit) => cg.getQueryBuilder().getNodesByQualifiedNameExact(name, limit), plan);
+        const pathSearch = !queryPaths ? undefined : (0, evidence_paths_1.searchEvidencePaths)({
+            getNode: id => cg.getNode(id),
+            getEdges: (id, direction, kinds, limit, preferred) => cg.getQueryBuilder().getEvidenceEdges(id, direction, kinds, limit, preferred),
+        }, (0, evidence_paths_1.resolveEvidencePathGoal)(query, nodes, focusIds, plan));
+        const result = (0, arkts_evidence_packs_1.buildArktsEvidencePacks)(cg, { projectRoot, query, nodes, focusIds,
+            maxChars: Math.min(budget.maxOutputChars, maxChars ?? budget.maxOutputChars), maxFiles, pathSearch });
+        if (!result)
+            return null;
+        // The pack renderer already supplies neutral guidance and exact source bytes.
+        return { content: [{ type: 'text', text: result.text }], [explore_session_state_1.EXPLORE_EMISSION_KEY]: result.emission,
+            _meta: { homegraphEvidencePacks: result.metadata } };
+    }
+    /** Render a compact symbol-bounded slice on the legacy mechanism path. */
     renderLightMechanismSource(projectRoot, filePath, nodes, maxChars) {
         const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, filePath);
         if (!absPath || !(0, fs_1.existsSync)(absPath))
@@ -5797,8 +6307,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, evidenceMaxChars) {
+        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);
@@ -5968,6 +6478,9 @@ class ToolHandler {
         const seeds = (0, query_utils_1.extractMechanismEntrySeeds)(query);
         const flow = this.buildFlowFromNamedSymbols(cg, `${query} ${seeds.join(' ')}`);
         const hasFlowPath = flow.pathNodeIds.size > 1;
+        const evidence = this.tryArktsEvidenceExplore(cg, query, projectRoot, [...fileNodes.values()].flat().concat([...flow.pathNodeIds].flatMap(id => { const n = cg.getNode(id); return n ? [n] : []; })), new Set([...seedIds, ...flow.pathNodeIds]), evidenceMaxChars, undefined, plan);
+        if (evidence)
+            return evidence;
         const managerSection = this.formatDomainRoleInventory(managerHits.length > 0
             ? managerHits
             : [...seedIds].map((id) => cg.getNode(id)).filter((n) => !!n && (0, query_utils_1.isDomainRoleSymbol)(n.name, n.filePath, domainPathTokens)));
@@ -6435,7 +6948,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, evidenceMaxChars) {
         // 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).
@@ -6449,8 +6962,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)
@@ -6610,6 +7128,9 @@ class ToolHandler {
         }
         if (seedIds.size === 0)
             return null;
+        const evidence = this.tryArktsEvidenceExplore(cg, query, projectRoot, [...fileNodes.values()].flat(), seedIds, evidenceMaxChars, undefined, plan);
+        if (evidence)
+            return evidence;
         const pathAffinity = (seedPath, otherPath) => {
             const a = seedPath.replace(/\\/g, '/').split('/');
             const b = otherPath.replace(/\\/g, '/').split('/');
@@ -9071,8 +9592,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);
@@ -9080,7 +9603,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,
@@ -9090,7 +9613,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)
@@ -9110,19 +9634,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);
@@ -9261,8 +9819,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);
@@ -9289,7 +9847,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;
@@ -9504,6 +10063,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 ?? '';
@@ -9699,6 +10260,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;
@@ -9758,6 +10328,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.');
@@ -9782,30 +10354,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.
@@ -9830,6 +10402,13 @@ class ToolHandler {
         }
         const flow = this.buildFlowFromNamedSymbols(cg, flowQuery);
         const hasFlowPath = flow.pathNodeIds.size > 0;
+        // Keep literal/resource and specialized inventory rendering intact. This
+        // first batch changes symbol-grounded structural evidence only.
+        if ((hasFlowPath || flow.text.length > 0 || plan?.intent === 'flow') && !subgraph.literalEvidence?.hits.length) {
+            const evidence = this.tryArktsEvidenceExplore(cg, query, projectRoot, [...subgraph.nodes.values()].concat([...flow.pathNodeIds].flatMap(id => { const n = cg.getNode(id); return n ? [n] : []; })), new Set([...subgraph.roots, ...flow.namedNodeIds, ...flow.pathNodeIds]), args._hgEvidenceMaxChars, explicitMaxFiles ? maxFiles : undefined, plan);
+            if (evidence)
+                return evidence;
+        }
         budget = tightenExploreBudgetForQuery(budget, query, { hasFlowPath });
         // Honor an explicit maxFiles from the caller — budget.defaultMaxFiles is only
         // a default when the agent didn't ask for more (adaptive sibling tests pass 12).
@@ -10036,6 +10615,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) {
@@ -10207,6 +10797,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);
@@ -10293,6 +10884,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);
@@ -10303,6 +10895,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 {
@@ -10325,6 +10918,7 @@ class ToolHandler {
                         if (sig) {
                             skel.push(exploreLineNumbersEnabled() ? `${lineNo}\t${sig}` : sig);
                             sigCount++;
+                            freshSkelRanges.push({ start: lineNo, end: lineNo });
                         }
                     }
                 }
@@ -10362,6 +10956,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);
@@ -10394,7 +10989,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')
@@ -10855,6 +11458,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.
@@ -10869,8 +11473,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
@@ -10899,6 +11505,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 {
@@ -10949,14 +11556,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
@@ -10967,7 +11645,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;
@@ -10993,7 +11672,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;
@@ -11028,7 +11708,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`);
         }
@@ -11397,21 +12077,18 @@ class ToolHandler {
         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.
+        // Surface the active SQLite backend: node:sqlite → wasm.
         const backend = cg.getBackend();
         if (backend === 'node-sqlite') {
             lines.push(`**Backend:** node-sqlite (built-in)`);
         }
-        else if (backend === 'native') {
-            lines.push(`**Backend:** native (better-sqlite3)`);
-        }
         else {
             lines.push(`**Backend:** ⚠ wasm (no WAL backend available) — ` +
                 `5-10x slower than WAL. Fix: ${sqlite_adapter_1.WASM_FALLBACK_FIX_RECIPE}`);
         }
         // Effective journal mode. 'wal' ⇒ concurrent reads never block on a writer;
-        // anything else ⇒ they can ("database is locked"). node:sqlite / native
-        // support WAL; wasm remaps to DELETE.
+        // anything else ⇒ they can ("database is locked"). node:sqlite supports WAL;
+        // wasm remaps to DELETE.
         const journalMode = cg.getJournalMode();
         if (journalMode === 'wal') {
             lines.push(`**Journal mode:** wal (concurrent reads safe)`);
@@ -11464,10 +12141,27 @@ class ToolHandler {
      */
     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.');
+        const state = (0, index_availability_1.resolveProductIndexState)(cg);
+        if (state === 'empty') {
+            return this.textResult((0, index_availability_1.productIndexGuidance)('empty'));
+        }
+        if (state === 'syncing') {
+            // Prefer returning the map when readable; only hard-stop if phase has no map.
+            try {
+                const peek = cg.getProjectMap({ includeFiles: false });
+                if (peek.modules.length === 0) {
+                    return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if ((0, index_availability_1.isSqliteBusyMessage)(msg)) {
+                    return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+                }
+                return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+            }
         }
+        const phase = cg.getBuildPhase();
         let map = cg.getProjectMap({
             module: typeof args.module === 'string' ? args.module : undefined,
             includeFiles: args.includeFiles !== false,
@@ -11486,6 +12180,9 @@ class ToolHandler {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
+                if ((0, index_availability_1.isSqliteBusyMessage)(message)) {
+                    return this.textResult((0, index_availability_1.productIndexGuidance)('syncing'));
+                }
                 return this.textResult(`Failed to build project map: ${message}`);
             }
         }
@@ -11493,14 +12190,18 @@ class ToolHandler {
             return this.textResult('No modules found in the project map.');
         }
         const FILE_CAP = 80;
+        const productState = (0, index_availability_1.resolveProductIndexState)(cg);
         const lines = [
-            `**Project map** (phase=${map.phase})`,
+            `**Project map** (status=${productState}, phase=${map.phase})`,
             `modules: ${map.modules.length} · files: ${map.fileCount}`,
             '',
         ];
-        if (map.phase === 'fast' || map.phase === 'indexing') {
+        if (productState === 'fast' || map.phase === 'fast' || map.phase === 'indexing') {
             lines.push('_Full symbol index still building — this map has modules/files only (no call graph)._', '');
         }
+        if (productState === 'syncing') {
+            lines.push('_Index write in progress — map may be briefly stale._', '');
+        }
         for (const m of map.modules) {
             const rootLabel = m.rootPath || '.';
             lines.push(`### ${m.name} (\`${rootLabel}\`) · ${m.kind} · ${m.fileCount} files`);
@@ -12396,6 +13097,9 @@ class ToolHandler {
             // Line-numbered (cat -n style, like homegraph_explore and Read) so the
             // agent can cite/edit exact lines without re-Reading the file for them.
             const numbered = node.startLine ? numberSourceLines(code, node.startLine) : code;
+            if (node.startLine && process.env.HOMEGRAPH_SOURCE_RECEIPTS === '1') {
+                lines.push('', (0, source_slice_identity_1.sourceSliceIdentity)(node.filePath, node.startLine, code));
+            }
             lines.push('', '```' + node.language, numbered, '```');
         }
         return lines.join('\n');
@@ -12404,7 +13108,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)) }],
         };
     }
     /**