homegraph 1.5.8 → 1.6.0

package/dist/mcp/daemon.d.ts

@@ -20,9 +20,12 @@
  *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
  *     close then decrements the daemon's refcount.
  *   - When the last client disconnects the daemon lingers for
- *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
- *     runs in the same project don't repay startup, then exits cleanly. This is
- *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default **60s**, Spec 0047) so a
+ *     quick reconnect does not repay startup — but **only after** any in-flight
+ *     auto-init/full index finishes (`building_fast` / `indexing`). While a
+ *     client is connected (refcount > 0) the daemon never idle-exits. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277)
+ *     without killing a half-built graph when the IDE just closed.
  *
  * What this file owns:
  *   - Listening on the daemon socket and spawning per-connection sessions.
@@ -41,6 +44,21 @@
  */
 import * as net from 'net';
 import { DaemonLockInfo } from './daemon-paths';
+/**
+ * Spec 0047: phases that block daemon idle-exit when clients=0.
+ * Routine watch/sync is NOT included.
+ */
+export declare function isBuildPhaseBlockingIdle(phase: string | null | undefined): boolean;
+/**
+ * Decide idle-timer action when the linger timer fires (refcount already 0).
+ * Pure helper for unit tests.
+ */
+export declare function decideIdleExitAction(opts: {
+    clientCount: number;
+    buildBlocking: boolean;
+}): 'exit' | 'rearm-idle' | 'poll-build';
+/** Default idle linger after last client (exported for tests). */
+export declare function defaultDaemonIdleTimeoutMs(): number;
 /**
  * Finalize daemon shutdown. On POSIX, exit immediately — it's clean and fast.
  * On Windows, do NOT force an exit while watchers may still be closing (that

package/dist/mcp/daemon.js

@@ -21,9 +21,12 @@
  *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
  *     close then decrements the daemon's refcount.
  *   - When the last client disconnects the daemon lingers for
- *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
- *     runs in the same project don't repay startup, then exits cleanly. This is
- *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *     `HOMEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default **60s**, Spec 0047) so a
+ *     quick reconnect does not repay startup — but **only after** any in-flight
+ *     auto-init/full index finishes (`building_fast` / `indexing`). While a
+ *     client is connected (refcount > 0) the daemon never idle-exits. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277)
+ *     without killing a half-built graph when the IDE just closed.
  *
  * What this file owns:
  *   - Listening on the daemon socket and spawning per-connection sessions.
@@ -75,6 +78,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_HELLO_LINE_BYTES = exports.Daemon = void 0;
+exports.isBuildPhaseBlockingIdle = isBuildPhaseBlockingIdle;
+exports.decideIdleExitAction = decideIdleExitAction;
+exports.defaultDaemonIdleTimeoutMs = defaultDaemonIdleTimeoutMs;
 exports.finalizeDaemonExit = finalizeDaemonExit;
 exports.tryAcquireDaemonLock = tryAcquireDaemonLock;
 exports.acquireLockViaExclusiveOpen = acquireLockViaExclusiveOpen;
@@ -92,8 +98,32 @@ const transport_1 = require("./transport");
 const daemon_paths_1 = require("./daemon-paths");
 const version_1 = require("./version");
 const daemon_registry_1 = require("./daemon-registry");
-/** Default idle linger after the last client disconnects. */
-const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+/** How often to re-check build phase while deferring idle exit (Spec 0047). */
+const BUILD_IDLE_POLL_MS = 2_000;
+/** Default idle linger after the last client disconnects (Spec 0047: 60s). */
+const DEFAULT_IDLE_TIMEOUT_MS = 60_000;
+/**
+ * Spec 0047: phases that block daemon idle-exit when clients=0.
+ * Routine watch/sync is NOT included.
+ */
+function isBuildPhaseBlockingIdle(phase) {
+    return phase === 'building_fast' || phase === 'indexing';
+}
+/**
+ * Decide idle-timer action when the linger timer fires (refcount already 0).
+ * Pure helper for unit tests.
+ */
+function decideIdleExitAction(opts) {
+    if (opts.clientCount > 0)
+        return 'rearm-idle';
+    if (opts.buildBlocking)
+        return 'poll-build';
+    return 'exit';
+}
+/** Default idle linger after last client (exported for tests). */
+function defaultDaemonIdleTimeoutMs() {
+    return DEFAULT_IDLE_TIMEOUT_MS;
+}
 /**
  * Hard ceiling on how long the daemon stays up with clients connected but no
  * inbound traffic. A backstop (#692): if a client's socket-close is never
@@ -372,15 +402,39 @@ class Daemon {
             return;
         if (this.idleTimeoutMs <= 0)
             return; // 0 = never idle-exit
+        // Spec 0047: if the last window closed mid-index, wait for build to finish
+        // before starting the idle linger — never exit while clients>0 either.
+        if (this.clients.size === 0 && this.engine.isIndexBuildInProgress()) {
+            this.idleTimer = setTimeout(() => {
+                this.idleTimer = null;
+                if (this.clients.size > 0)
+                    return; // reconnect disarmed the need
+                if (this.engine.isIndexBuildInProgress()) {
+                    this.armIdleTimer(); // keep polling until build settles
+                    return;
+                }
+                this.armIdleTimer(); // build done → arm full idle linger
+            }, BUILD_IDLE_POLL_MS);
+            this.idleTimer.unref?.();
+            return;
+        }
         this.idleTimer = setTimeout(() => {
             this.idleTimer = null;
             // Last-second sanity check: if a connection landed between the timer
             // firing and now, don't exit. (setImmediate-ordering is the only way
             // this races; cheap to defend against.)
-            if (this.clients.size > 0) {
+            const action = decideIdleExitAction({
+                clientCount: this.clients.size,
+                buildBlocking: this.engine.isIndexBuildInProgress(),
+            });
+            if (action === 'rearm-idle') {
                 this.armIdleTimer();
                 return;
             }
+            if (action === 'poll-build') {
+                this.armIdleTimer(); // switches to build-poll branch above
+                return;
+            }
             void this.stop('idle timeout');
         }, this.idleTimeoutMs);
         // Don't keep the event loop alive just for this — the net.Server keeps the

package/dist/mcp/engine.d.ts

@@ -48,6 +48,13 @@ export declare class MCPEngine {
     private opts;
     private closed;
     private queryPool;
+    /**
+     * Spec 0049: auto-init deferred because the root was empty. Probe until
+     * indexable, then run the normal create-DB path once.
+     */
+    private deferredAutoInitRoot;
+    private deferProbeTimer;
+    private deferAutoInitPromise;
     constructor(opts?: MCPEngineOptions);
     /**
      * Start the worker-thread query pool once a default project is open (daemon
@@ -67,8 +74,21 @@ export declare class MCPEngine {
     getProjectPath(): string | null;
     /** Shared ToolHandler — sessions delegate tool dispatch through this. */
     getToolHandler(): ToolHandler;
+    /**
+     * Spec 0047: true while auto-init / full symbol build is in flight.
+     * Used by the daemon idle timer — never idle-exit mid-build when clients=0.
+     * Does not include routine watch/sync increments.
+     */
+    isIndexBuildInProgress(): boolean;
     /** Whether the default project's HomeGraph is open. */
     hasDefaultHomeGraph(): boolean;
+    /** Spec 0049: true while auto-init is waiting for an empty root to grow sources. */
+    isAutoInitDeferred(): boolean;
+    /**
+     * Spec 0049: on tool call (or timer), re-check the deferred root and start
+     * the normal auto-init once it becomes indexable. Idempotent.
+     */
+    kickDeferredAutoInit(): Promise<boolean>;
     /**
      * Walk up from `searchFrom` to find the nearest `.homegraph/` and open it.
      * Idempotent: concurrent callers share one in-flight init; subsequent
@@ -100,6 +120,11 @@ export declare class MCPEngine {
      * @returns true if the engine is fully wired to a new (or racing) index
      */
     private tryAutoInit;
+    /** Spec 0049: create DB + fast map + background full (shared by first hit and kick). */
+    private runAutoInitCreate;
+    /** Spec 0049: remember empty root and (optionally) poll until indexable. */
+    private armDeferProbe;
+    private clearDeferProbe;
     /**
      * Open an index another process just created (Spec 0032 cold-start race).
      * Brief retries cover the window between mkdir and db file create.
@@ -143,6 +168,7 @@ export declare class MCPEngine {
  * Range: 1s … 30min. Used by product hosts (e.g. DevEco Code = 5 minutes).
  */
 export declare function parseFixedWindowEnv(raw: string | undefined): number | undefined;
+export { isIndexableRoot, parseDeferProbeMs } from './indexable-root';
 /**
  * Parse and clamp the HOMEGRAPH_WATCH_DEBOUNCE_MS env override.
  *

package/dist/mcp/engine.js

@@ -44,7 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCPEngine = void 0;
+exports.parseDeferProbeMs = exports.isIndexableRoot = exports.MCPEngine = void 0;
 exports.parseFixedWindowEnv = parseFixedWindowEnv;
 exports.parseDebounceEnv = parseDebounceEnv;
 const os = __importStar(require("os"));
@@ -57,13 +57,28 @@ const memory_budget_1 = require("./memory-budget");
 const db_1 = require("../db");
 const graph_sources_1 = require("../graph-sources");
 const utils_1 = require("../utils");
+const runtime_log_1 = require("../runtime-log");
+const indexable_root_1 = require("./indexable-root");
 // Lazy-load the heavy HomeGraph chain (sqlite + query/graph/context layers) OFF
 // the MCP startup path. It's only needed once a tool actually opens a project —
 // not to answer initialize/tools-list — so deferring it lets `serve mcp` (and
 // the daemon it spawns) bind + register tools in ~Node-startup time instead of
 // ~800ms, closing the "No such tool available" cold-start race that made headless
-// agents flounder. require() is sync + cached on the CommonJS build.
-const loadHomeGraph = () => require('../index').default;
+// agents flounder. Prefer dynamic import (vitest + CJS); sync require remains for
+// the sync retry path after an async load has warmed the cache (or under dist/).
+let homeGraphCtor = null;
+const loadHomeGraph = async () => {
+    if (!homeGraphCtor) {
+        homeGraphCtor = (await Promise.resolve().then(() => __importStar(require('../index')))).default;
+    }
+    return homeGraphCtor;
+};
+const loadHomeGraphSync = () => {
+    if (homeGraphCtor)
+        return homeGraphCtor;
+    homeGraphCtor = require('../index').default;
+    return homeGraphCtor;
+};
 /**
  * Shared MCP engine. Thread-safe in the sense that multiple sessions can
  * call its methods concurrently — internally it serializes initialization
@@ -85,6 +100,13 @@ class MCPEngine {
     // Off-loop read-tool pool (daemon mode only). Created lazily once the default
     // project is open — workers each hold their own WAL read connection.
     queryPool = null;
+    /**
+     * Spec 0049: auto-init deferred because the root was empty. Probe until
+     * indexable, then run the normal create-DB path once.
+     */
+    deferredAutoInitRoot = null;
+    deferProbeTimer = null;
+    deferAutoInitPromise = null;
     constructor(opts = {}) {
         this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false, rootFloor: opts.rootFloor ?? null };
         this.toolHandler = new tools_1.ToolHandler(null);
@@ -132,10 +154,42 @@ class MCPEngine {
     getToolHandler() {
         return this.toolHandler;
     }
+    /**
+     * Spec 0047: true while auto-init / full symbol build is in flight.
+     * Used by the daemon idle timer — never idle-exit mid-build when clients=0.
+     * Does not include routine watch/sync increments.
+     */
+    isIndexBuildInProgress() {
+        if (!this.cg)
+            return false;
+        try {
+            const phase = this.cg.getBuildPhase();
+            return phase === 'building_fast' || phase === 'indexing';
+        }
+        catch {
+            return false;
+        }
+    }
     /** Whether the default project's HomeGraph is open. */
     hasDefaultHomeGraph() {
         return this.toolHandler.hasDefaultHomeGraph();
     }
+    /** Spec 0049: true while auto-init is waiting for an empty root to grow sources. */
+    isAutoInitDeferred() {
+        return this.deferredAutoInitRoot !== null && !this.toolHandler.hasDefaultHomeGraph();
+    }
+    /**
+     * Spec 0049: on tool call (or timer), re-check the deferred root and start
+     * the normal auto-init once it becomes indexable. Idempotent.
+     */
+    async kickDeferredAutoInit() {
+        if (this.closed || this.toolHandler.hasDefaultHomeGraph())
+            return false;
+        const root = this.deferredAutoInitRoot;
+        if (!root)
+            return false;
+        return this.tryAutoInit(root);
+    }
     /**
      * Walk up from `searchFrom` to find the nearest `.homegraph/` and open it.
      * Idempotent: concurrent callers share one in-flight init; subsequent
@@ -194,7 +248,7 @@ class MCPEngine {
                 catch { /* ignore */ }
                 this.cg = null;
             }
-            this.cg = loadHomeGraph().openSync(resolvedRoot, { sources: mode });
+            this.cg = loadHomeGraphSync().openSync(resolvedRoot, { sources: mode });
             this.projectPath = resolvedRoot;
             this.toolHandler.setDefaultHomeGraph(this.cg);
             this.startWatching();
@@ -213,6 +267,7 @@ class MCPEngine {
         if (this.closed)
             return;
         this.closed = true;
+        this.clearDeferProbe();
         // Detach + terminate the worker pool first so no tool call routes to a
         // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
         this.toolHandler.setQueryPool(null);
@@ -252,7 +307,7 @@ class MCPEngine {
                 process.stderr.write(`[HomeGraph MCP] Graph sources=${mode} — skipping project/SDK open (tools return guidance).\n`);
                 return;
             }
-            this.cg = await loadHomeGraph().open(resolvedRoot, { sources: mode });
+            this.cg = await (await loadHomeGraph()).open(resolvedRoot, { sources: mode });
             this.toolHandler.setDefaultHomeGraph(this.cg);
             this.healBuildPhase(this.cg);
             this.startWatching();
@@ -282,11 +337,34 @@ class MCPEngine {
         // 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)) {
+            this.clearDeferProbe();
             return this.openAfterAutoInitRace(root);
         }
+        // Spec 0049: empty workspace — do not create `.homegraph/` (blocks
+        // in-place `devecocli create`). Probe later / on tool kick.
+        if (!(0, indexable_root_1.isIndexableRoot)(root)) {
+            this.armDeferProbe(root);
+            process.stderr.write(`[HomeGraph MCP] Auto-init deferred — empty root at ${root} ` +
+                `(no build-profile.json5 / indexable sources yet)\n`);
+            (0, runtime_log_1.logLifecycle)('auto-init.deferred', { projectRoot: root });
+            this.projectPath = root;
+            return false;
+        }
+        if (this.deferAutoInitPromise) {
+            return this.deferAutoInitPromise;
+        }
+        this.deferAutoInitPromise = this.runAutoInitCreate(root).finally(() => {
+            this.deferAutoInitPromise = null;
+        });
+        return this.deferAutoInitPromise;
+    }
+    /** Spec 0049: create DB + fast map + background full (shared by first hit and kick). */
+    async runAutoInitCreate(root) {
+        this.clearDeferProbe();
         try {
             process.stderr.write(`[HomeGraph MCP] Auto-init at ${root}\n`);
-            const HomeGraph = loadHomeGraph();
+            (0, runtime_log_1.logLifecycle)('auto-init.start', { projectRoot: root });
+            const HomeGraph = await 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`
@@ -312,6 +390,7 @@ class MCPEngine {
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     process.stderr.write(`[HomeGraph MCP] Fast build failed: ${msg}\n`);
+                    (0, runtime_log_1.logLifecycleError)('auto-init.fail', { projectRoot: root, phase: 'fast', msg });
                 }
                 this.startBackgroundFullBuild(cg);
             })();
@@ -324,9 +403,51 @@ class MCPEngine {
             }
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Auto-init failed: ${msg}\n`);
+            (0, runtime_log_1.logLifecycleError)('auto-init.fail', { projectRoot: root, msg });
+            // Keep probing so a later scaffold (or retry) can still land.
+            if (!(0, directory_1.isInitialized)(root)) {
+                this.armDeferProbe(root);
+            }
             return false;
         }
     }
+    /** Spec 0049: remember empty root and (optionally) poll until indexable. */
+    armDeferProbe(root) {
+        this.deferredAutoInitRoot = root;
+        if (this.deferProbeTimer)
+            return;
+        const ms = (0, indexable_root_1.parseDeferProbeMs)(process.env.HOMEGRAPH_DEFER_PROBE_MS);
+        if (ms <= 0)
+            return;
+        this.deferProbeTimer = setInterval(() => {
+            if (this.closed || this.toolHandler.hasDefaultHomeGraph()) {
+                this.clearDeferProbe();
+                return;
+            }
+            const target = this.deferredAutoInitRoot;
+            if (!target) {
+                this.clearDeferProbe();
+                return;
+            }
+            if (!(0, indexable_root_1.isIndexableRoot)(target))
+                return;
+            void this.tryAutoInit(target).then((ok) => {
+                if (ok)
+                    this.clearDeferProbe();
+            });
+        }, ms);
+        // Don't keep the process alive solely for the probe in direct mode.
+        if (typeof this.deferProbeTimer.unref === 'function') {
+            this.deferProbeTimer.unref();
+        }
+    }
+    clearDeferProbe() {
+        this.deferredAutoInitRoot = null;
+        if (this.deferProbeTimer) {
+            clearInterval(this.deferProbeTimer);
+            this.deferProbeTimer = null;
+        }
+    }
     /**
      * Open an index another process just created (Spec 0032 cold-start race).
      * Brief retries cover the window between mkdir and db file create.
@@ -342,7 +463,7 @@ class MCPEngine {
             }
             try {
                 process.stderr.write(`[HomeGraph MCP] Auto-init raced; opening existing index at ${root}\n`);
-                this.cg = await loadHomeGraph().open(root, { sources: mode });
+                this.cg = await (await loadHomeGraph()).open(root, { sources: mode });
                 this.projectPath = root;
                 this.toolHandler.setDefaultHomeGraph(this.cg);
                 this.healBuildPhase(this.cg);
@@ -400,6 +521,14 @@ class MCPEngine {
     startBackgroundFullBuild(cg) {
         cg.setBuildPhase('indexing');
         process.stderr.write('[HomeGraph MCP] Full build starting in-process (background)\n');
+        let projectRoot;
+        try {
+            projectRoot = cg.getProjectRoot();
+        }
+        catch {
+            projectRoot = this.projectPath ?? undefined;
+        }
+        (0, runtime_log_1.logLifecycle)('index.start', { projectRoot, via: 'auto-init' });
         void cg
             .indexAll()
             .then((result) => {
@@ -420,16 +549,20 @@ class MCPEngine {
                 cg.setBuildPhase('full');
                 process.stderr.write(`[HomeGraph MCP] Full build complete — files=${files || '?'} nodes=${nodes}` +
                     (ok ? '\n' : ' (soft-fail but symbols present)\n'));
+                (0, runtime_log_1.logLifecycle)('index.done', { projectRoot, files, nodes });
+                (0, runtime_log_1.logLifecycle)('auto-init.done', { projectRoot, files, nodes });
             }
             else {
                 cg.setBuildPhase('fast');
                 process.stderr.write('[HomeGraph MCP] Full build finished with no symbols — staying on fast map\n');
+                (0, runtime_log_1.logLifecycle)('index.done', { projectRoot, files: 0, nodes: 0, note: 'no-symbols' });
             }
             this.startWatchingAfterAutoInit();
         })
             .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Full build failed: ${msg}\n`);
+            (0, runtime_log_1.logLifecycleError)('index.fail', { projectRoot, msg });
             try {
                 let nodes = 0;
                 try {
@@ -575,6 +708,9 @@ function parseFixedWindowEnv(raw) {
         return undefined;
     return n;
 }
+var indexable_root_2 = require("./indexable-root");
+Object.defineProperty(exports, "isIndexableRoot", { enumerable: true, get: function () { return indexable_root_2.isIndexableRoot; } });
+Object.defineProperty(exports, "parseDeferProbeMs", { enumerable: true, get: function () { return indexable_root_2.parseDeferProbeMs; } });
 /**
  * Parse and clamp the HOMEGRAPH_WATCH_DEBOUNCE_MS env override.
  *

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

@@ -1,23 +1,53 @@
 /**
- * Product-facing index availability for MCP tool results (Spec 0032).
+ * Product-facing index availability for MCP tool results (Spec 0032 + 0035).
  *
- * 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.
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy /
+ * pending dirty files) to the five states hosts and agents should see.
  */
 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;
+export type ProductIndexState = 'empty' | 'fast' | 'full' | 'dirty' | 'syncing';
+/** One-line glossary for MCP initialize / tool surface (Spec 0035). */
+export declare const PRODUCT_STATUS_GLOSSARY = "status: empty=not ready \u00B7 fast=map only (homegraph_project) \u00B7 full=fresh \u00B7 dirty=usable but listed paths outdated \u00B7 syncing=write lock, retry";
+/** Whole-response guidance when the tool cannot usefully answer yet. */
+export declare function productIndexGuidance(state: Extract<ProductIndexState, 'empty' | 'fast' | 'syncing'>): string;
+/**
+ * Single status line for tool footers (and for guidance-only replies).
+ * `pendingPaths` only used when `state === 'dirty'`.
+ */
+export declare function formatProductStatusLine(state: ProductIndexState, opts?: {
+    pendingPaths?: string[];
+}): 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
+ * Priority: syncing > empty > fast > dirty > full
  */
 export declare function resolveProductIndexState(cg: HomeGraph): ProductIndexState;
 /** True when an error message indicates SQLite writer contention. */
 export declare function isSqliteBusyMessage(message: string): boolean;
+/** True when text is already a pure (or leading) HomeGraph status line. */
+export declare function textAlreadyHasProductStatus(text: string): boolean;
+/** Marker line for Spec 0038 project-root path hint (idempotent prepend). */
+export declare const PROJECT_ROOT_HINT_MARKER = "HomeGraph project root:";
+/**
+ * Short preamble: absolute project root + how to join repo-relative paths (Spec 0038).
+ * `absRoot` should already be resolved (platform-native absolute path).
+ */
+export declare function formatProjectRootPathHint(absRoot: string): string;
+/** True when text already carries a Spec 0038 project-root hint. */
+export declare function textAlreadyHasProjectRootHint(text: string): boolean;
+/** Marker for Spec 0043 bound-root projectPath soft-pin notice (idempotent prepend). */
+export declare const BOUND_PROJECT_PATH_PIN_MARKER = "This MCP session is bound to";
+/**
+ * English preamble when a tool `projectPath` resolves to a different index root
+ * than the MCP session's default bound root (Spec 0043). Success-shaped — not isError.
+ */
+export declare function formatBoundProjectPathPinNotice(opts: {
+    boundRoot: string;
+    requestedPath: string;
+    resolvedRoot: string | null;
+}): string;
+/** True when text already carries a Spec 0043 pin notice. */
+export declare function textAlreadyHasBoundProjectPathPinNotice(text: string): boolean;
 //# sourceMappingURL=index-availability.d.ts.map