@lzehrung/codegraph 3.0.1 → 3.1.0

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":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAC;AAenF,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAEpC,MAAM,UAAU,8BAA8B,CAAC,oBAAoB,GAAG,EAAE,CAAC,oBAAoB,EAAE;IAC7F,OAAO,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,SAAkB,EAClB,oBAAoB,GAAG,EAAE,CAAC,oBAAoB,EAAE;IAEhD,OAAO,wBAAwB,CAAC;QAC9B,SAAS;QACT,YAAY,EAAE,8BAA8B,CAAC,oBAAoB,CAAC;QAClE,GAAG,EAAE,gBAAgB;KACtB,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAkB;IAC5C,OAAO,8BAA8B,CAAC,SAAS,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,gEAAgE;IAChE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC;IAClE,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3C,6EAA6E;IAC7E,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,0BAA0B,CAAC,CAAC;IAC3F,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IACjD,MAAM,IAAI,KAAK,CACb,8CAA8C,OAAO,SAAS,UAAU,KAAK;QAC3E,2EAA2E,CAC9E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAA8B;IACnE,MAAM,YAAY,GAAG,IAAI,EAAE,UAAU,CAAC;IACtC,MAAM,OAAO,GACX,OAAO,YAAY,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC;QACnF,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACvC,CAAC,CAAC,gBAAgB,CAAC;IACvB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IACrE,MAAM,UAAU,GAAG,uBAAuB,EAAE,CAAC;IAC7C,+BAA+B,EAAE,CAAC;IAClC,OAAO,IAAI,OAAO,CAAC;QACjB,QAAQ,EAAE,UAAU;QACpB,QAAQ,EAAE,qBAAqB,EAAE;QACjC,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,OAAO;QACnB,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,OAAO,GAAG,CAAC;QACvC,WAAW,EAAE,MAAM;QACnB,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;KAC3E,CAAC,CAAC;AACL,CAAC"}

package/docs/mcp.md

@@ -41,6 +41,8 @@ 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.
 
+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.
 
 Stdio servers exit when the client closes stdin, when an IPC parent disconnects, or after `--idle-timeout-ms` of inactivity (default 30 minutes; `0` disables the idle timer). The CLI option is valid only with `--stdio`; HTTP transport has its own 30-minute idle session eviction.
@@ -86,7 +88,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.
@@ -122,11 +124,34 @@ Text and hybrid searches reuse a prepared handle for `.codegraph/cache/index-v1/
 
 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`.
 
+### 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 and for a read of the file list that has started before it releases the session, so that neither 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzehrung/codegraph",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "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.0",
+    "@lzehrung/codegraph-native": "^2.1.0",
+    "@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"
   }