codegraph-java 0.1.0

package/dist/mcp/engine.d.ts

@@ -0,0 +1,125 @@
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link CodeGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+import { ToolHandler } from './tools';
+export interface MCPEngineOptions {
+    /**
+     * Whether to start the file watcher when initializing. Daemon and direct
+     * modes both want this true; tests may set it false to keep the engine
+     * 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
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+export declare class MCPEngine {
+    private cg;
+    private toolHandler;
+    private projectPath;
+    private initPromise;
+    private lastRetrySubScanAt;
+    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
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath: string): void;
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath(): string | null;
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler(): ToolHandler;
+    /** Whether the default project's CodeGraph is open. */
+    hasDefaultCodeGraph(): boolean;
+    /**
+     * Walk up from `searchFrom` to find the nearest `.codegraph/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    ensureInitialized(searchFrom: string): Promise<void>;
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom: string): void;
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop(): void;
+    private doInitialize;
+    /** One stderr line when the default project came from the down-scan (#1606). */
+    private logSubprojectAdoption;
+    /**
+     * Start file watching on the active CodeGraph instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    private startWatching;
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    private catchUpSync;
+}
+/**
+ * Parse and clamp the CODEGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+export declare function parseDebounceEnv(raw: string | undefined): number | undefined;
+//# sourceMappingURL=engine.d.ts.map

package/dist/mcp/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAetC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,WAAW,CAAc;IAIjC,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,WAAW,CAA8B;IAGjD,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,MAAM,CAAS;IAGvB,OAAO,CAAC,SAAS,CAA0B;gBAE/B,IAAI,GAAE,gBAAqB;IAKvC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK7C,0EAA0E;IAC1E,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,yEAAyE;IACzE,cAAc,IAAI,WAAW;IAI7B,uDAAuD;IACvD,mBAAmB,IAAI,OAAO;IAI9B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAmC7C;;;OAGG;IACH,IAAI,IAAI,IAAI;YAiBE,YAAY;IA2C1B,gFAAgF;IAChF,OAAO,CAAC,qBAAqB;IAO7B;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAuDrB;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E"}

package/dist/mcp/engine.js

@@ -0,0 +1,392 @@
+"use strict";
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link CodeGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+exports.parseDebounceEnv = parseDebounceEnv;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const directory_1 = require("../directory");
+const sync_1 = require("../sync");
+const tools_1 = require("./tools");
+const query_pool_1 = require("./query-pool");
+// Lazy-load the heavy CodeGraph chain (sqlite + query/graph/context layers) OFF
+// the MCP startup path. It's only needed once a tool actually opens a project —
+// not to answer initialize/tools-list — so deferring it lets `serve --mcp` (and
+// the daemon it spawns) bind + register tools in ~Node-startup time instead of
+// ~800ms, closing the "No such tool available" cold-start race that made headless
+// agents flounder. require() is sync + cached on the CommonJS build.
+const loadCodeGraph = () => require('../index').default;
+/** How often the per-tool-call retry may re-run the sub-project down-scan. */
+const RETRY_SUBSCAN_TTL_MS = 5_000;
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+class MCPEngine {
+    cg = null;
+    toolHandler;
+    // Project root we resolved to. Null until `ensureInitialized` succeeds
+    // (or null forever if no .codegraph/ ever turned up — that's a valid
+    // state for the engine, since cross-project queries still work).
+    projectPath = null;
+    // Set on first `ensureInitialized` so subsequent sessions don't redo work.
+    initPromise = null;
+    // Throttle for the retry path's sub-project down-scan (#1606) — the scan is
+    // bounded but shouldn't run on every tool call in the no-default state.
+    lastRetrySubScanAt = 0;
+    watcherStarted = false;
+    opts;
+    closed = false;
+    // Off-loop read-tool pool (daemon mode only). Created lazily once the default
+    // project is open — workers each hold their own WAL read connection.
+    queryPool = null;
+    constructor(opts = {}) {
+        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false };
+        this.toolHandler = new tools_1.ToolHandler(null);
+    }
+    /**
+     * 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.
+     */
+    maybeStartPool(root) {
+        if (!this.opts.queryPool || this.queryPool || this.closed)
+            return;
+        const size = (0, query_pool_1.resolvePoolSize)(process.env.CODEGRAPH_QUERY_POOL_SIZE, os.cpus().length);
+        if (size <= 0) {
+            process.stderr.write('[CodeGraph MCP] Query pool disabled (CODEGRAPH_QUERY_POOL_SIZE=0); serving reads in-process.\n');
+            return;
+        }
+        try {
+            this.queryPool = new query_pool_1.QueryPool({ root, size });
+            this.toolHandler.setQueryPool(this.queryPool);
+            process.stderr.write(`[CodeGraph MCP] Query pool: up to ${size} worker thread(s) for concurrent reads.\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] Query pool unavailable (${msg}); serving reads in-process.\n`);
+            this.queryPool = null;
+        }
+    }
+    /**
+     * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+     * project path (from the `--path` CLI flag) without yet opening it. This
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath) {
+        this.projectPath = projectPath;
+        this.toolHandler.setDefaultProjectHint(projectPath);
+    }
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath() {
+        return this.projectPath;
+    }
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler() {
+        return this.toolHandler;
+    }
+    /** Whether the default project's CodeGraph is open. */
+    hasDefaultCodeGraph() {
+        return this.toolHandler.hasDefaultCodeGraph();
+    }
+    /**
+     * Walk up from `searchFrom` to find the nearest `.codegraph/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    async ensureInitialized(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultCodeGraph())
+            return;
+        if (this.initPromise) {
+            try {
+                await this.initPromise;
+            }
+            catch { /* let caller retry */ }
+            return;
+        }
+        this.initPromise = this.doInitialize(searchFrom).finally(() => {
+            this.initPromise = null;
+        });
+        try {
+            await this.initPromise;
+        }
+        catch {
+            // Init errors are logged inside `doInitialize`; falling through here
+            // matches MCPServer's previous "retry on next tool call" behavior.
+        }
+    }
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultCodeGraph())
+            return;
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        // Same resolution `doInitialize` used: up-walk, then the bounded workspace
+        // down-scan (#1606) — this retry is exactly the path that picks up a
+        // project (root or child) `cg init`'d after the server started. The
+        // down-scan is throttled so the persistent no-default state doesn't pay a
+        // directory walk on every tool call; the up-walk always runs.
+        const scanDue = Date.now() - this.lastRetrySubScanAt >= RETRY_SUBSCAN_TTL_MS;
+        const res = (0, directory_1.resolveServerRoot)(searchFrom, { subprojectScan: scanDue });
+        if (scanDue) {
+            this.lastRetrySubScanAt = Date.now();
+            if (!res.root)
+                this.toolHandler.setKnownSubprojects(res.candidates, searchFrom);
+        }
+        const resolvedRoot = res.root;
+        if (!resolvedRoot)
+            return;
+        if (res.viaSubScan)
+            this.logSubprojectAdoption(searchFrom, resolvedRoot);
+        try {
+            // Close any previously failed instance to avoid leaking resources.
+            if (this.cg) {
+                try {
+                    this.cg.close();
+                }
+                catch { /* ignore */ }
+                this.cg = null;
+            }
+            this.cg = loadCodeGraph().openSync(resolvedRoot);
+            this.projectPath = resolvedRoot;
+            this.toolHandler.setDefaultCodeGraph(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+            this.maybeStartPool(resolvedRoot);
+        }
+        catch {
+            // Still failing — caller will try again on the next tool call.
+        }
+    }
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Detach + terminate the worker pool first so no tool call routes to a
+        // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
+        this.toolHandler.setQueryPool(null);
+        if (this.queryPool) {
+            void this.queryPool.destroy();
+            this.queryPool = null;
+        }
+        this.toolHandler.closeAll();
+        if (this.cg) {
+            try {
+                this.cg.close();
+            }
+            catch { /* ignore */ }
+            this.cg = null;
+        }
+    }
+    async doInitialize(searchFrom) {
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        // Up-walk first; when nothing is indexed at or above searchFrom, a bounded
+        // down-scan may adopt a SINGLE indexed sub-project as the default (#1606 —
+        // the workspace-container shape where only children are indexed). Zero or
+        // several candidates → no default project, but SAY so (#1607): the silent
+        // variant of this state read as "CodeGraph is broken" and was diagnosable
+        // only by knowing to look for a missing ~/.codegraph/daemons/ entry.
+        const res = (0, directory_1.resolveServerRoot)(searchFrom);
+        const resolvedRoot = res.root;
+        if (!resolvedRoot) {
+            // Sessions may still discover a project later via roots/list, and the
+            // per-call retry re-resolves — this state is recoverable, hence stderr
+            // (not a failure) + candidates surfaced through the tool-call error.
+            this.projectPath = searchFrom;
+            this.toolHandler.setKnownSubprojects(res.candidates, searchFrom);
+            process.stderr.write(`[CodeGraph MCP] No .codegraph/ at or above ${searchFrom}: no default project, live sync disabled.\n`);
+            if (res.candidates.length > 0) {
+                const rels = res.candidates.map((c) => path.relative(searchFrom, c) || '.');
+                process.stderr.write(`[CodeGraph MCP] Indexed sub-projects found: ${rels.join(', ')}. Pass \`projectPath\` per call, or launch with --path.\n`);
+            }
+            return;
+        }
+        if (res.viaSubScan)
+            this.logSubprojectAdoption(searchFrom, resolvedRoot);
+        this.projectPath = resolvedRoot;
+        try {
+            this.cg = await loadCodeGraph().open(resolvedRoot);
+            this.toolHandler.setDefaultCodeGraph(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+            this.maybeStartPool(resolvedRoot);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] Failed to open project at ${resolvedRoot}: ${msg}\n`);
+        }
+    }
+    /** One stderr line when the default project came from the down-scan (#1606). */
+    logSubprojectAdoption(searchFrom, root) {
+        const rel = path.relative(searchFrom, root) || root;
+        process.stderr.write(`[CodeGraph MCP] No .codegraph/ at ${searchFrom}; adopted the single indexed sub-project ${rel} as the default project.\n`);
+    }
+    /**
+     * Start file watching on the active CodeGraph instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    startWatching() {
+        if (!this.cg || this.watcherStarted || !this.opts.watch)
+            return;
+        const disabledReason = (0, sync_1.watchDisabledReason)(this.projectPath ?? process.cwd());
+        if (disabledReason) {
+            process.stderr.write(`[CodeGraph MCP] File watcher disabled — ${disabledReason}. ` +
+                `The graph will not auto-update; run \`cg sync\` (or install the git sync hooks via \`cg init\`) to refresh.\n`);
+            this.watcherStarted = true;
+            return;
+        }
+        // Optional override for the debounce window via env var (issue #403).
+        // Useful for workspaces with bursty writes (formatter-on-save chains,
+        // large generated outputs) where the 2s default fires too often. Clamped
+        // to [100ms, 60s]; out-of-range / non-numeric values fall back to the
+        // FileWatcher default. We log the active value so it's discoverable.
+        const debounceMs = parseDebounceEnv(process.env.CODEGRAPH_WATCH_DEBOUNCE_MS);
+        if (debounceMs !== undefined) {
+            process.stderr.write(`[CodeGraph MCP] File watcher debounce: ${debounceMs}ms (CODEGRAPH_WATCH_DEBOUNCE_MS)\n`);
+        }
+        const started = this.cg.watch({
+            debounceMs,
+            onSyncComplete: (result) => {
+                if (result.filesChanged > 0) {
+                    process.stderr.write(`[CodeGraph MCP] Auto-synced ${result.filesChanged} file(s) in ${result.durationMs}ms\n`);
+                }
+            },
+            onSyncError: (err) => {
+                process.stderr.write(`[CodeGraph MCP] Auto-sync error: ${err.message}\n`);
+            },
+            onDegraded: (reason) => {
+                // Live watching gave up permanently (watch-resource exhaustion or a
+                // write lock held past the retry budget). Say so loudly and ONCE — the
+                // graph will no longer auto-update, so a long-running MCP session must
+                // not keep assuming it's fresh. The reason already names the remedy
+                // (`cg sync` / git sync hooks).
+                process.stderr.write(`[CodeGraph MCP] File watcher degraded — ${reason}\n`);
+            },
+        });
+        this.watcherStarted = true;
+        if (started) {
+            process.stderr.write('[CodeGraph MCP] File watcher active — graph will auto-sync on changes\n');
+        }
+        else {
+            process.stderr.write('[CodeGraph MCP] File watcher unavailable on this platform — run `cg sync` to refresh the graph after changes.\n');
+        }
+    }
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    catchUpSync() {
+        const cg = this.cg;
+        if (!cg)
+            return;
+        const p = cg
+            .sync()
+            .then((result) => {
+            const changed = result.filesAdded + result.filesModified + result.filesRemoved;
+            if (changed > 0) {
+                process.stderr.write(`[CodeGraph MCP] Caught up ${changed} file(s) changed since last run\n`);
+            }
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] Catch-up sync failed: ${msg}\n`);
+        });
+        this.toolHandler.setCatchUpGate(p);
+    }
+}
+exports.MCPEngine = MCPEngine;
+/**
+ * Parse and clamp the CODEGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+function parseDebounceEnv(raw) {
+    if (!raw || !raw.trim())
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return undefined;
+    if (n < 100 || n > 60000)
+        return undefined;
+    return n;
+}
+//# sourceMappingURL=engine.js.map

package/dist/mcp/engine.js.map

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