@lzehrung/codegraph 3.0.1 → 3.1.1

package/dist/util/worker-threads.js

@@ -16,4 +16,122 @@ export function resolveWorkerThreadCount(options) {
     }
     return Math.min(Math.max(os.availableParallelism() - 1, 1), max);
 }
+const NO_REQUIRE_ESM_FLAG = "--no-experimental-require-module";
+const REQUIRE_ESM_FLAGS = ["--experimental-require-module", NO_REQUIRE_ESM_FLAG];
+/**
+ * Host options that a worker thread must keep, so that it loads code the way its host does: preloads, resolution
+ * conditions, loaders, source maps, warning policy, and the module-loading feature switches. Node accepts only some
+ * options in a worker's `execArgv` and throws `ERR_WORKER_INVALID_EXEC_ARGV` for the rest. Node 22.16 and 24.15 both
+ * reject every V8 option (`--max-old-space-size`, `--stack-trace-limit`, `--expose-gc`, `--jitless`, ...) and every
+ * process-wide option (`--title`, `--openssl-config`, `--icu-data-dir`, `--report-on-fatalerror`, ...), and they
+ * reject `--cpu-prof-dir` and `--experimental-default-type`. A worker that is started with `--inspect-brk` or
+ * `--inspect-wait` stops until a debugger attaches, and `--cpu-prof` writes a profile per worker. Which options Node
+ * accepts changes between versions and `process.allowedNodeEnvironmentFlags` does not tell (it lists the rejected
+ * V8 and process-wide options too), so an option that is not listed here is not passed on, and an unknown future
+ * option can never make pool creation throw. Every listed option was started in a worker on Node 22.16 and 24.15.
+ */
+const WORKER_INHERITED_FLAGS = {
+    "--require": true,
+    "-r": true,
+    "--import": true,
+    "--conditions": true,
+    "-C": true,
+    "--loader": true,
+    "--experimental-loader": true,
+    "--enable-source-maps": true,
+    "--warnings": true,
+    "--no-warnings": true,
+    "--deprecation": true,
+    "--no-deprecation": true,
+    "--trace-deprecation": true,
+    "--throw-deprecation": true,
+    "--pending-deprecation": true,
+    "--trace-warnings": true,
+    "--disable-warning": true,
+    "--preserve-symlinks": true,
+    "--preserve-symlinks-main": true,
+    "--experimental-vm-modules": true,
+    "--experimental-strip-types": true,
+    "--experimental-transform-types": true,
+    "--experimental-detect-module": true,
+    "--no-experimental-detect-module": true,
+    "--experimental-import-meta-resolve": true,
+    "--experimental-require-module": true,
+    "--no-experimental-require-module": true,
+};
+/** The option name of an `execArgv` or `NODE_OPTIONS` token as Node reads it: without an `=value` part, and with `_`
+ * in a long option name read as `-` (`--experimental_require_module=true` is `--experimental-require-module`). */
+function optionName(token) {
+    const name = token.split("=", 1)[0] ?? token;
+    return name.startsWith("--") ? `--${name.slice(2).replaceAll("_", "-")}` : name;
+}
+/** Keeps the options of `execArgv` that a worker thread accepts and needs. An option owns the value tokens (those
+ * that do not start with `-`) that follow it, as in `--require ./preload.cjs`. */
+function inheritableExecArgv(execArgv) {
+    const kept = [];
+    let keeping = false;
+    for (const token of execArgv) {
+        if (token.startsWith("-")) {
+            const name = optionName(token);
+            keeping = Object.hasOwn(WORKER_INHERITED_FLAGS, name) && process.allowedNodeEnvironmentFlags.has(name);
+        }
+        if (keeping)
+            kept.push(token);
+    }
+    return kept;
+}
+/** Splits `NODE_OPTIONS` the way Node does: tokens are separated by spaces, and a double-quoted part may hold spaces
+ * and escape a character with a backslash. */
+function nodeOptionsTokens(nodeOptions) {
+    const tokens = [];
+    let current = "";
+    let inQuotes = false;
+    let pending = false;
+    for (let i = 0; i < nodeOptions.length; i += 1) {
+        const char = nodeOptions[i];
+        if (inQuotes && char === "\\" && i + 1 < nodeOptions.length) {
+            i += 1;
+            current += nodeOptions[i];
+        }
+        else if (char === '"') {
+            inQuotes = !inQuotes;
+            pending = true;
+        }
+        else if (char === " " && !inQuotes) {
+            if (pending || current)
+                tokens.push(current);
+            current = "";
+            pending = false;
+        }
+        else {
+            current += char;
+        }
+    }
+    if (pending || current)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * `execArgv` for the worker threads of a Piscina pool. Piscina's worker calls `require()` on its task module before
+ * it falls back to `import()`, and this package's workers are ES modules, so on Node 22 that first load runs through
+ * `require(esm)`. Terminating a worker thread while it is in that load aborts the whole process on Node 22.16
+ * (`FATAL ERROR: v8::Module::IsGraphAsync must be used on an instantiated module`), and `pool.destroy()` terminates
+ * every worker that has not finished starting. With `require(esm)` off, the `require()` fails at once and the
+ * `import()` after it can be interrupted safely.
+ *
+ * An explicit `execArgv` replaces the command-line options that a worker inherits, so this returns the host's options
+ * that {@link WORKER_INHERITED_FLAGS} lists (a host started with `node --require ./preload.cjs` still runs that preload
+ * in its workers), followed by `--no-experimental-require-module` when this Node knows it and the host has not chosen
+ * a require-module option itself. A worker re-reads `NODE_OPTIONS` from the environment, and its `execArgv` wins over
+ * it, so a require-module option in `NODE_OPTIONS` (for a preload that requires an ES module) counts as the host's
+ * choice too, and appending the flag then would override it.
+ */
+export function piscinaWorkerExecArgv() {
+    const execArgv = inheritableExecArgv(process.execArgv);
+    const hostChoseRequireEsm = [...execArgv, ...nodeOptionsTokens(process.env.NODE_OPTIONS ?? "")].some((token) => REQUIRE_ESM_FLAGS.includes(optionName(token)));
+    if (!hostChoseRequireEsm && process.allowedNodeEnvironmentFlags.has(NO_REQUIRE_ESM_FLAG)) {
+        execArgv.push(NO_REQUIRE_ESM_FLAG);
+    }
+    return execArgv;
+}
 //# sourceMappingURL=worker-threads.js.map

package/dist/util/worker-threads.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker-threads.js","sourceRoot":"","sources":["../../src/util/worker-threads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAWzB;kEACkE;AAClE,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;IACrC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QACjF,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;IAC3C,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC1F,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,oBAAoB,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"worker-threads.js","sourceRoot":"","sources":["../../src/util/worker-threads.ts"],"names":[],"mappings":"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"}

package/dist/worker/native-worker-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-worker-pool.d.ts","sourceRoot":"","sources":["../../src/worker/native-worker-pool.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEzF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAC;AAEvD,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAKF,wBAAgB,8BAA8B,CAAC,oBAAoB,SAA4B,GAAG,MAAM,CAEvG;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,CAAC,EAAE,MAAM,EAClB,oBAAoB,SAA4B,GAC/C,MAAM,CAMR;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,CAahD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAiB9E"}
+{"version":3,"file":"native-worker-pool.d.ts","sourceRoot":"","sources":["../../src/worker/native-worker-pool.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEzF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,CAAC;AAEvD,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAKF,wBAAgB,8BAA8B,CAAC,oBAAoB,SAA4B,GAAG,MAAM,CAEvG;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,CAAC,EAAE,MAAM,EAClB,oBAAoB,SAA4B,GAC/C,MAAM,CAMR;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,CAahD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAkB9E"}

package/dist/worker/native-worker-pool.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { Piscina } from "piscina";
-import { resolveWorkerThreadCount } from "../util/worker-threads.js";
+import { piscinaWorkerExecArgv, resolveWorkerThreadCount } from "../util/worker-threads.js";
 import { markWindowsProcessDrainRequired } from "../util/windows-process-drain.js";
 const HARD_MAX_THREADS = 64;
 const DEFAULT_NATIVE_THREAD_CAP = 8;
@@ -44,6 +44,7 @@ export function createNativeWorkerPool(opts) {
     markWindowsProcessDrainRequired();
     return new Piscina({
         filename: workerPath,
+        execArgv: piscinaWorkerExecArgv(),
         minThreads: 1,
         maxThreads: threads,
         maxQueue: opts?.maxQueue ?? threads * 4,

package/dist/worker/native-worker-pool.js.map

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

package/docs/mcp.md

@@ -20,7 +20,7 @@ codegraph server status --root /path/to/repo --json
 codegraph server stop --root /path/to/repo
 ```
 
-`server start` serializes lifecycle changes, launches `mcp serve`, waits for a same-root process and startup identity proved by a challenged `/health` response, then records the process at `.codegraph/server.json`. It defaults to `127.0.0.1:7331`; use `--host` explicitly for a non-loopback bind, `--replace` only to restart a live server for the same root, and `--startup-timeout-ms <1-86400000>` when a warmup needs more than the 15-second default.
+`server start` serializes lifecycle changes, launches `mcp serve`, waits for a same-root process and startup identity proved by a challenged `/health` response, then records the process at `.codegraph/server.json`. It defaults to `127.0.0.1:7331`; use `--host` explicitly for a non-loopback bind, `--replace` only to restart a live server for the same root, and `--startup-timeout-ms <1-86400000>` when the process needs more than the 15-second default to start answering `/health`. The index warmup runs in the background after that and does not count against the timeout.
 
 `server start --json` emits `status: "started"`, the registry fields, and `update`. `server status` retries challenged HTTP health checks and reports a verification remedy instead of removing metadata for an unreachable or identity-mismatched server. `server stop` removes only confirmed stale metadata or signals a Codegraph process whose proven health identity matches the registry.
 
@@ -32,14 +32,16 @@ Use `mcp serve` directly when another process manager owns the server:
 codegraph mcp serve --root /path/to/repo --port 7331
 ```
 
-Startup warms the base session cache by default now, matching the commands above. Pass `--no-warmup` for the old lazy startup, or `--warmup-symbols` to also build the detailed symbol graph before serving:
+The server answers `initialize` and `tools/list` as soon as it is serving, then builds the base session cache and the search index in the background (the default, `--warmup`). Pass `--warmup-symbols` to also build the detailed symbol graph in the background, or `--no-warmup` to build nothing up front:
 
 ```bash
 codegraph mcp serve --root . --stdio --no-warmup
 codegraph mcp serve --root . --port 7331 --warmup-symbols
 ```
 
-`--warmup` builds the base session cache before serving requests (the default). `--warmup-symbols` also builds the detailed symbol graph before serving requests. `--no-warmup` skips both and starts lazily.
+With `--no-warmup`, the first tool call that needs the index starts the build. In every mode, `search`, `explore`, `orient`, `get_file` with `includeGraphContext`, `review`, `packet_get`, `workspace_symbols`, and `impact` wait for a running build for at most `--index-wait-ms` (default 15000) and then answer `index_building`; every other tool waits for the index without a limit. See [Cold start and `index_building`](#cold-start-and-index_building).
+
+The server also watches the project for file changes and refreshes the index in the background. Pass `--no-watch` to turn that off; see [File watcher](#file-watcher).
 
 The shared HTTP endpoint is `http://127.0.0.1:7331/mcp`. HTTP binds to `127.0.0.1` by default; pass `--host <host>` only when another machine or container must reach it.
 
@@ -49,7 +51,9 @@ HTTP protocol sessions track last activity, cap concurrent legacy sessions (defa
 
 Each MCP server permits four concurrent tool calls by default across every HTTP request and protocol session; a saturated server returns a retryable busy error rather than queueing unbounded work. The programmatic server options `mcpToolConcurrency`, `httpBodyTimeoutMs`, and `mcpToolTimeoutMs` tune concurrency, the 30-second HTTP request-body deadline, and the 5-minute per-tool execution deadline; an HTTP body that misses its deadline receives `408 Request Timeout`, while an expired tool call is aborted and names its configured limit. Completed legacy requests refresh session activity before idle eviction is considered.
 
-Client cancellation returns promptly, but does not discard shared index or artifact work. A cancelled call continues to occupy its concurrency slot until its underlying operation settles, preventing a burst of abandoned requests from exceeding the configured resource bound; the MCP SDK aborts the individual in-flight HTTP request when its response socket closes without closing the shared protocol session. Shutdown rejects new calls and waits for active work before invalidating shared session resources.
+`mcpIndexWaitMs` (CLI `--index-wait-ms`) bounds only the wait of those tools for an index build, not the tool call itself; see [Cold start and `index_building`](#cold-start-and-index_building).
+
+Client cancellation returns promptly, but does not discard shared index or artifact work. A cancelled call continues to occupy its concurrency slot until its underlying operation settles, preventing a burst of abandoned requests from exceeding the configured resource bound; the MCP SDK aborts the individual in-flight HTTP request when its response socket closes without closing the shared protocol session. Shutdown rejects new calls and waits for active work, for the startup warmup, and for every index load that a call started, including one whose call stopped waiting or failed, before invalidating shared session resources.
 
 Use stdio for a client-owned subprocess. Use HTTP for one long-running codegraph process per repository, then point every MCP-capable IDE, terminal, or agent client at the same local URL. Exact config keys vary by client, but the MCP settings should use HTTP/Streamable HTTP transport plus the `/mcp` URL instead of a `command`/`args` stdio launch.
 
@@ -67,6 +71,8 @@ On Windows, installed-package servers map the verified native addon from `%LOCAL
 
 The published CLI and MCP runtime is a self-contained bundle rather than a set of lazy content-hashed chunks. This prevents an in-place package upgrade from deleting code that an already running server has not loaded yet; restart the client after an upgrade to select the new runtime.
 
+A server that keeps running through an upgrade can still need a module that the upgrade removed. The tool call then returns `isError: true` with a message that the codegraph package changed on disk and the MCP server must be restarted, in place of Node's `Cannot find module` text.
+
 Run `codegraph doctor` in the installed release to inspect `native.origin`, `native.update`, and any stale npm retirement siblings. `updateSafeForCurrentProcess` describes only the process running doctor; it does not prove that no other process or filesystem service holds a package file.
 
 ## Tools
@@ -86,7 +92,7 @@ The server exposes the same bounded primitives as the CLI and library session la
 - `get_file`: bounded project file read with `offset`/`limit` line pagination, exact `number<TAB>line` content, and optional direct graph context.
 - `get_symbol`: resolve a stable search or explain handle.
 - `goto`: definition lookup by portable handle, qualified `file::symbol` path, or file position.
-- `refs`: references by portable handle, qualified `file::symbol` path, or file position. Collection `limit` defaults to 25 and caps at 500 (`DEFAULT_MCP_COLLECTION_LIMIT` / `MAX_MCP_COLLECTION_LIMIT` in `src/mcp/tools.ts`). The response pairs `references` with `limit`, `totalSeen`, `truncated`, and `omitted`; `truncated` is exact because the lookup probes one reference past the limit. When truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full corpus-wide counts. Successful results also include `referenceCoverage`: `complete` means every statically linked candidate known to the current index was checked, while `partial` identifies one or more of `parser_degraded`, `unresolved_import`, `strategy_unavailable`, `name_equivalence_unavailable`, and `truncated` reasons, in that order, plus any known affected files. `strategy_unavailable` means that an applicable reference strategy could not prove all candidate sites, such as when a required scan did not run or a member access had an unknown receiver type. `name_equivalence_unavailable` means that a name-equivalence decision could not be verified. This scope does not certify unknown dynamic or bare imports. Resolved named and default import declaration references use top-level `importBinding` to identify `imported` source-name tokens and distinct `local` alias/default tokens.
+- `refs`: references by portable handle, qualified `file::symbol` path, or file position. Collection `limit` defaults to 25 and caps at 500 (`DEFAULT_MCP_COLLECTION_LIMIT` / `MAX_MCP_COLLECTION_LIMIT` in `src/mcp/tools.ts`). The response pairs `references` with `limit`, `totalSeen`, `truncated`, and `omitted`; `truncated` is exact because the lookup probes one reference past the limit. When truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full corpus-wide counts. Successful results also include `referenceCoverage`: `complete` means every statically linked candidate known to the current index was checked, while `partial` identifies one or more of `parser_degraded`, `parse_error`, `unresolved_import`, `strategy_unavailable`, `name_equivalence_unavailable`, and `truncated` reasons, in that order, plus any known affected files. For non-SCSS definitions, any ERROR/MISSING region in a candidate or scanned file makes coverage partial regardless of its contents. `strategy_unavailable` means that an applicable reference strategy could not prove all candidate sites, such as when a required scan did not run or a member access had an unknown receiver type. `name_equivalence_unavailable` means that a name-equivalence decision could not be verified. This scope does not certify unknown dynamic or bare imports. Resolved named and default import declaration references use top-level `importBinding` to identify `imported` source-name tokens and distinct `local` alias/default tokens.
 - `file_deps`, `path`: dependency navigation; pass `direction: "deps"` or `"rdeps"` to `file_deps`. `file_deps` uses the same collection `limit` default 25 / max 500 as `refs`. `file_deps.file` accepts a portable symbol handle or qualified symbol path and traverses its declaring file. `dependencies`/`reverseDependencies` carry the same `limit`/`totalSeen`/`truncated`/`omitted` metadata as `refs`, so a capped prefix is always distinguishable from a complete result; when truncated, `totalSeen` and `omitted` are lower bounds from the bounded probe, not full graph-wide counts.
 - `impact`: compact git-range impact analysis (`format: "compact"`, `impacted`, diagnostics). Bounded by default.
 - `review`: git-range review report (`riskSummary`, `reviewTasks`, candidate tests). MCP is a bounded transport: `projectFiles`, `changedFiles` (including per-file `symbols`), `graphDelta`, and `candidateTests` are capped at the response's `limits` with exact per-collection `omittedCounts`, and `summary` totals stay accurate for the full report. Library callers that need the complete unbounded report call `buildReviewReport` directly instead of going through MCP.
@@ -113,20 +119,86 @@ For MCP `explore`, `includeSource` defaults to `false`: source-bearing packets d
 
 ## Session lifecycle
 
-MCP keeps one codegraph session warm for the configured root. That makes follow-up calls cheaper than separate CLI invocations. `mcp serve` warms the base session cache during startup by default (matching the old `--warmup` flag), so a cold discovery-and-build cost lands on process startup rather than the first `tools/call`. Pass `--no-warmup` to start lazily instead, or `--warmup-symbols` to also build the detailed symbol graph before serving.
+MCP keeps one codegraph session warm for the configured root. That makes follow-up calls cheaper than separate CLI invocations. `mcp serve` builds the base session cache and the search index in the background once it is serving, so a cold discovery-and-build cost no longer delays `initialize` or `tools/list`. Pass `--no-warmup` to build only when a tool call needs the index, or `--warmup-symbols` to also build the detailed symbol graph.
 On the first `tools/call`, codegraph can emit `notifications/message` and, when the request includes `_meta.progressToken`, `notifications/progress` before the final result. Stdio carries them inline, and modern Streamable HTTP clients that accept `text/event-stream` receive them as a stream.
 
-Because startup now warms by default, a client's startup/readiness timeout - not just its per-request timeout - needs to cover a cold build on a large repository; the `startup_timeout_ms = 20000` Codex example below can be too short for a first run against a large tree. Raise `startup_timeout_ms` for large repositories, or pass `--no-warmup` to keep process startup instant and shift that cost back to the first `tools/call` (clients that enforce per-request timeouts should then send `_meta.progressToken` so they can keep a slow first request alive instead of timing it out).
+The `startup_timeout_ms = 20000` Codex example below is enough for a large repository: the server answers `initialize` at once and no longer builds before it serves. A client's per-request timeout is what a cold build can exceed, and [Cold start and `index_building`](#cold-start-and-index_building) keeps each request inside it.
 
 Text and hybrid searches reuse a prepared handle for `.codegraph/cache/index-v1/search-v1.sqlite` and cache identical responses by snapshot identity and request options. A detected refresh or explicit `refresh_index` closes the handle and clears cached responses before the next snapshot.
 
 If the sidecar is busy or unavailable, MCP uses the same exact in-memory matcher. [How it works](./how-it-works.md#cache-and-session-behavior) explains the search cache.
 
-Use `refresh_index` to rebuild the snapshot, reset SQLite artifact state, or recover after a change burst exceeds automatic limits. Concurrent refresh, artifact build, and automatic SQLite artifact refresh operations serialize per MCP server so each bundle is written consistently. With write access, `query_sqlite` refreshes codegraph SQLite artifacts after small edits; otherwise it refuses stale rows. `artifact_build` refuses stale indexes, so run `refresh_index` after large change bursts.
+Use `refresh_index` to rebuild the snapshot, reset SQLite artifact state, or recover after a change burst exceeds automatic limits (the [file watcher](#file-watcher) rebuilds in the background after such a burst unless `--no-watch` is set). Concurrent refresh, artifact build, automatic SQLite artifact refresh, and file watcher refresh operations serialize per MCP server, so each bundle is written consistently and no two index builds overlap. With write access, `query_sqlite` refreshes codegraph SQLite artifacts after small edits; otherwise it refuses stale rows. `artifact_build` refuses stale indexes, so run `refresh_index` after large change bursts.
 A session created with `freshness: { policy: "manual" }` (only possible when a library caller passes its own session to `createCodegraphMcpHandlers`) reports `freshness.state: "unchecked"`. It records no file signatures, so it cannot check a SQLite artifact or build a new one: `query_sqlite` rejects a stale artifact with that explanation, and `artifact_build` fails. Rebuild the artifact from a session whose policy is `check` or `auto`, for example with `codegraph artifact --sqlite`.
 `get_file` reads live bytes from disk after path confinement. It does not require a fresh index; only an explicit `includeGraphContext: true` checks indexed freshness and adds direct graph context, so returned file bytes and `totalLines` remain live even when `freshness` reports stale context.
 Tool schemas are flat JSON objects for broad client compatibility; argument combinations such as `refs` handle-vs-position mode are validated by the server. Legacy paired names (`callers`, `callees`, `supertypes`, `subtypes`, `deps`, and `rdeps`) remain accepted by `tools/call` as aliases, but only the unified tools appear in `tools/list`.
 
+### Cold start and `index_building`
+
+The first run on a large project builds the index from scratch, which can take longer than the 30 seconds that MCP clients commonly allow for one request. The main read tools stay inside that window:
+
+- `initialize` and `tools/list` answer at once on stdio and HTTP. The warmup starts after the server is serving and runs in the background; the HTTP server listens before it ends.
+- `search`, `explore`, `orient`, `get_file` with `includeGraphContext`, `review`, `packet_get`, `workspace_symbols`, and `impact` wait for the builds they read for at most `--index-wait-ms` (default 15000). The warmup and concurrent calls share each build, so a call joins one that is running instead of starting another.
+- Every other tool, such as `goto`, `refs`, `calls`, `file_deps`, `query_sqlite`, `refresh_index`, and `artifact_build`, waits for the index without a limit, as it did before. A client that calls one of them during a cold build needs a request timeout that covers the build.
+- `get_file` without `includeGraphContext` never waits: it reads the file from disk under the same root confinement as always. A `review` of a range without a changed file is answered from git and waits for nothing.
+
+When one of these tools waits at all, it first waits for a build that is running, because it checks freshness against it, then for what it reads:
+
+| Tool                | Reads                                                                                                                                                                                   |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search`            | The project index. `hybrid`, `symbol`, and `graph` also read the symbol graph, and `hybrid` and `text` the search index. A `path` search without `from` lists files and reads no index. |
+| `explore`           | What a `hybrid` `search` reads. With `includeSource` (off by default over MCP) and `maxPackets` above 0, also the detailed symbol graph and the duplicate analysis.                     |
+| `orient`            | The project index.                                                                                                                                                                      |
+| `workspace_symbols` | The project index.                                                                                                                                                                      |
+| `impact`            | The project index.                                                                                                                                                                      |
+| `get_file`          | The project index, only with `includeGraphContext`.                                                                                                                                     |
+| `review`            | The project index and the duplicate analysis, for a range with a changed file.                                                                                                          |
+| `packet_get`        | The detailed symbol graph, and for a file or symbol target the duplicate analysis (a SQL object or an unresolved target needs none). A `review:` target reads no session build.         |
+
+A call of these tools that has waited `--index-wait-ms` without its builds ending returns a normal result, not an error, and the builds continue:
+
+```json
+{
+  "status": "index_building",
+  "tool": "search",
+  "message": "Codegraph is still building the index for this project (Building search index, 19s so far). The build continues in the background; call 'search' again to wait for it.",
+  "retryAfterMs": 1000,
+  "waitedMs": 15003,
+  "progress": { "activity": "Building search index", "elapsedMs": 19100 }
+}
+```
+
+- Call the same tool again. The retry joins the builds that run, waits for what is left of them, up to the same budget, and then returns the normal result.
+- `progress.activity` names what is running, such as `Indexing files` or `Preparing duplicate analysis`. `current` and `total` appear only while the work has a measurable total, such as files parsed.
+- A cancelled request stops waiting at once; the builds are not cancelled.
+- When the session is replaced while a call waits, because a file changed, the file watcher refreshed, or `refresh_index` ran, the call builds what it reads again inside the same budget, up to three times in all.
+- The budget is a timer on the server's event loop. The builds hand the loop back every few milliseconds, between files, so the answer normally arrives within a second or two of the budget. A single large file can hold the loop longer, and a call also runs its own work once its builds end (a `review` of a large diff, for example), so keep the budget at least ten seconds below the client's timeout.
+
+Choose a request timeout longer than `--index-wait-ms`: the default of 15 seconds leaves a client that allows 30 fifteen seconds for the work that follows the builds; for a project where that is not enough, lower the budget. For a client that allows less, lower the budget (`--index-wait-ms 8000`); for one that allows more, raise it, or pass `--index-wait-ms 0` to make these tools wait for as long as the builds take too (the per-tool deadline still applies). Library callers set `mcpIndexWaitMs`. The setting belongs to the server: `codegraph.config.json` has no key for it.
+
+### File watcher
+
+`mcp serve` and `server start` watch the project root while the server runs, unless you pass `--no-watch`. The watcher is a hint: the freshness check that every index-backed tool call runs stays the authority, so a missed event costs speed, never correctness.
+
+- A file event outside the directories that default discovery ignores (`node_modules`, `.git`, `.codegraph`, `dist`, `build`, `target`, Python virtual environments, and the others listed under [Project config](./cli.md#project-config)) clears the cached freshness result at once. The next query then runs the full check instead of reusing a result that can be up to 5 seconds old. A tree that `discovery.includeGlobs` re-includes stays ignored here, so its edits wait for the freshness check. A cache directory that `--cache-dir`, `CODEGRAPH_CACHE_DIR`, or an absolute `cache.location` placed inside the project is ignored too, because the server writes there itself. The two are compared as real paths, so a project root or cache directory spelled through a symlink or junction still matches.
+- 500 ms after the last event, and at least 5 seconds after the previous background refresh ended, the server runs the freshness check and rebuilds the index in the background. Each new event restarts the 500 ms wait, so no refresh starts while events still arrive. A query that arrives during the rebuild waits for it, as on a cold start.
+- The background rebuild also covers a change burst above the automatic refresh limits (50 files or 2 MB, for example a branch switch), which a query alone reports as `stale` until `refresh_index`. A session that cannot read its configuration keeps its snapshot, as it does without the watcher.
+- One refresh runs at a time, and events during it schedule exactly one more. A refresh takes its turn in the same queue as `refresh_index`, `artifact_build`, and the automatic SQLite artifact refresh, so `refresh_index` waits for a rebuild that is running instead of starting a second one beside it. A refresh that still waits for its turn when a newer event arrives, or when the watcher pauses, gives the turn up: the burst that the event belongs to starts its own refresh once it settles. On Linux, each read of the file list for the per-directory watches takes its turn in that queue as well, so the first read of a server that started with `--no-warmup` cannot overlap a `refresh_index`. A failed refresh writes `[codegraph] watch refresh failed: <message>` to stderr and leaves the freshness check as it was.
+- When the server shuts down (stdin closes, or the HTTP server closes), it stops the watches and timers at once, then waits for a refresh that is running, for a read of the file list that has started, for the startup warmup, and for every index load that the warmup or a call started, including one whose call stopped waiting and one that ran beside a load that failed, before it releases the session, so that none writes the cache or the file signatures afterwards.
+- After 30 minutes without a tool call, the server closes every watch and cancels pending refreshes, including one that still waits for its turn behind a `refresh_index` or an `artifact_build`. The next tool call reopens the watches and clears the cached freshness result first, so the check sees every edit made during the pause. This matters most for `codegraph server start`, whose process lives until `server stop`.
+- Windows and macOS use one recursive watch on the root. Other platforms use one watch per directory that holds a discovered file, because Node's recursive watching on Linux walks the whole tree, `node_modules` included, and can exhaust inotify watches.
+- A watch that is lost with its directory (a deleted project root on Windows, a removed and recreated directory on Linux) closes at the first event that names the directory and counts as a change; the next refresh opens it again once the directory exists.
+- On Linux, a directory that appears later gets its watch from the event that reports it, and a directory that a file list named keeps its watch after the list stops naming it because its last source file was deleted. Either watch, and the ones above it, stay until the directory is removed, even while the directory holds only a placeholder such as `.gitkeep` or other directories, so that a source file added later is seen. At most 128 watches that no file list names stay open at once, the ones above those directories included. Past that, an event opens no watch, and the next refresh closes the watches that were opened longest ago.
+- If the system runs out of watches or file descriptors, the server logs `file watching disabled: <code>` and relies on the freshness check alone. Network drives and some container mounts may not deliver events; the freshness check still applies.
+- With `--no-warmup`, the watches open on the first tool call. Handlers from `createCodegraphMcpHandlers` and servers started with a caller-supplied `session` are not watched.
+
+The CLI exposes only `--no-watch`. Library callers of `serveCodegraphMcp` can tune the watcher (see the [library API](./library-api.md)):
+
+- `watch`: `false` turns the watcher off. Defaults to on.
+- `watchDebounceMs`: quiet time after the last event. Defaults to `500`.
+- `watchMinRefreshIntervalMs`: minimum time from the end of one background refresh to the start of the next. Defaults to `5000`.
+- `watchIdleMs`: time without a tool call before the watcher pauses; `0` never pauses. Defaults to `1800000` (30 minutes).
+
 ### `workspace_symbols`
 
 Call `workspace_symbols` with flat fields `query`, optional `kinds`, `exportedOnly`, `includeImports`, `fileGlob`, and `limit`. Imports are excluded by default; `fileGlob` matches project-relative paths, the default limit is 50, and both the schema and handler enforce a maximum of 500.
@@ -187,6 +259,8 @@ Only resolved, indexed `extends` and `implements` relationships are returned. Im
 
 Call `get_file` with a project-relative `file`. `offset` is the 1-based first line, `limit` is the maximum returned lines, and `maxBytes` bounds unnumbered raw page text including its line separators; defaults are `1`, `2000`, and `80000`, with output-page caps of `10000` lines and `500000` bytes. A separate 16 MiB hard input-size limit rejects larger raw reads and structural text-config summaries before unbounded I/O, bounding complete-stream binary/UTF-8 validation and total-line counting rather than returned page size.
 
+`file` is required and must be a project-relative path string. A missing, `null`, or non-string value is rejected with JSON-RPC `-32602` and `Invalid parameters for get_file: file: expected a project-relative file path string, received null`.
+
 ```json
 {
   "file": "src/auth.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzehrung/codegraph",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -82,20 +82,20 @@
   "license": "MIT",
   "description": "Multi-language repository map for agents and humans: MCP tools, dependency graphs, symbol indexes, impact review, and bounded source evidence.",
   "dependencies": {
-    "@lzehrung/codegraph-core": "3.0.1",
-    "@lzehrung/codegraph-native": "^2.0.1",
-    "@modelcontextprotocol/node": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@lzehrung/codegraph-core": "3.1.1",
+    "@lzehrung/codegraph-native": "^2.1.1",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@modelcontextprotocol/server": "^2.3.1",
     "jsonc-parser": "^3.3.1",
     "picomatch": "^4.0.3",
     "piscina": "^4.9.4",
     "smol-toml": "^1.9.1",
     "tinyglobby": "^0.2.17",
     "tsconfig-paths": "^4.2.0",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "overrides": {
-    "@hono/node-server": "^2.0.5",
+    "@hono/node-server": "^2.1.3",
     "@emnapi/core": "1.11.3",
     "@emnapi/runtime": "1.11.3"
   }