@reticlehq/server 2.4.0 → 2.6.0

package/dist/cloud/cloud-sync.js

@@ -15,18 +15,18 @@ export const CloudEnv = {
     KEY: 'RETICLE_CLOUD_KEY',
 };
 /** Paths the OSS server pushes to (match the cloud app's contract). */
-export const CLOUD_FLOWS_PATH = '/v1/flows';
-export const CLOUD_RUNS_PATH = '/v1/runs';
-export const CLOUD_PROJECT_RUNS_PATH = '/v1/project/runs';
-export const CLOUD_PROJECT_REGRESSION_PATH = '/v1/project/regression';
-export const CLOUD_VERIFICATIONS_PATH = '/v1/verifications';
+const CLOUD_FLOWS_PATH = '/v1/flows';
+const CLOUD_RUNS_PATH = '/v1/runs';
+const CLOUD_PROJECT_RUNS_PATH = '/v1/project/runs';
+const CLOUD_PROJECT_REGRESSION_PATH = '/v1/project/regression';
+const CLOUD_VERIFICATIONS_PATH = '/v1/verifications';
 /** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
 export function resolveCloudConfig(env) {
     const url = env[CloudEnv.URL];
     const apiKey = env[CloudEnv.KEY];
-    if (typeof url !== 'string' || url.length === 0)
+    if (typeof url !== 'string' || 0 === url.length)
         return null;
-    if (typeof apiKey !== 'string' || apiKey.length === 0)
+    if (typeof apiKey !== 'string' || 0 === apiKey.length)
         return null;
     return { url: url.replace(/\/+$/, ''), apiKey };
 }
@@ -40,7 +40,7 @@ export const SyncOutcome = {
  * throws — a failure is reported, not propagated, so the local save is authoritative.
  */
 export async function syncFlowToCloud(flow, config, projectId, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return { outcome: SyncOutcome.SKIPPED };
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_FLOWS_PATH}`, {
@@ -67,7 +67,7 @@ export async function syncFlowToCloud(flow, config, projectId, fetchImpl) {
  * built it), so the body is the run itself, not a wrapper. Best-effort: never throws, never blocks exit.
  */
 export async function syncRunToCloud(run, config, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return { outcome: SyncOutcome.SKIPPED };
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_RUNS_PATH}`, {
@@ -93,7 +93,7 @@ export async function syncRunToCloud(run, config, fetchImpl) {
  * truth). `projectId` scopes an org's multiple suites. Best-effort: never throws, never blocks the tool.
  */
 export async function syncRunRecordToCloud(record, projectId, config, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return { outcome: SyncOutcome.SKIPPED };
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_PROJECT_RUNS_PATH}`, {
@@ -127,7 +127,7 @@ export async function syncRunRecordToCloud(record, projectId, config, fetchImpl)
  * cloud), or null when not logged in / unreachable — so the caller degrades to local-only, never fails.
  */
 export async function fetchProjectRegressionFromCloud(config, projectId, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return null;
     try {
         const query = projectId === undefined ? '' : `?projectId=${encodeURIComponent(projectId)}`;
@@ -156,7 +156,7 @@ const ServerVerificationSchema = z.object({
  * submit fails, so the caller falls back to a local replay. Never throws.
  */
 export async function submitServerVerification(body, config, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return null;
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_VERIFICATIONS_PATH}`, {

package/dist/crawl/crawl-empty.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Why a crawl clicked nothing.
+ *
+ * `stepsRun: 0` came back with no `error` and nothing else, so "the page had no controls" and "it had
+ * 34 and none were clicked" were the same answer. Reported from a sweep on a page with 34 of them,
+ * and not reproducible here — crawl drives the bench app correctly — so the honest move is to make
+ * the zero carry its own diagnosis rather than guess at a cause.
+ */
+interface CrawlOutcome {
+    interactiveFound: number;
+    stepsRun: number;
+    maxSteps: number;
+    truncated: boolean;
+}
+export declare function crawlEmptyNote(outcome: CrawlOutcome): string | undefined;
+export {};

package/dist/crawl/crawl-empty.js

@@ -0,0 +1,24 @@
+/**
+ * Why a crawl clicked nothing.
+ *
+ * `stepsRun: 0` came back with no `error` and nothing else, so "the page had no controls" and "it had
+ * 34 and none were clicked" were the same answer. Reported from a sweep on a page with 34 of them,
+ * and not reproducible here — crawl drives the bench app correctly — so the honest move is to make
+ * the zero carry its own diagnosis rather than guess at a cause.
+ */
+export function crawlEmptyNote(outcome) {
+    if (outcome.stepsRun > 0)
+        return undefined;
+    if (outcome.maxSteps <= 0) {
+        return 'nothing was clicked because maxSteps is 0 — raise it to crawl at all';
+    }
+    if (0 === outcome.interactiveFound) {
+        const capped = outcome.truncated
+            ? ' The snapshot was also truncated, so controls past the cap were never seen — narrow `scope` and retry.'
+            : '';
+        return `no interactive controls were found on this page, so nothing was clicked — the crawl ran and found none, which is a result rather than a failure.${capped}`;
+    }
+    return (`${String(outcome.interactiveFound)} interactive controls were found and none of them were clicked. ` +
+        `That is not an empty page, so something stopped the loop — report it with reticle_feedback, ` +
+        `including this page's URL and one control's ref.`);
+}

package/dist/crawl/crawl-tools.js

@@ -37,6 +37,9 @@ export const CRAWL_TOOLS = [
         outputSchema: {
             interactiveFound: z.number(),
             stepsRun: z.number(),
+            // Present only when nothing was clicked, saying WHICH zero this is — an empty page, a step
+            // budget of zero, or controls found and none driven. A bare zero was unactionable.
+            note: z.string().optional(),
             anomalies: z.array(z.object({
                 kind: z.string(),
                 ref: z.string(),
@@ -64,7 +67,7 @@ export const CRAWL_TOOLS = [
                 ...(maxSteps !== undefined ? { maxSteps } : {}),
                 ...(settleMs !== undefined ? { settleMs } : {}),
                 ...(scope !== undefined ? { scope } : {}),
-                ...(args['confirmDangerous'] === true ? { confirmDangerous: true } : {}),
+                ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
             };
             return crawl(session, opts, nodeSleep);
         },

package/dist/crawl/crawl.js

@@ -1,4 +1,6 @@
+import { span } from '../trace.js';
 import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, ContradictionKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { crawlEmptyNote } from './crawl-empty.js';
 import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { findContradictions } from '../events/contradictions.js';
@@ -62,7 +64,7 @@ export async function crawl(session, opts, sleep) {
     // the controls it never reached are not merely unclicked — they were never seen. Reporting
     // `interactiveFound` without this would state a control count that is really a cap, and
     // `truncated:false` would positively assert that nothing was cut.
-    const coverageCapped = snapshot.truncated === true;
+    const coverageCapped = true === snapshot.truncated;
     const anomalies = [];
     const visited = [];
     const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
@@ -83,12 +85,18 @@ export async function crawl(session, opts, sleep) {
         session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
         let act;
         try {
-            act = await session.command(ReticleCommand.ACT, {
-                ref: item.ref,
-                action: ActionType.CLICK,
-                args: opts.confirmDangerous === true ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+            // One span per control clicked, so a slow crawl names the control rather than reporting a
+            // single multi-second total. The settle sleep below is INSIDE it deliberately: it is part of
+            // what a step costs, and hiding it would make the fixed budget look free.
+            act = await span('crawl.step', { ref: item.ref, desc: item.desc }, async () => {
+                const clicked = await session.command(ReticleCommand.ACT, {
+                    ref: item.ref,
+                    action: ActionType.CLICK,
+                    args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+                });
+                await sleep(settleMs);
+                return clicked;
             });
-            await sleep(settleMs);
         }
         finally {
             // Close on every exit so a throw cannot leak the window onto the next control's events.
@@ -147,7 +155,7 @@ export async function crawl(session, opts, sleep) {
         // noise for the false negative this check exists to catch.
         const dispatched = asRecord(act.result)['dispatched'] !== false && act.ok;
         if (dispatched &&
-            errs.length === 0 &&
+            0 === errs.length &&
             !events.some(isActivity) &&
             !legitimatelyInert(item.desc)) {
             counts.deadControls += 1;
@@ -171,5 +179,16 @@ export async function crawl(session, opts, sleep) {
         // partial sweep into "all controls healthy".
         truncated: items.length > stepsRun || coverageCapped,
         ...(coverageCapped ? { coverageNote: CAPPED_SNAPSHOT_NOTE } : {}),
+        // A bare `stepsRun: 0` made "the page had no controls" and "it had 34 and none were clicked" the
+        // same answer. See crawl-empty.
+        ...(() => {
+            const note = crawlEmptyNote({
+                interactiveFound: items.length,
+                stepsRun,
+                maxSteps,
+                truncated: coverageCapped,
+            });
+            return note === undefined ? {} : { note };
+        })(),
     };
 }

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

@@ -0,0 +1,73 @@
+/**
+ * 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 115-line daemon log containing zero of `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;
+/**
+ * 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.
+ */
+export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void): void;
+export {};

package/dist/daemon/daemon-resilience.js

@@ -0,0 +1,279 @@
+/**
+ * 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. Measured 2026-08-10/11: **84 of 84
+ * crash events were one fingerprint, `connect ECONNREFUSED`, and every affected user was in the
+ * never-verified set.** The proxy is BUILT to tolerate this — 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 invisible 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']);
+/** 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 `installCrashHandlers`: 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, {
+            // 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 115-line daemon log containing zero of `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.
+ */
+export function installProxyResilience(proc, log, onCrash = reportCrash) {
+    const expected = {
+        disconnected: 'reticle_mcp_proxy_client_disconnected',
+        unreachable: 'reticle_mcp_proxy_daemon_unreachable',
+    };
+    proc.on('unhandledRejection', (reason) => {
+        if (absorbExpected(reason, log, expected))
+            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 (absorbExpected(err, log, expected))
+            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);
+    });
+}

package/dist/daemon/daemon-usefulness.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether this daemon has ever been useful to anyone.
+ *
+ * Reticle is usually registered as a GLOBAL MCP server, so every agent session in every directory
+ * spawns it — including the three quarters of directories that are not web apps at all. Measured
+ * over a day: `stack` was null for 92 of 121 profiled projects, 50 were not even git repositories,
+ * and 74% of daemon sessions never called a single tool. Median daemon lifetime 28 minutes; total
+ * uptime across those sessions 10,816 minutes against 4.6 minutes of actual work — a duty cycle of
+ * **0.04%**.
+ *
+ * The existing idle-shutdown could never fire on any of it, because its predicate is
+ * `!agentConnected && …` and an attached agent keeps `agentConnected` true for the whole editor
+ * session. So a daemon sat for half an hour, in a directory with no app, doing nothing, holding
+ * memory and a port.
+ *
+ * The rule here is deliberately the most conservative one that still catches that population:
+ * a daemon is USELESS only if it has never served a tool call AND no browser has ever connected to
+ * it AND nothing is leased from the pool. All three are lifetime facts, not windows — so nothing
+ * transient trips it, and a daemon in this state provably holds no recording, baseline or session
+ * anybody could lose. When it does shut down, the MCP proxy reconnects and `ensureDaemon` spawns a
+ * fresh one on the next call, which is a path already exercised hundreds of times a day.
+ */
+export declare function noteToolCall(): void;
+export declare function everServedToolCall(): boolean;
+/** Tests only. */
+export declare function resetDaemonUsefulness(): void;
+interface UsefulnessFacts {
+    /** Has any tool been dispatched since this daemon booted? */
+    servedToolCall: boolean;
+    /** Has any browser session ever connected? */
+    everConnected: boolean;
+    /** Active pool leases — a lease means somebody is mid-flight even with no session yet. */
+    activeLeases: number;
+}
+/**
+ * True when the daemon has done nothing for anyone and has nothing to lose by exiting.
+ *
+ * Every clause is a LIFETIME fact. "No tool call in the last five minutes" would fire on a thinking
+ * pause; "no tool call ever" cannot.
+ */
+export declare function isUselessDaemon(facts: UsefulnessFacts): boolean;
+/** The little of SessionManager the idle predicate reads — structural, so a fake needs two methods. */
+interface IdleSessions {
+    count(): number;
+    everConnected(): boolean;
+}
+/** The little of BrowserPool it reads. */
+interface IdlePool {
+    activeCount(): number;
+}
+/**
+ * The daemon's whole "is anything happening" question.
+ *
+ * Two ways to be idle. The original — nobody attached, nothing connected. And the one that was
+ * missing: an agent IS attached but this daemon has never served a tool call and no browser has ever
+ * connected to it. `agentConnected` stays true for an entire editor session, so without the second
+ * clause the shutdown watcher could never fire on the 74% of daemons that spawn in a directory with
+ * no app and sit there for half an hour.
+ */
+export declare function buildIdlePredicate(agentConnected: () => boolean, sessions: IdleSessions, pool: IdlePool): () => boolean;
+export {};