@reticlehq/server 2.5.0 → 2.7.0

package/dist/cli/port-holder.js

@@ -0,0 +1,99 @@
+/**
+ * Who is holding the bridge port.
+ *
+ * `doctor` is what a user runs when the agent cannot reach the bridge, and the commonest real cause
+ * is that something else is on 4400. It already stopped saying "nothing is listening" for that case,
+ * but it did not say WHICH process — so the reader's next move was a shell command they had to know.
+ *
+ * Naming the holder is also the safe answer to a trap this project has hit for real: the obvious
+ * lookup, `lsof -ti tcp:4400 | xargs kill -9`, ALSO kills the agent's own `reticle mcp` proxy,
+ * because that proxy holds a client connection to the same port and `-ti` does not filter to
+ * listeners. Every invocation here is `-sTCP:LISTEN`, and the message never suggests `-ti`.
+ *
+ * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
+ * while the shelling out stays at the call site.
+ */
+/** `lsof -F pc` emits one field per line, prefixed by its selector: `p<pid>`, `c<command>`. */
+const PID_FIELD = 'p';
+const COMMAND_FIELD = 'c';
+/**
+ * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
+ *
+ * First, not "the only one": a dual-stack listener (IPv4 + IPv6) is reported twice, and on a port
+ * conflict the answer the reader needs is "something is there, here is what" rather than an
+ * exhaustive list. A second `p` record ends the first.
+ *
+ * Null on anything incomplete. Half an answer — a pid with no command — prints worse than the
+ * un-named message it would replace, which is the same mistake as the port lie this command fixed.
+ */
+export function parsePortHolder(stdout) {
+    let pid;
+    let command;
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (0 === line.length)
+            continue;
+        const value = line.slice(1);
+        if (line.startsWith(PID_FIELD)) {
+            if (pid !== undefined)
+                break; // a second record: the first one is the answer
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed <= 0)
+                return null;
+            pid = parsed;
+            continue;
+        }
+        if (line.startsWith(COMMAND_FIELD) && command === undefined)
+            command = value;
+    }
+    return pid === undefined || command === undefined ? null : { pid, command };
+}
+/** What `doctor` prints for a port held by something that is not a Reticle daemon. */
+export function describeForeignHolder(port, holder, 
+/**
+ * The pid we recorded for this port, from the daemon pid file.
+ *
+ * When it matches the process actually holding the port, the port is held by OUR daemon — one
+ * that accepts TCP and never answers `/status`, i.e. wedged. That classifies as FOREIGN, which is
+ * right for "can anything bind this?" and wrong to say out loud: the reader goes hunting a
+ * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
+ */
+ourPid) {
+    const tail = 'a daemon cannot bind it. Stop that process, or run Reticle on a different port ' +
+        '(`--port`), then retry.';
+    if (null === holder) {
+        /**
+         * We could not identify the holder — no `lsof` (every Windows user, and 35% of them by the
+         * 2026-08 telemetry; also a slim container), or the lookup timed out.
+         *
+         * This used to assert the port was held by "another process that is not a Reticle daemon",
+         * which is a claim the null case has NO evidence for. It is also the likeliest thing to be
+         * wrong: reaching here at all means presence is FOREIGN — the port accepts TCP and never
+         * answers `/status` — and the commonest cause of that is OUR OWN daemon, wedged. So on the one
+         * platform where the lookup cannot run, `doctor` sent the reader hunting a stranger and never
+         * named `reticle stop`, the fix that actually works.
+         *
+         * Say what is known, and name the recorded pid when there is one.
+         */
+        const ours = ourPid !== null && ourPid !== undefined
+            ? ` Reticle's own records show pid ${String(ourPid)} for this port — if that process is ` +
+                'still around it is a wedged Reticle daemon, and `reticle stop` clears it.'
+            : '';
+        return `port ${String(port)} is held by a process Reticle could not identify — ${tail}${ours}`;
+    }
+    if (ourPid !== null && ourPid !== undefined && ourPid === holder.pid) {
+        return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.pid)}), and it is ` +
+            'not responding — running but wedged, so nothing can use it and nothing else can bind the ' +
+            'port. Stop it with `reticle stop`; the next tool call starts a fresh one.');
+    }
+    return (`port ${String(port)} is held by pid ${String(holder.pid)} ("${holder.command}"), which is not ` +
+        `a Reticle daemon — ${tail}`);
+}
+/** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
+export function findPortHolder(port, exec) {
+    // -n/-P skip DNS and service-name lookups (slow, and irrelevant here). -sTCP:LISTEN is the part
+    // that matters: without it this also reports the agent's own MCP proxy, which is a client of the
+    // port, not its owner.
+    const out = exec('lsof', ['-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-F', 'pc']);
+    return null === out ? null : parsePortHolder(out);
+}

package/dist/cli.js

@@ -2,6 +2,8 @@
 import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
+import { stateDirProblem } from './daemon/state-dir.js';
+import { reticleStateHome } from './daemon/daemon.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { loadDotEnv } from './telemetry/dev-repo.js';
@@ -13,10 +15,13 @@ import { start, startDaemon } from './index.js';
 import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/server-version.js';
 import { log } from './log.js';
-import { readPid, isAlive, isRunning, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
+import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, logPath, } from './daemon/daemon.js';
+import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/port-presence.js';
 import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from './mcp/mcp-proxy.js';
-import { installDaemonResilience, installProxyResilience } from './daemon/daemon-resilience.js';
+import { installDaemonResilience, installProxyResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
+import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/heartbeat.js';
+import { everServedToolCall } from './daemon/daemon-usefulness.js';
 import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, } from './cli/cli-launch.js';
 import { handleVerify } from './cli/cli-verify.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
@@ -45,10 +50,38 @@ function handleInit(parsed) {
         process.exit(1);
 }
 function handleServe(parsed) {
-    if (isRunning(parsed.port)) {
+    void serveWithHonestExit(parsed);
+}
+/**
+ * Report the BIND, not the spawn.
+ *
+ * `serve` used to log `reticle_daemon_spawned` and exit 0 unconditionally, while the child died at
+ * `reticle_daemon_start_failed` with an EADDRINUSE nothing joined back to the parent. Three surfaces
+ * then disagreed about what was true and none of them named the port.
+ *
+ * Two changes, both about saying what is actually the case: refuse up front when the port is held by
+ * something that is not a Reticle daemon (a spawn there cannot succeed), and after spawning, wait
+ * for the daemon to actually answer before claiming it started.
+ */
+async function serveWithHonestExit(parsed) {
+    const presence = await probePresence(parsed.port, {
+        tcpOpen: probeDaemon,
+        status: fetchStatus,
+    });
+    if (presence === PortPresence.DAEMON) {
         log('reticle_daemon_already_running', { port: parsed.port });
         return;
     }
+    if (presence === PortPresence.FOREIGN) {
+        log('reticle_daemon_start_refused', {
+            port: parsed.port,
+            presence,
+            reason: describePresence(presence, parsed.port),
+        });
+        process.stderr.write(`${describePresence(presence, parsed.port)}\n`);
+        process.exit(1);
+        return;
+    }
     const scriptPath = process.argv[1];
     if (scriptPath === undefined) {
         log('reticle_serve_no_script', {});
@@ -69,8 +102,51 @@ function handleServe(parsed) {
             daemonArgs.push(HTTP_TOKEN_FLAG, parsed.httpToken);
     }
     spawnDaemon(process.execPath, scriptPath, daemonArgs, parsed.port);
+    // The child binds asynchronously and, when it cannot, exits 1 long after this process would have
+    // reported success. Wait for it to ANSWER — `/status` responding is the only evidence a daemon
+    // exists that does not come from the pid file the child may never have earned.
+    const bound = await waitForPresence(parsed.port, PortPresence.DAEMON, SERVE_BIND_TIMEOUT_MS);
+    if (!bound) {
+        const settled = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
+        log('reticle_daemon_start_failed_parent', {
+            port: parsed.port,
+            presence: settled,
+            reason: describePresence(settled, parsed.port),
+            log: logPath(parsed.port),
+            stateDir: stateDirProblem(reticleStateHome()) === undefined ? 'writable' : 'unwritable',
+        });
+        // Name the CAUSE when we can see it. An unwritable state directory is a first-run failure mode
+        // (locked-down home, read-only container mount, managed profile) that produced only "nothing is
+        // listening" — the symptom restated — and then pointed at a log INSIDE that directory, which
+        // cannot exist. Found by stress-testing 2.6.0 with `chmod 555 ~/.reticle`.
+        const dirProblem = stateDirProblem(reticleStateHome());
+        process.stderr.write(dirProblem === undefined
+            ? `the daemon did not come up on :${String(parsed.port)} — ${describePresence(settled, parsed.port)}\n` +
+                `see ${logPath(parsed.port)}\n`
+            : `the daemon did not come up on :${String(parsed.port)}.\n${dirProblem}\n`);
+        process.exit(1);
+        return;
+    }
     log('reticle_daemon_spawned', { port: parsed.port, ...(parsed.http ? { http: true } : {}) });
 }
+/** How long `serve` waits for the child to bind. Generous: a cold daemon start is seconds. */
+const SERVE_BIND_TIMEOUT_MS = 15_000;
+const PRESENCE_POLL_MS = 150;
+/** How long a daemon gets to shut down on its own before `stop` stops asking politely. */
+const GRACEFUL_STOP_MS = 5000;
+/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
+const FORCED_STOP_MS = 2000;
+async function waitForPresence(port, want, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presence === want)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, PRESENCE_POLL_MS));
+    }
+}
 function handleStop(port, quiet) {
     const pid = readPid(port);
     if (null === pid || !isAlive(pid)) {
@@ -81,18 +157,35 @@ function handleStop(port, quiet) {
     }
     process.kill(pid, 'SIGTERM');
     const started = Date.now();
+    let escalated = false;
     const poll = setInterval(() => {
         if (!isAlive(pid)) {
             clearInterval(poll);
             removePid(port);
             if (!quiet)
-                log('reticle_daemon_stopped', { port, pid });
+                log('reticle_daemon_stopped', { port, pid, ...(escalated ? { escalated } : {}) });
+            return;
+        }
+        const waited = Date.now() - started;
+        // A daemon that ignores SIGTERM is WEDGED — which is the one situation `stop` exists for. Giving
+        // up here left the port held, the pid file stale, and a human running `kill -9` by hand at the
+        // first two minutes of setup. Escalate instead: graceful first, then unconditional.
+        if (!escalated && waited > GRACEFUL_STOP_MS) {
+            escalated = true;
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone between the liveness check and here — the next tick reports it stopped.
+            }
             return;
         }
-        if (Date.now() - started > 5000) {
+        if (waited > GRACEFUL_STOP_MS + FORCED_STOP_MS) {
             clearInterval(poll);
+            // Surviving SIGKILL means the pid is not ours to kill (permissions) or is an unkillable
+            // zombie. Neither is retryable, and both need the pid named so a human can act on it.
             if (!quiet)
-                log('reticle_daemon_stop_timeout', { port, pid });
+                log('reticle_daemon_stop_timeout', { port, pid, escalated });
             process.exit(1);
         }
     }, 100);
@@ -100,7 +193,16 @@ function handleStop(port, quiet) {
 function handleStatus(port) {
     const pid = readPid(port);
     if (null === pid || !isAlive(pid)) {
-        log('reticle_status', { port, running: false });
+        // `running: false` on its own has been reported about a port that was demonstrably occupied,
+        // because the pid file is not the port. Ask the port before answering.
+        void probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then((presence) => {
+            log('reticle_status', {
+                port,
+                running: presenceIsUsable(presence),
+                presence,
+                ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+            });
+        });
         return;
     }
     // The daemon is up — ask it for live sessions + health so status is at-a-glance, not just a pid.
@@ -279,11 +381,21 @@ function handleOpen(requestedPort, url) {
             ...(connected
                 ? {}
                 : {
-                    note: 'the browser was launched but no Reticle session appeared. The app may still be ' +
-                        'loading, or it is not wired to this bridge — run `reticle doctor`, and check the ' +
-                        'app connects on port ' +
-                        String(port) +
-                        '.',
+                    // Two claims used to live here that this command cannot support. It said the browser
+                    // "was launched" — it asked the OS to open a URL and cannot see whether a window
+                    // appeared — and it offered "the app may still be loading" as a cause with equal
+                    // weight to the real one. It then pointed at `reticle doctor`, whose Chromium check is
+                    // about a browser THIS command never uses, so a missing Chromium reads as the
+                    // explanation for a session that is missing for an unrelated reason. Both misdirects
+                    // were reported from the field, each costing several calls of app-side wiring hunt.
+                    note: `the URL was handed to the system default browser (this command does not use ` +
+                        `Reticle's own Chromium, so a chromium warning from \`reticle doctor\` is unrelated ` +
+                        `to this). No Reticle session appeared. By far the likeliest cause is that the app ` +
+                        `carries no Reticle SDK, or dials a port other than ${String(port)} — run ` +
+                        `\`reticle init\` in the app's directory and restart its dev server. If the app IS ` +
+                        `wired, give the page a moment and check the browser console: the SDK announces its ` +
+                        `own connect failures there, including the one it refuses to make from a ` +
+                        `non-localhost host without allowNonLocalhost.`,
                 }),
         });
     })
@@ -327,12 +439,20 @@ function handleDaemonInner(parsed) {
             removePid(parsed.port);
             process.exit(1);
         });
-        const shutdown = () => {
+        const shutdown = (reason) => {
+            // Recorded BEFORE the async chain: `installExitTrace` reads it when Node is on its way out,
+            // which is after everything below has run. Without it the exit line says `code: 0` and a
+            // reader cannot tell a tidy stop from the bridge disappearing — see #123.
+            recordExitReason(reason);
             // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
             // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
             // own errors), so this can delay the exit by at most the send timeout, never prevent it.
             void daemonTelemetry
-                .shutdown()
+                // The reason rides out on the session summary, which is the only event that fires at this
+                // exact moment. The proxy emits the matching `mcp_connection_lost` and cannot know it —
+                // it sees a socket end and nothing more, which is how a scheduled idle exit came to make up
+                // the large majority of "outages". See SessionSummary.exit.
+                .shutdown(reason)
                 .then(() => server.close())
                 .then(() => {
                 removePid(parsed.port);
@@ -345,8 +465,10 @@ function handleDaemonInner(parsed) {
                 process.exit(1);
             });
         };
-        process.on('SIGTERM', shutdown);
-        process.on('SIGINT', shutdown);
+        // Wrapped rather than passed directly: a signal handler receives the signal name as its first
+        // argument, which would otherwise arrive as the reason.
+        process.on('SIGTERM', () => shutdown(DaemonExitReason.SIGNAL));
+        process.on('SIGINT', () => shutdown(DaemonExitReason.SIGNAL));
         // Self-shut-down when idle so a detached daemon (and any headless Chromium it launched) never
         // lingers on the user's machine after the editor closes. Reuses the same clean shutdown path.
         const attachedGraceEnv = process.env[ReticleEnv.IDLE_ATTACHED];
@@ -363,10 +485,23 @@ function handleDaemonInner(parsed) {
                 : { attachedGraceMs: resolveIdleShutdownMs(attachedGraceEnv) }),
             onShutdown: () => {
                 log('reticle_daemon_idle_exit', { port: parsed.port });
-                shutdown();
+                shutdown(DaemonExitReason.IDLE);
             },
         });
         idleShutdown.start();
+        // Say so, regularly, so a GAP in this log is itself evidence. `installExitTrace` hooks
+        // `'exit'`, which a SIGKILL never fires — so a killed daemon left nothing behind, and the one
+        // that exited tidily logged `code: 0`. A reader could not tell "shut down cleanly" from "the
+        // bridge every app on this machine needs is gone", and a correct SvelteKit install was written
+        // up as an install failure on exactly that ambiguity. See daemon/heartbeat.ts.
+        new DaemonHeartbeat({
+            log,
+            intervalMs: resolveHeartbeatMs(process.env[ReticleEnv.HEARTBEAT]),
+            facts: () => ({
+                sessions: server.bridge.sessions.count(),
+                served: everServedToolCall(),
+            }),
+        }).start();
     })
         .catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
@@ -447,7 +582,23 @@ function handleMcp(opts) {
     })
         .finally(() => {
         // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
-        void startMcpProxy(port, ensure);
+        //
+        // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
+        // fails — which is precisely the case this block exists to tolerate, a daemon that is not
+        // there yet — and with nothing attached that reject became an unhandledRejection. Reported
+        // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
+        // because the stack of a refused socket is entirely node internals and the privacy filter
+        // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
+        // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
+        // on serving from cache, waking a daemon on the next request — which is exactly why this
+        // must be logged as the expected condition it is rather than reported as a defect.
+        void startMcpProxy(port, ensure).catch((err) => {
+            log('reticle_mcp_proxy_first_connect_failed', {
+                port,
+                error: err instanceof Error ? err.message : String(err),
+                note: 'serving from cache; the next client request will try to start a daemon',
+            });
+        });
     });
 }
 function handleLegacyDrive(parsed) {
@@ -528,7 +679,7 @@ function main() {
             handleTelemetry(parsed.action);
             break;
         case 'feedback':
-            void handleFeedback(parsed.text, parsed.rating, parsed.bug);
+            void handleFeedback(parsed.text, parsed.rating, parsed.bug, parsed.feedbackKind, parsed.agent);
             break;
         case 'identify':
             void handleIdentify(parsed);

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

@@ -31,6 +31,30 @@ export type CrashKind = (typeof CrashKind)[keyof typeof CrashKind];
  * 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;
 /**

package/dist/daemon/daemon-resilience.js

@@ -8,10 +8,11 @@
  * 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 { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+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);
@@ -38,23 +39,48 @@ const DISCONNECT_CODES = new Set([
     'ECONNRESET',
     'ERR_STREAM_DESTROYED',
 ]);
-/** The disconnect code this failure carries, if that is all it was. */
-function disconnectCode(value) {
-    const code = value?.code;
-    return 'string' === typeof code && DISCONNECT_CODES.has(code) ? code : undefined;
+/**
+ * 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. In the field **every crash event
+ * carried 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 disconnect and report `true`, so the caller skips the crash report.
+ * 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 absorbDisconnect(value, log, event) {
-    const code = disconnectCode(value);
-    if (code === undefined)
+function absorbExpected(value, log, events) {
+    const hit = expectedCode(value);
+    if (hit === undefined)
         return false;
-    log(event, { code, note: 'the client went away — expected, not a crash' });
+    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. */
@@ -62,6 +88,19 @@ 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.
  *
@@ -85,6 +124,10 @@ function reportCrash(kind, value) {
         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.
@@ -106,6 +149,9 @@ function reportCrash(kind, value) {
                 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,
             },
         });
     }
@@ -126,9 +172,45 @@ function reportCrash(kind, value) {
  * 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 });
+        log('reticle_daemon_exiting', {
+            code: 'number' === typeof code ? code : null,
+            reason: exitReason,
+        });
     });
     for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
         proc.on(signal, () => {
@@ -140,9 +222,12 @@ export function installExitTrace(proc, log) {
 }
 export function installDaemonResilience(proc, log, onFatal) {
     installExitTrace(proc, log);
-    const disconnected = 'reticle_daemon_client_disconnected';
+    const expected = {
+        disconnected: 'reticle_daemon_client_disconnected',
+        unreachable: 'reticle_daemon_peer_unreachable',
+    };
     proc.on('unhandledRejection', (reason) => {
-        if (absorbDisconnect(reason, log, disconnected))
+        if (absorbExpected(reason, log, expected))
             return;
         log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
         reportCrash(CrashKind.UNHANDLED_REJECTION, reason);
@@ -151,7 +236,7 @@ export function installDaemonResilience(proc, log, onFatal) {
         // 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 (absorbDisconnect(err, log, disconnected))
+        if (absorbExpected(err, log, expected))
             return;
         log('reticle_daemon_uncaught_exception', { error: describe(err) });
         reportCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
@@ -171,16 +256,19 @@ export function installDaemonResilience(proc, log, onFatal) {
  * `onCrash` is for reporting only — it must not end the process.
  */
 export function installProxyResilience(proc, log, onCrash = reportCrash) {
-    const disconnected = 'reticle_mcp_proxy_client_disconnected';
+    const expected = {
+        disconnected: 'reticle_mcp_proxy_client_disconnected',
+        unreachable: 'reticle_mcp_proxy_daemon_unreachable',
+    };
     proc.on('unhandledRejection', (reason) => {
-        if (absorbDisconnect(reason, log, disconnected))
+        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 (absorbDisconnect(err, log, disconnected))
+        if (absorbExpected(err, log, expected))
             return;
         log('reticle_mcp_proxy_uncaught_exception', {
             error: describe(err),