@aroman22/codegraph-vba 1.3.3

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

@@ -0,0 +1,42 @@
+import type { DaemonRecord, StopResult } from './daemon-registry';
+/** Sentinel option values (not real roots, so they can't collide with a project path). */
+export declare const STOP_ALL = "__stop_all__";
+export declare const CANCEL = "__cancel__";
+export interface PickItem {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/** Compact uptime: `45s`, `12m`, `3h 5m`. */
+export declare function formatUptime(ms: number): string;
+/**
+ * Build the ordered, UI-ready option list: the current project's daemon first
+ * (so it's the auto-selected default), the rest newest-first, then "Stop all"
+ * (only when there's more than one) and "Cancel".
+ */
+export declare function buildPickItems(daemons: DaemonRecord[], cwdRoot: string | null, now: number): PickItem[];
+export interface PickerDeps {
+    list: () => DaemonRecord[];
+    stop: (root: string) => Promise<StopResult>;
+    stopAll: () => Promise<StopResult[]>;
+    /** Realpath'd root of the current project's daemon, or null. */
+    cwdRoot: string | null;
+    now: () => number;
+    /** Render the picker; returns the chosen value or a cancel sentinel. */
+    select: (opts: {
+        message: string;
+        options: PickItem[];
+        initialValue: string;
+    }) => Promise<unknown>;
+    isCancel: (v: unknown) => boolean;
+    /** Per-action note (e.g. "Stopped daemon …"). */
+    note: (msg: string) => void;
+    /** Final line + teardown (clack outro). */
+    done: (msg: string) => void;
+}
+/**
+ * Pick a daemon → stop it → re-prompt with what's left, until the user cancels
+ * (Esc / Ctrl-C / "Cancel"), picks "Stop all", or nothing remains.
+ */
+export declare function runDaemonPicker(deps: PickerDeps): Promise<void>;
+//# sourceMappingURL=daemon-manager.d.ts.map

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

@@ -0,0 +1,73 @@
+/**
+ * Daemon socket + lockfile path helpers — issue #411.
+ *
+ * One shared `codegraph serve --mcp` daemon per project root means we need a
+ * stable, project-keyed rendezvous between cooperating processes. The IPC
+ * surface area is just two file paths:
+ *
+ *   - `daemon.sock` — Unix domain socket / named pipe the daemon listens on.
+ *   - `daemon.pid` — atomic-create lockfile holding the daemon's pid + version.
+ *
+ * Both live under `.codegraph/` so the project-scoped uninstall (`codegraph
+ * uninit`) sweeps them up for free.
+ *
+ * Special-case: Unix domain socket paths have a hard length limit (~104 on
+ * macOS, ~108 on Linux); when the in-project path exceeds it we fall back to
+ * an absolute-path hash under `os.tmpdir()`. The pidfile always stays in the
+ * project (it doesn't have a length limit) — and acts as the authoritative
+ * pointer to the socket path the daemon chose.
+ *
+ * Second special-case (#997, #974): some filesystems can't host an AF_UNIX node
+ * AT ALL — ExFAT/FAT external volumes, certain network mounts, WSL2 DrvFs — so
+ * `listen()` throws ENOTSUP/EACCES regardless of path length. We can't cheaply
+ * tell those apart from a normal volume up front, so instead of guessing we
+ * expose an ORDERED candidate list (`getDaemonSocketCandidates`): the in-project
+ * path first, the deterministic tmpdir path as the fallback of last resort. The
+ * daemon binds the first that works (relocating past a capability error); the
+ * proxy connects the first that answers. Both walk the SAME list, so they still
+ * converge on whichever the daemon bound with zero coordination.
+ */
+/**
+ * Ordered socket / named-pipe path candidates the daemon should try to bind (and
+ * the proxy should try to connect) for `projectRoot`, most-preferred first.
+ * Deterministic given a project root, so independent processes converge without
+ * coordination — even when the preferred candidate is unusable and both fall
+ * through to the same fallback.
+ *
+ *   - Windows: a single named pipe (lives in the kernel pipe namespace, not on
+ *     the project FS, so neither the length nor the ExFAT hazard applies).
+ *   - Short in-project path: `[ .codegraph/daemon.sock , <tmpdir> ]` — try the
+ *     project first, fall back to tmpdir if its FS can't host a socket (#997).
+ *   - Long in-project path (deep monorepos, Bazel out dirs): `[ <tmpdir> ]` only
+ *     — bind would throw ENAMETOOLONG, so we skip straight to tmpdir.
+ */
+export declare function getDaemonSocketCandidates(projectRoot: string): string[];
+/**
+ * The PREFERRED (primary) socket path — candidate 0. Use this only where a
+ * single representative path is wanted (the lockfile's informational
+ * `socketPath` field, status display). For binding/connecting, walk the full
+ * {@link getDaemonSocketCandidates} list — the daemon may bind a fallback when
+ * candidate 0 is unusable.
+ */
+export declare function getDaemonSocketPath(projectRoot: string): string;
+/** Absolute path to the daemon pid lockfile for `projectRoot`. */
+export declare function getDaemonPidPath(projectRoot: string): string;
+/** Structured contents of the pid lockfile. */
+export interface DaemonLockInfo {
+    pid: number;
+    version: string;
+    socketPath: string;
+    startedAt: number;
+}
+/**
+ * Serialize a {@link DaemonLockInfo} for writing to the pidfile. JSON for
+ * human readability — operators occasionally `cat` this when debugging.
+ */
+export declare function encodeLockInfo(info: DaemonLockInfo): string;
+/**
+ * Parse a pidfile body. Tolerant of old-format pidfiles (plain decimal pid) so
+ * a 0.10.x daemon doesn't trip over a 0.9.x lockfile if that ever happens —
+ * we treat such a lockfile as "process is unknown version, refuse to share."
+ */
+export declare function decodeLockInfo(raw: string): DaemonLockInfo | null;
+//# sourceMappingURL=daemon-paths.d.ts.map

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

@@ -0,0 +1,47 @@
+export interface DaemonRecord {
+    /** Realpath'd project root the daemon serves. */
+    root: string;
+    pid: number;
+    version: string;
+    socketPath: string;
+    /** Epoch ms when the daemon bound its socket. */
+    startedAt: number;
+}
+/**
+ * `~/.codegraph/daemons` — GLOBAL, keyed off the home install dir. (The
+ * `CODEGRAPH_DIR` env var only renames the per-project index dir, not this.)
+ */
+export declare function getRegistryDir(): string;
+/**
+ * Is `pid` a live process? `kill(pid, 0)` sends no signal — it just probes:
+ * ESRCH ⇒ dead, EPERM ⇒ alive but not ours (still alive). Same liveness check
+ * the PPID watchdog (#277) and daemon lock arbitration use.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/** Best-effort: record this daemon so `list`/`stop --all` can find it. */
+export declare function registerDaemon(rec: DaemonRecord): void;
+/** Best-effort: drop this daemon's record on graceful shutdown. */
+export declare function deregisterDaemon(root: string): void;
+/**
+ * All registered daemons whose process is still alive, newest first. Dead/garbage
+ * records are deleted as a side effect (self-healing) unless `prune` is false.
+ */
+export declare function listDaemons(opts?: {
+    prune?: boolean;
+}): DaemonRecord[];
+export interface StopResult {
+    root: string;
+    pid: number | null;
+    /** 'term' graceful, 'kill' force, 'not-running' stale lock, 'no-daemon' none found. */
+    outcome: 'term' | 'kill' | 'not-running' | 'no-daemon';
+}
+/**
+ * Stop the daemon serving `root`: SIGTERM, wait, then SIGKILL if it won't go,
+ * then sweep its artifacts. `root` must be realpath'd (match how the daemon
+ * keys its socket/lockfile). Resolves the pid from the authoritative lockfile,
+ * falling back to the registry.
+ */
+export declare function stopDaemonAt(root: string): Promise<StopResult>;
+/** Stop every registered, live daemon. */
+export declare function stopAllDaemons(): Promise<StopResult[]>;
+//# sourceMappingURL=daemon-registry.d.ts.map

package/dist/mcp/daemon.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * One detached `codegraph serve --mcp` daemon process per project root,
+ * accepting N concurrent MCP clients over a Unix-domain socket (or named pipe
+ * on Windows). Each incoming connection gets its own {@link MCPSession}; all
+ * sessions share a single {@link MCPEngine}, which means a single file watcher
+ * (one inotify set), a single SQLite connection (one WAL writer), and a single
+ * tree-sitter warm-up — paid once, amortized across every agent talking to the
+ * project.
+ *
+ * Lifecycle (see also `./index.ts` and `./proxy.ts`):
+ *   - The daemon is spawned **detached** (its own session/process group, stdio
+ *     decoupled) by the first launcher that finds no daemon running. It is NOT
+ *     a child of any MCP host, so closing one terminal / Ctrl-C'ing one session
+ *     can't take it down and sever the others. That's why this process has no
+ *     PPID watchdog: it deliberately outlives every individual client.
+ *   - Every MCP host talks to the daemon through a thin `proxy` process (the
+ *     thing the host actually spawned). The proxy keeps the #277 PPID watchdog,
+ *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
+ *     close then decrements the daemon's refcount.
+ *   - When the last client disconnects the daemon lingers for
+ *     `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
+ *     runs in the same project don't repay startup, then exits cleanly. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *
+ * What this file owns:
+ *   - Listening on the daemon socket and spawning per-connection sessions.
+ *   - The handshake "hello" line that lets a proxy verify it found a
+ *     same-version daemon before piping any JSON-RPC through it.
+ *   - The lockfile (`.codegraph/daemon.pid`) competing daemons arbitrate
+ *     against — atomic `O_EXCL` create with the full record written in the same
+ *     breath (no empty-file window) + cleanup on exit.
+ *   - Reference counting + idle timeout.
+ *   - Graceful shutdown on SIGTERM/SIGINT and idle exit.
+ *
+ * What this file does NOT own:
+ *   - The proxy side (`./proxy.ts`).
+ *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
+ *   - The MCP protocol state machine — that's `./session.ts`.
+ */
+import * as net from 'net';
+import { DaemonLockInfo } from './daemon-paths';
+/** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
+declare const MAX_HELLO_LINE_BYTES = 4096;
+/**
+ * Wire format for the one-shot hello line the daemon emits on every new
+ * connection. Versioned with the package's own semver so a 0.9.x proxy never
+ * pipes through a 0.10.x daemon (or vice-versa) — the proxy falls back to
+ * direct mode on mismatch rather than risk subtle wire incompatibilities.
+ */
+export interface DaemonHello {
+    codegraph: string;
+    pid: number;
+    socketPath: string;
+    protocol: 1;
+}
+/**
+ * Optional reverse-handshake line a proxy sends right after it verifies the
+ * daemon hello, carrying its own pids so the daemon can reap the client if its
+ * process dies WITHOUT the socket ever signalling close (the Windows named-pipe
+ * hazard behind #692). Entirely optional and fail-safe: a connection that never
+ * sends it (a legacy/direct client) just falls back to the socket-close
+ * lifecycle. The `codegraph_client` marker is what tells it apart from the
+ * client's first JSON-RPC message.
+ */
+export interface DaemonClientHello {
+    codegraph_client: 1;
+    pid: number;
+    hostPid: number | null;
+}
+export interface DaemonStartResult {
+    /** Always-non-null for a successfully-started daemon. */
+    socketPath: string;
+    /** Lockfile contents as written. */
+    lock: DaemonLockInfo;
+}
+/**
+ * Run as the shared daemon for `projectRoot`. Resolves once the socket is
+ * listening. The Daemon owns the socket, the engine, and the lockfile until
+ * `stop()` is called or it exits on idle/signal.
+ *
+ * Race-safe: callers must first call `tryAcquireDaemonLock(projectRoot)` and
+ * only construct a Daemon if they got the lock (`kind: 'acquired'`). The atomic
+ * `O_EXCL` create inside the acquire helper — which now also writes the full
+ * record before returning — is the only synchronization between competing
+ * daemons.
+ */
+export declare class Daemon {
+    private projectRoot;
+    private server;
+    private clients;
+    /** Per-client peer pids from the optional client-hello, for the liveness sweep. */
+    private clientPeers;
+    private idleTimer;
+    private idleTimeoutMs;
+    private maxIdleMs;
+    private lastActivityAt;
+    private maxIdleTimer;
+    private clientSweepTimer;
+    private engine;
+    private stopping;
+    private socketPath;
+    private pidPath;
+    constructor(projectRoot: string, opts?: {
+        idleTimeoutMs?: number;
+        maxIdleMs?: number;
+    });
+    /**
+     * Bind the socket, kick off engine init, and register signal handlers. The
+     * lockfile body was already written atomically by `tryAcquireDaemonLock`, so
+     * there is nothing to write here. The promise resolves once the server is
+     * listening — the daemon then sticks around until idle/shutdown.
+     */
+    start(): Promise<DaemonStartResult>;
+    /** Currently-connected client count. Exposed for tests / status output. */
+    getClientCount(): number;
+    /** The socket path the daemon is (or will be) listening on. */
+    getSocketPath(): string;
+    /** Graceful shutdown: close all sessions, the engine, and clean up the lock. */
+    stop(reason?: string): Promise<void>;
+    private handleConnection;
+    private dropClient;
+    private armIdleTimer;
+    private disarmIdleTimer;
+    /**
+     * Defense-in-depth against a daemon that outlives its clients (#692), for the
+     * cases the refcount + idle timer miss because a socket close never arrives:
+     *   - **Inactivity backstop:** exit if no inbound traffic for `maxIdleMs` while
+     *     clients are still (nominally) connected. A phantom client sends nothing,
+     *     so it can't pin the daemon past this window.
+     *   - **Liveness sweep:** drop any client whose peer process has died (per the
+     *     client-hello pids), which re-arms the idle timer once the last real
+     *     client is gone. Catches a dead peer within one sweep instead of waiting
+     *     out the whole backstop.
+     * Both timers are unref'd — the listening server keeps the loop alive, and
+     * neither should hold it open on its own.
+     */
+    private startLivenessTimers;
+    /**
+     * Drop every connected client whose peer process is gone. Returns the count
+     * reaped. `isAlive` is injected for testing. Clients with unknown pids (no
+     * client-hello) are skipped — they rely on the socket-close path.
+     */
+    reapDeadClients(isAlive: (pid: number) => boolean): number;
+    private cleanupLockfile;
+}
+/**
+ * Result of `tryAcquireDaemonLock`. Either we got the lockfile (caller becomes
+ * the daemon), or it already existed (caller should connect to the existing
+ * daemon as a proxy, or — if the holder is dead — clear it and retry).
+ */
+export type AcquireResult = {
+    kind: 'acquired';
+    pidPath: string;
+    info: DaemonLockInfo;
+} | {
+    kind: 'taken';
+    existing: DaemonLockInfo | null;
+    pidPath: string;
+};
+/**
+ * Atomically create the daemon pidfile with its full record already in place.
+ * Returns either an `acquired` result (the caller is the daemon-elect and may
+ * construct a {@link Daemon}) or a `taken` result.
+ *
+ * must-fix 1 (issue #411 review): the lockfile must appear in ONE atomic step,
+ * already complete — never empty, even momentarily. The first attempt at this
+ * (`O_EXCL` create then a separate `writeSync`) left a microsecond window where
+ * the file existed but was empty; under concurrent daemon startup a third
+ * candidate could read that empty file, decode it as `null`, and `unlink` the
+ * winner's lock → two daemons (two watchers, two writers). The window was
+ * normally too small to hit, but the file watcher's extra startup time made
+ * concurrent daemons overlap enough to reproduce it reliably.
+ *
+ * The fix writes the complete record to a private temp file, then hard-links it
+ * into place: `link()` is atomic AND exclusive (EEXIST if the target exists), so
+ * the pidfile becomes visible in one step already containing a full record.
+ * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
+ * There is no empty-file window at all.
+ *
+ * Filesystems without hard links (#997): ExFAT/FAT external volumes and some
+ * network mounts can't `link()` at all — it throws ENOTSUP/EPERM, which would
+ * otherwise kill the daemon before it ever reaches the socket bind. There we
+ * fall back to an O_EXCL create (`acquireLockViaExclusiveOpen`): still exclusive
+ * ("first writer wins"), but the full record is written through the fd in a
+ * second step, so the empty-file window the link approach removed is reopened —
+ * only on these filesystems, only for the microseconds between create and write
+ * (far narrower than the original bug, which the file watcher's startup latency
+ * widened). The race's worst case is two daemons briefly; on a single external
+ * drive that's strictly better than the daemon never starting at all.
+ */
+export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+/**
+ * Exclusive-create the pidfile (O_CREAT|O_EXCL via the `wx` flag) and write the
+ * full record through the same fd — the hard-link-free fallback used by
+ * {@link tryAcquireDaemonLock} on filesystems without `link()`. Returns true if
+ * we created it (acquired the lock), false on EEXIST (another candidate holds
+ * it). Any other error propagates. Still exclusive, so "first writer wins" holds
+ * exactly as the link path does; the only difference is the brief empty-file
+ * window between create and write. Exported for testing.
+ */
+export declare function acquireLockViaExclusiveOpen(pidPath: string, info: DaemonLockInfo): boolean;
+/**
+ * Remove a stale pidfile, but only if it still names a dead process. Re-reads
+ * the file immediately before unlinking so we never delete a lock that a live
+ * daemon (re)acquired in the meantime.
+ *
+ * must-fix 1 (issue #411 review): the original unconditionally `unlink`'d,
+ * which let a racing candidate delete a healthy daemon's lock. Passing
+ * `expectedDeadPid` (the pid the caller believed was dead) makes the clear a
+ * compare-and-delete: bail if the file now holds a different pid, or any live
+ * pid. Returns true when the stale lock is gone (or was already gone).
+ */
+export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?: number): boolean;
+/**
+ * Probe whether `pid` is currently alive (signal-0). Treats EPERM as alive on
+ * every platform (the process exists, it's just not ours to signal) so we never
+ * mistake a live daemon for a dead one and clear its lock.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Bind the first usable socket from an ordered candidate list, relocating past
+ * any path that fails to bind for a non-conflict reason (see {@link
+ * SOCKET_BIND_CONFLICT_CODE}). The injected `listen` does the real
+ * `net.Server.listen` (and stale-socket clear); abstracted so the relocation
+ * policy is unit-testable without a real unsupported filesystem. Returns the
+ * server plus the path actually bound. An EADDRINUSE, or any error on the LAST
+ * candidate, propagates — the caller releases the lockfile and falls back to
+ * direct mode (#974). Exported for testing.
+ */
+export declare function bindFirstUsableSocket(candidates: string[], listen: (socketPath: string) => Promise<net.Server>, opts?: {
+    onRelocate?: (from: string, to: string, code: string) => void;
+}): Promise<{
+    server: net.Server;
+    socketPath: string;
+}>;
+/**
+ * Parse one client-hello line. Returns the peer pids if `line` is a well-formed
+ * client-hello (carries the `codegraph_client` marker), or null otherwise — in
+ * which case the caller treats the bytes as ordinary JSON-RPC.
+ */
+export declare function parseClientHelloLine(line: string): {
+    pid: number;
+    hostPid: number | null;
+} | null;
+/**
+ * A client's peer is dead when its proxy process is gone, or when its known
+ * host process is gone. Unknown pid (no client-hello) is never "dead" on this
+ * basis — those clients rely on the socket-close path. Exported for testing.
+ */
+export declare function peerIsDead(peers: {
+    pid: number | null;
+    hostPid: number | null;
+}, isAlive: (pid: number) => boolean): boolean;
+/** Exported for test stubs that need to bound the hello-line read. */
+export { MAX_HELLO_LINE_BYTES };
+//# sourceMappingURL=daemon.d.ts.map

package/dist/mcp/dynamic-boundaries.d.ts

@@ -0,0 +1,41 @@
+export interface BoundaryMatch {
+    /** Stable form id, e.g. 'computed-call' — used for per-form dedupe. */
+    form: string;
+    /** Human label for the dispatch form, e.g. 'computed member call'. */
+    label: string;
+    /** One-line source snippet of the site (from the original, untrimmed text). */
+    snippet: string;
+    /** 1-based line within the scanned body's FILE (absolute, ready to print). */
+    line: number;
+    /**
+     * Statically-visible dispatch key, when one exists: the string literal in
+     * `handlers['save']`, the `:symbol` in ruby `send`, the type name in
+     * `Send(new CreateCmd(...))`. Drives candidate lookup. Undefined when the
+     * key is a runtime value (variable, computed expression).
+     */
+    key?: string;
+    /** For typed-bus matches the key is a TYPE name (candidates ~ `${key}Handler`). */
+    keyIsType?: boolean;
+    /** Additional sites of the same form+key in this body beyond the reported one. */
+    moreSites?: number;
+}
+/**
+ * Blank the CONTENTS of string literals (quotes preserved, offsets preserved)
+ * so dispatch-shaped prose — docs, error messages, template text — can't fire
+ * a matcher. Run AFTER comment stripping (comments are already spaces).
+ * Backslash escapes are honored; `'`/`"` strings end at a newline (treated as
+ * unterminated, matching the comment stripper); backticks span lines, and
+ * `${...}` interpolations inside them are blanked too — missing a dispatch
+ * inside a template literal is acceptable, false-firing on prose is not.
+ */
+export declare function blankStringContents(text: string): string;
+/**
+ * Scan one symbol's body for dynamic-dispatch sites.
+ *
+ * @param body       the symbol's source text (sliced from the file)
+ * @param language   Node.language of the symbol
+ * @param fileStartLine 1-based line where `body` starts in its file — returned
+ *                      line numbers are absolute file lines.
+ */
+export declare function scanDynamicDispatch(body: string, language: string, fileStartLine: number): BoundaryMatch[];
+//# sourceMappingURL=dynamic-boundaries.d.ts.map

package/dist/mcp/engine.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 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;
+    /**
+     * 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