@colbymchenry/codegraph 1.1.1 → 1.1.3

package/README.md

@@ -606,6 +606,18 @@ add a negation — `!vendor/`. The defaults apply uniformly, so committing a
 dependency or build directory doesn't force it into the graph; the `.gitignore`
 negation is the explicit opt-in.
 
+`.gitignore` can't drop a directory you've **committed**, though. For a vendored
+theme or SDK that's checked into the repo (e.g. a Metronic theme under
+`static/`), list it under `exclude` in `codegraph.json` — gitignore-style
+patterns, matched against repo-root-relative paths, honored on index, sync, and
+watch:
+
+```json
+{
+  "exclude": ["static/", "**/vendor/**"]
+}
+```
+
 ### Custom file extensions
 
 If your project uses a non-standard extension for a [supported

package/dist/bin/command-supervision.d.ts

@@ -0,0 +1,12 @@
+export interface CommandSupervision {
+    /** Tear down both watchdogs. Idempotent; call when the command finishes. */
+    stop(): void;
+}
+/**
+ * Install the liveness + PPID watchdogs for the duration of a CLI command.
+ * `label` is used in the shutdown notice (e.g. `"index"`). Returns a handle
+ * whose `stop()` must be called when the command completes so neither watchdog
+ * outlives it.
+ */
+export declare function installCommandSupervision(label: string): CommandSupervision;
+//# sourceMappingURL=command-supervision.d.ts.map

package/dist/db/migrations.d.ts

@@ -7,7 +7,7 @@ import { SqliteDatabase } from './sqlite-adapter';
 /**
  * Current schema version
  */
-export declare const CURRENT_SCHEMA_VERSION = 5;
+export declare const CURRENT_SCHEMA_VERSION = 6;
 /**
  * Migration definition
  */

package/dist/directory.d.ts

@@ -85,6 +85,38 @@ export declare function findIndexedSubprojectRoots(root: string, opts?: {
     maxDepth?: number;
     max?: number;
 }): string[];
+/**
+ * Does `prompt` contain an explicit structural keyword (English or CJK)? A
+ * keyword is a strong, self-contained signal, so the front-load hook fires on it
+ * directly — no graph check needed. (A *code-token* match, by contrast, is only
+ * a candidate the hook verifies against the graph first; see {@link extractCodeTokens}.)
+ */
+export declare function hasStructuralKeyword(prompt: string): boolean;
+/**
+ * Identifier-shaped tokens in `prompt` — camelCase / PascalCase-with-inner-cap,
+ * snake_case, a `name(` call, or the two sides of an `a.b` member access. Naming
+ * a symbol is a code question whatever the surrounding human language, and these
+ * shapes almost never occur in ordinary prose, so they catch the common
+ * "<symbol> 的调用链?" / "where is <symbol> 定義" prompts no keyword list would.
+ *
+ * These are *candidates*, not a verdict: a tech brand like `JavaScript` or
+ * `GitHub` is identifier-shaped too, so the front-load hook checks each token
+ * against the actual index ({@link getNodesByName}) and only fires when one is a
+ * real symbol here — otherwise a brand-name prompt would inject ~16KB of
+ * low-relevance context (issue #994 follow-up). A doc/data filename ("README.md")
+ * is excluded from the member-access form since it's a file reference, not a symbol.
+ */
+export declare function extractCodeTokens(prompt: string): string[];
+/**
+ * Cheap, graph-free candidate gate for the front-load hook: could `prompt` be a
+ * structural / flow / impact / "where-how" question worth front-loading context
+ * for? True on an explicit keyword (English or CJK, issue #994) OR an
+ * identifier-shaped token. A keyword is sufficient to fire on its own; a
+ * token-only match is only a candidate the hook then verifies against the graph
+ * (a brand name like `JavaScript` is token-shaped but isn't a symbol). Every
+ * non-candidate prompt ("fix this typo", in any language) stays a zero-cost no-op.
+ */
+export declare function isStructuralPrompt(prompt: string): boolean;
 /**
  * What the front-load hook should do for a prompt issued from a directory.
  */

package/dist/extraction/index.d.ts

@@ -66,12 +66,24 @@ export declare function buildDefaultIgnore(rootDir: string): Ignore;
  */
 export declare class ScopeIgnore {
     private rootMatcher;
+    /**
+     * Project `codegraph.json` `exclude` patterns (#999), matched against the
+     * full root-relative path. Wins over everything else — an explicit user
+     * exclude applies even to tracked files and even inside embedded repos.
+     */
+    private exclude;
     private embedded;
     private defaults;
     constructor(rootMatcher: Ignore, embedded: Array<{
         root: string;
         matcher: Ignore;
-    }>);
+    }>, 
+    /**
+     * Project `codegraph.json` `exclude` patterns (#999), matched against the
+     * full root-relative path. Wins over everything else — an explicit user
+     * exclude applies even to tracked files and even inside embedded repos.
+     */
+    exclude?: Ignore | null);
     ignores(rel: string): boolean;
 }
 /**

package/dist/extraction/languages/c-cpp.d.ts

@@ -7,6 +7,22 @@ import type { LanguageExtractor } from '../tree-sitter-types';
  * template args. Returns undefined for primitives / void / `auto` / empty.
  */
 export declare function normalizeCppReturnType(raw: string): string | undefined;
+/**
+ * Strip C++ template arguments from a base-type reference name so it matches the
+ * bare class/struct the template was DEFINED as. `template<typename T> class
+ * Base { … }` is indexed as a node named `Base`, but a derived class
+ * `class D : public Base<int>` records its base as the full `Base<int>` (and
+ * `class Q : public ns::Tpl<int>` as `ns::Tpl<int>`) — neither name-matches
+ * `Base` / `ns::Tpl`, so the `extends` edge never resolves and the derived class
+ * looks like it inherits from nothing (#1043).
+ *
+ * Removes every balanced `<…>` group regardless of nesting or position, so
+ * `Base<int>` → `Base`, `ns::Tpl<Foo<int>>` → `ns::Tpl`, and the rare
+ * `Outer<int>::Inner` → `Outer::Inner`. The remaining qualified head is exactly
+ * what the non-templated base case already produces, so resolution treats them
+ * identically. A name with no template args passes through unchanged.
+ */
+export declare function stripCppTemplateArgs(name: string): string;
 export declare const cExtractor: LanguageExtractor;
 export declare const cppExtractor: LanguageExtractor;
 //# sourceMappingURL=c-cpp.d.ts.map

package/dist/extraction/parse-pool.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Parse worker pool — runs tree-sitter parsing across N worker threads so a full
+ * `codegraph index` uses every core instead of pinning one.
+ *
+ * Why this exists: `ExtractionOrchestrator.indexAll()` already reads files in
+ * parallel, but it parsed them through a SINGLE worker thread, so on an
+ * N-core machine indexing a large repo used one core and left the rest idle
+ * (issue #1015, the parse-time half of #320). Spreading the parse calls across a
+ * pool of workers — each its own tree-sitter WASM heap — restores multi-core
+ * throughput. SQLite storage stays on the main thread (it isn't thread-safe), so
+ * only the CPU-bound parse step is parallelised; results are stored as they
+ * arrive, in whatever order they finish.
+ *
+ * Design mirrors {@link ../mcp/query-pool} (idle-list dispatch, lazy growth,
+ * throttled cold-starts, crash recovery), with parse-specific behaviour:
+ *   - per-worker recycle: WASM linear memory grows but never shrinks, so each
+ *     worker is torn down and replaced after `recycleInterval` parses to reclaim
+ *     its heap — the same reason the old single worker recycled.
+ *   - reject, don't retry: a parse that crashes or times out its worker REJECTS
+ *     (with a message the orchestrator's retry pass recognises) rather than being
+ *     silently requeued — the orchestrator owns the smarter two-stage retry
+ *     (fresh worker, then comment-stripped) on a clean WASM heap.
+ *   - a size-1 pool reproduces the old single-worker path exactly, which is the
+ *     conservative rollback: set `CODEGRAPH_PARSE_WORKERS=1`.
+ *
+ * Memory: peak scales with pool size (≈ size × a worker's pre-recycle heap), so
+ * the default is capped and the env var lets constrained machines dial it down.
+ */
+import type { Language, ExtractionResult } from '../types';
+/**
+ * Minimal worker surface the pool drives — satisfied by a real `worker_threads`
+ * Worker. Abstracted so tests can inject a fake worker and exercise the pool's
+ * queue / growth / recycle / crash-recovery logic without spawning threads or a
+ * built `dist/`.
+ */
+export interface ParsePoolWorker {
+    postMessage(msg: unknown): void;
+    terminate(): Promise<number> | void;
+    on(event: 'message', cb: (m: unknown) => void): void;
+    on(event: 'error', cb: (e: Error) => void): void;
+    on(event: 'exit', cb: (code: number) => void): void;
+}
+/** A single file to parse. `language` is resolved on the main thread (it holds
+ *  the project's codegraph.json extension overrides) and handed to the worker. */
+export interface ParseTask {
+    filePath: string;
+    content: string;
+    language: Language;
+    frameworkNames?: string[];
+}
+/**
+ * Resolve the pool size from the `CODEGRAPH_PARSE_WORKERS` override and the
+ * machine's core count.
+ *   - explicit `0` or `1` → 1 worker (the old single-worker path; the rollback).
+ *   - explicit `N` → N, clamped to [1, 16].
+ *   - unset / blank / non-numeric → `clamp(cores - 1, 1, 8)` (leave a core for
+ *     the main thread + UI; never zero — parsing always needs a worker).
+ */
+export declare function resolveParsePoolSize(envVal: string | undefined, cpuCount: number): number;
+export interface ParseWorkerPoolOptions {
+    /** Languages to load grammars for in every worker at spawn. */
+    languages: Language[];
+    /** Number of worker threads (≥1). Clamp the resolved value before passing. */
+    size: number;
+    /** Compiled `parse-worker.js` path. Required unless `createWorker` is given. */
+    workerScriptPath?: string;
+    /** Parses per worker before recycle. Default 250. */
+    recycleInterval?: number;
+    /** Base per-parse timeout (ms); scaled by file size per parse. Default 10s. */
+    parseTimeoutMs?: number;
+    /** Worker factory (tests inject a fake). Defaults to a real `worker_threads` Worker. */
+    createWorker?: () => ParsePoolWorker;
+    /** Optional verbose logger (the orchestrator's `[worker] …` logger). */
+    log?: (msg: string) => void;
+}
+export declare class ParseWorkerPool {
+    private idle;
+    private queue;
+    private inflight;
+    private workers;
+    private pending;
+    private parseCounts;
+    private nextId;
+    private totalCrashes;
+    private destroyed;
+    private readonly languages;
+    private readonly maxSize;
+    private readonly recycleInterval;
+    private readonly parseTimeoutMs;
+    private readonly createWorker;
+    private readonly log;
+    constructor(opts: ParseWorkerPoolOptions);
+    /** Pool size cap (for logging). */
+    get size(): number;
+    /** Live worker count (for tests). */
+    get liveWorkers(): number;
+    /** False once the crash budget is exhausted (or after destroy). */
+    get healthy(): boolean;
+    /**
+     * Parse one file on the pool. Resolves with the extraction result, or REJECTS
+     * if the parse times out or its worker crashes — the caller records the error
+     * and (for worker-exit/OOM rejections) re-attempts in its retry pass.
+     */
+    requestParse(task: ParseTask): Promise<ExtractionResult>;
+    private spawnOne;
+    private onMessage;
+    /** A worker died (crash hook / OOM exit / spawn error). Reject its in-flight
+     *  parse so the caller's retry pass can re-attempt it, then respawn. */
+    private onWorkerGone;
+    /** Tear down a worker that has hit its recycle threshold and replace it. Not a
+     *  crash, so it doesn't count against the budget. */
+    private recycle;
+    private removeWorker;
+    private dispatch;
+    private onTimeout;
+    private drain;
+    private settle;
+    /**
+     * Recycle every idle worker now (fresh WASM heaps). The orchestrator calls
+     * this before its retry pass so crash-on-memory files get the cleanest heap.
+     */
+    recycleAll(): void;
+    /** Terminate all workers and reject any outstanding parses. */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=parse-pool.d.ts.map

package/dist/extraction/tree-sitter.d.ts

@@ -438,6 +438,27 @@ export declare class TreeSitterExtractor {
      * arguments (`new Foo(bar())`) get their own `calls` references.
      */
     private extractInstantiation;
+    /**
+     * Is this C++ `declaration` a stack/direct-initialization object construction
+     * that invokes a constructor — `Calculator calc(0)` (direct-init) or
+     * `Widget w{1, 2}` (brace-init) — as opposed to a plain variable or a
+     * function declaration? Used to emit an `instantiates` edge for the
+     * call-less construction syntax (#1035); heap `new T(...)` is handled
+     * separately by INSTANTIATION_KINDS.
+     *
+     * Two signals, both required:
+     *  - the `type` field is a class-like NAMED type (`type_identifier`,
+     *    `template_type`, or `qualified_identifier`). Primitives (`int x(0)`),
+     *    `auto` (`placeholder_type_specifier` — that form always carries a real
+     *    `call_expression`, already handled), and sized specifiers are excluded —
+     *    they construct no class; and
+     *  - a declarator carries constructor arguments: an `init_declarator` whose
+     *    `value` is an `argument_list` (`(args)`) or `initializer_list` (`{args}`).
+     *    This skips default construction `Calculator c;` (no value) and the
+     *    most-vexing-parse `Calculator c();` (a bodyless `function_declarator`,
+     *    a function decl — not a construction).
+     */
+    private isCppStackConstruction;
     /**
      * Static-member / value-read pass. A type/enum/class used only via a member
      * VALUE — `Enum.value`, `Type.CONST`, `Colors.red`, `Foo::BAR` — recorded no

package/dist/mcp/daemon-paths.d.ts

@@ -16,11 +16,38 @@
  * an absolute-path hash under `os.tmpdir()`. The pidfile always stays in the
  * project (it doesn't have a length limit) — and acts as the authoritative
  * pointer to the socket path the daemon chose.
+ *
+ * Second special-case (#997, #974): some filesystems can't host an AF_UNIX node
+ * AT ALL — ExFAT/FAT external volumes, certain network mounts, WSL2 DrvFs — so
+ * `listen()` throws ENOTSUP/EACCES regardless of path length. We can't cheaply
+ * tell those apart from a normal volume up front, so instead of guessing we
+ * expose an ORDERED candidate list (`getDaemonSocketCandidates`): the in-project
+ * path first, the deterministic tmpdir path as the fallback of last resort. The
+ * daemon binds the first that works (relocating past a capability error); the
+ * proxy connects the first that answers. Both walk the SAME list, so they still
+ * converge on whichever the daemon bound with zero coordination.
+ */
+/**
+ * Ordered socket / named-pipe path candidates the daemon should try to bind (and
+ * the proxy should try to connect) for `projectRoot`, most-preferred first.
+ * Deterministic given a project root, so independent processes converge without
+ * coordination — even when the preferred candidate is unusable and both fall
+ * through to the same fallback.
+ *
+ *   - Windows: a single named pipe (lives in the kernel pipe namespace, not on
+ *     the project FS, so neither the length nor the ExFAT hazard applies).
+ *   - Short in-project path: `[ .codegraph/daemon.sock , <tmpdir> ]` — try the
+ *     project first, fall back to tmpdir if its FS can't host a socket (#997).
+ *   - Long in-project path (deep monorepos, Bazel out dirs): `[ <tmpdir> ]` only
+ *     — bind would throw ENAMETOOLONG, so we skip straight to tmpdir.
  */
+export declare function getDaemonSocketCandidates(projectRoot: string): string[];
 /**
- * Compute the socket / named-pipe path the daemon should listen on (and the
- * proxy should connect to) for `projectRoot`. Deterministic given a project
- * root, so independent processes converge without coordination.
+ * The PREFERRED (primary) socket path — candidate 0. Use this only where a
+ * single representative path is wanted (the lockfile's informational
+ * `socketPath` field, status display). For binding/connecting, walk the full
+ * {@link getDaemonSocketCandidates} list — the daemon may bind a fallback when
+ * candidate 0 is unusable.
  */
 export declare function getDaemonSocketPath(projectRoot: string): string;
 /** Absolute path to the daemon pid lockfile for `projectRoot`. */

package/dist/mcp/daemon.d.ts

@@ -39,7 +39,18 @@
  *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
  *   - The MCP protocol state machine — that's `./session.ts`.
  */
+import * as net from 'net';
 import { DaemonLockInfo } from './daemon-paths';
+/**
+ * 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
+ * trips the libuv assertion above); instead mark success and let the loop drain
+ * to a natural exit, with an UNREF'd backstop that force-exits only if a stray
+ * handle would otherwise hang shutdown. Pure and platform-injected so both
+ * branches are unit-testable off-Windows. Returns the backstop timer (Windows)
+ * so callers/tests can clear it.
+ */
+export declare function finalizeDaemonExit(platform: NodeJS.Platform, exit: (code: number) => void): NodeJS.Timeout | null;
 /** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
 declare const MAX_HELLO_LINE_BYTES = 4096;
 /**
@@ -177,8 +188,29 @@ export type AcquireResult = {
  * the pidfile becomes visible in one step already containing a full record.
  * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
  * There is no empty-file window at all.
+ *
+ * Filesystems without hard links (#997): ExFAT/FAT external volumes and some
+ * network mounts can't `link()` at all — it throws ENOTSUP/EPERM, which would
+ * otherwise kill the daemon before it ever reaches the socket bind. There we
+ * fall back to an O_EXCL create (`acquireLockViaExclusiveOpen`): still exclusive
+ * ("first writer wins"), but the full record is written through the fd in a
+ * second step, so the empty-file window the link approach removed is reopened —
+ * only on these filesystems, only for the microseconds between create and write
+ * (far narrower than the original bug, which the file watcher's startup latency
+ * widened). The race's worst case is two daemons briefly; on a single external
+ * drive that's strictly better than the daemon never starting at all.
  */
 export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+/**
+ * Exclusive-create the pidfile (O_CREAT|O_EXCL via the `wx` flag) and write the
+ * full record through the same fd — the hard-link-free fallback used by
+ * {@link tryAcquireDaemonLock} on filesystems without `link()`. Returns true if
+ * we created it (acquired the lock), false on EEXIST (another candidate holds
+ * it). Any other error propagates. Still exclusive, so "first writer wins" holds
+ * exactly as the link path does; the only difference is the brief empty-file
+ * window between create and write. Exported for testing.
+ */
+export declare function acquireLockViaExclusiveOpen(pidPath: string, info: DaemonLockInfo): boolean;
 /**
  * Remove a stale pidfile, but only if it still names a dead process. Re-reads
  * the file immediately before unlinking so we never delete a lock that a live
@@ -197,6 +229,22 @@ export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?:
  * mistake a live daemon for a dead one and clear its lock.
  */
 export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Bind the first usable socket from an ordered candidate list, relocating past
+ * any path that fails to bind for a non-conflict reason (see {@link
+ * SOCKET_BIND_CONFLICT_CODE}). The injected `listen` does the real
+ * `net.Server.listen` (and stale-socket clear); abstracted so the relocation
+ * policy is unit-testable without a real unsupported filesystem. Returns the
+ * server plus the path actually bound. An EADDRINUSE, or any error on the LAST
+ * candidate, propagates — the caller releases the lockfile and falls back to
+ * direct mode (#974). Exported for testing.
+ */
+export declare function bindFirstUsableSocket(candidates: string[], listen: (socketPath: string) => Promise<net.Server>, opts?: {
+    onRelocate?: (from: string, to: string, code: string) => void;
+}): Promise<{
+    server: net.Server;
+    socketPath: string;
+}>;
 /**
  * Parse one client-hello line. Returns the peer pids if `line` is a well-formed
  * client-hello (carries the `codegraph_client` marker), or null otherwise — in

package/dist/mcp/engine.d.ts

@@ -17,6 +17,15 @@ export interface MCPEngineOptions {
      * cheap. Honors {@link watchDisabledReason} regardless.
      */
     watch?: boolean;
+    /**
+     * Whether to off-load read-tool dispatch to a worker-thread pool. Only the
+     * SHARED daemon wants this — it serves many concurrent clients on one event
+     * loop, so without a pool concurrent explores serialize and starve the MCP
+     * transport. Direct mode (one stdio client, no concurrency) leaves it off so a
+     * single call never pays a worker round-trip. `CODEGRAPH_QUERY_POOL_SIZE=0`
+     * disables it even in daemon mode.
+     */
+    queryPool?: boolean;
 }
 /**
  * Shared MCP engine. Thread-safe in the sense that multiple sessions can
@@ -32,7 +41,15 @@ export declare class MCPEngine {
     private watcherStarted;
     private opts;
     private closed;
+    private queryPool;
     constructor(opts?: MCPEngineOptions);
+    /**
+     * Start the worker-thread query pool once a default project is open (daemon
+     * mode only; honors `CODEGRAPH_QUERY_POOL_SIZE`). Idempotent and best-effort:
+     * if workers can't spawn on this platform the ToolHandler keeps serving reads
+     * in-process, so the pool can only help, never break, tool calls.
+     */
+    private maybeStartPool;
     /**
      * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
      * project path (from the `--path` CLI flag) without yet opening it. This

package/dist/mcp/ppid-watchdog.d.ts

@@ -41,4 +41,22 @@ export interface SupervisionState {
  * supervisor and should shut down, or null while it is still supervised.
  */
 export declare function supervisionLostReason(state: SupervisionState): string | null;
+/** Default PPID poll cadence (ms). Shared by the MCP server and CLI commands. */
+export declare const DEFAULT_PPID_POLL_MS = 5000;
+/**
+ * Resolve the PPID watchdog poll interval from an env override
+ * (`CODEGRAPH_PPID_POLL_MS`). A value of `0` disables the watchdog entirely
+ * (escape hatch for embedded scenarios where the parent legitimately re-parents
+ * the process on purpose). Anything non-numeric or negative falls back to the
+ * default.
+ */
+export declare function parsePpidPollMs(raw: string | undefined): number;
+/**
+ * Parse the host PID propagated across the `--liftoff-only` re-exec
+ * (`CODEGRAPH_HOST_PPID`). Returns a positive integer PID, or null when
+ * unset/invalid — the direct-launch path, where the watchdog falls back to
+ * `process.ppid` divergence. PIDs of 0/1 are rejected (0 = unknown, 1 = init,
+ * i.e. already orphaned), so the watchdog doesn't latch onto init.
+ */
+export declare function parseHostPpid(raw: string | undefined): number | null;
 //# sourceMappingURL=ppid-watchdog.d.ts.map

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

@@ -0,0 +1,94 @@
+/**
+ * Query pool — runs CPU-heavy read-tool calls on a pool of worker threads so
+ * the shared daemon's main event loop stays free for the MCP transport.
+ *
+ * Why this exists: see {@link ./query-worker}. One daemon, one event loop, one
+ * synchronous SQLite connection serializes every concurrent `codegraph_explore`
+ * AND starves the transport (a 10-way wave delivered 0 transport heartbeats in
+ * 25s — responses can't flush until the whole batch drains, so clients time
+ * out). Spreading the dispatch across worker threads (each its own WAL read
+ * 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.
+ *   - 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.
+ */
+import type { ToolResult } from './tools';
+/**
+ * Minimal worker surface the pool drives — satisfied by a real `worker_threads`
+ * Worker. Abstracted so tests can inject a fake worker and exercise the pool's
+ * queue / growth / crash-recovery / backstop logic without spawning threads or
+ * needing a built `dist/`.
+ */
+export interface PoolWorker {
+    postMessage(msg: unknown): void;
+    terminate(): Promise<number> | void;
+    on(event: 'message', cb: (m: unknown) => void): void;
+    on(event: 'error', cb: (e: Error) => void): void;
+    on(event: 'exit', cb: (code: number) => void): void;
+}
+export interface QueryPoolOptions {
+    /** Default project root each worker opens at spawn. */
+    root: string;
+    /** Max worker threads. Defaults to `clamp(cores-1, 1, 16)`. */
+    size?: number;
+    /** Linger before a queued call gets busy-guidance. Default 45s. */
+    softTimeoutMs?: number;
+    /** Retries for an in-flight call whose worker crashed. Default 1. */
+    maxRetries?: number;
+    /** Worker factory (tests inject a fake). Defaults to a real `worker_threads` Worker. */
+    createWorker?: () => PoolWorker;
+}
+/**
+ * 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.
+ */
+export declare function resolvePoolSize(envVal: string | undefined, cpuCount: number): number;
+export declare class QueryPool {
+    private idle;
+    private queue;
+    private inflight;
+    private workers;
+    private pendingWorkers;
+    private nextId;
+    private totalCrashes;
+    private destroyed;
+    private readonly root;
+    private readonly maxSize;
+    private readonly softTimeoutMs;
+    private readonly maxRetries;
+    private readonly createWorker;
+    constructor(opts: QueryPoolOptions);
+    /** Pool size cap (for logging/status). */
+    get size(): number;
+    /** Live worker count (for tests/status). */
+    get liveWorkers(): number;
+    /**
+     * False once the crash budget is exhausted (or after destroy). The ToolHandler
+     * checks this and falls back to in-process dispatch — a broken worker platform
+     * degrades to today's behavior instead of failing tool calls.
+     */
+    get healthy(): boolean;
+    private spawnOne;
+    private onMessage;
+    private onWorkerGone;
+    private drain;
+    private settle;
+    /** Run a read tool on the pool. Always resolves (never rejects). */
+    run(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** Terminate all workers and answer any outstanding calls gracefully. */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=query-pool.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * Query worker thread — issue: concurrent MCP tool calls starve the daemon.
+ *
+ * The shared daemon serves every session on ONE event loop with synchronous
+ * `node:sqlite`. `codegraph_explore` is CPU-heavy (FTS + RWR/personalized-
+ * PageRank + impact + output building) stitched together by microtask `await`s,
+ * so N concurrent explores keep the microtask queue continuously full and
+ * starve the macrotask phases — timers AND socket I/O. The transport freezes:
+ * no response flushes, no request is read, until the whole batch drains. With
+ * ~10 subagents that routinely exceeds the MCP client's request timeout.
+ *
+ * This worker moves the heavy read-tool dispatch OFF the daemon's main loop.
+ * Each worker owns its OWN read connection (node:sqlite WAL allows N concurrent
+ * readers across connections — verified: a worker reader sees the main writer's
+ * committed catch-up/watcher writes), so {@link QueryPool} runs N tool calls in
+ * true parallel up to core count while the main loop stays free for the MCP
+ * transport. The worker runs {@link ToolHandler.executeReadTool} — validation +
+ * dispatch + error classification — and returns the raw {@link ToolResult}; the
+ * MAIN thread keeps the catch-up gate, the watcher-state notices (staleness /
+ * worktree), `codegraph_status`, and telemetry, none of which a watcher-less
+ * read connection can answer.
+ */
+export {};
+//# sourceMappingURL=query-worker.d.ts.map

package/dist/mcp/tools.d.ts

@@ -4,6 +4,7 @@
  * Defines the tools exposed by the CodeGraph MCP server.
  */
 import type CodeGraph from '../index';
+import type { QueryPool } from './query-pool';
 import type { PendingFile } from '../sync';
 /**
  * An expected, recoverable "codegraph can't serve this" condition — most
@@ -113,6 +114,33 @@ export interface ToolDefinition {
         properties: Record<string, PropertySchema>;
         required?: string[];
     };
+    /** Behavioral hints for clients (see {@link ToolAnnotations}). */
+    annotations?: ToolAnnotations;
+}
+/**
+ * MCP ToolAnnotations — behavioral hints a client MAY use to decide how, or
+ * whether, to run a tool (introduced in the 2025-03-26 spec, carried in
+ * 2025-06-18). They are advisory and never to be trusted for security, but
+ * clients gate on them: Cursor's Ask mode, for one, refuses any MCP tool that
+ * doesn't advertise `readOnlyHint: true` (issue #1018).
+ *
+ * The field is purely additive — a client that predates annotations ignores it
+ * — so codegraph advertises these even though `initialize` still negotiates the
+ * 2024-11-05 protocol version.
+ *
+ * https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations
+ */
+export interface ToolAnnotations {
+    /** Human-readable title for the tool. */
+    title?: string;
+    /** If true, the tool does not modify its environment. Default (unset): false. */
+    readOnlyHint?: boolean;
+    /** Meaningful only when NOT read-only: may the tool perform destructive updates? */
+    destructiveHint?: boolean;
+    /** If true, repeat calls with the same arguments have no additional effect. */
+    idempotentHint?: boolean;
+    /** If true, the tool interacts with an open world of external entities. */
+    openWorldHint?: boolean;
 }
 interface PropertySchema {
     type: string;
@@ -159,7 +187,15 @@ export declare class ToolHandler {
     private defaultProjectHint;
     private worktreeMismatchCache;
     private catchUpGate;
+    private queryPool;
     constructor(cg: CodeGraph | null);
+    /**
+     * Engine-only: attach (or detach with null) the worker-thread query pool. The
+     * shared daemon sets this once its default project is open; the workers each
+     * hold their own WAL read connection and run {@link executeReadTool}. A
+     * worker's own ToolHandler never has a pool, so there is no nested off-loading.
+     */
+    setQueryPool(pool: QueryPool | null): void;
     /**
      * Update the default CodeGraph instance (e.g. after lazy initialization)
      */
@@ -286,6 +322,27 @@ export declare class ToolHandler {
      * Execute a tool by name
      */
     execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Run a single read tool to completion and return its raw {@link ToolResult},
+     * classifying expected failures the same way {@link execute}'s catch does so
+     * the SHAPE is identical whether dispatch runs in-process or on a worker:
+     * NotIndexed → success-shaped guidance, PathRefusal → clean error, anything
+     * else → internal-error-with-retry. Never throws.
+     *
+     * This is the worker thread's entry point (see {@link ./query-worker}) and the
+     * in-process fallback for {@link execute}. It deliberately does NOT run the
+     * catch-up gate or the staleness/worktree notices — those need the daemon's
+     * watched main instance and stay on the main thread. Cross-cutting allowlist +
+     * path validation already ran in {@link execute} before routing here.
+     */
+    executeReadTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Pure dispatch over the read tools — the switch, with no gate, no notices, no
+     * allowlist/validation (the caller owns those). `codegraph_status` is handled
+     * on the main thread in {@link execute} and never reaches here. May throw
+     * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
+     */
+    private dispatchTool;
     /**
      * Handle codegraph_search
      */

package/dist/project-config.d.ts

@@ -12,6 +12,17 @@ export interface ProjectConfig {
      * are never discovered or indexed (#970, #976).
      */
     includeIgnored?: string[];
+    /**
+     * Gitignore-style patterns for paths to keep OUT of the index — even when
+     * they are git-TRACKED, which `.gitignore` cannot do (#999). The escape hatch
+     * for a committed vendor/theme/SDK directory (e.g. a checked-in Metronic theme
+     * under `static/`) that bloats the graph and slows indexing but isn't really
+     * your code. Matched against project-root-relative paths, so a directory like
+     * `"static/"`, a double-star vendor glob, or `"assets/theme"` all work.
+     * Absent/empty (the default) excludes nothing beyond the built-in defaults
+     * and your `.gitignore`.
+     */
+    exclude?: string[];
 }
 /**
  * Load the validated extension overrides for a project, mtime-cached.
@@ -31,6 +42,15 @@ export declare function loadExtensionOverrides(rootDir: string): Record<string,
  * are never discovered or indexed (#970, #976).
  */
 export declare function loadIncludeIgnoredPatterns(rootDir: string): string[];
+/**
+ * Load the validated `exclude` patterns for a project, mtime-cached.
+ *
+ * These name paths to keep OUT of the index even when git-tracked — the escape
+ * hatch for a committed vendor/theme/SDK directory `.gitignore` can't drop
+ * (#999). An empty result — the zero-config default — excludes nothing beyond
+ * the built-in defaults and the project's `.gitignore`.
+ */
+export declare function loadExcludePatterns(rootDir: string): string[];
 /** Test/maintenance hook: forget cached config (e.g. after rewriting it in a test). */
 export declare function clearProjectConfigCache(): void;
 //# sourceMappingURL=project-config.d.ts.map

package/dist/resolution/c-fnptr-synthesizer.d.ts

@@ -1,31 +1,3 @@
-/**
- * C/C++ function-pointer dispatch synthesis (#932).
- *
- * C/C++ polymorphism is the function pointer: a struct carries a fn-pointer
- * field (`int (*fn)(int)`, or a fn-pointer-typedef field `hook_func func`),
- * concrete functions are *registered* into it through a table
- * (`static struct cmd cmds[] = {{"add", cmd_add}, …}`, a designated
- * `.fn = cmd_add`, or `x->fn = cmd_add`), and the dispatcher calls through it
- * indirectly (`p->fn(argv)`). Static extraction captures neither the
- * registration→field binding nor the indirect call, so the dispatcher→handler
- * edge is missing and `git`'s `run_builtin` looks like it calls nothing, the
- * hooks in `hook_demo.c` are unreachable, etc.
- *
- * This bridges it, keyed by **(struct type, fn-pointer field)**:
- *   • registrations — a function bound to `S.field` via a positional
- *     initializer (matched by field index), a designated `.field = fn`, or a
- *     direct `x.field = fn` / `x->field = fn` assignment;
- *   • dispatch — `recv->field(…)` / `recv.field(…)` where `recv` resolves to a
- *     value of struct type `S` (from the enclosing function's params / locals),
- *     falling back to the field name when it is unique to one struct;
- *   • field←field propagation — `a->f = b->g` merges `B.g`'s handlers into
- *     `A.f`, so a generic single-slot hook that is reassigned from a registry
- *     (the `hook_demo.c` shape: `h->func = found->fn`) still resolves.
- *
- * Whole-graph pass after base resolution; all edges are `provenance:'heuristic'`
- * (`synthesizedBy:'fn-pointer-dispatch'`). High precision via the (type, field)
- * key + a real-function gate; a project with no fn-pointer dispatch is a no-op.
- */
 import type { Edge } from '../types';
 import type { QueryBuilder } from '../db/queries';
 import type { ResolutionContext } from './types';

package/dist/sync/worktree.d.ts

@@ -25,6 +25,15 @@
  * is exactly the distinction this module relies on.
  */
 export declare function gitWorktreeRoot(dir: string): string | null;
+/**
+ * Absolute, symlink-resolved git **common** directory for `dir` — the shared
+ * `.git` that all worktrees of one repository point at. Linked worktrees of the
+ * same repo report the SAME common dir; a submodule or an embedded clone is a
+ * DIFFERENT repository and reports its own (`…/.git/modules/<name>` or its own
+ * `.git`). That distinction is what separates a genuine "borrowed worktree"
+ * from a nested repo the parent index already covers. Null when not a repo.
+ */
+export declare function gitCommonDir(dir: string): string | null;
 export interface WorktreeIndexMismatch {
     /** The git working tree the command was run from. */
     worktreeRoot: string;

package/dist/types.d.ts

@@ -235,7 +235,12 @@ export interface SearchOptions {
 export interface SearchResult {
     /** Matching node */
     node: Node;
-    /** Relevance score (0-1) */
+    /**
+     * Relevance score for relative ranking only — higher is more relevant.
+     * NOT normalized and NOT a 0-1 fraction: the FTS path returns an unbounded
+     * BM25 magnitude (often in the tens or hundreds), while the fuzzy/exact
+     * paths return ~0-1. Use it to order results, not as an absolute percentage.
+     */
     score: number;
     /** Matched text snippets for highlighting */
     highlights?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
   "bin": {
     "codegraph": "npm-shim.js"
@@ -15,12 +15,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@colbymchenry/codegraph-darwin-arm64": "1.1.1",
-    "@colbymchenry/codegraph-darwin-x64": "1.1.1",
-    "@colbymchenry/codegraph-linux-arm64": "1.1.1",
-    "@colbymchenry/codegraph-linux-x64": "1.1.1",
-    "@colbymchenry/codegraph-win32-arm64": "1.1.1",
-    "@colbymchenry/codegraph-win32-x64": "1.1.1"
+    "@colbymchenry/codegraph-darwin-arm64": "1.1.3",
+    "@colbymchenry/codegraph-darwin-x64": "1.1.3",
+    "@colbymchenry/codegraph-linux-arm64": "1.1.3",
+    "@colbymchenry/codegraph-linux-x64": "1.1.3",
+    "@colbymchenry/codegraph-win32-arm64": "1.1.3",
+    "@colbymchenry/codegraph-win32-x64": "1.1.3"
   },
   "files": [
     "npm-shim.js",