homegraph 1.5.6 → 1.5.8

package/dist/mcp/explore-repeat-guard.js

@@ -2,13 +2,9 @@
 /**
  * Session-level explore repeat / partial guidance (generic).
  *
- * Stops agents from treating `homegraph_explore` as an iterative keyword
- * searcher: overlapping queries after a successful explore get a short refuse
- * instead of another multi-kB payload. Partial/busy replies carry concrete
- * retry anchors extracted from the query — never an empty 242-char shell.
- *
- * Failure fuse (post A/B): hard-cap explores per session, require tight
- * single-Type follow-ups after 2 calls, and bind Partial → named Next anchor.
+ * Repeated evidence is deduplicated; lexical overlap alone cannot prove that a
+ * follow-up's evidence obligation is already covered. Incomplete retrieval gets
+ * one bounded recovery, including when the first response was short or SDK-only.
  *
  * Shape-driven only — no product nouns.
  */
@@ -36,6 +32,7 @@ exports.formatSecondPartialStopFooter = formatSecondPartialStopFooter;
 exports.extractRetryIntentHints = extractRetryIntentHints;
 exports.formatPartialExploreGuidance = formatPartialExploreGuidance;
 const query_utils_1 = require("../search/query-utils");
+const explore_session_state_1 = require("./explore-session-state");
 /** Tokens that do not distinguish one explore bag from another. */
 const STOP = new Set([
     'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'on', 'for', 'with', 'from',
@@ -153,21 +150,17 @@ function extractNextAnchorFromText(text) {
     return id?.slice(0, 120);
 }
 function inferExplorePartialMeta(text) {
-    // Soft-close / coarse-locate ANSWER must win over a leftover Partial header
-    // (same response used to emit both — session fuse must treat it as closed).
-    const closedAnswer = /\*\*ANSWER NOW\*\*|Mechanism explore complete — \*\*ANSWER NOW\*\*|Explore complete — ANSWER NOW|Coarse locate — ANSWER|Coarse locate complete/i
-        .test(text);
-    const partial = /\*\*Partial locator\*\*|Partial locator|⚠️ \*\*Partial result\*\*|\*\*Partial result\*\*/i.test(text)
-        && !closedAnswer;
+    // Compatibility for renderers without structured receipts. A positive
+    // completion slogan must never erase a separately reported coverage gap.
+    const partial = /\*\*Partial locator\*\*|Partial locator|⚠️ \*\*Partial result\*\*|\*\*Partial result\*\*/i.test(text);
     return {
         partial,
         nextAnchor: partial ? extractNextAnchorFromText(text) : undefined,
     };
 }
-const OVERLAP_THRESHOLD = 0.45;
 /**
- * Absolute explore fuse per session/project (counted responses ≥400 chars).
- * After this many, refuse — answer from prior Anchors or ONE narrow Grep.
+ * Absolute retrieval budget per session/project. Empty receipts count as
+ * attempts too, so failed recovery cannot create an unbounded retry loop.
  */
 const MAX_EXPLORES = 2;
 /**
@@ -177,21 +170,7 @@ const MAX_EXPLORES = 2;
  */
 const MAX_DEPTH_AFTER_PARTIAL = 1;
 function isCountedCall(call) {
-    return (call.responseBytes || 0) >= 400;
-}
-/** Shared mechanism domain stems (theme/install/xml/…) between two queries. */
-function domainStemOverlap(a, b) {
-    const sa = new Set((0, query_utils_1.mechanismDomainPathTokens)(a));
-    const sb = new Set((0, query_utils_1.mechanismDomainPathTokens)(b));
-    let shared = 0;
-    for (const t of sa) {
-        if (sb.has(t))
-            shared++;
-    }
-    return shared;
-}
-function hadClosedExplore(calls) {
-    return calls.some((c) => isCountedCall(c) && c.partial !== true);
+    return call.evidenceStatus !== undefined || (call.responseBytes || 0) >= 400;
 }
 /**
  * Whether this explore should short-refuse instead of re-running.
@@ -199,59 +178,31 @@ function hadClosedExplore(calls) {
 function decideExploreRepeat(prior, query) {
     if (!prior || prior.calls.length === 0)
         return { refuse: false, reason: 'ok' };
-    const qTokens = exploreQueryTokens(query);
     const counted = prior.calls.filter(isCountedCall);
-    const novel = novelAnchorsVsPriors(query, prior.calls);
     const last = counted[counted.length - 1];
-    // Hard fuse — never explore×N after two counted calls (inventory Manager hops included).
-    if (counted.length >= MAX_EXPLORES) {
+    // Keep the lifetime budget even if bounded state has evicted early receipts.
+    if (Math.max(prior.callCount, counted.length) >= MAX_EXPLORES) {
         return {
             refuse: true,
             matched: last,
             reason: 'hard-cap',
         };
     }
-    // Partial named a Next anchor — follow-up MUST include that name (no novel-Type bypass).
-    if (last?.partial && last.nextAnchor) {
-        const na = last.nextAnchor.toLowerCase();
-        if (!query.toLowerCase().includes(na)) {
-            return {
-                refuse: true,
-                matched: last,
-                reason: 'next-anchor',
-            };
-        }
-    }
-    // After a closed ANSWER explore, refuse NL paraphrase bags that share domain
-    // stems (theme/install/parse…) — stops D33-style explore×N token storms.
-    if (hadClosedExplore(counted) && !isTightExploreFollowUp(query)) {
-        for (const call of counted) {
-            if (call.partial === true)
-                continue;
-            const overlap = queryTokenOverlapScore(qTokens, exploreQueryTokens(call.query));
-            const domainShared = domainStemOverlap(query, call.query);
-            if (domainShared >= 2 || overlap >= 0.28) {
-                return { refuse: true, matched: call, reason: 'overlap' };
-            }
-        }
-    }
-    // Overlap with any prior counted explore — unless a tight novel Type/file bag
-    // (and, after Partial, only when Next anchor is already in the query above).
-    if (novel.length > 0 && isTightExploreFollowUp(query)) {
+    // Missing or SDK-only evidence is not a successfully answered query. Permit
+    // its single recovery even if the query overlaps or uses another next anchor.
+    if (last && (0, explore_session_state_1.inferExploreEvidenceStatus)(last) !== 'complete') {
         return { refuse: false, reason: 'ok' };
     }
-    let best;
-    let bestScore = 0;
+    const normalized = (s) => s.trim().toLowerCase().replace(/\s+/g, ' ');
     for (const call of counted) {
-        const score = queryTokenOverlapScore(qTokens, exploreQueryTokens(call.query));
-        if (score > bestScore) {
-            bestScore = score;
-            best = call;
+        if ((0, explore_session_state_1.inferExploreEvidenceStatus)(call) !== 'complete')
+            continue;
+        // Even the same token bag can reverse a relation ("A calls B" versus
+        // "B calls A"). Only an identical normalized request proves repetition.
+        if (normalized(query) === normalized(call.query)) {
+            return { refuse: true, matched: call, reason: 'overlap' };
         }
     }
-    if (best && bestScore >= OVERLAP_THRESHOLD) {
-        return { refuse: true, matched: best, reason: 'overlap' };
-    }
     return { refuse: false, reason: 'ok' };
 }
 /** Short success-shaped refuse when a repeat explore would waste tokens. */
@@ -262,12 +213,12 @@ function formatExploreRepeatRefuse(decision, query) {
         ? `\nAlready covered files include: ${files.map((f) => `\`${f}\``).join(', ')}.`
         : '';
     const next = decision.matched?.nextAnchor
-        ? `\nPrior **Next anchor** was \`${decision.matched.nextAnchor}\` — use that name, or ONE narrow Grep.`
+        ? `\nSuggested **Next anchor:** \`${decision.matched.nextAnchor}\`.`
         : '';
     let why;
     switch (decision.reason) {
         case 'hard-cap':
-            why = `This session already ran **${MAX_EXPLORES}** \`homegraph_explore\` calls on this project. Stop exploring.`;
+            why = `This session reached its **${MAX_EXPLORES}** \`homegraph_explore\` retrieval attempts on this project, including incomplete attempts.`;
             break;
         case 'next-anchor':
             why = `Prior explore was Partial and named a **Next anchor** — do not re-explore a paraphrase of "${priorQ}${priorQ.length >= 100 ? '…' : ''}".`;
@@ -276,14 +227,14 @@ function formatExploreRepeatRefuse(decision, query) {
             why = `Explore call budget exhausted for this project in the session.`;
             break;
         default:
-            why = `This query overlaps a prior explore (bag ≈ "${priorQ}${priorQ.length >= 100 ? '…' : ''}").`;
+            why = `This query repeats the same evidence request as "${priorQ}${priorQ.length >= 100 ? '…' : ''}".`;
     }
     return [
-        '**Skip repeat explore — stop HomeGraph drill-down.**',
+        '**Explore retrieval limit — reuse evidence already returned.**',
         why + fileLine + next,
         `Current query: "${query.trim().slice(0, 160)}${query.trim().length > 160 ? '…' : ''}"`,
-        'Answer from Anchors / digests already in this conversation, or run **ONE narrow Grep** for residual unindexed wiring.',
-        'Do **not** glob/read the whole repo, and do **not** fan out `homegraph_explore` / `homegraph_node` / callers on the same bag.',
+        'This limit does not mean the task or its evidence is complete. Inspect missing source with a targeted Read or narrow Grep, then continue the requested edits and validation.',
+        'Do not repeat the same explore or reread unchanged source already shown; keep any remaining inspection scoped to uncovered evidence.',
     ].join('\n');
 }
 /** Latest counted explore call (≥400 response bytes), if any. */
@@ -301,21 +252,14 @@ function latestCountedExplore(prior) {
  * Whether `homegraph_node` / callers / callees should short-refuse after a
  * Partial explore (same failure class as explore×N — depth fan-out).
  *
- * After Partial: callers/callees are refused immediately (wrong tool + often a
- * multi-def token bomb). `homegraph_node` gets one shot, then refuse.
+ * Any one focused depth tool may recover missing evidence. The shared budget
+ * prevents fan-out without declaring callers/callees intrinsically invalid.
  */
-function decideDepthToolFuse(prior, depthCallCount, toolName) {
+function decideDepthToolFuse(prior, depthCallCount, _toolName) {
     const last = latestCountedExplore(prior);
-    if (!last?.partial)
+    if (!last || (0, explore_session_state_1.inferExploreEvidenceStatus)(last) === 'complete')
         return { refuse: false, reason: 'ok' };
     const nextAnchor = last.nextAnchor;
-    if (toolName === 'homegraph_callers' || toolName === 'homegraph_callees') {
-        return {
-            refuse: true,
-            reason: 'partial-no-callers',
-            nextAnchor,
-        };
-    }
     if (depthCallCount >= MAX_DEPTH_AFTER_PARTIAL) {
         return {
             refuse: true,
@@ -328,20 +272,18 @@ function decideDepthToolFuse(prior, depthCallCount, toolName) {
 /** Success-shaped refuse when Partial already spent its one depth drill. */
 function formatDepthToolRefuse(decision, toolName, symbolHint) {
     const next = decision.nextAnchor
-        ? `\nPrior **Next anchor** was \`${decision.nextAnchor}\` — ONE \`homegraph_node\` / tighter explore with that name, or ONE narrow Grep.`
+        ? `\nSuggested **Next anchor:** \`${decision.nextAnchor}\`.`
         : '';
     const sym = symbolHint?.trim()
         ? `\nRequested: \`${symbolHint.trim().slice(0, 80)}\``
         : '';
-    const why = decision.reason === 'partial-no-callers'
-        ? `Prior \`homegraph_explore\` was a Partial locator — do **not** call \`${toolName}\` next (multi-def dumps + fan-out).`
-        : `Prior \`homegraph_explore\` was a Partial locator; this session already used its **${MAX_DEPTH_AFTER_PARTIAL}** `
-            + `allowed \`homegraph_node\` call on this project.`;
+    const why = `Prior retrieval was incomplete; this session already used its **${MAX_DEPTH_AFTER_PARTIAL}** `
+        + `focused depth recovery call on this project (requested \`${toolName}\`).`;
     return [
-        '**Skip HomeGraph depth drill — stop after Partial.**',
+        '**Depth recovery budget reached — evidence may still be incomplete.**',
         why + next + sym,
-        'Answer from Anchors / digests already in this conversation, or run **ONE narrow Grep** for residual unindexed wiring.',
-        'Do **not** fan out more `homegraph_node` / callers / callees, and do **not** glob/read the whole repo.',
+        'Use a targeted Read or narrow Grep for the missing evidence, then continue the requested edits and validation.',
+        'Reuse source already shown and avoid repeating the same depth query.',
     ].join('\n');
 }
 /**
@@ -446,33 +388,31 @@ function formatNextAnchorCaption(c) {
     return `\`${c.name}\` (${c.kind}) — \`${c.filePath.replace(/\\/g, '/')}:${line}\``;
 }
 /**
- * Soft-close opening banner (must match footer — never pair with Partial locator).
+ * Coarse retrieval banner: source reuse is separate from task completion.
  */
 function formatMechanismSoftCloseHeader() {
-    return ('> **Coarse locate — ANSWER from anchors + digests below.** '
-        + 'Treat inventory + Source as already Read. '
-        + 'ONE narrow Grep only for residual unindexed wiring — do not re-explore or fan out depth tools.');
+    return ('> **Coarse source evidence below.** '
+        + 'Reuse the source shown for these symbols. '
+        + 'Check relevance and uncovered wiring before continuing the requested edits or explanation.');
 }
 /**
- * Soft-close footer: enough inventory + digest to answer without another explore.
- * Must NOT contain "Partial locator" so the session fuse treats the call as closed.
+ * Coarse retrieval footer; never claims that an inventory completes the task.
  */
 function formatMechanismSoftCloseFooter(next) {
     const hint = next
         ? ` Primary Type: \`${next.name}\`.`
         : '';
-    return ('> **Coarse locate — ANSWER from anchors + digests above.**'
+    return ('> **Coarse source evidence returned.**'
         + hint
-        + ' ONE narrow Grep only for residual unindexed wiring named above. '
-        + 'Do **not** re-explore, fan out `homegraph_node` / callers, or glob/read the repo.');
+        + ' Retrieval is not task completion. Reuse the displayed source; inspect uncovered code '
+        + 'with one focused follow-up or targeted Read/Grep, then continue authorized edits and checks.');
 }
 /** Honest Partial footer with a single Next anchor + ONE Grep. */
 function formatMechanismPartialFooter(nextCaption) {
     return ('> **Partial locator** — not a full mechanism closure. '
         + `**Next anchor:** ${nextCaption}. `
-        + 'ONE tighter `homegraph_explore` **only** with that exact name, '
-        + 'or **ONE narrow Grep** for residual unindexed wiring — '
-        + 'do **not** fan out `homegraph_node` / Read / glob, and do **not** ANSWER NOW from inventory alone.');
+        + 'One focused recovery may use this anchor or a different uncovered part of the task. '
+        + 'Use targeted Read/Grep if the evidence remains missing; an inventory alone does not establish behavior.');
 }
 /**
  * Appended when a second counted Partial is emitted in the same session —
@@ -485,10 +425,10 @@ function formatSecondPartialStopFooter(nextAnchor) {
     return [
         '',
         '---',
-        '> **Second Partial — stop HomeGraph.** Do **not** call `homegraph_explore` again.'
+        '> **Second Partial — explore retrieval budget reached.** Do not repeat `homegraph_explore`.'
             + next
-            + ' Answer from Anchors / digests already returned, or **ONE narrow Grep** for residual unindexed wiring. '
-            + 'Do not glob/read the whole repo.',
+            + ' Evidence remains incomplete. Inspect only missing source with targeted Read or narrow Grep, '
+            + 'then continue the requested edits and validation. Reuse unchanged source already returned.',
     ].join('\n');
 }
 /**
@@ -531,10 +471,10 @@ function formatPartialExploreGuidance(opts) {
         : 'If you retry, ONE tight \`homegraph_explore\` with a single Type / file / `@kit` name — not a broad paraphrase.';
     return [
         `⚠️ **Partial result** — ${why}. This is NOT an error.`,
-        'Prefer **ONE narrow Grep** for residual unindexed wiring using names already in the question — do **not** glob/read the repo.',
+        'A targeted Read or **ONE narrow Grep** may recover missing evidence using names already in the question.',
         anchorLine,
-        'At most **one** `homegraph_node` (or callers/callees) after Partial — further depth calls are refused. Do not open a Grep/Read storm.',
-        'If a second explore still Partials, **stop HomeGraph** and answer from anchors + ONE narrow Grep.',
+        'At most **one** focused `homegraph_node` or callers/callees recovery after Partial; reuse source already returned.',
+        'If a second explore is still Partial, its retrieval budget is exhausted. Inspect missing source directly and continue the requested work; do not infer task completion.',
     ].join('\n');
 }
 //# sourceMappingURL=explore-repeat-guard.js.map

package/dist/mcp/explore-session-state.d.ts

@@ -74,6 +74,8 @@ export interface ExploreFileEmission {
     /** Set when ranges were dropped to stay under the per-file bound. */
     rangesTruncated?: boolean;
 }
+/** Retrieval coverage only; even complete evidence does not complete a coding task. */
+export type ExploreEvidenceStatus = 'complete' | 'partial' | 'empty' | 'sdk-only';
 /** What one explore call emitted, as reported by the handler. */
 export interface ExploreEmission {
     /** Resolved project root — the key state is filed under. */
@@ -85,14 +87,30 @@ export interface ExploreEmission {
     sourceBytes: number;
     /** Total chars of the response the agent received. */
     responseBytes: number;
+    /** Internal receipt: declarations actually shown, not all retrieval candidates.
+     * A located node is source-grounded, not proof of relevance to the user's task.
+     */
+    locatedNodes?: Array<{
+        id: string;
+        name: string;
+        qualifiedName?: string;
+        filePath: string;
+        startLine: number;
+    }>;
+    /** Derived by the executor from emitted evidence, never from a completion banner. */
+    evidenceStatus?: ExploreEvidenceStatus;
+    /** Bounded descriptions of retrieval obligations with emitted supporting evidence. */
+    coveredObligations?: string[];
+    /** Requested retrieval obligations that the emitted evidence did not cover. */
+    uncoveredObligations?: string[];
     /**
-     * True when the response was an honest Partial / coarse locator (not a
-     * closed ANSWER NOW). Used by the repeat guard to fuse failures.
+     * True when some requested evidence is missing. Legacy renderers may supply
+     * this without evidenceStatus; a textual completion banner cannot clear it.
      */
     partial?: boolean;
     /**
-     * Concrete next Type / file the Partial named — follow-up explore must
-     * include this string (case-insensitive) or be refused as paraphrase churn.
+     * Suggested next Type / file. Advisory: a missing evidence obligation may
+     * require a different source, especially after an irrelevant first hit.
      */
     nextAnchor?: string;
 }
@@ -140,7 +158,11 @@ export declare const EXPLORE_SESSION_LIMITS: {
     readonly MAX_RANGES_PER_FILE: 24;
     /** Most-recent calls per project included in {@link ExploreSessionView}. */
     readonly MAX_VIEW_CALLS: 4;
+    readonly MAX_LOCATED_NODES: 64;
+    readonly MAX_OBLIGATIONS: 12;
 };
+/** Conservative fallback for older renderers that have not supplied a receipt. */
+export declare function inferExploreEvidenceStatus(emission: ExploreEmission): ExploreEvidenceStatus;
 /**
  * Key a project root is filed under. Resolved so `/repo` and `/repo/` agree;
  * case-folded on the two platforms whose filesystems are case-insensitive, so a

package/dist/mcp/explore-session-state.js

@@ -73,6 +73,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExploreSessionState = exports.EXPLORE_SESSION_LIMITS = exports.EXPLORE_SESSION_VIEW_ARG = exports.EXPLORE_EMISSION_KEY = void 0;
+exports.inferExploreEvidenceStatus = inferExploreEvidenceStatus;
 exports.exploreProjectKey = exploreProjectKey;
 exports.coalesceRanges = coalesceRanges;
 exports.rangesCover = rangesCover;
@@ -113,7 +114,31 @@ exports.EXPLORE_SESSION_LIMITS = {
     MAX_RANGES_PER_FILE: 24,
     /** Most-recent calls per project included in {@link ExploreSessionView}. */
     MAX_VIEW_CALLS: 4,
+    MAX_LOCATED_NODES: 64,
+    MAX_OBLIGATIONS: 12,
 };
+/** Conservative fallback for older renderers that have not supplied a receipt. */
+function inferExploreEvidenceStatus(emission) {
+    if (emission.evidenceStatus === 'empty' || emission.evidenceStatus === 'sdk-only') {
+        return emission.evidenceStatus;
+    }
+    if (emission.partial || emission.uncoveredObligations?.length || emission.evidenceStatus === 'partial') {
+        return 'partial';
+    }
+    if (emission.evidenceStatus === 'complete')
+        return 'complete';
+    const paths = [
+        ...(Array.isArray(emission.files) ? emission.files : [])
+            .filter((f) => f && f.bytes > 0 && f.ranges?.length > 0).map((f) => f.path),
+        ...(Array.isArray(emission.locatedNodes) ? emission.locatedNodes : [])
+            .filter((n) => n && typeof n.filePath === 'string').map((n) => n.filePath),
+    ];
+    if (paths.length === 0)
+        return 'empty';
+    if (paths.every((p) => /^(?:ohos-sdk|sdk):/i.test(p)))
+        return 'sdk-only';
+    return 'complete';
+}
 /**
  * Key a project root is filed under. Resolved so `/repo` and `/repo/` agree;
  * case-folded on the two platforms whose filesystems are case-insensitive, so a
@@ -195,7 +220,13 @@ class ExploreSessionState {
             files: this.boundFiles(emission.files),
             sourceBytes: Math.max(0, emission.sourceBytes || 0),
             responseBytes: Math.max(0, emission.responseBytes || 0),
-            partial: emission.partial === true,
+            evidenceStatus: inferExploreEvidenceStatus(emission),
+            coveredObligations: boundObligations(emission.coveredObligations),
+            uncoveredObligations: boundObligations(emission.uncoveredObligations),
+            locatedNodes: (Array.isArray(emission.locatedNodes) ? emission.locatedNodes : []).filter((n) => n && typeof n.id === 'string'
+                && typeof n.name === 'string' && typeof n.filePath === 'string' && Number.isFinite(n.startLine))
+                .slice(0, exports.EXPLORE_SESSION_LIMITS.MAX_LOCATED_NODES).map((n) => ({ ...n })),
+            partial: inferExploreEvidenceStatus(emission) !== 'complete',
             nextAnchor: typeof emission.nextAnchor === 'string' && emission.nextAnchor.trim()
                 ? emission.nextAnchor.trim().slice(0, 120)
                 : undefined,
@@ -204,7 +235,7 @@ class ExploreSessionState {
         if (state.calls.length > exports.EXPLORE_SESSION_LIMITS.MAX_CALLS_RETAINED) {
             state.calls.splice(0, state.calls.length - exports.EXPLORE_SESSION_LIMITS.MAX_CALLS_RETAINED);
         }
-        // Fresh explore → reset depth fuse window (Partial gets one drill; closed clears).
+        // Fresh retrieval resets the bounded recovery window; task completion is unrelated.
         if (record.partial)
             this.depthAfterPartial.set(key, 0);
         else
@@ -253,7 +284,7 @@ class ExploreSessionState {
                 responseBytes: state.responseBytes,
                 calls: state.calls
                     .slice(-exports.EXPLORE_SESSION_LIMITS.MAX_VIEW_CALLS)
-                    .map((c) => ({ ...c, files: c.files.map((f) => ({ ...f, ranges: [...f.ranges] })) })),
+                    .map(cloneCall),
             })),
         };
     }
@@ -318,7 +349,22 @@ function cloneProject(state) {
         projectRoot: state.projectRoot,
         callCount: state.callCount,
         responseBytes: state.responseBytes,
-        calls: state.calls.map((c) => ({ ...c, files: c.files.map((f) => ({ ...f, ranges: [...f.ranges] })) })),
+        calls: state.calls.map(cloneCall),
+    };
+}
+function boundObligations(values) {
+    if (!Array.isArray(values))
+        return undefined;
+    return [...new Set(values.filter((s) => typeof s === 'string' && s.trim())
+            .map((s) => s.trim().slice(0, 240)))].slice(0, exports.EXPLORE_SESSION_LIMITS.MAX_OBLIGATIONS);
+}
+function cloneCall(c) {
+    return {
+        ...c,
+        files: c.files.map((f) => ({ ...f, ranges: f.ranges.map((r) => ({ ...r })) })),
+        locatedNodes: c.locatedNodes?.map((n) => ({ ...n })),
+        coveredObligations: c.coveredObligations ? [...c.coveredObligations] : undefined,
+        uncoveredObligations: c.uncoveredObligations ? [...c.uncoveredObligations] : undefined,
     };
 }
 /**

package/dist/mcp/index-availability.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Product-facing index availability for MCP tool results (Spec 0032).
+ *
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy)
+ * to the four states hosts and agents should see in tool text.
+ */
+import type HomeGraph from '../index';
+/** Agent-visible index readiness (tool return copy — not tools/list gating). */
+export type ProductIndexState = 'empty' | 'fast' | 'full' | 'syncing';
+export declare function productIndexGuidance(state: Exclude<ProductIndexState, 'full'>): string;
+/**
+ * Resolve the product state from a live HomeGraph handle.
+ *
+ * - empty: fast map not ready (`none` / `building_fast`)
+ * - fast: map ready, full index not done (`fast` / `indexing`)
+ * - full: symbol index ready
+ * - syncing: full (or empty-while-contended-init) and a writer holds the lock /
+ *   this process is indexing — reads may fail or see a moving target
+ */
+export declare function resolveProductIndexState(cg: HomeGraph): ProductIndexState;
+/** True when an error message indicates SQLite writer contention. */
+export declare function isSqliteBusyMessage(message: string): boolean;
+//# sourceMappingURL=index-availability.d.ts.map

package/dist/mcp/index-availability.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Product-facing index availability for MCP tool results (Spec 0032).
+ *
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy)
+ * to the four states hosts and agents should see in tool text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.productIndexGuidance = productIndexGuidance;
+exports.resolveProductIndexState = resolveProductIndexState;
+exports.isSqliteBusyMessage = isSqliteBusyMessage;
+const EMPTY_LINES = [
+    'HomeGraph status=empty — project map is not ready yet.',
+    'Retry in a few seconds (or call `homegraph_project` once the fast build completes).',
+];
+const FAST_LINES = [
+    'HomeGraph status=fast — module/file map is ready; full symbol index is still building.',
+    'Use `homegraph_project` for the module/file map now, then retry this tool once indexing finishes.',
+];
+const SYNCING_LINES = [
+    'HomeGraph status=syncing — the index is being written (lock held or local index/sync in progress).',
+    'Retry this tool shortly; do not busy-loop.',
+];
+function productIndexGuidance(state) {
+    switch (state) {
+        case 'empty':
+            return EMPTY_LINES.join('\n');
+        case 'fast':
+            return FAST_LINES.join('\n');
+        case 'syncing':
+            return SYNCING_LINES.join('\n');
+    }
+}
+/**
+ * Resolve the product state from a live HomeGraph handle.
+ *
+ * - empty: fast map not ready (`none` / `building_fast`)
+ * - fast: map ready, full index not done (`fast` / `indexing`)
+ * - full: symbol index ready
+ * - syncing: full (or empty-while-contended-init) and a writer holds the lock /
+ *   this process is indexing — reads may fail or see a moving target
+ */
+function resolveProductIndexState(cg) {
+    let phase;
+    try {
+        phase = cg.getBuildPhase();
+    }
+    catch {
+        return 'syncing';
+    }
+    if (phase === 'building_fast' || phase === 'none') {
+        try {
+            if (cg.isWriteLockedByOther())
+                return 'syncing';
+        }
+        catch {
+            return 'syncing';
+        }
+        return 'empty';
+    }
+    if (phase === 'fast' || phase === 'indexing') {
+        return 'fast';
+    }
+    // full
+    try {
+        if (cg.isWriteLockedByOther() || cg.isIndexing())
+            return 'syncing';
+    }
+    catch {
+        return 'syncing';
+    }
+    return 'full';
+}
+/** True when an error message indicates SQLite writer contention. */
+function isSqliteBusyMessage(message) {
+    return /SQLITE_BUSY|database is locked/i.test(message);
+}
+//# sourceMappingURL=index-availability.js.map

package/dist/mcp/index.js

@@ -142,8 +142,9 @@ function daemonInternalSet() {
  * fail to share the daemon.
  */
 function resolveDaemonRoot(explicitPath) {
-    const candidate = explicitPath ?? process.cwd();
-    const root = (0, directory_1.findNearestHomeGraphRoot)(candidate);
+    // An explicit host path is also the walk-up floor (spec 0028): a stray
+    // ancestor .homegraph must not redirect the daemon to the wrong tree.
+    const root = (0, directory_1.findNearestHomeGraphRoot)(explicitPath ?? process.cwd(), explicitPath ?? undefined);
     if (!root)
         return null;
     try {
@@ -349,7 +350,7 @@ class MCPServer {
         // is a second V8 isolate + a second open of the project DB, and on large
         // indexes (hundreds of MB) that alone pushed process-tree RSS to ~5GB.
         // Soft deadlines + compact-before-pool still run on the warm main connection.
-        this.engine = new engine_1.MCPEngine({ queryPool: false });
+        this.engine = new engine_1.MCPEngine({ queryPool: false, rootFloor: this.projectPath ?? undefined });
         const transport = new transport_1.StdioTransport();
         this.session = new session_1.MCPSession(transport, this.engine, {
             explicitProjectPath: this.projectPath,
@@ -471,7 +472,7 @@ class MCPServer {
             getDaemonSocket,
             // Daemon-unavailable fallback is one client — same as direct mode: no
             // pool. Duplicating the DB open here blew RSS on large indexes.
-            makeEngine: () => new engine_1.MCPEngine({ queryPool: false }),
+            makeEngine: () => new engine_1.MCPEngine({ queryPool: false, rootFloor: root ?? undefined }),
             root,
         });
     }

package/dist/mcp/query-cache.d.ts

@@ -15,7 +15,7 @@
 import type { QueryBuilder } from '../db/queries';
 import type { ToolResult } from './tools';
 /** Bump when cache-key normalization or cached payload shape changes. */
-export declare const QUERY_CACHE_FORMAT_VERSION = 1;
+export declare const QUERY_CACHE_FORMAT_VERSION = 5;
 export declare function isMcpQueryCacheEnabled(): boolean;
 export declare function isCacheableMcpTool(toolName: string): boolean;
 /**