homegraph 1.2.0 → 1.4.1

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

@@ -10,17 +10,25 @@
  * connection) restores true multi-core parallelism and an idle main loop.
  *
  * Properties:
- *   - lazy growth: one warm worker on construct, grows to `size` on demand, so a
- *     single-agent session pays for one connection and a 10-subagent burst grows
- *     to the core budget.
+ *   - lazy growth: **no worker until the first heavy call**, then grows to
+ *     `size` on demand. Eager warm-start used to open a second full DB on every
+ *     MCP session and balloon RSS (~5GB on ~800MB indexes).
+ *   - **default concurrency is 1** — each worker is another V8 + WAL open; on
+ *     large indexes two workers routinely doubled working-set into multi-GB.
+ *     Override with `CODEGRAPH_QUERY_POOL_SIZE` when you truly need more.
+ *   - **admission**: when outstanding work already fills `size` in-flight plus
+ *     another `size` waiting, further calls resolve immediately with
+ *     success-shaped busy/partial guidance instead of queuing up to die at the
+ *     client hard timeout.
  *   - crash recovery: a dead worker is respawned and its in-flight call retried
  *     once; a poison call that keeps crashing fails gracefully (never wedges the
  *     pool). A crash budget trips a circuit breaker (`healthy` → false) so the
  *     caller falls back to in-process dispatch instead of thrashing respawns.
  *   - graceful backstop: a call that can't be served within `softTimeoutMs`
- *     resolves with SUCCESS-shaped "busy, retry" guidance — never `isError`, so
- *     a momentary overload can't teach the agent to abandon codegraph — instead
- *     of hanging past the client's hard timeout.
+ *     (default 20s, clamped ≤30s — well under typical ~60s MCP client timeouts)
+ *     resolves with SUCCESS-shaped static "Partial / busy, retry" guidance —
+ *     never `isError`, and never DB/FTS work on the timeout callback (that
+ *     can freeze the transport so the client still sees empty `-32001`).
  */
 import type { ToolResult } from './tools';
 /**
@@ -39,9 +47,9 @@ export interface PoolWorker {
 export interface QueryPoolOptions {
     /** Default project root each worker opens at spawn. */
     root: string;
-    /** Max worker threads. Defaults to `clamp(cores-1, 1, 16)`. */
+    /** Max worker threads. Defaults to `clamp(cores-1, 1, DEFAULT_POOL_CAP)`. */
     size?: number;
-    /** Linger before a queued call gets busy-guidance. Default 45s. */
+    /** Linger before a queued/in-flight call gets busy-guidance. Default 20s (≤30s clamp). */
     softTimeoutMs?: number;
     /** Retries for an in-flight call whose worker crashed. Default 1. */
     maxRetries?: number;
@@ -51,11 +59,19 @@ export interface QueryPoolOptions {
 /**
  * Resolve the pool size from the `CODEGRAPH_QUERY_POOL_SIZE` override and the
  * machine's core count. `0` (or a negative) explicitly disables the pool (the
- * caller serves in-process — today's behavior). Unset → `clamp(cores-1, 1, 16)`:
- * leave a core for the main loop + OS, but never zero, since even one worker
- * frees the transport and lets responses flush incrementally.
+ * caller serves in-process — today's behavior). Unset → `clamp(cores-1, 1, 1)`:
+ * one parallel explore without a second full-DB RSS hit. Explicit overrides still
+ * honor up to {@link MAX_POOL_SIZE}.
  */
 export declare function resolvePoolSize(envVal: string | undefined, cpuCount: number): number;
+/**
+ * Soft / tool deadline. Env `CODEGRAPH_QUERY_BUSY_TIMEOUT_MS` may raise or
+ * lower it, but is always clamped into `[1000, MAX_BUSY_TIMEOUT_MS]` so a
+ * mistaken `60000` cannot race DevEco/Cursor's ~60s MCP hard timeout.
+ */
+export declare function resolveBusyTimeoutMs(): number;
+/** Same as {@link resolveBusyTimeoutMs} — used by ToolHandler for all tools. */
+export declare function resolveToolDeadlineMs(): number;
 export declare class QueryPool {
     private idle;
     private queue;
@@ -70,7 +86,14 @@ export declare class QueryPool {
     private readonly softTimeoutMs;
     private readonly maxRetries;
     private readonly createWorker;
+    private everReady;
     constructor(opts: QueryPoolOptions);
+    /**
+     * True once at least one worker has completed a successful cold-start handshake.
+     * False during the cold-start window (and after destroy) so ToolHandler can
+     * fall back to in-process dispatch instead of queuing behind a busy backstop.
+     */
+    get ready(): boolean;
     /** Pool size cap (for logging/status). */
     get size(): number;
     /** Live worker count (for tests/status). */
@@ -81,13 +104,24 @@ export declare class QueryPool {
      * degrades to today's behavior instead of failing tool calls.
      */
     get healthy(): boolean;
+    /** In-flight + unsettled queued jobs (for admission / tests). */
+    outstandingCount(): number;
+    /**
+     * How many unsettled jobs we tolerate before refusing new ones immediately.
+     * One full wave running + one full wave waiting — further fan-out gets
+     * busy/partial guidance instead of stacking up to the soft timeout.
+     */
+    private admissionLimit;
     private spawnOne;
     private onMessage;
     private onWorkerGone;
     private drain;
     private settle;
+    private settleBusyOrPartial;
     /** Run a read tool on the pool. Always resolves (never rejects). */
-    run(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    run(toolName: string, args: Record<string, unknown>, opts?: {
+        onSoftTimeout?: () => ToolResult | null | undefined;
+    }): Promise<ToolResult>;
     /** Terminate all workers and answer any outstanding calls gracefully. */
     destroy(): Promise<void>;
 }

package/dist/mcp/query-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-pool.d.ts","sourceRoot":"","sources":["../../src/mcp/query-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACpC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACrD,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACjD,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;CACrD;AA6CD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,UAAU,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOpF;AAwBD,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,OAAO,CAAyB;IAMxC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;gBAEpC,IAAI,EAAE,gBAAgB;IASlC,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAAyB;IAE3C,4CAA4C;IAC5C,IAAI,WAAW,IAAI,MAAM,CAA8B;IAEvD;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,SAAS;IAqBjB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,KAAK;IAuBb,OAAO,CAAC,MAAM;IAOd,oEAAoE;IACpE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAkBzE,yEAAyE;IACnE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAc/B"}
+{"version":3,"file":"query-pool.d.ts","sourceRoot":"","sources":["../../src/mcp/query-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACpC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACrD,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACjD,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;CACrD;AA8DD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,UAAU,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOpF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAoBD,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,OAAO,CAAyB;IAMxC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAChD,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,EAAE,gBAAgB;IAUlC;;;;OAIG;IACH,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAAyB;IAE3C,4CAA4C;IAC5C,IAAI,WAAW,IAAI,MAAM,CAA8B;IAEvD;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,iEAAiE;IACjE,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,SAAS;IAsBjB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,KAAK;IAuBb,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,mBAAmB;IAU3B,oEAAoE;IACpE,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,CAAA;KAAE,GAC7D,OAAO,CAAC,UAAU,CAAC;IA2BtB,yEAAyE;IACnE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAc/B"}

package/dist/mcp/query-pool.js

@@ -11,17 +11,25 @@
  * connection) restores true multi-core parallelism and an idle main loop.
  *
  * Properties:
- *   - lazy growth: one warm worker on construct, grows to `size` on demand, so a
- *     single-agent session pays for one connection and a 10-subagent burst grows
- *     to the core budget.
+ *   - lazy growth: **no worker until the first heavy call**, then grows to
+ *     `size` on demand. Eager warm-start used to open a second full DB on every
+ *     MCP session and balloon RSS (~5GB on ~800MB indexes).
+ *   - **default concurrency is 1** — each worker is another V8 + WAL open; on
+ *     large indexes two workers routinely doubled working-set into multi-GB.
+ *     Override with `CODEGRAPH_QUERY_POOL_SIZE` when you truly need more.
+ *   - **admission**: when outstanding work already fills `size` in-flight plus
+ *     another `size` waiting, further calls resolve immediately with
+ *     success-shaped busy/partial guidance instead of queuing up to die at the
+ *     client hard timeout.
  *   - crash recovery: a dead worker is respawned and its in-flight call retried
  *     once; a poison call that keeps crashing fails gracefully (never wedges the
  *     pool). A crash budget trips a circuit breaker (`healthy` → false) so the
  *     caller falls back to in-process dispatch instead of thrashing respawns.
  *   - graceful backstop: a call that can't be served within `softTimeoutMs`
- *     resolves with SUCCESS-shaped "busy, retry" guidance — never `isError`, so
- *     a momentary overload can't teach the agent to abandon codegraph — instead
- *     of hanging past the client's hard timeout.
+ *     (default 20s, clamped ≤30s — well under typical ~60s MCP client timeouts)
+ *     resolves with SUCCESS-shaped static "Partial / busy, retry" guidance —
+ *     never `isError`, and never DB/FTS work on the timeout callback (that
+ *     can freeze the transport so the client still sees empty `-32001`).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -59,13 +67,29 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryPool = void 0;
 exports.resolvePoolSize = resolvePoolSize;
+exports.resolveBusyTimeoutMs = resolveBusyTimeoutMs;
+exports.resolveToolDeadlineMs = resolveToolDeadlineMs;
 const worker_threads_1 = require("worker_threads");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 /** Compiled sibling — `query-worker.js` lives next to this file in `dist/mcp/`. */
 const WORKER_FILE = path.join(__dirname, 'query-worker.js');
-/** Default linger before a queued call is answered with busy-guidance. */
-const DEFAULT_BUSY_TIMEOUT_MS = 45_000; // < the ~60s MCP client request timeout
+/**
+ * Default soft backstop — must stay **well below** typical MCP client hard
+ * timeouts (~60s). Eval / agent configs sometimes set the env to 60000, which
+ * races the client and yields empty `-32001`; we clamp to
+ * {@link MAX_BUSY_TIMEOUT_MS} regardless. Prefer returning busy/partial early
+ * so the agent can retry once instead of waiting out the client hard cut.
+ */
+const DEFAULT_BUSY_TIMEOUT_MS = 15_000;
+/** Hard ceiling — leave headroom under ~30–60s client timeouts (flush / scheduling). */
+const MAX_BUSY_TIMEOUT_MS = 20_000;
+/**
+ * Default concurrent workers when env is unset. Keep at 1: a second connection
+ * on a large index is a multi-GB RSS hit. Explicit env overrides still go up to
+ * {@link MAX_POOL_SIZE}.
+ */
+const DEFAULT_POOL_CAP = 1;
 /** Hard ceiling on pool size regardless of core count / env. */
 const MAX_POOL_SIZE = 16;
 /**
@@ -87,9 +111,9 @@ const MAX_CONCURRENT_SPAWN = 2;
 /**
  * Resolve the pool size from the `CODEGRAPH_QUERY_POOL_SIZE` override and the
  * machine's core count. `0` (or a negative) explicitly disables the pool (the
- * caller serves in-process — today's behavior). Unset → `clamp(cores-1, 1, 16)`:
- * leave a core for the main loop + OS, but never zero, since even one worker
- * frees the transport and lets responses flush incrementally.
+ * caller serves in-process — today's behavior). Unset → `clamp(cores-1, 1, 1)`:
+ * one parallel explore without a second full-DB RSS hit. Explicit overrides still
+ * honor up to {@link MAX_POOL_SIZE}.
  */
 function resolvePoolSize(envVal, cpuCount) {
     if (envVal !== undefined && envVal !== '') {
@@ -98,8 +122,13 @@ function resolvePoolSize(envVal, cpuCount) {
             return Math.min(Math.floor(n), MAX_POOL_SIZE);
         // non-numeric / negative → fall through to the default
     }
-    return Math.max(1, Math.min(cpuCount - 1, MAX_POOL_SIZE));
+    return Math.max(1, Math.min(cpuCount - 1, DEFAULT_POOL_CAP));
 }
+/**
+ * Soft / tool deadline. Env `CODEGRAPH_QUERY_BUSY_TIMEOUT_MS` may raise or
+ * lower it, but is always clamped into `[1000, MAX_BUSY_TIMEOUT_MS]` so a
+ * mistaken `60000` cannot race DevEco/Cursor's ~60s MCP hard timeout.
+ */
 function resolveBusyTimeoutMs() {
     const raw = process.env.CODEGRAPH_QUERY_BUSY_TIMEOUT_MS;
     if (raw === undefined || raw === '')
@@ -107,17 +136,25 @@ function resolveBusyTimeoutMs() {
     const n = Number(raw);
     if (!Number.isFinite(n) || n < 1000)
         return DEFAULT_BUSY_TIMEOUT_MS;
-    return Math.floor(n);
+    return Math.min(Math.floor(n), MAX_BUSY_TIMEOUT_MS);
+}
+/** Same as {@link resolveBusyTimeoutMs} — used by ToolHandler for all tools. */
+function resolveToolDeadlineMs() {
+    return resolveBusyTimeoutMs();
 }
 /** Success-shaped overload guidance (NEVER isError — see the abandonment rule). */
-function busyGuidance(waitedMs) {
+function busyGuidance(waitedMs, reason = 'timeout') {
     const secs = Math.max(1, Math.round(waitedMs / 1000));
+    const why = reason === 'admission'
+        ? 'too many concurrent HomeGraph queries are already in flight'
+        : `this call waited ${secs}s in the queue / on a worker`;
     return {
         content: [{
                 type: 'text',
-                text: `CodeGraph is busy serving other concurrent requests right now (this call waited ${secs}s in the queue). ` +
-                    `This is NOT an error and the index is fine — wait a few seconds and retry this exact call; it will return normally. ` +
-                    `If you can't wait, use your built-in tools for just this one step.`,
+                text: `⚠️ **Partial result** — HomeGraph is busy (${why}). This is NOT an error. ` +
+                    `Retry ONE \`homegraph_explore\` with the concrete symbol/file names from the question — ` +
+                    `do not fire search+explore or node+callers+callees in parallel, and do not fall back to grep/read ` +
+                    `for symbols you already named (that duplicates tokens). A single retry usually returns full source.`,
             }],
     };
 }
@@ -140,13 +177,23 @@ class QueryPool {
     softTimeoutMs;
     maxRetries;
     createWorker;
+    everReady = false;
     constructor(opts) {
         this.root = opts.root;
-        this.maxSize = Math.max(1, Math.min(opts.size ?? Math.max(1, os.cpus().length - 1), MAX_POOL_SIZE));
+        this.maxSize = Math.max(1, Math.min(opts.size ?? Math.min(DEFAULT_POOL_CAP, Math.max(1, os.cpus().length - 1)), MAX_POOL_SIZE));
         this.softTimeoutMs = opts.softTimeoutMs ?? resolveBusyTimeoutMs();
         this.maxRetries = opts.maxRetries ?? 1;
         this.createWorker = opts.createWorker ?? (() => new worker_threads_1.Worker(WORKER_FILE, { workerData: { root: this.root } }));
-        this.spawnOne(); // one eager warm worker, ready for the first call
+        // One eager warm worker so the first tool call isn't queued behind a cold start (#662).
+        this.spawnOne();
+    }
+    /**
+     * True once at least one worker has completed a successful cold-start handshake.
+     * False during the cold-start window (and after destroy) so ToolHandler can
+     * fall back to in-process dispatch instead of queuing behind a busy backstop.
+     */
+    get ready() {
+        return this.everReady && !this.destroyed;
     }
     /** Pool size cap (for logging/status). */
     get size() { return this.maxSize; }
@@ -160,6 +207,18 @@ class QueryPool {
     get healthy() {
         return !this.destroyed && this.totalCrashes < CRASH_BUDGET;
     }
+    /** In-flight + unsettled queued jobs (for admission / tests). */
+    outstandingCount() {
+        return this.inflight.size + this.queue.filter((j) => !j.settled).length;
+    }
+    /**
+     * How many unsettled jobs we tolerate before refusing new ones immediately.
+     * One full wave running + one full wave waiting — further fan-out gets
+     * busy/partial guidance instead of stacking up to the soft timeout.
+     */
+    admissionLimit() {
+        return this.maxSize * 2;
+    }
     spawnOne() {
         if (this.destroyed || this.workers.size >= this.maxSize)
             return;
@@ -185,6 +244,8 @@ class QueryPool {
             this.pendingWorkers.delete(w);
             if (m.ok === false)
                 this.totalCrashes++; // hard open failure
+            else
+                this.everReady = true;
             this.idle.push(w);
             this.drain();
             return;
@@ -257,19 +318,35 @@ class QueryPool {
             clearTimeout(job.softTimer);
         job.resolve(result);
     }
+    settleBusyOrPartial(job, reason) {
+        if (job.settled)
+            return;
+        const partial = job.onSoftTimeout?.();
+        if (partial) {
+            this.settle(job, partial);
+            return;
+        }
+        this.settle(job, busyGuidance(Date.now() - job.enqueuedAt, reason));
+    }
     /** Run a read tool on the pool. Always resolves (never rejects). */
-    run(toolName, args) {
+    run(toolName, args, opts) {
         return new Promise((resolve) => {
             const job = {
                 id: this.nextId++, toolName, args, resolve,
                 retries: 0, settled: false, enqueuedAt: Date.now(),
+                onSoftTimeout: opts?.onSoftTimeout,
             };
+            // Hard admission: refuse to stack another wave that would sit until soft
+            // timeout / client hard timeout. Caller gets partial/busy NOW.
+            if (this.outstandingCount() >= this.admissionLimit()) {
+                this.settleBusyOrPartial(job, 'admission');
+                return;
+            }
             // Don't let the caller wait past softTimeoutMs. The worker may still be
             // busy (we can't cancel synchronous CPU), but the CLIENT gets a prompt,
-            // success-shaped "retry" instead of a hard timeout.
+            // success-shaped "retry"/partial instead of a hard timeout.
             job.softTimer = setTimeout(() => {
-                if (!job.settled)
-                    this.settle(job, busyGuidance(Date.now() - job.enqueuedAt));
+                this.settleBusyOrPartial(job, 'timeout');
             }, this.softTimeoutMs);
             job.softTimer.unref?.();
             this.queue.push(job);

package/dist/mcp/query-pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-pool.js","sourceRoot":"","sources":["../../src/mcp/query-pool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-pool.js","sourceRoot":"","sources":["../../src/mcp/query-pool.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server-instructions.d.ts

@@ -1,32 +1,9 @@
 /**
  * Server-level instructions emitted in the MCP `initialize` response.
  *
- * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
- * SDK, …) surface this text in the agent's system prompt automatically,
- * giving the agent a high-level playbook for the homegraph toolset
- * before it sees individual tool descriptions.
- *
- * Goals when editing this:
- *   - Lead the agent to homegraph_explore for any structural/flow question
- *   - Reinforce "explore instead of Read/Grep" for indexed code
- *   - Anti-patterns (don't re-verify with grep; don't hand-reconstruct flows)
- *
- * HomeGraph exposes the full tool surface by default (search, node, explore,
- * spec tools, …). Lead with homegraph_explore for structural questions; the
- * other tools are available when a narrower step helps.
- */
-export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 code intelligence over an indexed knowledge graph\n\nHomeGraph is a SQLite knowledge graph of every symbol, edge, and file in\nthe workspace \u2014 pre-computed structure you would otherwise re-derive by\nreading files (cached intelligence: thousands of parse/trace decisions you\ndon't pay to re-reason each run). Reads are sub-millisecond; the index lags\nwrites by ~1s through the file watcher. Reach for it BEFORE *and* while\nwriting or editing code \u2014 not just for questions: one call returns the\nverbatim source PLUS who calls it and what it affects, so you edit with the\nblast radius in view. More accurate context, in far fewer tokens and\nround-trips than reading files yourself.\n\n## Primary tool: homegraph_explore \u2014 use it instead of reading files\n\nFor structural and flow questions, `homegraph_explore` is Read-equivalent. It\ntakes either a natural-language question or a bag of symbol/file names and\nreturns the **verbatim, line-numbered source** of the relevant symbols\ngrouped by file \u2014 the same `<n>\\t<line>` shape `Read` gives you, safe to\n`Edit` from \u2014 PLUS the call path among them (including dynamic-dispatch hops\nlike callbacks, React re-render, and JSX children that grep can't follow) and\na blast-radius summary of what depends on them.\n\nWhether you're answering \"how does X work\" or implementing a change (fixing a\nbug, adding a feature), call `homegraph_explore` before you Read. ONE call\nusually answers the whole question. HomeGraph IS the pre-built search index \u2014\nso running your own grep + read loop, or delegating the lookup to a separate\nfile-reading sub-task/agent, repeats work homegraph already did and costs more\nfor the same answer. A direct homegraph answer is typically one to a few\ncalls; a grep/read exploration is dozens.\n\n## How to query\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `homegraph_explore` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `homegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.\n- **Reading or editing a file/symbol you can name** \u2192 put its name or file path in the `homegraph_explore` query \u2014 it returns that current line-numbered source (safe to `Edit` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.\n- **Need more?** Call `homegraph_explore` again with more specific names \u2014 treat the source it returns as already Read.\n\n## Anti-patterns\n\n- **Trust homegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep or Read first** to find or understand indexed code \u2014 ONE `homegraph_explore` returns the relevant symbols' source together in a single round-trip. Reach for raw `Read`/`Grep` only to confirm a specific detail homegraph didn't cover, or for what homegraph doesn't index (configs, docs).\n- **Don't reconstruct a flow by hand** \u2014 name the endpoints in one `homegraph_explore` and it surfaces the path between them, dynamic-dispatch hops included.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust homegraph. A different, rarer banner \u2014 \"\u26A0\uFE0F HomeGraph auto-sync is DISABLED\u2026\" \u2014 means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.\n\n## Limitations\n\n- If a tool reports a project isn't indexed (no `.homegraph/`), stop calling homegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision \u2014 mention they can run `homegraph init` if it comes up, but don't run it yourself.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. HomeGraph supplements those with structural context they don't have.\n";
-/**
- * Instructions variant sent when the server's own root has NO homegraph index.
- *
- * The tools are still exposed (gating tool availability on whether `./` has an
- * index is the bug behind #964: it breaks monorepos where only sub-projects are
- * indexed, and a server that started before `homegraph init` never surfaces the
- * tools afterward). Instead of an "inactive" note, this variant tells the agent
- * homegraph works **per project**: there's no default project to query, so pass
- * a `projectPath` to any project that HAS a `.homegraph/`. The full single-
- * project playbook ({@link SERVER_INSTRUCTIONS}) is sent instead when the root
- * IS indexed, so the common case stays tight.
+ * Single source of truth for agent-facing tool guidance (issue #529).
+ * Edit here — not installer prompts or eval harness prompts.
  */
-export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 available (per-project; pass projectPath)\n\nHomeGraph is a SQLite knowledge graph of a codebase's symbols, edges, and\nfiles: one `homegraph_explore` call returns the verbatim, line-numbered source\nof the relevant symbols PLUS the call paths between them and a blast-radius\nsummary \u2014 replacing a grep + Read loop with one round-trip.\n\nThis server started somewhere with no `.homegraph/` of its own, so there is no\ndefault project \u2014 but the tools are available and work **per project**:\n\n- To query a project that HAS a `.homegraph/` index (e.g. a service inside a\n  monorepo, or a second repo), pass its path as `projectPath` to\n  `homegraph_explore` (and any other homegraph tool). HomeGraph resolves the\n  nearest `.homegraph/` at or above that path and answers from it \u2014 for as many\n  projects as you like in one session.\n- For a project with no `.homegraph/`, use your built-in tools (Read/Grep/Glob)\n  for that project. Indexing is the user's decision \u2014 don't run it yourself, but\n  if it comes up they can run `homegraph init` in a project to enable homegraph\n  there (a new index is picked up live, no restart).\n";
+export declare const SERVER_INSTRUCTIONS = "# HomeGraph \u2014 when to call\n\nHomeGraph is a **local structural index of THIS repo**: symbols + call/import/extends edges + files. Use it only when the answer needs that graph.\n\n## Call HomeGraph (closed set)\n\nUse `homegraph_explore` (primary) when **all** of these hold:\n\n1. The evidence lives **in this repository's source** (not an external SDK manual).\n2. You need **structure**: definition location, who calls whom, how A reaches B, multi-file wiring, or in-repo import/usage of a named API/`@kit` module.\n3. You can put **concrete names** in `query` \u2014 symbol, `Type.member`, file basename, or `@kit\u2026` (skip `homegraph_search` when names are already known).\n\nTypical fits:\n\n- How a **feature in this repo** is wired (mechanism / cross-file / click\u2192handler flow)\n- Callers / callees / blast radius of a **named** symbol\n- What a **named component/method** does (include the name; one explore is enough)\n- In-repo usages of an imported API (not the official feature catalog)\n\n**One explore with names** beats search\u2192explore\u2192node\u2192grep\u2192read. Treat returned line-numbered source as already Read. After a full explore \u2014 **answer**; do not re-verify with grep/read/node for the same symbols. Busy/partial \u2192 retry that **same** explore once.\n\n## Do not call HomeGraph otherwise\n\nIf the question is **outside the set above**, do **not** open any `homegraph_*` tool \u2014 use Read / Grep / Glob / SDK docs. HomeGraph is not a general Q&A layer; forcing it on the wrong shape costs time and tokens and often lowers quality.\n\n## Tool roles\n\n| Tool | Role |\n|------|------|\n| **homegraph_explore** | Primary for the closed set above |\n| homegraph_node | One known symbol body (or indexed file) after explore named it |\n| homegraph_callers / callees | Compact edge lists for a named symbol |\n| homegraph_search | Rare \u2014 unknown spelling only |\n| homegraph_files | Folder tree only |\n\n## Tips\n\n- **Deadline / partial** \u2014 success-shaped; retry ONE explore with the same names. Do not abandon to grep for those symbols.\n- **Staleness banner** \u2014 Read only the listed edited files.\n- **Not indexed** \u2014 built-in tools; user runs `homegraph init` \u2014 you do not.\n";
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# HomeGraph \u2014 per-project (pass projectPath)\n\nHomeGraph indexes a codebase into a symbol graph. Call it **only** for in-repo structural / flow / usage questions on a project that has `.homegraph/`. Pass that project as `projectPath`.\n\n- Fits the closed set (structure, callers, wiring, named symbol/file) \u2192 `homegraph_explore`\n- Anything else \u2192 Read/Grep/Glob \u2014 **do not call homegraph_***\n- No index \u2192 Read/Grep/Glob; user runs `homegraph init` if they want indexing\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,4sJAkD/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,4pCAmB7C,CAAC"}
+{"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,mBAAmB,wtEAwC/B,CAAC;AAEF,eAAO,MAAM,iCAAiC,yfAO7C,CAAC"}

package/dist/mcp/server-instructions.js

@@ -1,104 +1,59 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
 /**
  * Server-level instructions emitted in the MCP `initialize` response.
  *
- * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
- * SDK, …) surface this text in the agent's system prompt automatically,
- * giving the agent a high-level playbook for the homegraph toolset
- * before it sees individual tool descriptions.
- *
- * Goals when editing this:
- *   - Lead the agent to homegraph_explore for any structural/flow question
- *   - Reinforce "explore instead of Read/Grep" for indexed code
- *   - Anti-patterns (don't re-verify with grep; don't hand-reconstruct flows)
- *
- * HomeGraph exposes the full tool surface by default (search, node, explore,
- * spec tools, …). Lead with homegraph_explore for structural questions; the
- * other tools are available when a narrower step helps.
+ * Single source of truth for agent-facing tool guidance (issue #529).
+ * Edit here — not installer prompts or eval harness prompts.
  */
-exports.SERVER_INSTRUCTIONS = `# HomeGraph — code intelligence over an indexed knowledge graph
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
+exports.SERVER_INSTRUCTIONS = `# HomeGraph — when to call
 
-HomeGraph is a SQLite knowledge graph of every symbol, edge, and file in
-the workspace — pre-computed structure you would otherwise re-derive by
-reading files (cached intelligence: thousands of parse/trace decisions you
-don't pay to re-reason each run). Reads are sub-millisecond; the index lags
-writes by ~1s through the file watcher. Reach for it BEFORE *and* while
-writing or editing code — not just for questions: one call returns the
-verbatim source PLUS who calls it and what it affects, so you edit with the
-blast radius in view. More accurate context, in far fewer tokens and
-round-trips than reading files yourself.
+HomeGraph is a **local structural index of THIS repo**: symbols + call/import/extends edges + files. Use it only when the answer needs that graph.
 
-## Primary tool: homegraph_explore — use it instead of reading files
+## Call HomeGraph (closed set)
 
-For structural and flow questions, \`homegraph_explore\` is Read-equivalent. It
-takes either a natural-language question or a bag of symbol/file names and
-returns the **verbatim, line-numbered source** of the relevant symbols
-grouped by file — the same \`<n>\\t<line>\` shape \`Read\` gives you, safe to
-\`Edit\` from — PLUS the call path among them (including dynamic-dispatch hops
-like callbacks, React re-render, and JSX children that grep can't follow) and
-a blast-radius summary of what depends on them.
+Use \`homegraph_explore\` (primary) when **all** of these hold:
 
-Whether you're answering "how does X work" or implementing a change (fixing a
-bug, adding a feature), call \`homegraph_explore\` before you Read. ONE call
-usually answers the whole question. HomeGraph IS the pre-built search index —
-so running your own grep + read loop, or delegating the lookup to a separate
-file-reading sub-task/agent, repeats work homegraph already did and costs more
-for the same answer. A direct homegraph answer is typically one to a few
-calls; a grep/read exploration is dozens.
+1. The evidence lives **in this repository's source** (not an external SDK manual).
+2. You need **structure**: definition location, who calls whom, how A reaches B, multi-file wiring, or in-repo import/usage of a named API/\`@kit\` module.
+3. You can put **concrete names** in \`query\` — symbol, \`Type.member\`, file basename, or \`@kit…\` (skip \`homegraph_search\` when names are already known).
 
-## How to query
+Typical fits:
 
-- **Almost any question — "how does X work", architecture, a bug, "what/where is X", or surveying an area** → \`homegraph_explore\` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.
-- **"How does X reach/become Y? / the flow / the path from X to Y"** → \`homegraph_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.
-- **Reading or editing a file/symbol you can name** → put its name or file path in the \`homegraph_explore\` query — it returns that current line-numbered source (safe to \`Edit\` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.
-- **Need more?** Call \`homegraph_explore\` again with more specific names — treat the source it returns as already Read.
+- How a **feature in this repo** is wired (mechanism / cross-file / click→handler flow)
+- Callers / callees / blast radius of a **named** symbol
+- What a **named component/method** does (include the name; one explore is enough)
+- In-repo usages of an imported API (not the official feature catalog)
 
-## Anti-patterns
+**One explore with names** beats search→explore→node→grep→read. Treat returned line-numbered source as already Read. After a full explore — **answer**; do not re-verify with grep/read/node for the same symbols. Busy/partial → retry that **same** explore once.
 
-- **Trust homegraph's results — don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.
-- **Don't grep or Read first** to find or understand indexed code — ONE \`homegraph_explore\` returns the relevant symbols' source together in a single round-trip. Reach for raw \`Read\`/\`Grep\` only to confirm a specific detail homegraph didn't cover, or for what homegraph doesn't index (configs, docs).
-- **Don't reconstruct a flow by hand** — name the endpoints in one \`homegraph_explore\` and it surfaces the path between them, dynamic-dispatch hops included.
-- **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust homegraph. A different, rarer banner — "⚠️ HomeGraph auto-sync is DISABLED…" — means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.
+## Do not call HomeGraph otherwise
 
-## Limitations
+If the question is **outside the set above**, do **not** open any \`homegraph_*\` tool — use Read / Grep / Glob / SDK docs. HomeGraph is not a general Q&A layer; forcing it on the wrong shape costs time and tokens and often lowers quality.
 
-- If a tool reports a project isn't indexed (no \`.homegraph/\`), stop calling homegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision — mention they can run \`homegraph init\` if it comes up, but don't run it yourself.
-- Index lags file writes by ~1 second.
-- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
-- No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. HomeGraph supplements those with structural context they don't have.
-`;
-/**
- * Instructions variant sent when the server's own root has NO homegraph index.
- *
- * The tools are still exposed (gating tool availability on whether `./` has an
- * index is the bug behind #964: it breaks monorepos where only sub-projects are
- * indexed, and a server that started before `homegraph init` never surfaces the
- * tools afterward). Instead of an "inactive" note, this variant tells the agent
- * homegraph works **per project**: there's no default project to query, so pass
- * a `projectPath` to any project that HAS a `.homegraph/`. The full single-
- * project playbook ({@link SERVER_INSTRUCTIONS}) is sent instead when the root
- * IS indexed, so the common case stays tight.
- */
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — available (per-project; pass projectPath)
+## Tool roles
 
-HomeGraph is a SQLite knowledge graph of a codebase's symbols, edges, and
-files: one \`homegraph_explore\` call returns the verbatim, line-numbered source
-of the relevant symbols PLUS the call paths between them and a blast-radius
-summary — replacing a grep + Read loop with one round-trip.
+| Tool | Role |
+|------|------|
+| **homegraph_explore** | Primary for the closed set above |
+| homegraph_node | One known symbol body (or indexed file) after explore named it |
+| homegraph_callers / callees | Compact edge lists for a named symbol |
+| homegraph_search | Rare — unknown spelling only |
+| homegraph_files | Folder tree only |
+
+## Tips
+
+- **Deadline / partial** — success-shaped; retry ONE explore with the same names. Do not abandon to grep for those symbols.
+- **Staleness banner** — Read only the listed edited files.
+- **Not indexed** — built-in tools; user runs \`homegraph init\` — you do not.
+`;
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# HomeGraph — per-project (pass projectPath)
 
-This server started somewhere with no \`.homegraph/\` of its own, so there is no
-default project — but the tools are available and work **per project**:
+HomeGraph indexes a codebase into a symbol graph. Call it **only** for in-repo structural / flow / usage questions on a project that has \`.homegraph/\`. Pass that project as \`projectPath\`.
 
-- To query a project that HAS a \`.homegraph/\` index (e.g. a service inside a
-  monorepo, or a second repo), pass its path as \`projectPath\` to
-  \`homegraph_explore\` (and any other homegraph tool). HomeGraph resolves the
-  nearest \`.homegraph/\` at or above that path and answers from it — for as many
-  projects as you like in one session.
-- For a project with no \`.homegraph/\`, use your built-in tools (Read/Grep/Glob)
-  for that project. Indexing is the user's decision — don't run it yourself, but
-  if it comes up they can run \`homegraph init\` in a project to enable homegraph
-  there (a new index is picked up live, no restart).
+- Fits the closed set (structure, callers, wiring, named symbol/file) → \`homegraph_explore\`
+- Anything else → Read/Grep/Glob — **do not call homegraph_***
+- No index → Read/Grep/Glob; user runs \`homegraph init\` if they want indexing
 `;
 //# sourceMappingURL=server-instructions.js.map

package/dist/mcp/server-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDlC,CAAC;AAEF;;;;;;;;;;;GAWG;AACU,QAAA,iCAAiC,GAAG;;;;;;;;;;;;;;;;;;;CAmBhD,CAAC"}
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwClC,CAAC;AAEW,QAAA,iCAAiC,GAAG;;;;;;;CAOhD,CAAC"}