homegraph 1.5.6 → 1.5.8

package/dist/mcp/engine.js

@@ -49,7 +49,6 @@ exports.parseFixedWindowEnv = parseFixedWindowEnv;
 exports.parseDebounceEnv = parseDebounceEnv;
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 const directory_1 = require("../directory");
 const sync_1 = require("../sync");
 const tools_1 = require("./tools");
@@ -87,7 +86,7 @@ class MCPEngine {
     // project is open — workers each hold their own WAL read connection.
     queryPool = null;
     constructor(opts = {}) {
-        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false };
+        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false, rootFloor: opts.rootFloor ?? null };
         this.toolHandler = new tools_1.ToolHandler(null);
     }
     /**
@@ -146,7 +145,7 @@ class MCPEngine {
      * subsequent-tool-call semantics; we preserve them by NOT throwing when the
      * search misses (just leaves `cg` null so the next call can retry).
      */
-    async ensureInitialized(searchFrom) {
+    async ensureInitialized(searchFrom, floor) {
         if (this.closed)
             return;
         if (this.toolHandler.hasDefaultHomeGraph())
@@ -158,7 +157,7 @@ class MCPEngine {
             catch { /* let caller retry */ }
             return;
         }
-        this.initPromise = this.doInitialize(searchFrom).finally(() => {
+        this.initPromise = this.doInitialize(searchFrom, floor).finally(() => {
             this.initPromise = null;
         });
         try {
@@ -174,13 +173,13 @@ class MCPEngine {
      * background `ensureInitialized` already finished (or failed) and we need
      * to pick up a project that appeared *after* the engine started.
      */
-    retryInitializeSync(searchFrom) {
+    retryInitializeSync(searchFrom, floor) {
         if (this.closed)
             return;
         if (this.toolHandler.hasDefaultHomeGraph())
             return;
         this.toolHandler.setDefaultProjectHint(searchFrom);
-        const resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom, floor ?? this.opts.rootFloor ?? undefined);
         if (!resolvedRoot)
             return;
         try {
@@ -230,9 +229,9 @@ class MCPEngine {
             this.cg = null;
         }
     }
-    async doInitialize(searchFrom) {
+    async doInitialize(searchFrom, floor) {
         this.toolHandler.setDefaultProjectHint(searchFrom);
-        let resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom);
+        let resolvedRoot = (0, directory_1.findNearestHomeGraphRoot)(searchFrom, floor ?? this.opts.rootFloor ?? undefined);
         if (!resolvedRoot && autoInitEnabled()) {
             const created = await this.tryAutoInit(searchFrom);
             if (created)
@@ -280,66 +279,86 @@ class MCPEngine {
             process.stderr.write(`[HomeGraph MCP] Auto-init skipped — ${invalid}\n`);
             return false;
         }
+        // Race: another process finished init before we entered — open, don't bail
+        // (Spec 0032). Returning false here left the session with no cg forever.
         if ((0, directory_1.isInitialized)(root)) {
-            // Race: another process finished init between our findNearest and here.
-            return false;
+            return this.openAfterAutoInitRace(root);
         }
         try {
             process.stderr.write(`[HomeGraph MCP] Auto-init at ${root}\n`);
             const HomeGraph = loadHomeGraph();
             // Create DB immediately so tools/open succeed; index in background.
             const cg = await HomeGraph.init(root, { index: false });
+            // Pin empty state before returning so the first tool call cannot see `none`
+            // while the async fast-map task has not started (Spec 0032).
+            cg.setBuildPhase('building_fast');
             this.cg = cg;
             this.projectPath = root;
             this.toolHandler.setDefaultHomeGraph(cg);
-            this.startWatching();
+            // Defer watch/catch-up until the full build finishes so auto-sync does not
+            // contend with the same-process writer (Spec 0032).
             this.maybeStartPool(root);
-            // Fast map in-process (seconds, MCP stays up). Full index in a *detached*
-            // child — in-process indexAll wedges the MCP event loop on large repos,
-            // so DevEco marks the server "Connection closed" and agents fall back.
+            // Fast build in-process (seconds). Full build continues in *this* process
+            // as a background task — no sibling CLI (avoids second writer / lock fights).
+            // indexAll already yields between batches so MCP stdio can still answer
+            // tools with empty/fast/syncing guidance while the full build runs.
             void (async () => {
                 try {
                     cg.setBuildPhase('building_fast');
                     const map = cg.buildProjectMap();
                     cg.setBuildPhase('fast');
-                    process.stderr.write(`[HomeGraph MCP] Fast project map ready — modules=${map.modules.length} files=${map.files.length} (${map.durationMs}ms)\n`);
+                    process.stderr.write(`[HomeGraph MCP] Fast build ready — modules=${map.modules.length} files=${map.files.length} (${map.durationMs}ms)\n`);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
-                    process.stderr.write(`[HomeGraph MCP] Fast project map failed: ${msg}\n`);
+                    process.stderr.write(`[HomeGraph MCP] Fast build failed: ${msg}\n`);
                 }
-                this.startDetachedFullIndex(cg, root);
+                this.startBackgroundFullBuild(cg);
             })();
             return true;
         }
         catch (err) {
             // Concurrent init from another process — treat as success path via open.
-            if ((0, directory_1.isInitialized)(root)) {
-                process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
-                try {
-                    const mode = (0, graph_sources_1.resolveGraphSources)();
-                    if (!(0, graph_sources_1.graphSourceFlags)(mode).openProjectDb)
-                        return false;
-                    this.cg = await loadHomeGraph().open(root, { sources: mode });
-                    this.projectPath = root;
-                    this.toolHandler.setDefaultHomeGraph(this.cg);
-                    this.healBuildPhase(this.cg);
-                    this.startWatching();
-                    this.catchUpSync();
-                    this.maybeStartPool(root);
-                    return true;
-                }
-                catch (openErr) {
-                    const msg = openErr instanceof Error ? openErr.message : String(openErr);
-                    process.stderr.write(`[HomeGraph MCP] Auto-init open-after-race failed: ${msg}\n`);
-                    return false;
-                }
+            if (await this.openAfterAutoInitRace(root)) {
+                return true;
             }
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Auto-init failed: ${msg}\n`);
             return false;
         }
     }
+    /**
+     * Open an index another process just created (Spec 0032 cold-start race).
+     * Brief retries cover the window between mkdir and db file create.
+     */
+    async openAfterAutoInitRace(root) {
+        const mode = (0, graph_sources_1.resolveGraphSources)();
+        if (!(0, graph_sources_1.graphSourceFlags)(mode).openProjectDb)
+            return false;
+        for (let i = 0; i < 25; i++) {
+            if (!(0, directory_1.isInitialized)(root)) {
+                await new Promise((r) => setTimeout(r, 40));
+                continue;
+            }
+            try {
+                process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
+                this.cg = await loadHomeGraph().open(root, { sources: mode });
+                this.projectPath = root;
+                this.toolHandler.setDefaultHomeGraph(this.cg);
+                this.healBuildPhase(this.cg);
+                this.startWatching();
+                this.catchUpSync();
+                this.maybeStartPool(root);
+                return true;
+            }
+            catch (openErr) {
+                const msg = openErr instanceof Error ? openErr.message : String(openErr);
+                process.stderr.write(`[HomeGraph MCP] Auto-init open-after-race retry: ${msg}\n`);
+                await new Promise((r) => setTimeout(r, 40));
+            }
+        }
+        return false;
+    }
     /**
      * If a previous auto-init child finished indexing but never flipped
      * build_phase (MCP died mid-flight), heal so deep tools unlock.
@@ -355,10 +374,18 @@ class MCPEngine {
                 process.stderr.write(`[HomeGraph MCP] Healed build_phase → full (index_state=${state})\n`);
                 return;
             }
-            // Index finished enough to have symbols but metadata stuck on indexing.
-            if ((phase === 'indexing' || phase === 'fast') && cg.getStats().nodeCount > 0 && state !== 'indexing') {
+            // Symbols present after a full-build attempt — unlock deep tools even if
+            // metadata stayed on indexing/fast (crash mid-flight or soft fail).
+            let nodes = 0;
+            try {
+                nodes = cg.getStats().nodeCount;
+            }
+            catch {
+                return;
+            }
+            if (nodes > 0 && state !== 'failed' && (phase === 'indexing' || phase === 'fast')) {
                 cg.setBuildPhase('full');
-                process.stderr.write(`[HomeGraph MCP] Healed build_phase → full (nodes present, index_state=${state ?? 'null'})\n`);
+                process.stderr.write(`[HomeGraph MCP] Healed build_phase → full (nodes=${nodes}, index_state=${state ?? 'null'})\n`);
             }
         }
         catch {
@@ -366,88 +393,68 @@ class MCPEngine {
         }
     }
     /**
-     * Run `homegraph index` in a detached sibling process so the MCP stdio
-     * server stays responsive (fast map + homegraph_project keep working).
+     * Full symbol build in this MCP/daemon process (Spec 0032).
+     * Fire-and-forget: MCP tools keep answering with empty/fast/syncing while
+     * indexAll yields between batches. One writer — no sibling CLI process.
      */
-    startDetachedFullIndex(cg, root) {
-        cg.setBuildPhase('indexing');
-        const scriptPath = process.argv[1];
-        if (!scriptPath) {
-            process.stderr.write('[HomeGraph MCP] No script path — falling back to in-process indexAll\n');
-            this.startInProcessFullIndex(cg);
-            return;
-        }
-        const args = [...process.execArgv, scriptPath, 'index', root];
-        const env = { ...process.env };
-        delete env.HOMEGRAPH_AUTO_INIT;
-        process.stderr.write(`[HomeGraph MCP] Spawning background full index (detached) for ${root}\n`);
-        try {
-            const child = (0, child_process_1.spawn)(process.execPath, args, {
-                detached: true,
-                stdio: 'ignore',
-                windowsHide: true,
-                env,
-            });
-            child.on('error', (err) => {
-                process.stderr.write(`[HomeGraph MCP] Detached index spawn error: ${err.message}; falling back in-process\n`);
-                this.startInProcessFullIndex(cg);
-            });
-            child.unref();
-            this.watchIndexCompletion(cg);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[HomeGraph MCP] Detached index spawn failed (${msg}); falling back in-process\n`);
-            this.startInProcessFullIndex(cg);
-        }
-    }
-    startInProcessFullIndex(cg) {
+    startBackgroundFullBuild(cg) {
         cg.setBuildPhase('indexing');
+        process.stderr.write('[HomeGraph MCP] Full build starting in-process (background)\n');
         void cg
             .indexAll()
             .then((result) => {
-            cg.setBuildPhase('full');
             const files = result && typeof result === 'object' && 'filesIndexed' in result
-                ? String(result.filesIndexed)
-                : '?';
-            process.stderr.write(`[HomeGraph MCP] Auto-init index complete — files=${files}\n`);
-        })
-            .catch((err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[HomeGraph MCP] Auto-init index failed: ${msg}\n`);
+                ? Number(result.filesIndexed ?? 0)
+                : 0;
+            const ok = !result || result.success !== false;
+            let nodes = 0;
             try {
-                cg.setBuildPhase('fast');
+                nodes = cg.getStats().nodeCount;
             }
             catch {
-                /* ignore */
+                /* busy */
             }
-        });
-    }
-    watchIndexCompletion(cg) {
-        const started = Date.now();
-        const maxMs = 3 * 60 * 60 * 1000;
-        const timer = setInterval(() => {
+            // Prefer symbols on disk over a soft failure flag — agents must unlock
+            // deep tools once a usable graph exists.
+            if (ok || nodes > 0 || files > 0) {
+                cg.setBuildPhase('full');
+                process.stderr.write(`[HomeGraph MCP] Full build complete — files=${files || '?'} nodes=${nodes}` +
+                    (ok ? '\n' : ' (soft-fail but symbols present)\n'));
+            }
+            else {
+                cg.setBuildPhase('fast');
+                process.stderr.write('[HomeGraph MCP] Full build finished with no symbols — staying on fast map\n');
+            }
+            this.startWatchingAfterAutoInit();
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[HomeGraph MCP] Full build failed: ${msg}\n`);
             try {
-                const state = cg.getQueryBuilder().getMetadata('index_state');
-                if (state === 'complete' || state === 'partial') {
-                    cg.setBuildPhase('full');
-                    clearInterval(timer);
-                    process.stderr.write(`[HomeGraph MCP] Auto-init index complete — index_state=${state}\n`);
-                    return;
+                let nodes = 0;
+                try {
+                    nodes = cg.getStats().nodeCount;
                 }
-                if (state === 'failed') {
-                    cg.setBuildPhase('fast');
-                    clearInterval(timer);
-                    process.stderr.write('[HomeGraph MCP] Auto-init index failed — index_state=failed\n');
-                    return;
+                catch {
+                    /* ignore */
+                }
+                cg.setBuildPhase(nodes > 0 ? 'full' : 'fast');
+                if (nodes > 0) {
+                    process.stderr.write(`[HomeGraph MCP] Full build error after symbols written — phase=full (nodes=${nodes})\n`);
                 }
             }
             catch {
-                /* lock / transient */
+                /* ignore */
             }
-            if (Date.now() - started > maxMs)
-                clearInterval(timer);
-        }, 2000);
+            this.startWatchingAfterAutoInit();
+        });
+    }
+    /** Enable watch + catch-up once auto-init full build is done (or gave up). */
+    startWatchingAfterAutoInit() {
+        if (this.watcherStarted)
+            return;
+        this.startWatching();
+        this.catchUpSync();
     }
     /**
      * Start file watching on the active HomeGraph instance. Idempotent — the

package/dist/mcp/evidence-rendering.d.ts

@@ -0,0 +1,10 @@
+import type { Node } from '../types';
+/** Multiple parser roles for one source declaration are not overloads. */
+export declare function canonicalSourceDeclarations(nodes: Node[]): Node[];
+/** Guidance describes retrieval; it must never close the host's coding task.
+ * Source fences are byte-preserved, including strings that resemble guidance.
+ */
+export declare function neutralRetrievalGuidance(text: string): string;
+/** Preserve complete lines at a shared output limit; never forge a full body. */
+export declare function trimEvidenceAtLine(text: string, limit: number): string;
+//# sourceMappingURL=evidence-rendering.d.ts.map

package/dist/mcp/evidence-rendering.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalSourceDeclarations = canonicalSourceDeclarations;
+exports.neutralRetrievalGuidance = neutralRetrievalGuidance;
+exports.trimEvidenceAtLine = trimEvidenceAtLine;
+/** Multiple parser roles for one source declaration are not overloads. */
+function canonicalSourceDeclarations(nodes) {
+    const out = [];
+    const roles = new Map();
+    const ids = new Set();
+    for (const node of nodes) {
+        if (ids.has(node.id))
+            continue;
+        ids.add(node.id);
+        if (node.kind !== 'struct' && node.kind !== 'component') {
+            out.push(node);
+            continue;
+        }
+        const key = `${node.filePath}:${node.startLine}:${node.name}`;
+        const prior = roles.get(key);
+        if (prior === undefined) {
+            roles.set(key, out.length);
+            out.push(node);
+        }
+        else if (node.kind === 'component')
+            out[prior] = node;
+    }
+    return out;
+}
+/** Guidance describes retrieval; it must never close the host's coding task.
+ * Source fences are byte-preserved, including strings that resemble guidance.
+ */
+function neutralRetrievalGuidance(text) {
+    let fence = '';
+    return text.split('\n').map((line) => {
+        const marker = line.match(/^\s*(`{3,}|~{3,})/);
+        if (marker) {
+            if (!fence)
+                fence = marker[1][0];
+            else if (marker[1][0] === fence)
+                fence = '';
+            return line;
+        }
+        if (fence)
+            return line;
+        if (/^>\s*\*\*Explore complete/i.test(line)) {
+            return '> Retrieval returned the evidence shown above. Check missing requirements, continue the requested edits, and verify the resulting code.';
+        }
+        if (/^>/.test(line) && /treat as already Read|treat it as already Read/i.test(line)) {
+            return '> The displayed source ranges are available as evidence. Inspect omitted ranges or changed files when needed; avoid repeating unchanged ranges.';
+        }
+        return line
+            .replace(/\*{0,2}ANSWER NOW\*{0,2}/g, 'use the evidence shown')
+            .replace(/Flow \+ Source above are authoritative for this query\./g, 'Source coverage is limited to the displayed ranges.')
+            .replace(/Do \*\*not\*\* grep\/read\/`homegraph_node`\/`homegraph_search`[^.]*\./gi, 'Inspect missing evidence as needed.')
+            .replace(/do\s+\*{0,2}not\*{0,2}\s+(?:re-)?(?:grep|read|glob)(?:\/[^.;]+)?[^.;]*[.;]/gi, 'Avoid duplicate reads of unchanged ranges;');
+    }).join('\n');
+}
+/** Preserve complete lines at a shared output limit; never forge a full body. */
+function trimEvidenceAtLine(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const note = '\n[Partial source: shared output budget reached; omitted ranges remain available for a focused lookup.]';
+    const cut = text.slice(0, Math.max(0, limit - note.length - 5));
+    const boundary = cut.lastIndexOf('\n');
+    let kept = boundary >= 0 ? cut.slice(0, boundary) : '';
+    if ((kept.match(/^\s*```/gm)?.length ?? 0) % 2)
+        kept += '\n```';
+    return kept + note;
+}
+//# sourceMappingURL=evidence-rendering.js.map

package/dist/mcp/explore-repeat-guard.d.ts

@@ -1,13 +1,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.
  */
@@ -65,10 +61,10 @@ export declare function latestCountedExplore(prior: ExploreProjectState | null |
  * 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.
  */
-export declare function decideDepthToolFuse(prior: ExploreProjectState | null | undefined, depthCallCount: number, toolName?: string): DepthToolFuseDecision;
+export declare function decideDepthToolFuse(prior: ExploreProjectState | null | undefined, depthCallCount: number, _toolName?: string): DepthToolFuseDecision;
 /** Success-shaped refuse when Partial already spent its one depth drill. */
 export declare function formatDepthToolRefuse(decision: DepthToolFuseDecision, toolName: string, symbolHint?: string): string;
 /** Candidate Type for Partial **Next anchor** / digest preference. */
@@ -92,12 +88,11 @@ export declare function pickBestDomainRoleAnchor(candidates: ReadonlyArray<Domai
 /** Format Next anchor caption used in Partial / soft-close footers. */
 export declare function formatNextAnchorCaption(c: DomainRoleAnchorCandidate): string;
 /**
- * Soft-close opening banner (must match footer — never pair with Partial locator).
+ * Coarse retrieval banner: source reuse is separate from task completion.
  */
 export declare function formatMechanismSoftCloseHeader(): string;
 /**
- * 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.
  */
 export declare function formatMechanismSoftCloseFooter(next?: DomainRoleAnchorCandidate): string;
 /** Honest Partial footer with a single Next anchor + ONE Grep. */