@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/daemon/binding/daemon-status-probe.d.ts

@@ -0,0 +1,2 @@
+/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
+export declare function fetchStatus(port: number): Promise<unknown>;

package/dist/command/daemon/binding/daemon-status-probe.js

@@ -0,0 +1,48 @@
+import * as http from 'node:http';
+import { LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
+import { loopbackAgent } from '../../../surface/loopback-agent.js';
+/**
+ * The impure half of `probePresence`: ask the port whether a Reticle daemon is answering.
+ *
+ * It lives beside `port-presence.ts` rather than in `launch/` because every caller of
+ * `probePresence` passes it — status, doctor, kill, verify, drive, the daemon lifecycle and the
+ * MCP wake path all spell `probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })`.
+ * Filed under `launch/` it read as a launcher helper, and it is not one; the proxy could not reach
+ * it there without inventing a dependency on a directory it has no other business with.
+ *
+ * The rule it feeds stays pure and socket-free in `port-presence.ts`. That split is deliberate: a
+ * probe that starts lying is a different failure from a rule that does.
+ */
+/** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
+const STATUS_PROBE_TIMEOUT_MS = 1000;
+/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
+export function fetchStatus(port) {
+    return new Promise((resolve) => {
+        const req = http.get({
+            host: LOOPBACK_HOST,
+            port,
+            path: STATUS_PATH,
+            timeout: STATUS_PROBE_TIMEOUT_MS,
+            // Shares the proxy's keep-alive agent: the proxy calls this on every reconnect, and a socket
+            // per probe is the same churn the POST leg was fixed for.
+            agent: loopbackAgent,
+        }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => (body += chunk));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    resolve(undefined);
+                }
+            });
+        });
+        req.on('error', () => resolve(undefined));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(undefined);
+        });
+    });
+}

package/dist/command/daemon/binding/loopback-reach.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which of `localhost`'s two answers can actually reach the bridge.
+ *
+ * `localhost` is a name with two answers, and Windows Chrome tries the IPv6 one first. The daemon
+ * binds `127.0.0.1`, so `loopback-alias.ts` forwards `[::1]:port` to it — best-effort by contract,
+ * because a machine with IPv6 off or something already holding `[::1]:port` must not stop the daemon
+ * serving. When that alias does not open, the daemon is serving perfectly on IPv4 and the page's
+ * documented default URL cannot reach it. The daemon's own view is "the bridge was up for the whole
+ * window", and it is right.
+ *
+ * Nothing said which half was missing. The one record was a field on the `mcp_daemon_started` log
+ * line, so the condition that makes `localhost` unreachable on the platform with most of our
+ * installs was invisible unless somebody read the daemon's JSON. The install gate's Windows cell
+ * reports exactly this shape — `init` exits 1 with "the SDK IS in the page and never dialled", while
+ * the page's own console says it could not open a websocket to `ws://localhost:<port>` after three
+ * attempts, and the very next boot of the same scaffold connects — and none of the three causes that
+ * diagnosis offers is this one.
+ *
+ * This answers it by connecting, at the moment of the diagnosis, rather than by remembering what
+ * happened at startup: a probe is true about now, and a startup flag is true about startup.
+ */
+/** Which loopback addresses answered on the bridge port. */
+export interface LoopbackReach {
+    /** `127.0.0.1` answered — what the daemon binds. */
+    readonly v4: boolean;
+    /** `[::1]` answered — what `localhost` resolves to first on Windows. */
+    readonly v6: boolean;
+}
+/**
+ * Probe both halves of loopback on the bridge port.
+ *
+ * Both are attempted even when the first answers: the interesting result is the DISAGREEMENT, and
+ * learning that v4 works tells you nothing about the address the browser will actually pick.
+ */
+export declare function probeLoopbackReach(port: number): Promise<LoopbackReach>;
+/**
+ * True when the bridge is reachable as an IPv4 address and NOT as the name the SDK is told to dial.
+ *
+ * This is the whole condition worth naming. Both up is healthy; both down is an ordinary "the daemon
+ * is not there" that every other check already reports; v6-only cannot happen on a `127.0.0.1` bind.
+ */
+export declare function isLocalhostSplit(reach: LoopbackReach): boolean;

package/dist/command/daemon/binding/loopback-reach.js

@@ -0,0 +1,63 @@
+/**
+ * Which of `localhost`'s two answers can actually reach the bridge.
+ *
+ * `localhost` is a name with two answers, and Windows Chrome tries the IPv6 one first. The daemon
+ * binds `127.0.0.1`, so `loopback-alias.ts` forwards `[::1]:port` to it — best-effort by contract,
+ * because a machine with IPv6 off or something already holding `[::1]:port` must not stop the daemon
+ * serving. When that alias does not open, the daemon is serving perfectly on IPv4 and the page's
+ * documented default URL cannot reach it. The daemon's own view is "the bridge was up for the whole
+ * window", and it is right.
+ *
+ * Nothing said which half was missing. The one record was a field on the `mcp_daemon_started` log
+ * line, so the condition that makes `localhost` unreachable on the platform with most of our
+ * installs was invisible unless somebody read the daemon's JSON. The install gate's Windows cell
+ * reports exactly this shape — `init` exits 1 with "the SDK IS in the page and never dialled", while
+ * the page's own console says it could not open a websocket to `ws://localhost:<port>` after three
+ * attempts, and the very next boot of the same scaffold connects — and none of the three causes that
+ * diagnosis offers is this one.
+ *
+ * This answers it by connecting, at the moment of the diagnosis, rather than by remembering what
+ * happened at startup: a probe is true about now, and a startup flag is true about startup.
+ */
+import net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+import { IPV6_LOOPBACK } from './loopback-alias.js';
+/** Long enough for a loopback TCP handshake, short enough to sit inside a diagnosis. */
+const REACH_TIMEOUT_MS = 500;
+/** Can a TCP connection be opened to this address and port at all. */
+function canConnect(host, port) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        const settle = (answer) => {
+            socket.destroy();
+            resolve(answer);
+        };
+        socket.setTimeout(REACH_TIMEOUT_MS, () => settle(false));
+        socket.once('connect', () => settle(true));
+        // Refused, unreachable, IPv6 disabled entirely — all of them are "this address does not answer",
+        // which is the only question being asked. An unhandled 'error' here would take down the caller.
+        socket.once('error', () => settle(false));
+    });
+}
+/**
+ * Probe both halves of loopback on the bridge port.
+ *
+ * Both are attempted even when the first answers: the interesting result is the DISAGREEMENT, and
+ * learning that v4 works tells you nothing about the address the browser will actually pick.
+ */
+export async function probeLoopbackReach(port) {
+    const [v4, v6] = await Promise.all([
+        canConnect(LOOPBACK_HOST, port),
+        canConnect(IPV6_LOOPBACK, port),
+    ]);
+    return { v4, v6 };
+}
+/**
+ * True when the bridge is reachable as an IPv4 address and NOT as the name the SDK is told to dial.
+ *
+ * This is the whole condition worth naming. Both up is healthy; both down is an ordinary "the daemon
+ * is not there" that every other check already reports; v6-only cannot happen on a `127.0.0.1` bind.
+ */
+export function isLocalhostSplit(reach) {
+    return reach.v4 && !reach.v6;
+}

package/dist/command/daemon/daemon-resilience.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
+ * single stray error must not take the whole fleet down:
+ *
+ * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
+ * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
+ * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
+ * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
+ * daemon, which beats crashing silently or limping along corrupt.
+ */
+export interface ProcessLike {
+    on(event: string, listener: (arg: unknown) => void): unknown;
+}
+type LogFn = (event: string, data: Record<string, unknown>) => void;
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export declare const CrashKind: {
+    readonly UNHANDLED_REJECTION: "unhandled_rejection";
+    readonly UNCAUGHT_EXCEPTION: "uncaught_exception";
+};
+export type CrashKind = (typeof CrashKind)[keyof typeof CrashKind];
+/**
+ * Log EVERY way this process can leave, so a death always leaves a line.
+ *
+ * Reported from the field: a daemon log containing not one `reticle_daemon_idle_exit`,
+ * `reticle_daemon_close_error`, `daemon_stopped`, `uncaught` or `unhandled` — the daemon simply
+ * stopped existing mid-wait. Both crash handlers below already log before exiting, so their silence
+ * ruled themselves out and left nothing else to read: no shutdown path had run at all.
+ *
+ * `exit` fires for every in-process exit including an explicit `process.exit`, and carries the code.
+ * The signals cover an external kill. What neither can catch is SIGKILL or an OOM abort — and that
+ * is the point: after this, silence in the log is itself the finding, because every other door is
+ * now instrumented.
+ */
+/**
+ * Why the daemon is going away — carried ON the exit line, not left to be inferred.
+ *
+ * From the field (#123): a real gate log read `reticle_daemon_signalled SIGTERM` then
+ * `reticle_daemon_exiting code:0`, then 21 seconds with nothing listening. `code: 0` is the last
+ * line before the port goes dark and it cannot distinguish "shut down tidily" from "the bridge every
+ * app on this machine needs is now gone". A correct install was written up as a failure naming the
+ * fixture because of it.
+ *
+ * `UNKNOWN` is the load-bearing member, not a fallback: it means the process left through Node
+ * WITHOUT passing a shutdown path — an uncaught throw, a stray `process.exit`. That is a different
+ * fact from an idle exit, and the one worth noticing.
+ */
+export declare const DaemonExitReason: {
+    /** A shutdown signal arrived (SIGTERM/SIGINT). */
+    readonly SIGNAL: "signal";
+    /** The idle timer fired and the daemon retired itself. */
+    readonly IDLE: "idle";
+    /** Left through Node, but not via any shutdown path we own. */
+    readonly UNKNOWN: "unknown";
+};
+export type DaemonExitReason = (typeof DaemonExitReason)[keyof typeof DaemonExitReason];
+/** Record why the daemon is shutting down. Called by a shutdown path before it exits. */
+export declare function recordExitReason(reason: DaemonExitReason): void;
+export declare function installExitTrace(proc: ProcessLike, log: LogFn): void;
+export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, onFatal: () => void): void;
+/** The handle the proxy keeps, so it can say when a session proved itself usable. */
+export interface ProxyResilience {
+    /**
+     * A stream reached an `endpoint` frame: there is a working session, so whatever disconnects came
+     * before it were reconnects rather than a runaway.
+     *
+     * The same signal that already earns a fresh RETRY budget in `mcp-proxy.ts`, and chosen there for
+     * the same reason: response headers are produced by a daemon that accepts SSE and drops it, and an
+     * `endpoint` frame is not.
+     */
+    noteUsableSession(): void;
+}
+/**
+ * Process-level resilience for the MCP PROXY, whose rule is the opposite of the daemon's.
+ *
+ * The daemon exits on an uncaught throw because the next `reticle mcp` respawns it. Nothing respawns
+ * the proxy — it is the stdio server the editor launched, and its exit is what the user experiences
+ * as "the MCP server disconnected, open /mcp and reconnect". So it logs and keeps serving: its whole
+ * state is a socket and a queue, and it already knows how to rebuild both (see the reconnect and
+ * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
+ * dead one answers nothing and needs a human.
+ *
+ * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
+ * it is the subject of DISCONNECT_STORM below.
+ */
+export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void, onGone?: () => void): ProxyResilience;
+export {};

package/dist/command/daemon/daemon-resilience.js

@@ -0,0 +1,339 @@
+/**
+ * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
+ * single stray error must not take the whole fleet down:
+ *
+ * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
+ * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
+ * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
+ * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
+ * daemon, which beats crashing silently or limping along corrupt.
+ */
+import { RETICLE_DEFAULT_PORT, TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { errorSkeleton, errorTypeOf, fingerprintCrash, MAX_REPORTED_FRAMES, reticleFrames, } from '../../telemetry/error-fingerprint.js';
+import { getSessionMetrics } from '../../telemetry/session-metrics.js';
+import { machineSnapshot } from '../../telemetry/machine-snapshot.js';
+import { crashCause } from '../../telemetry/crash-cause.js';
+import { getTelemetry } from '../../telemetry/telemetry.js';
+function describe(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+/**
+ * Node error codes that mean THE OTHER END WENT AWAY, not "we broke".
+ *
+ * One real session produced nine `runtime_crashed` events, all `write EPIPE`: the MCP client closed
+ * its half of the stdio pipe and the very next `process.stdout.write` failed, which is the ordinary
+ * way a client leaves. Counted as uncaught exceptions they poison the only metric that answers "is
+ * Reticle stable?" — and they recur every single time an editor is closed.
+ *
+ * Matched on `err.code`, never on the message: a message is prose, gets wrapped, localised and
+ * rewritten, and matching it would eventually swallow a real crash that merely mentioned a pipe.
+ *
+ * - `EPIPE` — wrote to a pipe whose reader is gone. The stdio case, and the nine.
+ * - `ECONNRESET` — the peer reset the socket; stdio is a socket when the parent piped it, and the
+ *   HTTP/SSE surface produces it when a client vanishes mid-response.
+ * - `ERR_STREAM_DESTROYED` — the same race one tick later: the stream was already torn down when
+ *   the write landed.
+ */
+const DISCONNECT_CODES = new Set([
+    'EPIPE',
+    'ECONNRESET',
+    'ERR_STREAM_DESTROYED',
+]);
+/**
+ * Nobody went away — nobody was ever there. A refused connect is the daemon not being up YET.
+ *
+ * This is the difference that made `runtime_crashed` useless. The proxy is BUILT to tolerate a
+ * refused connect — it answers the handshake from cache and wakes a daemon on the next request — so
+ * reporting it as a crash meant the one metric that is supposed to say "Reticle broke" said nothing
+ * but "the daemon had not booted yet", and a real crash would have been buried underneath it.
+ *
+ * Absorbed, not silenced: it still logs, and the outage it belongs to is already counted as
+ * `connect_error` on `mcp_connection_lost`, which is the metric that can actually act on it.
+ */
+const UNREACHABLE_CODES = new Set(['ECONNREFUSED']);
+/**
+ * How many absorbed client disconnects mean the client is GONE rather than between reconnects.
+ *
+ * Absorbing a disconnect and continuing is right for one: the client closed a socket, the proxy
+ * rebuilds it. It is catastrophic for a stream of them, because the write that failed is retried
+ * immediately, fails identically, and is absorbed again — a tight loop with no backoff and no exit.
+ *
+ * Left unbounded, such a proxy can pin a core for days after its editor closed, emitting identical
+ * log lines, with no daemon-side symptom at all: the daemon beside it reports healthy and
+ * `sessions: 0`, so it is findable only by running `ps` by hand.
+ *
+ * Chosen well above the handful a genuine reconnect produces and far below a runaway. The proxy's
+ * whole purpose is to be the stdio server its editor launched; once that editor is gone there is
+ * nobody left to serve, and the correct thing is to leave rather than to burn a core proving it.
+ */
+const DISCONNECT_STORM = 20;
+/** The expected-failure code this value carries, and which class it belongs to. */
+function expectedCode(value) {
+    const raw = value?.code;
+    if ('string' !== typeof raw)
+        return undefined;
+    if (DISCONNECT_CODES.has(raw))
+        return { code: raw, unreachable: false };
+    if (UNREACHABLE_CODES.has(raw))
+        return { code: raw, unreachable: true };
+    return undefined;
+}
+/**
+ * Log an expected failure and report `true`, so the caller skips the crash report.
+ *
+ * It is still WRITTEN DOWN. A client leaving is normal, but a daemon that suddenly logs a hundred of
+ * these is a finding — the difference between "not a crash" and "not worth knowing" is the whole
+ * reason this logs instead of returning early in silence.
+ */
+function absorbExpected(value, log, events) {
+    const hit = expectedCode(value);
+    if (hit === undefined)
+        return false;
+    log(hit.unreachable ? events.unreachable : events.disconnected, {
+        code: hit.code,
+        note: hit.unreachable
+            ? 'the daemon was not reachable — expected while it boots, not a crash'
+            : 'the client went away — expected, not a crash',
+    });
+    return true;
+}
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export const CrashKind = {
+    UNHANDLED_REJECTION: 'unhandled_rejection',
+    UNCAUGHT_EXCEPTION: 'uncaught_exception',
+};
+/**
+ * The ports Reticle itself uses, so a refusal can be classified as ours or somebody else's.
+ *
+ * Read here rather than threaded through `installDaemonResilience`: a crash handler is installed once,
+ * at startup, and the port can be set after it. The values are only ever compared against — the
+ * port a crash names is turned into an enum and then discarded.
+ */
+function knownPorts() {
+    const configured = Number(process.env['RETICLE_PORT']);
+    return Number.isInteger(configured) && configured > 0
+        ? [RETICLE_DEFAULT_PORT, configured]
+        : [RETICLE_DEFAULT_PORT];
+}
+/**
+ * Report a crash with enough detail to actually diagnose it.
+ *
+ * This is the only place in the product that learns about a crash at all. An uncaught exception in a
+ * long-running daemon takes down every agent attached to it, and the only other record is a line in a
+ * local log nobody sends us.
+ *
+ * The first version sent a hash and nothing else, which made crashes rankable and undiagnosable — you
+ * could see that forty machines hit `a3f2c1d8e9b0` and had no way to learn what that was. So it now
+ * carries the four things an RCA needs: WHERE (our own frames, with function names and line numbers),
+ * WHAT (the message with every variable part stripped), WHEN (the tool in flight), and WHY-ish (the
+ * agent's approach run before it). All of it is our code and our vocabulary; the user's stack frames,
+ * their paths, and the contents of their message are removed before any of it is built.
+ *
+ * Best-effort and wrapped: reporting a crash must never be the reason a crash gets worse.
+ */
+function reportCrash(kind, value) {
+    try {
+        const errorType = errorTypeOf(value);
+        const stack = value instanceof Error ? (value.stack ?? '') : '';
+        const message = describe(value);
+        const { breadcrumb, inFlight } = getSessionMetrics().trail;
+        const machine = machineSnapshot();
+        // Where the frames cannot say. A refused socket's stack is entirely node internals, so
+        // `reticleFrames` correctly keeps nothing and the report lands with no location at all — the
+        // single commonest crash shape in a loopback-heavy tool.
+        const cause = crashCause(value, knownPorts());
+        void getTelemetry().emit(TelemetryEventKind.RUNTIME_CRASHED, {
+            /*
+             * DETACHED, because the fatal path exits immediately behind this call.
+             *
+             * `uncaughtException` reports the crash and then calls `onFatal`, which is
+             * `process.exit(1)` in `cli.ts`. An in-process send has a 2s budget and gets microseconds, so
+             * every crash report on the path that actually kills the daemon was being dropped: the one
+             * class of event you cannot ask the user to reproduce, lost precisely when it fired. A
+             * disowned child outlives the exit and sends it.
+             *
+             * This is the `daemon_stopped` bug again, one handler over. That one was emitted
+             * fire-and-forget before `process.exit(0)`, nothing threw, no test reddened, and the data was
+             * gone for months.
+             */
+            detach: true,
+            // A crash is ALWAYS reached through something the agent asked for — the daemon does nothing on
+            // its own — so attributing it to the agent is accurate rather than a guess.
+            actor: TelemetryActor.AGENT,
+            crash: {
+                kind,
+                errorType,
+                fingerprint: fingerprintCrash(errorType, stack, message),
+                // The skeleton, not the message: every quoted string, path, URL, id and number is replaced
+                // by `*` first. This is what makes the fingerprint mean something to a human reading a chart.
+                message: errorSkeleton(message).slice(0, 300),
+                // Our own frames, our own published code. The file, the line, and the function — which is the
+                // whole of "where did it break". Frames from the user's app never survive this.
+                frames: reticleFrames(stack).slice(0, MAX_REPORTED_FRAMES),
+                ...(inFlight !== undefined ? { tool: inFlight } : {}),
+                ...(breadcrumb.length > 0 ? { breadcrumb } : {}),
+                // Crashes cluster hard by runtime version and architecture, and we were recording neither.
+                nodeVersion: process.versions.node,
+                arch: process.arch,
+                // "Out of memory" and "our bug" look identical in a stack trace. This is what tells them apart.
+                ...(machine !== undefined ? { machine } : {}),
+                // The syscall, the errno, whether it was loopback, whether the port was ours, and the
+                // innermost frame in NODE's own source. Present only when the error carries them.
+                ...cause,
+            },
+        });
+    }
+    catch {
+        /* a crash report must never be the reason a crash gets worse */
+    }
+}
+/**
+ * Log EVERY way this process can leave, so a death always leaves a line.
+ *
+ * Reported from the field: a daemon log containing not one `reticle_daemon_idle_exit`,
+ * `reticle_daemon_close_error`, `daemon_stopped`, `uncaught` or `unhandled` — the daemon simply
+ * stopped existing mid-wait. Both crash handlers below already log before exiting, so their silence
+ * ruled themselves out and left nothing else to read: no shutdown path had run at all.
+ *
+ * `exit` fires for every in-process exit including an explicit `process.exit`, and carries the code.
+ * The signals cover an external kill. What neither can catch is SIGKILL or an OOM abort — and that
+ * is the point: after this, silence in the log is itself the finding, because every other door is
+ * now instrumented.
+ */
+/**
+ * Why the daemon is going away — carried ON the exit line, not left to be inferred.
+ *
+ * From the field (#123): a real gate log read `reticle_daemon_signalled SIGTERM` then
+ * `reticle_daemon_exiting code:0`, then 21 seconds with nothing listening. `code: 0` is the last
+ * line before the port goes dark and it cannot distinguish "shut down tidily" from "the bridge every
+ * app on this machine needs is now gone". A correct install was written up as a failure naming the
+ * fixture because of it.
+ *
+ * `UNKNOWN` is the load-bearing member, not a fallback: it means the process left through Node
+ * WITHOUT passing a shutdown path — an uncaught throw, a stray `process.exit`. That is a different
+ * fact from an idle exit, and the one worth noticing.
+ */
+export const DaemonExitReason = {
+    /** A shutdown signal arrived (SIGTERM/SIGINT). */
+    SIGNAL: 'signal',
+    /** The idle timer fired and the daemon retired itself. */
+    IDLE: 'idle',
+    /** Left through Node, but not via any shutdown path we own. */
+    UNKNOWN: 'unknown',
+};
+/**
+ * Set by whichever shutdown path is running, read once by the exit handler.
+ *
+ * A module-level value rather than a parameter because the two are separated by the whole process
+ * lifetime: the reason is known when shutdown STARTS and the exit line is written when Node is on
+ * its way out. Exit runs once, on one thread, after everything else — so there is nothing to race.
+ */
+let exitReason = DaemonExitReason.UNKNOWN;
+/** Record why the daemon is shutting down. Called by a shutdown path before it exits. */
+export function recordExitReason(reason) {
+    exitReason = reason;
+}
+export function installExitTrace(proc, log) {
+    proc.on('exit', (code) => {
+        log('reticle_daemon_exiting', {
+            code: 'number' === typeof code ? code : null,
+            reason: exitReason,
+        });
+    });
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+        proc.on(signal, () => {
+            // Log only. Whatever installed a real handler for this signal still runs; adding an exit here
+            // would race the shutdown that flushes the session summary.
+            log('reticle_daemon_signalled', { signal });
+        });
+    }
+}
+export function installDaemonResilience(proc, log, onFatal) {
+    installExitTrace(proc, log);
+    const expected = {
+        disconnected: 'reticle_daemon_client_disconnected',
+        unreachable: 'reticle_daemon_peer_unreachable',
+    };
+    proc.on('unhandledRejection', (reason) => {
+        if (absorbExpected(reason, log, expected))
+            return;
+        log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
+        reportCrash(CrashKind.UNHANDLED_REJECTION, reason);
+    });
+    proc.on('uncaughtException', (err) => {
+        // Not fatal either: Node's "the process state is undefined" guidance is about a throw that
+        // escaped everything, not about a write to a socket somebody closed. Exiting here would let one
+        // departing client take down the daemon serving every other agent.
+        if (absorbExpected(err, log, expected))
+            return;
+        log('reticle_daemon_uncaught_exception', { error: describe(err) });
+        reportCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
+        onFatal();
+    });
+}
+/**
+ * Process-level resilience for the MCP PROXY, whose rule is the opposite of the daemon's.
+ *
+ * The daemon exits on an uncaught throw because the next `reticle mcp` respawns it. Nothing respawns
+ * the proxy — it is the stdio server the editor launched, and its exit is what the user experiences
+ * as "the MCP server disconnected, open /mcp and reconnect". So it logs and keeps serving: its whole
+ * state is a socket and a queue, and it already knows how to rebuild both (see the reconnect and
+ * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
+ * dead one answers nothing and needs a human.
+ *
+ * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
+ * it is the subject of DISCONNECT_STORM below.
+ */
+export function installProxyResilience(proc, log, onCrash = reportCrash, onGone = () => process.exit(0)) {
+    const expected = {
+        disconnected: 'reticle_mcp_proxy_client_disconnected',
+        unreachable: 'reticle_mcp_proxy_daemon_unreachable',
+    };
+    // "Absorb the disconnect and keep serving" is right for ONE disconnect and catastrophic for a
+    // stream of them — see DISCONNECT_STORM. Counted since the last USABLE SESSION rather than since
+    // this process started: a lifetime tally reaches the threshold on a working week, because the
+    // classifier reads `ECONNRESET` as "the peer vanished" and on this leg the peer is the DAEMON,
+    // which restarts routinely and is the thing the proxy exists to survive.
+    let disconnects = 0;
+    let gone = false;
+    const absorb = (value) => {
+        if (!absorbExpected(value, log, expected))
+            return false;
+        if (false === expectedCode(value)?.unreachable) {
+            disconnects += 1;
+            if (disconnects >= DISCONNECT_STORM && !gone) {
+                gone = true;
+                log('reticle_mcp_proxy_client_gone', {
+                    disconnects,
+                    note: 'the client end is gone for good, not between reconnects — exiting instead of retrying forever',
+                });
+                onGone();
+            }
+        }
+        return true;
+    };
+    const noteUsableSession = () => {
+        // Not after `gone`: the process is already leaving, and a late frame must not look like a
+        // reason to stay. Nothing brings the proxy back from `onGone` by design.
+        if (gone)
+            return;
+        disconnects = 0;
+    };
+    proc.on('unhandledRejection', (reason) => {
+        if (absorb(reason))
+            return;
+        log('reticle_mcp_proxy_unhandled_rejection', { reason: describe(reason) });
+        onCrash(CrashKind.UNHANDLED_REJECTION, reason);
+    });
+    proc.on('uncaughtException', (err) => {
+        // The client closing its end of stdio is how this process is SUPPOSED to end its day.
+        if (absorb(err))
+            return;
+        log('reticle_mcp_proxy_uncaught_exception', {
+            error: describe(err),
+            note: 'still serving — exiting here would disconnect the MCP client',
+        });
+        onCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
+    });
+    return { noteUsableSession };
+}