@quolu/lattice 0.1.0

package/sensor/dist/mcp/startup-handshake.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Never-initialized backstop for `serve --mcp` (#1185).
+ *
+ * Every real MCP host sends `initialize` immediately after spawning a server.
+ * A server that has received NO bytes at all for many minutes is not serving
+ * anyone — it is the residue of an abandoned launch: the host killed the
+ * launcher chain during startup (config probe, instant cancel, initialize
+ * timeout) but kept our stdio pipe fds open, so stdin never EOFs. If the kill
+ * landed before {@link ../mcp/early-ppid} could observe the real parent, the
+ * PPID watchdog is blind too (baseline `1`), and — pre-#1185 — the orphan
+ * lived until the HOST process exited, accumulating one ~30MB node process
+ * per occurrence.
+ *
+ * This backstop closes that last hole: arm a one-shot timer at serve start
+ * and disarm it on the first byte of client traffic. If the timer fires, the
+ * caller shuts the server down. The default is deliberately generous (15
+ * minutes) — hosts initialize within milliseconds, so the only processes this
+ * ever reaps are ones nobody is talking to. It never affects a session that
+ * spoke even once: after the first byte the timer is gone for good (a
+ * quiet-but-live session is the PPID watchdog's / stdin teardown's job).
+ *
+ * IMPORTANT (callers): attaching a `'data'` listener switches the stream into
+ * flowing mode. Arm this AFTER the real stdin consumer is attached, in the
+ * same synchronous block, so no early bytes are emitted while only our
+ * listener exists. The detached daemon must never arm this — its stdin is
+ * `'ignore'` and its lifecycle is refcount/idle-based.
+ *
+ * Tune with `CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS`; `0` disables.
+ */
+/** Default wait for the first byte of MCP traffic before assuming orphaned. */
+export declare const DEFAULT_STARTUP_HANDSHAKE_TIMEOUT_MS = 900000;
+export declare const STARTUP_HANDSHAKE_TIMEOUT_ENV = "CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS";
+/**
+ * Parse the timeout env override. Missing/invalid → default; `<= 0` → `0`
+ * (disabled), the same disable convention as `CODEGRAPH_PPID_POLL_MS`.
+ */
+export declare function parseStartupHandshakeTimeoutMs(raw: string | undefined): number;
+/**
+ * Arm the backstop. `onAbandoned` runs at most once, only if no `'data'` event
+ * arrives on `stream` within the timeout. Returns a disarm function (idempotent;
+ * also detaches the listener). `stream`/`timeoutMs` are injectable for tests.
+ */
+export declare function armStartupHandshakeTimeout(onAbandoned: () => void, stream?: NodeJS.ReadableStream, timeoutMs?: number): () => void;
+//# sourceMappingURL=startup-handshake.d.ts.map

package/sensor/dist/mcp/startup-handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-handshake.d.ts","sourceRoot":"","sources":["../../src/mcp/startup-handshake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,oCAAoC,SAAU,CAAC;AAE5D,eAAO,MAAM,6BAA6B,2CAA2C,CAAC;AAEtF;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM9E;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,IAAI,EACvB,MAAM,GAAE,MAAM,CAAC,cAA8B,EAC7C,SAAS,GAAE,MAAmF,GAC7F,MAAM,IAAI,CAcZ"}

package/sensor/dist/mcp/startup-handshake.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Never-initialized backstop for `serve --mcp` (#1185).
+ *
+ * Every real MCP host sends `initialize` immediately after spawning a server.
+ * A server that has received NO bytes at all for many minutes is not serving
+ * anyone — it is the residue of an abandoned launch: the host killed the
+ * launcher chain during startup (config probe, instant cancel, initialize
+ * timeout) but kept our stdio pipe fds open, so stdin never EOFs. If the kill
+ * landed before {@link ../mcp/early-ppid} could observe the real parent, the
+ * PPID watchdog is blind too (baseline `1`), and — pre-#1185 — the orphan
+ * lived until the HOST process exited, accumulating one ~30MB node process
+ * per occurrence.
+ *
+ * This backstop closes that last hole: arm a one-shot timer at serve start
+ * and disarm it on the first byte of client traffic. If the timer fires, the
+ * caller shuts the server down. The default is deliberately generous (15
+ * minutes) — hosts initialize within milliseconds, so the only processes this
+ * ever reaps are ones nobody is talking to. It never affects a session that
+ * spoke even once: after the first byte the timer is gone for good (a
+ * quiet-but-live session is the PPID watchdog's / stdin teardown's job).
+ *
+ * IMPORTANT (callers): attaching a `'data'` listener switches the stream into
+ * flowing mode. Arm this AFTER the real stdin consumer is attached, in the
+ * same synchronous block, so no early bytes are emitted while only our
+ * listener exists. The detached daemon must never arm this — its stdin is
+ * `'ignore'` and its lifecycle is refcount/idle-based.
+ *
+ * Tune with `CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS`; `0` disables.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STARTUP_HANDSHAKE_TIMEOUT_ENV = exports.DEFAULT_STARTUP_HANDSHAKE_TIMEOUT_MS = void 0;
+exports.parseStartupHandshakeTimeoutMs = parseStartupHandshakeTimeoutMs;
+exports.armStartupHandshakeTimeout = armStartupHandshakeTimeout;
+/** Default wait for the first byte of MCP traffic before assuming orphaned. */
+exports.DEFAULT_STARTUP_HANDSHAKE_TIMEOUT_MS = 900_000; // 15 min
+exports.STARTUP_HANDSHAKE_TIMEOUT_ENV = 'CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS';
+/**
+ * Parse the timeout env override. Missing/invalid → default; `<= 0` → `0`
+ * (disabled), the same disable convention as `CODEGRAPH_PPID_POLL_MS`.
+ */
+function parseStartupHandshakeTimeoutMs(raw) {
+    if (raw === undefined || raw === '')
+        return exports.DEFAULT_STARTUP_HANDSHAKE_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return exports.DEFAULT_STARTUP_HANDSHAKE_TIMEOUT_MS;
+    if (parsed <= 0)
+        return 0;
+    return Math.floor(parsed);
+}
+/**
+ * Arm the backstop. `onAbandoned` runs at most once, only if no `'data'` event
+ * arrives on `stream` within the timeout. Returns a disarm function (idempotent;
+ * also detaches the listener). `stream`/`timeoutMs` are injectable for tests.
+ */
+function armStartupHandshakeTimeout(onAbandoned, stream = process.stdin, timeoutMs = parseStartupHandshakeTimeoutMs(process.env[exports.STARTUP_HANDSHAKE_TIMEOUT_ENV])) {
+    if (timeoutMs <= 0)
+        return () => { };
+    const onFirstData = () => { clearTimeout(timer); };
+    const timer = setTimeout(() => {
+        stream.removeListener('data', onFirstData);
+        onAbandoned();
+    }, timeoutMs);
+    // Never let the backstop itself keep an otherwise-finished process alive.
+    timer.unref?.();
+    stream.once('data', onFirstData);
+    return () => {
+        stream.removeListener('data', onFirstData);
+        clearTimeout(timer);
+    };
+}
+//# sourceMappingURL=startup-handshake.js.map

package/sensor/dist/mcp/startup-handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-handshake.js","sourceRoot":"","sources":["../../src/mcp/startup-handshake.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAWH,wEAMC;AAOD,gEAkBC;AAxCD,+EAA+E;AAClE,QAAA,oCAAoC,GAAG,OAAO,CAAC,CAAC,SAAS;AAEzD,QAAA,6BAA6B,GAAG,wCAAwC,CAAC;AAEtF;;;GAGG;AACH,SAAgB,8BAA8B,CAAC,GAAuB;IACpE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,4CAAoC,CAAC;IACjF,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,4CAAoC,CAAC;IAC1E,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,SAAgB,0BAA0B,CACxC,WAAuB,EACvB,SAAgC,OAAO,CAAC,KAAK,EAC7C,YAAoB,8BAA8B,CAAC,OAAO,CAAC,GAAG,CAAC,qCAA6B,CAAC,CAAC;IAE9F,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,GAAG,EAAE,GAAkB,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,GAAS,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3C,WAAW,EAAE,CAAC;IAChB,CAAC,EAAE,SAAS,CAAC,CAAC;IACd,0EAA0E;IAC1E,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACjC,OAAO,GAAS,EAAE;QAChB,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3C,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC"}

package/sensor/dist/mcp/stdin-teardown.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Treat a stdin failure as a shutdown signal — issue #799.
+ *
+ * An MCP stdio server's lifeline is its stdin: when the host/client goes away,
+ * stdin should end and the server should exit. The server paths listened for
+ * `'end'` and `'close'` — but NOT `'error'`.
+ *
+ * That gap bites with a socket-backed stdin, which is the shape VS Code /
+ * Claude Code use (a socketpair, not a pipe). When the client dies, the socket
+ * can surface as an `'error'` (ECONNRESET / hangup) rather than a clean
+ * `'close'`. With no `'error'` listener, Node escalates it to the process-wide
+ * `uncaughtException` handler, which logs and keeps running — so the server
+ * orphans instead of exiting. Worse, on Linux a `POLLHUP` socket fd left
+ * registered in epoll wakes the event loop continuously, pinning a core at
+ * 100% CPU (the spin reported in #799); once the main thread spins, the
+ * `setInterval` PPID watchdog can't even fire, so the orphan runs forever.
+ *
+ * Fix: listen for `'error'` as well, and DESTROY the stdin stream on any
+ * terminal event so the fd leaves epoll and can't keep churning, then run the
+ * caller's shutdown. Fires `onTerminal` at most once — callers' shutdowns are
+ * already re-entry-guarded, but the single-shot guard also keeps `destroy()`'s
+ * follow-on `'close'` from re-invoking it.
+ *
+ * `stream` is injectable for tests; it defaults to `process.stdin`.
+ */
+export declare function treatStdinFailureAsShutdown(onTerminal: () => void, stream?: NodeJS.ReadableStream): void;
+//# sourceMappingURL=stdin-teardown.d.ts.map

package/sensor/dist/mcp/stdin-teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin-teardown.d.ts","sourceRoot":"","sources":["../../src/mcp/stdin-teardown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,IAAI,EACtB,MAAM,GAAE,MAAM,CAAC,cAA8B,GAC5C,IAAI,CAiBN"}

package/sensor/dist/mcp/stdin-teardown.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.treatStdinFailureAsShutdown = treatStdinFailureAsShutdown;
+/**
+ * Treat a stdin failure as a shutdown signal — issue #799.
+ *
+ * An MCP stdio server's lifeline is its stdin: when the host/client goes away,
+ * stdin should end and the server should exit. The server paths listened for
+ * `'end'` and `'close'` — but NOT `'error'`.
+ *
+ * That gap bites with a socket-backed stdin, which is the shape VS Code /
+ * Claude Code use (a socketpair, not a pipe). When the client dies, the socket
+ * can surface as an `'error'` (ECONNRESET / hangup) rather than a clean
+ * `'close'`. With no `'error'` listener, Node escalates it to the process-wide
+ * `uncaughtException` handler, which logs and keeps running — so the server
+ * orphans instead of exiting. Worse, on Linux a `POLLHUP` socket fd left
+ * registered in epoll wakes the event loop continuously, pinning a core at
+ * 100% CPU (the spin reported in #799); once the main thread spins, the
+ * `setInterval` PPID watchdog can't even fire, so the orphan runs forever.
+ *
+ * Fix: listen for `'error'` as well, and DESTROY the stdin stream on any
+ * terminal event so the fd leaves epoll and can't keep churning, then run the
+ * caller's shutdown. Fires `onTerminal` at most once — callers' shutdowns are
+ * already re-entry-guarded, but the single-shot guard also keeps `destroy()`'s
+ * follow-on `'close'` from re-invoking it.
+ *
+ * `stream` is injectable for tests; it defaults to `process.stdin`.
+ */
+function treatStdinFailureAsShutdown(onTerminal, stream = process.stdin) {
+    let fired = false;
+    const fire = () => {
+        if (fired)
+            return;
+        fired = true;
+        // Drop the fd from epoll so a hung/half-closed socket can't keep waking
+        // the loop. Best-effort: the stream may already be torn down.
+        try {
+            stream.destroy?.();
+        }
+        catch {
+            /* already gone */
+        }
+        onTerminal();
+    };
+    stream.on('end', fire);
+    stream.on('close', fire);
+    stream.on('error', fire);
+}
+//# sourceMappingURL=stdin-teardown.js.map

package/sensor/dist/mcp/stdin-teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin-teardown.js","sourceRoot":"","sources":["../../src/mcp/stdin-teardown.ts"],"names":[],"mappings":";;AAyBA,kEAoBC;AA7CD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,2BAA2B,CACzC,UAAsB,EACtB,SAAgC,OAAO,CAAC,KAAK;IAE7C,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,KAAK;YAAE,OAAO;QAClB,KAAK,GAAG,IAAI,CAAC;QACb,wEAAwE;QACxE,8DAA8D;QAC9D,IAAI,CAAC;YACF,MAAuC,CAAC,OAAO,EAAE,EAAE,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;QACD,UAAU,EAAE,CAAC;IACf,CAAC,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC"}