cgraphx 1.1.0

package/dist/mcp/liveness-watchdog.js

@@ -0,0 +1,207 @@
+"use strict";
+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.DEFAULT_WATCHDOG_TIMEOUT_MS = void 0;
+exports.parseWatchdogTimeoutMs = parseWatchdogTimeoutMs;
+exports.deriveCheckIntervalMs = deriveCheckIntervalMs;
+exports.installMainThreadWatchdog = installMainThreadWatchdog;
+/**
+ * Main-thread liveness watchdog — belt-and-suspenders for #850.
+ *
+ * The #850 fix removes the one *known* trigger (the uncaught-exception handler
+ * no longer formats a raw Error's `.stack`). But ANY synchronous, non-yielding
+ * loop on the main thread — a future V8 stack-format pathology, a runaway
+ * regex, an accidental `while (true)` — wedges the event loop, and from JS you
+ * cannot interrupt it: timers, signal handlers, and the PPID watchdog all run
+ * *on* that blocked loop, so the process pins a core forever with no
+ * self-recovery (the exact unrecoverable state #850 reported).
+ *
+ * **Why a separate PROCESS, not a worker thread.** A worker thread was the
+ * obvious first choice and it works in a toy process — but it was validated to
+ * FAIL in the real daemon (#850 live test). V8 isolates in one process
+ * coordinate on global safepoints, so when one thread requests a GC every other
+ * thread must reach a safepoint before it can proceed. A main thread wedged in
+ * a tight, non-allocating loop never reaches one, which strands the watchdog
+ * worker on its very next allocation/safepoint check — and the #850 hot loop
+ * (`SourcePositionTableIterator::Advance`, a non-allocating C++ table walk) is
+ * exactly that shape. A child process shares no isolate and no heap with the
+ * parent, so the wedge cannot touch it; it kills via the kernel, which honours
+ * SIGKILL regardless of what the parent's threads are doing.
+ *
+ * **How.** The parent writes a heartbeat byte to the child's stdin every
+ * `checkMs` from a timer — firing at all means the event loop is turning. The
+ * child resets a kill-timer on each byte; if none arrives for `timeoutMs` it
+ * `SIGKILL`s the parent so a fresh daemon starts on the next connection. When
+ * the parent exits normally the pipe closes and the child exits too (no
+ * orphan).
+ *
+ * **Won't fire on real work.** Heavy parsing runs in the parse worker
+ * (off-thread) and indexing shells out to a child process, so the daemon's main
+ * thread only ever does fast, bounded work. The default timeout is ~300× the
+ * 5h #850 wedge shorter, yet far longer than any legitimate main-thread block.
+ * Opt out with `CGRAPHX_NO_WATCHDOG=1`; tune with `CGRAPHX_WATCHDOG_TIMEOUT_MS`.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+/** Default: 60s — ~300× shorter than the 5h #850 wedge, far longer than any real main-thread block. */
+exports.DEFAULT_WATCHDOG_TIMEOUT_MS = 60_000;
+/** `true` for `1/true/yes/on` (case-insensitive); `false` otherwise. */
+function isEnvTruthy(raw) {
+    if (!raw)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+}
+/** Parse the timeout env, falling back to the default for missing/invalid values. */
+function parseWatchdogTimeoutMs(raw, fallback = exports.DEFAULT_WATCHDOG_TIMEOUT_MS) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Derive a heartbeat cadence that emits several beats inside the timeout window. */
+function deriveCheckIntervalMs(timeoutMs) {
+    return Math.min(2000, Math.max(50, Math.round(timeoutMs / 5)));
+}
+/** Arming/teardown diagnostics, gated on the existing MCP debug switch. */
+function debug(msg) {
+    if (process.env.CGRAPHX_MCP_DEBUG) {
+        try {
+            fs.writeSync(2, `[cgraphx watchdog] ${msg}\n`);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * The watchdog child body, run via `node -e`. Inlined as a string (not a
+ * shipped `.js`) so there is no dist-vs-src path to resolve — it runs
+ * identically under `tsx` in tests and under the bundle in production. Reads its
+ * target pid + timeout from argv; an MSG built once at startup (the child is
+ * never wedged, so allocation here is fine).
+ */
+const CHILD_SOURCE = `
+const fs = require('fs');
+const parentPid = Number(process.argv[1]);
+const timeoutMs = Number(process.argv[2]);
+const secs = Math.round(timeoutMs / 1000);
+const MSG = Buffer.from('[cgraphx] Main thread unresponsive for ~' + secs + 's — killing the wedged process so a fresh one can start (#850). Disable with CGRAPHX_NO_WATCHDOG=1.\\n');
+function kill() {
+  try { fs.writeSync(2, MSG); } catch (e) {}
+  try { process.kill(parentPid, 'SIGKILL'); } catch (e) {}
+  process.exit(0);
+}
+let timer = setTimeout(kill, timeoutMs);
+process.stdin.on('data', () => { clearTimeout(timer); timer = setTimeout(kill, timeoutMs); });
+process.stdin.on('end', () => process.exit(0));   // parent closed the pipe (exited) -> no orphan
+process.stdin.on('error', () => process.exit(0)); // pipe broke -> parent gone
+process.stdin.resume();
+`;
+/**
+ * Install the main-thread liveness watchdog for a long-lived process. Returns a
+ * handle to stop it, or `null` when disabled or when the child can't be spawned
+ * (degraded, never throws — a missing watchdog must never keep a process from
+ * starting).
+ */
+function installMainThreadWatchdog() {
+    if (isEnvTruthy(process.env.CGRAPHX_NO_WATCHDOG))
+        return null;
+    const timeoutMs = parseWatchdogTimeoutMs(process.env.CGRAPHX_WATCHDOG_TIMEOUT_MS);
+    const checkMs = deriveCheckIntervalMs(timeoutMs);
+    let child;
+    try {
+        // No execArgv inheritance (unlike Worker), so the child carries none of our
+        // V8 flags — it runs no WASM and needs none. stderr inherits the parent's
+        // fd 2 so the kill notice lands wherever the parent logs (daemon.log).
+        child = (0, child_process_1.spawn)(process.execPath, ['-e', CHILD_SOURCE, String(process.pid), String(timeoutMs)], {
+            stdio: ['pipe', 'ignore', 'inherit'],
+            windowsHide: true,
+            // The watchdog touches no files; keep its cwd off the project/temp dir
+            // so it can't hold one open (Windows EPERM-on-cleanup, mirrors the
+            // parse-worker quirk).
+            cwd: os.tmpdir(),
+        });
+    }
+    catch (err) {
+        debug(`spawn failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    const stdin = child.stdin;
+    if (!stdin) {
+        debug('child has no stdin pipe; not arming');
+        try {
+            child.kill();
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    // Writing after the child exits surfaces EPIPE on the stream — swallow it so
+    // it can't escalate to the global handler (which now exits, #850).
+    stdin.on('error', () => { });
+    child.on('error', (err) => debug(`child error: ${err.message}`));
+    // Heartbeat: a byte per tick. When the main thread wedges, these stop and the
+    // child's timeout fires. unref'd so it never keeps the process alive itself.
+    const heartbeat = setInterval(() => {
+        try {
+            stdin.write('\n');
+        }
+        catch { /* child gone */ }
+    }, checkMs);
+    heartbeat.unref();
+    // Neither the child nor its pipe should keep the parent alive past its work.
+    child.unref();
+    try {
+        stdin.unref?.();
+    }
+    catch { /* ignore */ }
+    debug(`armed (child pid ${child.pid ?? '?'}): timeoutMs=${timeoutMs} checkMs=${checkMs}`);
+    let stopped = false;
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(heartbeat);
+            try {
+                stdin.end();
+            }
+            catch { /* ignore */ } // EOF -> child exits cleanly
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ } // belt-and-suspenders
+        },
+    };
+}
+//# sourceMappingURL=liveness-watchdog.js.map

package/dist/mcp/liveness-watchdog.js.map

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

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

@@ -0,0 +1,44 @@
+/**
+ * Shared decision logic for the PPID watchdog (#277, #692).
+ *
+ * The watchdog's job: notice that the process we depend on — our parent, or the
+ * MCP host reached past an intermediate launcher — has died, so an orphaned
+ * proxy / direct server shuts itself down instead of leaking forever.
+ *
+ * Parent death surfaces differently per OS, and getting this wrong is what
+ * caused the unbounded daemon/proxy leak on Windows (#692, #576):
+ *
+ *   - **POSIX** reparents an orphan to init (pid 1), so `process.ppid` *changes*
+ *     the instant the parent dies. That divergence is the classic #277 signal.
+ *   - **Windows** never reparents: `process.ppid` keeps reporting the original
+ *     (now-dead) parent forever, so the change-check can never fire. There we
+ *     must poll the original parent's *liveness* instead.
+ *
+ * The liveness fallback is deliberately gated to Windows. On POSIX a
+ * double-forked grandparent can legitimately outlive the reparent, so a dead
+ * `originalPpid` is not proof of orphaning there — the change-check is the
+ * correct and sufficient POSIX signal, and using liveness too would risk a
+ * false-positive shutdown.
+ */
+export interface SupervisionState {
+    /** `process.ppid` captured at startup. */
+    originalPpid: number;
+    /** `process.ppid` right now. */
+    currentPpid: number;
+    /**
+     * The MCP host pid threaded past an intermediate launcher
+     * (`CGRAPHX_HOST_PPID`), or null when unknown — e.g. the standalone bundle,
+     * which pre-bakes `--liftoff-only` and so never runs the relaunch that sets it.
+     */
+    hostPpid: number | null;
+    /** Liveness probe — `process.kill(pid, 0)` in production, stubbed in tests. */
+    isAlive: (pid: number) => boolean;
+    /** Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Returns a human-readable reason string when the process has lost its
+ * supervisor and should shut down, or null while it is still supervised.
+ */
+export declare function supervisionLostReason(state: SupervisionState): string | null;
+//# sourceMappingURL=ppid-watchdog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ppid-watchdog.d.ts","sourceRoot":"","sources":["../../src/mcp/ppid-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+EAA+E;IAC/E,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAmB5E"}

package/dist/mcp/ppid-watchdog.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supervisionLostReason = supervisionLostReason;
+/**
+ * Returns a human-readable reason string when the process has lost its
+ * supervisor and should shut down, or null while it is still supervised.
+ */
+function supervisionLostReason(state) {
+    const { originalPpid, currentPpid, hostPpid, isAlive } = state;
+    const platform = state.platform ?? process.platform;
+    // POSIX: the parent dying reparents us, so ppid diverges. (Never on Windows.)
+    if (currentPpid !== originalPpid) {
+        return `ppid ${originalPpid} -> ${currentPpid}`;
+    }
+    // Windows: ppid is stable across parent death, so detect it by liveness.
+    // Skip pid 0/1 — "unknown" and init are never a real Windows parent, and a
+    // bogus liveness probe there must not trigger a shutdown.
+    if (platform === 'win32' && originalPpid > 1 && !isAlive(originalPpid)) {
+        return `parent pid ${originalPpid} exited`;
+    }
+    // Either platform: the host pid threaded past a launcher shim is gone.
+    if (hostPpid !== null && !isAlive(hostPpid)) {
+        return `host pid ${hostPpid} exited`;
+    }
+    return null;
+}
+//# sourceMappingURL=ppid-watchdog.js.map

package/dist/mcp/ppid-watchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ppid-watchdog.js","sourceRoot":"","sources":["../../src/mcp/ppid-watchdog.ts"],"names":[],"mappings":";;AA2CA,sDAmBC;AAvBD;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,KAAuB;IAC3D,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC/D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IAEpD,8EAA8E;IAC9E,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;QACjC,OAAO,QAAQ,YAAY,OAAO,WAAW,EAAE,CAAC;IAClD,CAAC;IACD,yEAAyE;IACzE,2EAA2E;IAC3E,0DAA0D;IAC1D,IAAI,QAAQ,KAAK,OAAO,IAAI,YAAY,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACvE,OAAO,cAAc,YAAY,SAAS,CAAC;IAC7C,CAAC;IACD,uEAAuE;IACvE,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5C,OAAO,YAAY,QAAQ,SAAS,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/mcp/proxy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * MCP proxy mode — issue #411.
+ *
+ * The proxy is a near-transparent stdio↔socket pipe. Once it has verified
+ * the daemon's hello line (same major.minor.patch as ours), it does no
+ * protocol parsing of its own: every byte the MCP host writes to the proxy's
+ * stdin goes straight to the daemon socket, and every byte the daemon emits
+ * goes straight to the host's stdout. Server-initiated JSON-RPC requests
+ * (e.g. `roots/list`) flow through the same pipe transparently.
+ *
+ * Lifecycle expectations:
+ *   - The proxy exits when *either* stream closes (host stdin closed →
+ *     daemon socket end, or daemon-side socket close → host stdout end).
+ *   - Closing the socket on the proxy side is what tells the daemon to
+ *     decrement its connected-clients refcount.
+ *   - On a parent-process death we can't detect via stdin close (e.g. SIGKILL
+ *     of the MCP host), the proxy's PPID watchdog catches it — same logic
+ *     the direct-mode server uses; see issue #277.
+ */
+import * as net from 'net';
+import { DaemonHello } from './daemon';
+import type { MCPEngine } from './engine';
+/**
+ * Log a successful daemon attach — gated behind {@link LOG_ATTACH_ENV} so it is
+ * silent by default (see #618). Exported for tests.
+ */
+export declare function logAttachedDaemon(socketPath: string, hello: DaemonHello): void;
+export interface ProxyResult {
+    /**
+     * `proxied` — successfully attached to a same-version daemon and piped
+     * stdio. The proxy stays alive until either end closes.
+     * `fallback-needed` — the daemon rejected us (version mismatch / unreachable
+     * socket) and the caller should run the server in direct mode.
+     */
+    outcome: 'proxied' | 'fallback-needed';
+    reason?: string;
+}
+/**
+ * Attempt to connect to the daemon at `socketPath` and pipe stdio through it.
+ *
+ * Returns a promise that resolves when either:
+ *   - the connection succeeded and one of stdin/socket has now closed
+ *     (after which the process should exit), or
+ *   - the connection failed early enough that the caller can still fall
+ *     back to direct mode.
+ *
+ * The `expectedVersion` param defaults to the package's own version — daemon
+ * and proxy MUST match exactly. Mismatch resolves with
+ * `outcome: 'fallback-needed'` so the caller can transparently start its own
+ * server. (We accept the cost of two concurrent servers in this case as the
+ * price of never silently running a stale daemon against newer client code.)
+ */
+export declare function runProxy(socketPath: string, expectedVersion?: string): Promise<ProxyResult>;
+/**
+ * Connect to a daemon at `socketPath` and verify its hello (exact version match).
+ * Returns the live socket (hello already consumed) or null if unreachable / stale
+ * / version-mismatched. Unlike {@link runProxy} it does NOT pipe — the caller
+ * owns the socket. Used by the local-handshake proxy's background connect.
+ */
+export declare function connectWithHello(socketPath: string, expectedVersion?: string): Promise<net.Socket | 'version-mismatch' | null>;
+/** Dependencies the local-handshake proxy needs, injected by MCPServer (which
+ *  owns the daemon-spawn machinery and the engine factory). */
+export interface LocalHandshakeDeps {
+    /** Probe → spawn → retry → hello-verify; resolves a connected daemon socket,
+     *  or null when the daemon path is genuinely unavailable (→ in-process fallback). */
+    getDaemonSocket(): Promise<net.Socket | null>;
+    /** Lazily create an in-process engine — used ONLY if the daemon never comes up,
+     *  preserving the "a broken daemon never wedges a session" guarantee. */
+    makeEngine(): MCPEngine;
+    /** Project root for the fallback engine's lazy init. */
+    root: string;
+}
+/**
+ * Local-handshake proxy (the cold-start fix).
+ *
+ * Answers `initialize` + `tools/list` from STATIC constants the instant the
+ * client asks — tools register in ~process-startup time instead of waiting
+ * ~600ms for the daemon to spawn+bind, which is what produced the "No such tool
+ * available" race that made headless agents flail into grep/Read. Tool CALLS are
+ * forwarded to the shared daemon (connected in the background); the daemon's
+ * response to the forwarded `initialize` is suppressed (the client already got
+ * the local one). If the daemon never comes up (version mismatch / spawn fail),
+ * a lazily-created in-process engine serves the calls — so the handshake speedup
+ * never costs the old fall-back-to-direct robustness.
+ */
+export declare function runLocalHandshakeProxy(deps: LocalHandshakeDeps): Promise<void>;
+//# sourceMappingURL=proxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/mcp/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAE3B,OAAO,EAAqB,WAAW,EAAwB,MAAM,UAAU,CAAC;AAQhF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAc1C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAK9E;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,OAAO,EAAE,SAAS,GAAG,iBAAiB,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,eAAe,GAAE,MAAgC,GAChD,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,eAAe,GAAE,MAAgC,GAChD,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC,CAgCjD;AAsBD;+DAC+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC;yFACqF;IACrF,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C;6EACyE;IACzE,UAAU,IAAI,SAAS,CAAC;IACxB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiLpF"}