@reticlehq/server 3.1.0 → 3.2.0

package/dist/command/cli.js

@@ -8,7 +8,6 @@ import { openFailureNote } from './cli/answers/open-note.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
-import { stateDirProblem } from './daemon/state-dir.js';
 import { readDevServers } from './daemon/dev-servers.js';
 import { hasAnyAppConnectedBefore, hasProjectConnectedBefore, } from '../memory/recall/prior/connection-memory.js';
 import { attachStatusFields } from '../surface/mcp/attach-memory.js';
@@ -16,7 +15,7 @@ import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
 import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
-import { daemonSpawnArgs, daemonStartOptions } from './cli/daemon-start-options.js';
+import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
 import { loadDotEnv } from '../telemetry/dev-repo.js';
@@ -26,20 +25,20 @@ import { createNodeFileSystem } from '../memory/project/fs/fs-port.js';
 import { affectedSavedFlows } from '../language/flows/change/flow-sources.js';
 import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
-import { startDaemon, RETICLE_VERIFY_DEFAULT_PORT } from '../index.js';
-import { verifyEndpointMismatch } from '../status-payload.js';
+import { startDaemon } from '../index.js';
 import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/identity/server-version.js';
 import { log } from '../log.js';
-import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, logPath, } from './daemon/daemon.js';
+import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
 import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/binding/port-presence.js';
 import { waitForDaemon, probeDaemon } from '../surface/mcp/mcp-proxy.js';
 import { installDaemonResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/lifetime/heartbeat.js';
 import { everServedToolCall } from './daemon/lifetime/daemon-usefulness.js';
-import { DAEMON_START_FAILED_EVENT, readDaemonStartupCause, } from './daemon/lifetime/startup-failure.js';
-import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
+import { DAEMON_START_FAILED_EVENT } from './daemon/lifetime/startup-failure.js';
+import { summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
+import { fetchStatus } from './daemon/binding/daemon-status-probe.js';
 import { handleDrive } from './cli/drive/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
 import { runKill } from './cli/cli-kill.js';
@@ -77,178 +76,26 @@ function handleInit(parsed) {
     }, io);
     void continueAfterInit(parsed, result, io, cwd);
 }
-function handleServe(parsed) {
-    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) {
-        // A daemon that is already up was started with ITS flags, not these — `serve` only attaches.
-        // Exiting 0 here regardless is how `--http-port` came to be accepted and ignored (#687): the
-        // running daemon kept serving whatever it was started with, and the flag vanished without a
-        // word. Ask the daemon which verify port it actually serves and refuse when it is not the one
-        // requested — a flag that cannot be honoured must say so, not report success.
-        if (parsed.http) {
-            const mismatch = verifyEndpointMismatch(await fetchStatus(parsed.port), parsed.httpPort ?? RETICLE_VERIFY_DEFAULT_PORT);
-            if (mismatch !== undefined) {
-                log('reticle_daemon_start_refused', { port: parsed.port, reason: mismatch });
-                process.stderr.write(`${mismatch}\n`);
-                process.exit(1);
-                return;
-            }
-        }
-        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', {});
-        process.exit(1);
-        return;
-    }
-    const daemonArgs = daemonSpawnArgs(parsed);
-    const startupStartedAt = Date.now();
-    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 });
-        const startupCause = readDaemonStartupCause(logPath(parsed.port), startupStartedAt);
-        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',
-            ...(startupCause === undefined ? {} : { cause: startupCause }),
-        });
-        // 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. Reproduced with `chmod 555 ~/.reticle`.
-        const dirProblem = stateDirProblem(reticleStateHome());
-        process.stderr.write(dirProblem === undefined
-            ? startupCause === 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${startupCause}\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)) {
-        removePid(port);
-        if (!quiet)
-            log('reticle_daemon_not_running', { port });
-        return;
-    }
-    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, ...(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 (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, escalated });
-            process.exit(1);
-        }
-    }, 100);
-}
+// `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
+// largest group this file could give up without splitting something that belongs together.
+import { handleServe, handleStop, handleRestart } from './cli/lifecycle/daemon-lifecycle.js';
+import { statusLines } from './cli/status/status-lines.js';
 /**
- * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
+ * Log the status event AND print it for a person.
  *
- * The two halves are reported separately on purpose. A restart that killed the old daemon and then
- * could not start a new one leaves the user in a different place from one that could not kill
- * anything at all, and a single `ok: false` cannot tell them which happened.
+ * Both, not either: the JSON line is documented and is what a log is for, and the block is for
+ * whoever is reading the terminal — which, once an agent is running the command, is somebody who
+ * did not type it and cannot be assumed to parse it.
  */
-async function handleRestart(port, force) {
-    const freed = await runKill(port, force);
-    if (!freed) {
-        log('reticle_restart_aborted', {
-            port,
-            reason: 'the port was not freed, so nothing was started — the old holder is still there',
-        });
-        process.exit(1);
+function reportStatus(fields, json) {
+    if (json) {
+        log('reticle_status', fields);
         return;
     }
-    // Reuses `serve`'s path, which waits for the daemon to ANSWER before claiming it started and exits
-    // non-zero when it does not. A restart that reports success for a daemon that never bound is the
-    // same lie `serve` already stopped telling.
-    await serveWithHonestExit({ port, headless: true, http: false });
+    process.stdout.write(`${statusLines(fields).join('\n')}\n`);
 }
-export async function handleStatus(port) {
+export async function handleStatus(port, json = false) {
+    const report = (fields) => reportStatus(fields, json);
     const pid = readPid(port);
     // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
     const projectId = readProjectId(process.cwd());
@@ -281,7 +128,7 @@ export async function handleStatus(port) {
     // process exists; a Reticle daemon is running only when the shared port probe reaches /status.
     const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
     if (!presenceIsUsable(presence)) {
-        log('reticle_status', {
+        report({
             port,
             running: false,
             presence,
@@ -310,7 +157,7 @@ export async function handleStatus(port) {
     const update = availableUpdate();
     const nudge = update === undefined ? {} : { updateAvailable: update };
     if (payload === undefined) {
-        log('reticle_status', {
+        report({
             port,
             running: true,
             pid,
@@ -342,7 +189,7 @@ export async function handleStatus(port) {
             devServerPorts,
         })
         : {};
-    log('reticle_status', {
+    report({
         port,
         running: true,
         pid,
@@ -752,7 +599,7 @@ export function main() {
             void handleRestart(parsed.port, parsed.force);
             break;
         case 'status':
-            void handleStatus(parsed.port);
+            void handleStatus(parsed.port, parsed.json);
             break;
         case 'license':
             handleLicense();

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

@@ -57,6 +57,18 @@ export type DaemonExitReason = (typeof DaemonExitReason)[keyof typeof DaemonExit
 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.
  *
@@ -70,5 +82,5 @@ export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, o
  * `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): void;
+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

@@ -290,7 +290,10 @@ export function installProxyResilience(proc, log, onCrash = reportCrash, onGone
         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.
+    // 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) => {
@@ -309,6 +312,13 @@ export function installProxyResilience(proc, log, onCrash = reportCrash, 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;
@@ -325,4 +335,5 @@ export function installProxyResilience(proc, log, onCrash = reportCrash, onGone
         });
         onCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
     });
+    return { noteUsableSession };
 }

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

@@ -1,3 +1,4 @@
+export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
 /** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
 export declare const STATE_DIR_ENV: "RETICLE_STATE_DIR";
 /**
@@ -10,20 +11,10 @@ export declare const STATE_DIR_ENV: "RETICLE_STATE_DIR";
  */
 export declare function reticleStateHome(): string;
 export declare function logPath(port: number): string;
-/**
- * How large a daemon log may get before it is rolled over to `<name>.1`.
- *
- * It was unbounded. A real dev machine reached **24MB** on one port, which is not merely untidy: it
- * is the difference between a log somebody opens and a log somebody gives up on, and it is disk that
- * nothing ever reclaims. One previous generation is kept, because the question people bring to this
- * file ("what happened just now?") is answered by the current one and the question they bring next
- * ("and just before that?") is answered by the other.
- */
-export declare const MAX_DAEMON_LOG_BYTES: number;
 /**
  * Roll the log over if it has grown past the cap. Best-effort: a daemon must still start when the
  * log cannot be rotated, because failing to launch over housekeeping is strictly worse than a large
- * file.
+ * file. The cap itself, the mid-run check and the prune live in lifetime/log-cap.ts.
  */
 export declare function rotateDaemonLog(path: string, deps: {
     fileSize(p: string): number;

package/dist/command/daemon/daemon.js

@@ -5,6 +5,10 @@ import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, ReticleEnv } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { uncleanPredecessor } from './lifetime/unclean-predecessor.js';
+import { MAX_DAEMON_LOG_BYTES, pruneOldDaemonLogs } from './lifetime/log-cap.js';
+// Re-exported from their owner so callers outside this directory — the proxy log, the rotation
+// tests — keep reaching `daemon` rather than `lifetime`, which is a sink. See lifetime/log-cap.ts.
+export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
 /** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
 export const STATE_DIR_ENV = ReticleEnv.STATE_DIR;
 /**
@@ -30,20 +34,10 @@ function registryPath(port) {
 export function logPath(port) {
     return join(reticleStateHome(), `daemon-${port}.log`);
 }
-/**
- * How large a daemon log may get before it is rolled over to `<name>.1`.
- *
- * It was unbounded. A real dev machine reached **24MB** on one port, which is not merely untidy: it
- * is the difference between a log somebody opens and a log somebody gives up on, and it is disk that
- * nothing ever reclaims. One previous generation is kept, because the question people bring to this
- * file ("what happened just now?") is answered by the current one and the question they bring next
- * ("and just before that?") is answered by the other.
- */
-export const MAX_DAEMON_LOG_BYTES = 8 * 1024 * 1024;
 /**
  * Roll the log over if it has grown past the cap. Best-effort: a daemon must still start when the
  * log cannot be rotated, because failing to launch over housekeeping is strictly worse than a large
- * file.
+ * file. The cap itself, the mid-run check and the prune live in lifetime/log-cap.ts.
  */
 export function rotateDaemonLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
     try {
@@ -259,6 +253,9 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
     // Roll the log BEFORE opening the append handle, or the daemon writes into the renamed file
     // through an fd that no longer matches any name anyone can find.
     rotateDaemonLog(logFilePath, deps);
+    // Every OTHER port's leftovers, while we are already here and holding the directory. The clock is
+    // read at this I/O boundary rather than injected, same as the timestamp written below.
+    pruneOldDaemonLogs(deps.home, Date.now());
     let logFd;
     try {
         logFd = deps.openFile(logFilePath, 'a');

package/dist/command/daemon/lifetime/heartbeat.d.ts

@@ -51,6 +51,14 @@ interface DaemonHeartbeatOptions {
     intervalMs?: number;
     /** Injected, per the repo rule: never call Date.now() inside logic. */
     clock?: () => number;
+    /**
+     * The log file this beat writes into, for the size check that rides along with it. Injected only
+     * by tests; the default is the daemon's own stderr. See guardDaemonLog.
+     */
+    logGuard?: {
+        size(): number;
+        truncate(): void;
+    };
 }
 export declare class DaemonHeartbeat {
     #private;

package/dist/command/daemon/lifetime/heartbeat.js

@@ -17,6 +17,7 @@
  *
  * A heartbeat nobody interprets is just log volume.
  */
+import { DAEMON_LOG_TRUNCATED_EVENT, guardDaemonLog } from './log-cap.js';
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
 /** Written by installExitTrace when the process exits through Node. */
@@ -55,6 +56,7 @@ export class DaemonHeartbeat {
     #facts;
     #intervalMs;
     #clock;
+    #logGuard;
     #startedAt;
     #timer;
     constructor(opts) {
@@ -62,6 +64,7 @@ export class DaemonHeartbeat {
         this.#facts = opts.facts;
         this.#intervalMs = opts.intervalMs ?? DAEMON_HEARTBEAT_MS;
         this.#clock = opts.clock ?? (() => Date.now());
+        this.#logGuard = opts.logGuard;
         this.#startedAt = this.#clock();
     }
     /**
@@ -72,6 +75,13 @@ export class DaemonHeartbeat {
      * ambiguity this exists to remove.
      */
     beat() {
+        // The one thing a running daemon does on a timer, so it is also where the log it is filling gets
+        // looked at. `rotateDaemonLog` runs at spawn and never again: a detached daemon then writes for
+        // days with nothing checking the size, which is how a log reaches its cap with no mechanism left
+        // that would ever trim it. The beat is itself one of those writes.
+        const reclaimed = guardDaemonLog(this.#logGuard);
+        if (0 < reclaimed)
+            this.#log(DAEMON_LOG_TRUNCATED_EVENT, { reclaimedBytes: reclaimed });
         const facts = this.#facts();
         this.#log(DAEMON_HEARTBEAT_EVENT, {
             uptimeMs: this.#clock() - this.#startedAt,