@reticlehq/server 3.1.0 → 3.3.0

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

@@ -0,0 +1,32 @@
+/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
+export declare function fetchStatus(port: number): Promise<unknown>;
+/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
+interface StatusSession {
+    sessionId: string;
+    url: string;
+    projectId?: string;
+    throttled: boolean;
+    /**
+     * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,
+     * which reads as visible — the conservative answer, since it keeps the reuse this command has
+     * always done rather than opening a tab on a guess.
+     */
+    hidden: boolean;
+    stale: boolean;
+    pendingMarks: number;
+    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
+    unresponsive?: true;
+}
+/**
+ * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export declare function summarizeStatus(payload: unknown): {
+    sessionCount: number;
+    sessions: StatusSession[];
+    why?: string;
+    /** The same diagnosis without the differential, for a surface a person reads. */
+    whyLead?: string;
+};
+export {};

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

@@ -0,0 +1,93 @@
+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);
+        });
+    });
+}
+/**
+ * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export function summarizeStatus(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return { sessionCount: 0, sessions: [] };
+    const obj = payload;
+    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
+    // here would silently undo the reason it is on the wire.
+    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
+    // Absent on a daemon older than this field, which is why every reader falls back to `why`.
+    const whyLead = 'string' === typeof obj['whyLead'] ? obj['whyLead'] : undefined;
+    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
+    const sessions = raw
+        .map((s) => {
+        if (typeof s !== 'object' || null === s)
+            return null;
+        const r = s;
+        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
+        if ('' === sessionId)
+            return null;
+        return {
+            sessionId,
+            url: 'string' === typeof r['url'] ? r['url'] : '',
+            ...('string' === typeof r['projectId'] && 0 < r['projectId'].length
+                ? { projectId: r['projectId'] }
+                : {}),
+            throttled: true === r['throttled'],
+            hidden: true === r['hidden'],
+            stale: true === r['stale'],
+            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
+            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
+        };
+    })
+        .filter((s) => s !== null);
+    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
+    return {
+        sessionCount,
+        sessions,
+        ...(why === undefined ? {} : { why }),
+        ...(whyLead === undefined ? {} : { whyLead }),
+    };
+}

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/binding/port-presence.d.ts

@@ -65,7 +65,7 @@ export declare function probePresence(port: number, probes: {
  * these lets the sentence tell them apart when — and only when — the recorded pid for the port
  * matches the process actually holding it.
  */
-export interface PortHolder {
+interface PortHolder {
     /** The pid we recorded for this port, from the daemon pid file. `null` when there is none. */
     ourPid: number | null;
     /** The pid actually holding the port, when the caller could determine it. */

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/idle-shutdown.d.ts

@@ -1,4 +1,4 @@
-export interface IdleShutdownOptions {
+interface IdleShutdownOptions {
     /** True when nothing is using the daemon: no agent connected, no browser session, no pool lease. */
     isIdle: () => boolean;
     /** Clean teardown + process exit. Called at most once. */
@@ -52,3 +52,4 @@ export declare function resolveIdleCheckMs(raw: string | undefined): number;
  * broken.
  */
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;
+export {};

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,

package/dist/command/daemon/lifetime/log-cap.d.ts

@@ -0,0 +1,68 @@
+/**
+ * How big the daemon's log may get, and the three things that keep it there.
+ *
+ * `rotateDaemonLog` runs at spawn. `guardDaemonLog` runs while the daemon lives, because a detached
+ * daemon writes for days — a beat every thirty seconds plus every session, tool call and reconnect —
+ * and a size checked once at start is a size nothing will ever check again. A log measured at 98% of
+ * the cap and still climbing had no remaining mechanism that would trim it, and the tracker carries
+ * the same failure with a bigger number: the daemon log filling a disk, and a user who left over it.
+ * `pruneOldDaemonLogs` is the other half of the disk — one file per port ever bound, forever.
+ *
+ * Here rather than in daemon.ts because the size check has to be called from the heartbeat, and
+ * `lifetime` is a sink: nothing in it may reach back into its parent. Same reason nothing here
+ * logs — the caller that has a logger emits `DAEMON_LOG_TRUNCATED_EVENT`.
+ */
+/**
+ * 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;
+/**
+ * Reclaim a log that has already run past `max`, by TRUNCATING IT IN PLACE. Returns bytes reclaimed.
+ *
+ * The one definition behind both logs Reticle writes: the daemon log, and the MCP proxy log in
+ * surface/mcp/proxy/proxy-log.ts, which delegates to this. An uncapped proxy log has filled a disk
+ * and broken unrelated builds, Docker and ordinary shell commands with ENOSPC; the daemon log is
+ * larger, longer-lived and had the same hole, so it gets the same answer rather than a second one.
+ *
+ * In place, never renamed or unlinked: a rename moves the bytes without reclaiming a byte, and a
+ * file a running process still holds open keeps its blocks allocated after an unlink until that
+ * handle closes. `: > ~/.reticle/daemon-4400.log` is the operation being copied here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: dying over housekeeping is strictly worse
+ * than a large file.
+ */
+export declare function recoverOversizedLog(deps: {
+    size(): number;
+    truncate(): void;
+}, max?: number): number;
+/** Emitted into the fresh log immediately after a truncation, so the gap explains itself. */
+export declare const DAEMON_LOG_TRUNCATED_EVENT = "reticle_daemon_log_truncated";
+/** Keep a RUNNING daemon's log under the cap. Returns the bytes reclaimed, 0 when it was fine. */
+export declare function guardDaemonLog(deps?: {
+    size(): number;
+    truncate(): void;
+}): number;
+/**
+ * How long a daemon log outlives its daemon.
+ *
+ * Every port ever bound leaves a `daemon-<port>.log` behind and nothing removed any of them — one
+ * machine held 128 files in `~/.reticle`, logs the large majority. Nothing enumerates them either:
+ * every reader (`doctor`, the startup-cause reader, the lifecycle messages) opens the log of the
+ * port it is asking about right now, so a log for a port that will never be bound again is read by
+ * nobody. A week is long enough to still have last Tuesday's crash when somebody asks about it.
+ */
+export declare const DAEMON_LOG_RETENTION_MS: number;
+/**
+ * Delete daemon logs nothing has written to in the retention window. Returns the names removed.
+ *
+ * Age is the whole test, and it doubles as the liveness probe: a live daemon beats into its log
+ * every thirty seconds, so a log older than a week has no daemon behind it by construction.
+ * Best-effort throughout — a log that will not delete is not a reason to fail a daemon start.
+ */
+export declare function pruneOldDaemonLogs(home: string, nowMs: number): string[];

package/dist/command/daemon/lifetime/log-cap.js

@@ -0,0 +1,115 @@
+/**
+ * How big the daemon's log may get, and the three things that keep it there.
+ *
+ * `rotateDaemonLog` runs at spawn. `guardDaemonLog` runs while the daemon lives, because a detached
+ * daemon writes for days — a beat every thirty seconds plus every session, tool call and reconnect —
+ * and a size checked once at start is a size nothing will ever check again. A log measured at 98% of
+ * the cap and still climbing had no remaining mechanism that would trim it, and the tracker carries
+ * the same failure with a bigger number: the daemon log filling a disk, and a user who left over it.
+ * `pruneOldDaemonLogs` is the other half of the disk — one file per port ever bound, forever.
+ *
+ * Here rather than in daemon.ts because the size check has to be called from the heartbeat, and
+ * `lifetime` is a sink: nothing in it may reach back into its parent. Same reason nothing here
+ * logs — the caller that has a logger emits `DAEMON_LOG_TRUNCATED_EVENT`.
+ */
+import { fstatSync, ftruncateSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 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;
+/**
+ * Reclaim a log that has already run past `max`, by TRUNCATING IT IN PLACE. Returns bytes reclaimed.
+ *
+ * The one definition behind both logs Reticle writes: the daemon log, and the MCP proxy log in
+ * surface/mcp/proxy/proxy-log.ts, which delegates to this. An uncapped proxy log has filled a disk
+ * and broken unrelated builds, Docker and ordinary shell commands with ENOSPC; the daemon log is
+ * larger, longer-lived and had the same hole, so it gets the same answer rather than a second one.
+ *
+ * In place, never renamed or unlinked: a rename moves the bytes without reclaiming a byte, and a
+ * file a running process still holds open keeps its blocks allocated after an unlink until that
+ * handle closes. `: > ~/.reticle/daemon-4400.log` is the operation being copied here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: dying over housekeeping is strictly worse
+ * than a large file.
+ */
+export function recoverOversizedLog(deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        const size = deps.size();
+        if (max >= size)
+            return 0;
+        deps.truncate();
+        return size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * The daemon's log, as the daemon itself can address it: its own stderr.
+ *
+ * `spawnDaemon` hands the child `stdio: ['ignore', logFd, logFd]`, so inside a running daemon fd 2
+ * IS `daemon-<port>.log`, opened with O_APPEND — which is what makes truncating it safe: an
+ * appending write always lands at the new end of file, so there is no sparse hole and no lost
+ * handle. No path, no port and no second open are needed to reach it. When the daemon runs in the
+ * foreground fd 2 is a terminal, whose reported size is 0, so this is a no-op there.
+ */
+const DAEMON_LOG_FD = 2;
+/** Emitted into the fresh log immediately after a truncation, so the gap explains itself. */
+export const DAEMON_LOG_TRUNCATED_EVENT = 'reticle_daemon_log_truncated';
+const daemonLogFdOps = {
+    size: () => fstatSync(DAEMON_LOG_FD).size,
+    truncate: () => ftruncateSync(DAEMON_LOG_FD, 0),
+};
+/** Keep a RUNNING daemon's log under the cap. Returns the bytes reclaimed, 0 when it was fine. */
+export function guardDaemonLog(deps = daemonLogFdOps) {
+    return recoverOversizedLog(deps);
+}
+/**
+ * How long a daemon log outlives its daemon.
+ *
+ * Every port ever bound leaves a `daemon-<port>.log` behind and nothing removed any of them — one
+ * machine held 128 files in `~/.reticle`, logs the large majority. Nothing enumerates them either:
+ * every reader (`doctor`, the startup-cause reader, the lifecycle messages) opens the log of the
+ * port it is asking about right now, so a log for a port that will never be bound again is read by
+ * nobody. A week is long enough to still have last Tuesday's crash when somebody asks about it.
+ */
+export const DAEMON_LOG_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Delete daemon logs nothing has written to in the retention window. Returns the names removed.
+ *
+ * Age is the whole test, and it doubles as the liveness probe: a live daemon beats into its log
+ * every thirty seconds, so a log older than a week has no daemon behind it by construction.
+ * Best-effort throughout — a log that will not delete is not a reason to fail a daemon start.
+ */
+export function pruneOldDaemonLogs(home, nowMs) {
+    const pruned = [];
+    let files;
+    try {
+        files = readdirSync(home);
+    }
+    catch {
+        return pruned; // no ~/.reticle yet → nothing to prune
+    }
+    for (const file of files) {
+        if (null === /^daemon-\d+\.log(\.1)?$/.exec(file))
+            continue;
+        const path = join(home, file);
+        try {
+            if (DAEMON_LOG_RETENTION_MS > nowMs - statSync(path).mtimeMs)
+                continue;
+            unlinkSync(path);
+            pruned.push(file);
+        }
+        catch {
+            // unreadable or already gone — either way it is not this process's problem
+        }
+    }
+    return pruned;
+}

package/dist/command/setup/agent-notice-memory.d.ts

@@ -0,0 +1,16 @@
+/** One client we could not write to, and why. */
+export interface ManualNotice {
+    readonly name: string;
+    readonly file: string;
+    readonly why: string;
+}
+/** Where the stamp lives, under the state home the caller resolves. */
+export declare const NOTICE_MEMORY_BASENAME = "agent-notices.json";
+/** Identity of a notice: the same client, the same file, for the same reason. */
+export declare function noticeKey(n: ManualNotice): string;
+/** Pure. The notices `said` has not already recorded, in order, without repeats. */
+export declare function unsaidNotices(said: readonly string[], notices: readonly ManualNotice[]): ManualNotice[];
+/** Every key recorded before. An unreadable or malformed stamp reads as "nothing was said". */
+export declare function readSaid(stateHome: string): string[];
+/** Record these keys beside whatever was there. A failed write costs a repeated line, nothing more. */
+export declare function rememberSaid(stateHome: string, keys: readonly string[]): void;