homegraph 1.5.7 → 1.5.8

package/dist/mcp/tools.js

@@ -21,9 +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
@@ -657,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.',
@@ -687,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',
@@ -714,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',
@@ -815,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: {
@@ -860,7 +864,7 @@ exports.tools = [
     },
     {
         name: 'homegraph_usages',
-        description: 'PRIMARY first tool for a narrow WHERE-USED question about one named API, `.member`, ALL_CAPS constant, field, or mutex. ' +
+        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.',
@@ -879,7 +883,7 @@ exports.tools = [
     },
     {
         name: 'homegraph_modules',
-        description: 'PRIMARY first tool for a narrow DEPENDENCY/CYCLE question about named path modules or `*common` / `*service` / `*component` / `*constants` 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.',
@@ -898,7 +902,7 @@ exports.tools = [
     },
     {
         name: 'homegraph_native',
-        description: 'PRIMARY first tool for a narrow NAPI/NATIVE EXPORT or registration question about one named path or Type. ' +
+        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.',
@@ -917,26 +921,16 @@ exports.tools = [
     },
     {
         name: 'homegraph_explore',
-        description: 'GENERAL PRIMARY entry for understanding THIS repo before you edit or answer structural questions. ' +
-            'For an explicit narrow where-used, named module dependency/cycle, or NAPI/native export inventory, choose ' +
-            'homegraph_usages, homegraph_modules, or homegraph_native instead; this tool keeps conservative auto-routing only for compatibility. ' +
-            'Returns call paths + compact line-numbered source for the relevant symbols. Required: `query`. ' +
-            'CALL FIRST (alone, no parallel Grep/Read) when you will change an existing codebase — pass the user task or domain keywords ' +
-            '(page/module/feature/component words); locate where to edit before writing code. Also CALL FIRST for how/wired questions, ' +
-            'named Type/Component/Page/Dialog, Type.member, click→handler, inheritance/subtypes, declaration/attribute sites, ' +
-            'or a cross-symbol mechanism/flow. Use the named focused tools for exact usage, module-topology, or native-export inventories. ' +
-            'PascalCase names optional when domain keywords suffice. ' +
-            'For edits preserve the requested action, target product/module and exclusions; taskContext may carry the full task. ' +
-            'Prefer callers/node when one named symbol is already enough. ' +
-            'DO NOT call for topic file-lists with no Type/file, literal copy hunts / pure existence compares with no anchors, ' +
-            'official-docs-only asks, empty-project-from-scratch scaffolds, git history, or media/binary asset inventories — those return Skip. ' +
-            '@kit / OHOS API questions ARE in scope when the SDK API graph is available — exact where-used → homegraph_usages; ' +
-            'mechanism/API-symbol flow → homegraph_explore. ' +
-            'Literal string/pattern hunts → Grep; media assets → Glob; git history → git. ' +
-            'One explore; then answer or edit from Source + trail — do not re-grep/node/read the same symbols. ' +
-            'Overlapping paraphrase explores are refused (name a new Type/file/@kit to continue). ' +
-            'Busy/partial → retry ONCE with the named Next anchor or ONE narrow Grep — not a Grep/node storm '
-            + '(session refuses further explore / depth fan-out after Partial).',
+        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: {
@@ -1015,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: {
@@ -1483,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
@@ -1524,7 +1517,7 @@ class ToolHandler {
                 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;
@@ -1534,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
      *
@@ -1913,7 +1953,7 @@ class ToolHandler {
     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])
+        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
@@ -2023,7 +2063,10 @@ class ToolHandler {
                     }
                     cacheKey = (0, query_cache_1.buildMcpQueryCacheKey)(toolName, args, fileCount);
                     const cached = cacheIndex.getEntry(cacheQueries, cacheKey);
-                    if (cached) {
+                    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);
@@ -2082,8 +2125,8 @@ class ToolHandler {
                             // 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) {
@@ -2137,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.');
         }
@@ -2193,6 +2240,10 @@ class ToolHandler {
         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;
@@ -2406,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.');
         }
@@ -2449,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');
@@ -5339,7 +5391,7 @@ class ToolHandler {
                 } } };
     }
     /** Select once; legacy section builders consume the same canonical query/features. */
-    tryPlannedFastPath(cg, plan, root) {
+    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);
@@ -5350,8 +5402,8 @@ class ToolHandler {
         if (plan.source === 'llm' && (plan.intent === 'general' || plan.intent === 'flow'))
             return null;
         return this.tryFastInventoryExplore(cg, query, root, plan)
-            ?? this.tryLightMechanismExplore(cg, query, root, plan)
-            ?? this.tryCompactLocalSymbolExplore(cg, query, root, plan);
+            ?? 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) {
@@ -5385,7 +5437,7 @@ class ToolHandler {
             return served;
         }
         const fast = args[QUERY_FAST_ATTEMPTED_ARG] === true && plan.source === 'rules'
-            ? null : this.tryPlannedFastPath(cg, plan, cg.getProjectRoot());
+            ? null : this.tryPlannedFastPath(cg, plan, cg.getProjectRoot(), args._hgEvidenceMaxChars);
         if (fast)
             return fast;
         return this.handleExplore({ ...args, query, [QUERY_PLAN_ARG]: plan });
@@ -5448,7 +5500,10 @@ class ToolHandler {
             }
             seenQueries.add(`${compiled.intent}:${compiled.canonicalQuery}`);
             try {
-                const result = await this.executePlannedStep({ ...args, [QUERY_DEADLINE_ARG]: deadline }, compiled);
+                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];
@@ -5491,7 +5546,16 @@ class ToolHandler {
                 bindings.set(step.id, visibleBindings);
                 const bodyCap = Math.max(0, cap - receipt.length - 2);
                 const trimmed = neutralBody.length > bodyCap;
-                const kept = (0, evidence_rendering_1.trimEvidenceAtLine)(neutralBody, bodyCap);
+                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
@@ -6185,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))
@@ -6223,7 +6307,7 @@ class ToolHandler {
      * findRelevantContext. Fast enough for MCP budget; complete enough to avoid
      * agent grep/read loops (token savings).
      */
-    tryLightMechanismExplore(cg, query, projectRoot, plan) {
+    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']);
@@ -6394,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)));
@@ -6861,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, plan) {
+    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).
@@ -7041,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('/');
@@ -10312,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).
@@ -11980,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)`);
@@ -12047,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,
@@ -12069,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}`);
             }
         }
@@ -12076,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`);
@@ -12979,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');

package/dist/spec/llm/client.js

@@ -1,23 +1,10 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAiLlmClient = void 0;
 exports.parseJsonResponse = parseJsonResponse;
-/**
- * Provider-agnostic LLM client for spec
- *
- * Supports OpenAI-compatible chat completions API with automatic retry on
- * transient errors (rate limits, server errors, network failures). No mock
- * mode — callers that need test doubles inject their own stubs implementing
- * the interface.
- *
- * @module spec/llm/client
- */
-const openai_1 = __importDefault(require("openai"));
 const errors_1 = require("../../errors");
 const retry_1 = require("./retry");
+const openai_sdk_1 = require("./openai-sdk");
 // =============================================================================
 // Shared JSON extraction
 // =============================================================================
@@ -102,7 +89,8 @@ class OpenAiLlmClient {
      * we handle retries ourselves with proper visibility).
      */
     buildClient() {
-        return new openai_1.default({
+        const OpenAI = (0, openai_sdk_1.loadOpenAI)();
+        return new OpenAI({
             apiKey: this.config.apiKey,
             baseURL: this.resolveBaseURL(),
             maxRetries: 0, // disable SDK retry

package/dist/spec/llm/openai-sdk.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lazy load of the optional `openai` package (Spec 0031).
+ *
+ * MCP `serve mcp` must start without it. Spec LLM commands require
+ * `npm install openai`.
+ *
+ * @module spec/llm/openai-sdk
+ */
+export declare const OPENAI_INSTALL_HINT = "The openai package is not installed. Spec LLM calls need it: npm install openai";
+/** Default export of `openai` — the client constructor plus `RateLimitError` etc. */
+export type OpenAIClientCtor = typeof import('openai').default;
+export declare function loadOpenAI(): OpenAIClientCtor;
+export declare function tryLoadOpenAI(): OpenAIClientCtor | undefined;
+//# sourceMappingURL=openai-sdk.d.ts.map