@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,119 @@
+/**
+ * A regular beat, so SILENCE in the daemon log becomes evidence.
+ *
+ * `installExitTrace` hooks `'exit'`, which a SIGKILL never fires. So a daemon that is killed —
+ * crashed, OOM-ed, swept by another project, `kill -9`'d by the recipe in every troubleshooting
+ * thread — leaves no trace at all, and the last line before its port goes dark is whatever it
+ * happened to be doing. Worse, a daemon that DID exit logs `code: 0`, so a tidy shutdown and a
+ * violent death are the same shape to anyone reading the file.
+ *
+ * Measured cost of that: a correct SvelteKit install was written up as an install failure, because
+ * the daemon had died 21 seconds earlier and nothing in the log said so. The fixture was named in the
+ * report; the daemon was not.
+ *
+ * Two halves, and the second is what makes the first worth having:
+ *   - DaemonHeartbeat emits `reticle_daemon_alive` on a fixed cadence, unconditionally.
+ *   - classifyDaemonLife reads a log back and says which way the daemon ended.
+ *
+ * A heartbeat nobody interprets is just log volume.
+ */
+/** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
+export declare const DAEMON_HEARTBEAT_EVENT = "reticle_daemon_alive";
+/**
+ * How often a live daemon says so.
+ *
+ * A daemon that lives half an hour writes about sixty lines at 30s — readable, and small against a log
+ * that already rotates. Shorter would make the gap sharper and the file noisier; the gap only needs
+ * to be legible against a connect window, which is measured in seconds.
+ */
+export declare const DAEMON_HEARTBEAT_MS = 30000;
+/**
+ * The cadence, from the environment. Same shape as `resolveIdleCheckMs`: a bad value falls back
+ * rather than throwing, and 0 or negative is not a legal cadence — it would spin.
+ */
+export declare function resolveHeartbeatMs(raw: string | undefined): number;
+interface HeartbeatFacts {
+    /** Browser sessions connected right now. */
+    sessions: number;
+    /**
+     * Has this daemon EVER served a tool call? A lifetime fact, not a window count.
+     *
+     * It is the difference between a death that cost somebody work and one that cost nothing — the
+     * same distinction `isUselessDaemon` already draws. A windowed count would reset under the reader
+     * and make a long-lived daemon look freshly idle.
+     */
+    served: boolean;
+}
+interface DaemonHeartbeatOptions {
+    log: (event: string, fields: Record<string, unknown>) => void;
+    /** Read at each beat, never cached — the point is to describe the daemon NOW. */
+    facts: () => HeartbeatFacts;
+    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;
+    constructor(opts: DaemonHeartbeatOptions);
+    /**
+     * One beat. Exposed so a test can drive it with an injected clock rather than waiting.
+     *
+     * Unconditional on purpose. Skipping the beat when nothing happened is the obvious optimisation and
+     * it destroys the signal: silence would then mean "idle" OR "dead", which is precisely the
+     * ambiguity this exists to remove.
+     */
+    beat(): void;
+    start(): void;
+    stop(): void;
+}
+/** How a daemon's life ended, as far as its own log can say. */
+export declare const DaemonEnd: {
+    /** Still beating within tolerance. */
+    readonly ALIVE: "alive";
+    /** Logged its own exit, with no signal before it. */
+    readonly CLEAN: "clean";
+    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
+    readonly SIGNALLED: "signalled";
+    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
+    readonly DIED_SILENTLY: "died_silently";
+    /** No beat was ever emitted, so this log cannot answer the question. */
+    readonly UNKNOWN: "unknown";
+};
+export type DaemonEnd = (typeof DaemonEnd)[keyof typeof DaemonEnd];
+/**
+ * One parsed line of a daemon log. The index signature is not laziness: these lines carry whatever
+ * their event needed (`code`, `port`, `pid`, `reason`, …), and a reader that refused unknown keys
+ * would reject the very file it exists to read.
+ */
+interface LogLine {
+    t: number;
+    event: string;
+    signal?: unknown;
+    everyMs?: unknown;
+    [field: string]: unknown;
+}
+export interface DaemonLife {
+    end: DaemonEnd;
+    /** When the last beat landed, or undefined if there was never one. */
+    lastBeatMs?: number;
+    /** How long the log has been silent, when that is the finding. */
+    silentForMs?: number;
+    signal?: string;
+}
+/**
+ * Read a daemon log back and say how it ended.
+ *
+ * UNKNOWN rather than ALIVE when there is no heartbeat at all — every log written before this
+ * existed, and any file the reader was pointed at by mistake. Inferring health from the absence of a
+ * signal we never sent is the same confident-wrong this module replaces.
+ */
+export declare function classifyDaemonLife(lines: readonly LogLine[], nowMs: number): DaemonLife;
+export {};

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

@@ -0,0 +1,151 @@
+/**
+ * A regular beat, so SILENCE in the daemon log becomes evidence.
+ *
+ * `installExitTrace` hooks `'exit'`, which a SIGKILL never fires. So a daemon that is killed —
+ * crashed, OOM-ed, swept by another project, `kill -9`'d by the recipe in every troubleshooting
+ * thread — leaves no trace at all, and the last line before its port goes dark is whatever it
+ * happened to be doing. Worse, a daemon that DID exit logs `code: 0`, so a tidy shutdown and a
+ * violent death are the same shape to anyone reading the file.
+ *
+ * Measured cost of that: a correct SvelteKit install was written up as an install failure, because
+ * the daemon had died 21 seconds earlier and nothing in the log said so. The fixture was named in the
+ * report; the daemon was not.
+ *
+ * Two halves, and the second is what makes the first worth having:
+ *   - DaemonHeartbeat emits `reticle_daemon_alive` on a fixed cadence, unconditionally.
+ *   - classifyDaemonLife reads a log back and says which way the daemon ended.
+ *
+ * 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. */
+const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
+/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
+const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
+/**
+ * How often a live daemon says so.
+ *
+ * A daemon that lives half an hour writes about sixty lines at 30s — readable, and small against a log
+ * that already rotates. Shorter would make the gap sharper and the file noisier; the gap only needs
+ * to be legible against a connect window, which is measured in seconds.
+ */
+export const DAEMON_HEARTBEAT_MS = 30_000;
+/**
+ * How many beats may be missed before a reader calls it dead.
+ *
+ * Timers slip under load — the battery boots three servers and a browser — and a reader that cries
+ * death on one late beat is a reader people learn to ignore. Two intervals plus a margin.
+ */
+const MISSED_BEATS_TOLERATED = 2;
+/**
+ * The cadence, from the environment. Same shape as `resolveIdleCheckMs`: a bad value falls back
+ * rather than throwing, and 0 or negative is not a legal cadence — it would spin.
+ */
+export function resolveHeartbeatMs(raw) {
+    if (raw === undefined || '' === raw.trim())
+        return DAEMON_HEARTBEAT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DAEMON_HEARTBEAT_MS;
+    return Math.floor(n);
+}
+export class DaemonHeartbeat {
+    #log;
+    #facts;
+    #intervalMs;
+    #clock;
+    #logGuard;
+    #startedAt;
+    #timer;
+    constructor(opts) {
+        this.#log = opts.log;
+        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();
+    }
+    /**
+     * One beat. Exposed so a test can drive it with an injected clock rather than waiting.
+     *
+     * Unconditional on purpose. Skipping the beat when nothing happened is the obvious optimisation and
+     * it destroys the signal: silence would then mean "idle" OR "dead", which is precisely the
+     * 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,
+            // The cadence travels WITH the beat so a reader never hard-codes it. Hard-coding is how the
+            // reader and the emitter drift apart the first time the interval is tuned.
+            everyMs: this.#intervalMs,
+            sessions: facts.sessions,
+            served: facts.served,
+        });
+    }
+    start() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => this.beat(), this.#intervalMs);
+        // Never the reason a process stays alive — this is a diagnostic, not a workload.
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+/** How a daemon's life ended, as far as its own log can say. */
+export const DaemonEnd = {
+    /** Still beating within tolerance. */
+    ALIVE: 'alive',
+    /** Logged its own exit, with no signal before it. */
+    CLEAN: 'clean',
+    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
+    SIGNALLED: 'signalled',
+    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
+    DIED_SILENTLY: 'died_silently',
+    /** No beat was ever emitted, so this log cannot answer the question. */
+    UNKNOWN: 'unknown',
+};
+/**
+ * Read a daemon log back and say how it ended.
+ *
+ * UNKNOWN rather than ALIVE when there is no heartbeat at all — every log written before this
+ * existed, and any file the reader was pointed at by mistake. Inferring health from the absence of a
+ * signal we never sent is the same confident-wrong this module replaces.
+ */
+export function classifyDaemonLife(lines, nowMs) {
+    const beats = lines.filter((l) => l.event === DAEMON_HEARTBEAT_EVENT);
+    const exit = lines.findLast((l) => l.event === DAEMON_EXIT_EVENT);
+    const signal = lines.findLast((l) => l.event === DAEMON_SIGNAL_EVENT);
+    if (exit !== undefined) {
+        // A signal is the CAUSE; the exit line only says it happened. Reporting `clean` for a SIGTERMed
+        // daemon is how "shut down tidily" and "the bridge every app needs is gone" became one sentence.
+        return signal === undefined
+            ? { end: DaemonEnd.CLEAN }
+            : {
+                end: DaemonEnd.SIGNALLED,
+                ...('string' === typeof signal.signal ? { signal: signal.signal } : {}),
+            };
+    }
+    const last = beats.at(-1);
+    if (last === undefined)
+        return { end: DaemonEnd.UNKNOWN };
+    const everyMs = 'number' === typeof last.everyMs ? last.everyMs : DAEMON_HEARTBEAT_MS;
+    const silentForMs = nowMs - last.t;
+    return silentForMs > everyMs * MISSED_BEATS_TOLERATED
+        ? { end: DaemonEnd.DIED_SILENTLY, lastBeatMs: last.t, silentForMs }
+        : { end: DaemonEnd.ALIVE, lastBeatMs: last.t };
+}

package/dist/command/daemon/lifetime/idle-grace.d.ts

@@ -0,0 +1,32 @@
+/**
+ * How long an idle daemon is given before it shuts itself down.
+ *
+ * It used to be one number for every case, and at 5 minutes that number killed live runs: a
+ * daemon shutting down repeatedly under somebody working normally, their editor's Reticle
+ * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
+ * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
+ * was wrong with their install.
+ *
+ * Reverting is not an option. Daemons used to sit idle for long stretches doing almost nothing,
+ * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
+ * rule is what fixed that.
+ *
+ * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
+ * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
+ * wait: quiet with a client attached means the human is thinking or the install is slow; the same
+ * quiet with nobody attached means the daemon is unwanted. Both still exit.
+ */
+/**
+ * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
+ * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
+ * the slow installs that were killing runs, and comfortably short of the long idles the
+ * shorter rule was introduced to end.
+ */
+export declare const ATTACHED_GRACE_MULTIPLIER = 6;
+/**
+ * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
+ * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
+ * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
+ * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
+ */
+export declare function idleGraceMs(baseMs: number, agentAttached: boolean, overrideMs?: number): number;

package/dist/command/daemon/lifetime/idle-grace.js

@@ -0,0 +1,41 @@
+/**
+ * How long an idle daemon is given before it shuts itself down.
+ *
+ * It used to be one number for every case, and at 5 minutes that number killed live runs: a
+ * daemon shutting down repeatedly under somebody working normally, their editor's Reticle
+ * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
+ * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
+ * was wrong with their install.
+ *
+ * Reverting is not an option. Daemons used to sit idle for long stretches doing almost nothing,
+ * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
+ * rule is what fixed that.
+ *
+ * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
+ * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
+ * wait: quiet with a client attached means the human is thinking or the install is slow; the same
+ * quiet with nobody attached means the daemon is unwanted. Both still exit.
+ */
+/**
+ * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
+ * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
+ * the slow installs that were killing runs, and comfortably short of the long idles the
+ * shorter rule was introduced to end.
+ */
+export const ATTACHED_GRACE_MULTIPLIER = 6;
+/**
+ * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
+ * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
+ * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
+ * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
+ */
+export function idleGraceMs(baseMs, agentAttached, overrideMs) {
+    // A non-positive base means the watcher is disabled; multiplying must not resurrect it.
+    if (baseMs <= 0)
+        return baseMs;
+    if (!agentAttached)
+        return baseMs;
+    return overrideMs !== undefined && overrideMs > 0
+        ? overrideMs
+        : baseMs * ATTACHED_GRACE_MULTIPLIER;
+}

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/daemon/state-dir.js

@@ -0,0 +1,59 @@
+/**
+ * Can Reticle write the directory it keeps everything in?
+ *
+ * `~/.reticle` holds the pid files, the daemon logs, the telemetry id and outbox, and every saved
+ * flow. A daemon that cannot write it does not start — and until now said nothing useful about why.
+ *
+ * Reproduced with `chmod 555 ~/.reticle`:
+ *
+ *   the daemon did not come up on :4415 — nothing is listening on :4415 — no daemon is running
+ *   see /…/.reticle/daemon-4415.log
+ *
+ * The first line restates the symptom. The second points at a log **inside the unwritable
+ * directory**, so the one diagnostic offered cannot exist. Someone hitting this — a locked-down home
+ * directory, a container with a read-only mount, a managed corporate profile — has nothing to go on.
+ *
+ * Deliberately a PROBE, not a permission-bit read: `stat` says what the mode claims, and an ACL, a
+ * read-only mount, SELinux or a full disk all produce a writable-looking mode and a failing write.
+ * The only honest test of "can I write here" is writing.
+ */
+import { mkdirSync, existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/** Probe filename. Distinctive so a leftover is obviously ours, and unlinked immediately either way. */
+const PROBE = '.reticle-write-probe';
+/**
+ * A sentence naming the problem, or `undefined` when the directory is usable.
+ *
+ * A directory that does not exist yet is NOT a problem: the daemon creates it, and the creation
+ * failing is caught by the same probe on the parent path.
+ */
+export function stateDirProblem(dir) {
+    if (!existsSync(dir)) {
+        // Not yet created is the ordinary first-run state. Only report if we cannot create it.
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return (`Reticle cannot create its state directory at ${dir}. Everything it keeps — the daemon ` +
+                'log, the pid file, saved flows — lives there, so the daemon cannot start. Check the ' +
+                'permissions on the parent directory, or point Reticle elsewhere with HOME.');
+        }
+        return undefined;
+    }
+    const probe = join(dir, PROBE);
+    try {
+        writeFileSync(probe, '', 'utf8');
+    }
+    catch {
+        return (`Reticle cannot write to its state directory at ${dir}. Everything it keeps — the daemon ` +
+            'log, the pid file, saved flows — lives there, so the daemon cannot start. Make it writable ' +
+            '(`chmod u+w`), or point Reticle elsewhere with HOME.');
+    }
+    try {
+        unlinkSync(probe);
+    }
+    catch {
+        /* wrote but could not clean up: the directory IS writable, which is the question asked */
+    }
+    return undefined;
+}

package/dist/command/daemon/wake-decision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a woken MCP proxy may do with whatever is sitting on its port.
+ *
+ * Pulled out as a pure function because the wake path lives inside a long side-effecting closure in
+ * `mcp-command.ts`, and the decision it was getting wrong is three lines of reasoning that deserve a
+ * test of their own.
+ *
+ * `resolveMcpPort` asks the identity question at BOOT and relocates rather than adopting a stranger.
+ * The wake path asked only whether a daemon answered, so after an idle exit freed the port and
+ * another project's daemon bound it, a dormant proxy could reattach to a daemon that was not its
+ * own — and then serve an agent verdicts about a different application. `adoptable` is the same rule
+ * boot uses; this is just the wake path finally asking it.
+ */
+import { PortPresence } from './binding/port-presence.js';
+export declare const WakeAction: {
+    /** A daemon we may use is already here. */
+    readonly USE: "use";
+    /** Nothing is listening: start one. */
+    readonly SPAWN: "spawn";
+    /** Somebody else's. Go dormant with a reason rather than pretend the wake succeeded. */
+    readonly REFUSE: "refuse";
+};
+export type WakeAction = (typeof WakeAction)[keyof typeof WakeAction];
+/**
+ * Identity is asked only of a port that actually holds a daemon.
+ *
+ * A FREE port must stay spawnable whatever the registry says about it, because a stale entry is the
+ * registry's ordinary state for the moment after any daemon exits — and refusing there would turn
+ * every idle retirement into a permanent lockout, which is the failure this whole path exists to
+ * prevent.
+ */
+export declare function decideWake(presence: PortPresence, daemonProjectId: string | undefined, callerProjectId: string | undefined): WakeAction;

package/dist/command/daemon/wake-decision.js

@@ -0,0 +1,38 @@
+/**
+ * What a woken MCP proxy may do with whatever is sitting on its port.
+ *
+ * Pulled out as a pure function because the wake path lives inside a long side-effecting closure in
+ * `mcp-command.ts`, and the decision it was getting wrong is three lines of reasoning that deserve a
+ * test of their own.
+ *
+ * `resolveMcpPort` asks the identity question at BOOT and relocates rather than adopting a stranger.
+ * The wake path asked only whether a daemon answered, so after an idle exit freed the port and
+ * another project's daemon bound it, a dormant proxy could reattach to a daemon that was not its
+ * own — and then serve an agent verdicts about a different application. `adoptable` is the same rule
+ * boot uses; this is just the wake path finally asking it.
+ */
+import { PortPresence } from './binding/port-presence.js';
+import { adoptable } from './daemon-resolve.js';
+export const WakeAction = {
+    /** A daemon we may use is already here. */
+    USE: 'use',
+    /** Nothing is listening: start one. */
+    SPAWN: 'spawn',
+    /** Somebody else's. Go dormant with a reason rather than pretend the wake succeeded. */
+    REFUSE: 'refuse',
+};
+/**
+ * Identity is asked only of a port that actually holds a daemon.
+ *
+ * A FREE port must stay spawnable whatever the registry says about it, because a stale entry is the
+ * registry's ordinary state for the moment after any daemon exits — and refusing there would turn
+ * every idle retirement into a permanent lockout, which is the failure this whole path exists to
+ * prevent.
+ */
+export function decideWake(presence, daemonProjectId, callerProjectId) {
+    if (PortPresence.FREE === presence)
+        return WakeAction.SPAWN;
+    if (PortPresence.DAEMON !== presence)
+        return WakeAction.REFUSE;
+    return adoptable(daemonProjectId, callerProjectId) ? WakeAction.USE : WakeAction.REFUSE;
+}