@reticlehq/server 2.4.0 → 2.6.0

package/dist/daemon/daemon-usefulness.js

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

package/dist/{daemon.d.ts → daemon/daemon.d.ts}

@@ -1,4 +1,34 @@
+/** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
+export declare const STATE_DIR_ENV: "RETICLE_STATE_DIR";
+/**
+ * Where the daemon keeps pidfiles, the discovery registry and its logs.
+ *
+ * `~/.reticle` unless overridden. The override exists because a read-only $HOME is not hypothetical
+ * — a sandboxed agent or a locked-down Windows profile cannot write there, and until now that meant
+ * the daemon could not start at all. Read per call rather than captured at import, so a test (and a
+ * wrapper that sets it late) sees the current value.
+ */
+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.
+ */
+export declare function rotateDaemonLog(path: string, deps: {
+    fileSize(p: string): number;
+    renameFile(from: string, to: string): void;
+}, max?: number): boolean;
 export declare function readPid(port: number, home?: string): number | null;
 export declare function isAlive(pid: number): boolean;
 export declare function writePid(port: number): void;
@@ -20,13 +50,6 @@ export declare function writeDaemonRegistry(port: number, meta: {
     projectId?: string;
     startedAt: number;
 }): void;
-export declare function removeDaemonRegistry(port: number): void;
-/**
- * Discover the port of a live daemon serving `projectId` by reading the registry entries in ~/.reticle.
- * Returns null when none matches (caller falls back to the default port — never guesses a mismatched
- * daemon). Stale entries (crashed daemons) are ignored via the pid liveness probe.
- */
-export declare function discoverDaemonPortForProject(projectId: string | undefined): number | null;
 export declare function isRunning(port: number): boolean;
 /**
  * Find the port of a live reticle daemon by scanning ~/.reticle/daemon-<port>.pid files — so `reticle open`
@@ -52,13 +75,15 @@ export interface SpawnDaemonDeps {
     readonly home: string;
     openFile(path: string, flags: string): number;
     closeFile(fd: number): void;
+    /** Size in bytes, or 0 when the file does not exist yet. */
+    fileSize(path: string): number;
+    renameFile(from: string, to: string): void;
     spawnChild(command: string, args: readonly string[], options: {
         detached: boolean;
         stdio: readonly ('ignore' | number)[];
     }): SpawnedChild;
     pidAlive(pid: number): boolean;
 }
-export declare function defaultSpawnDaemonDeps(): SpawnDaemonDeps;
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
  * Writes the PID file from the parent before returning so callers can call isRunning

package/dist/{daemon.js → daemon/daemon.js}

@@ -1,19 +1,62 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, writeSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { daemonRegistryFileName, daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
-const RETICLE_HOME = join(homedir(), '.reticle');
-function pidPath(port, home = RETICLE_HOME) {
+import { daemonRegistryFileName, ReticleEnv } from '@reticlehq/core';
+import { log } from '../log.js';
+import { uncleanPredecessor } from './unclean-predecessor.js';
+/** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
+export const STATE_DIR_ENV = ReticleEnv.STATE_DIR;
+/**
+ * Where the daemon keeps pidfiles, the discovery registry and its logs.
+ *
+ * `~/.reticle` unless overridden. The override exists because a read-only $HOME is not hypothetical
+ * — a sandboxed agent or a locked-down Windows profile cannot write there, and until now that meant
+ * the daemon could not start at all. Read per call rather than captured at import, so a test (and a
+ * wrapper that sets it late) sees the current value.
+ */
+export function reticleStateHome() {
+    const override = process.env[STATE_DIR_ENV];
+    if (override !== undefined && override.length > 0)
+        return override;
+    return join(homedir(), '.reticle');
+}
+function pidPath(port, home = reticleStateHome()) {
     return join(home, `daemon-${port}.pid`);
 }
 function registryPath(port) {
-    return join(RETICLE_HOME, daemonRegistryFileName(port));
+    return join(reticleStateHome(), daemonRegistryFileName(port));
 }
 export function logPath(port) {
-    return join(RETICLE_HOME, `daemon-${port}.log`);
+    return join(reticleStateHome(), `daemon-${port}.log`);
 }
-export function readPid(port, home = RETICLE_HOME) {
+/**
+ * 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.
+ */
+export function rotateDaemonLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        if (max >= deps.fileSize(path))
+            return false;
+        deps.renameFile(path, `${path}.1`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readPid(port, home = reticleStateHome()) {
     const path = pidPath(port, home);
     if (!existsSync(path))
         return null;
@@ -30,7 +73,7 @@ export function isAlive(pid) {
     }
 }
 export function writePid(port) {
-    mkdirSync(RETICLE_HOME, { recursive: true });
+    mkdirSync(reticleStateHome(), { recursive: true });
     writeFileSync(pidPath(port), String(process.pid), 'utf8');
 }
 /**
@@ -39,7 +82,7 @@ export function writePid(port) {
  * the orphan-race guard: a losing childB (EADDRINUSE) must not delete the winning childA's live pidfile.
  */
 export function shouldRemovePid(owner, expectedPid, alive) {
-    return owner === null || owner === expectedPid || !alive;
+    return null === owner || owner === expectedPid || !alive;
 }
 export function removePid(port, expectedPid = process.pid) {
     const path = pidPath(port);
@@ -66,14 +109,14 @@ export function writeDaemonRegistry(port, meta) {
         ...(meta.projectId !== undefined ? { projectId: meta.projectId } : {}),
     };
     try {
-        mkdirSync(RETICLE_HOME, { recursive: true });
+        mkdirSync(reticleStateHome(), { recursive: true });
         writeFileSync(registryPath(port), JSON.stringify(entry), 'utf8');
     }
     catch {
         // discovery is a convenience — never block startup on it
     }
 }
-export function removeDaemonRegistry(port) {
+function removeDaemonRegistry(port) {
     const path = registryPath(port);
     try {
         if (existsSync(path))
@@ -83,34 +126,6 @@ export function removeDaemonRegistry(port) {
         // racing another cleaner — already gone
     }
 }
-/**
- * Discover the port of a live daemon serving `projectId` by reading the registry entries in ~/.reticle.
- * Returns null when none matches (caller falls back to the default port — never guesses a mismatched
- * daemon). Stale entries (crashed daemons) are ignored via the pid liveness probe.
- */
-export function discoverDaemonPortForProject(projectId) {
-    const entries = [];
-    let files;
-    try {
-        files = readdirSync(RETICLE_HOME);
-    }
-    catch {
-        return null; // no ~/.reticle yet
-    }
-    for (const file of files) {
-        if (daemonRegistryPort(file) === null)
-            continue;
-        try {
-            const parsed = DaemonRegistryEntrySchema.safeParse(JSON.parse(readFileSync(join(RETICLE_HOME, file), 'utf8')));
-            if (parsed.success)
-                entries.push(parsed.data);
-        }
-        catch {
-            // unreadable/corrupt entry — skip it
-        }
-    }
-    return pickDaemonPort(entries, projectId, isAlive);
-}
 export function isRunning(port) {
     const pid = readPid(port);
     return pid !== null && isAlive(pid);
@@ -124,12 +139,12 @@ export function discoverDaemonPort() {
     reclaimStaleDaemons(); // sweep crashed daemons' stale pidfiles before scanning for live ones
     let found = null;
     try {
-        for (const file of readdirSync(RETICLE_HOME)) {
+        for (const file of readdirSync(reticleStateHome())) {
             const m = /^daemon-(\d+)\.pid$/.exec(file);
-            if (m === null)
+            if (null === m)
                 continue;
             const port = Number(m[1]);
-            if (isRunning(port) && (found === null || port < found))
+            if (isRunning(port) && (null === found || port < found))
                 found = port;
         }
     }
@@ -144,7 +159,7 @@ export function discoverDaemonPort() {
  * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
-export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
+export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAlive) {
     const reclaimed = [];
     let files;
     try {
@@ -155,7 +170,7 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
     }
     for (const file of files) {
         const match = /^daemon-(\d+)\.pid$/.exec(file);
-        if (match === null)
+        if (null === match)
             continue;
         const path = join(home, file);
         let pid = null;
@@ -167,7 +182,7 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
         catch {
             pid = null; // unreadable pidfile counts as stale
         }
-        if (pid === null || !pidAlive(pid)) {
+        if (null === pid || !pidAlive(pid)) {
             try {
                 unlinkSync(path);
                 removeDaemonRegistry(Number(match[1])); // drop the sidecar discovery entry too
@@ -180,11 +195,13 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
     }
     return reclaimed;
 }
-export function defaultSpawnDaemonDeps() {
+function defaultSpawnDaemonDeps() {
     return {
-        home: RETICLE_HOME,
+        home: reticleStateHome(),
         openFile: openSync,
         closeFile: closeSync,
+        fileSize: (path) => (existsSync(path) ? statSync(path).size : 0),
+        renameFile: renameSync,
         spawnChild: (command, args, options) => spawn(command, [...args], { detached: options.detached, stdio: [...options.stdio] }),
         pidAlive: isAlive,
     };
@@ -198,12 +215,27 @@ export function defaultSpawnDaemonDeps() {
  * pattern as reclaimStaleDaemons(home, pidAlive).
  */
 export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpawnDaemonDeps()) {
-    mkdirSync(deps.home, { recursive: true });
+    try {
+        mkdirSync(deps.home, { recursive: true });
+    }
+    catch (err) {
+        // The log-file open below has always been guarded; this was not, so the ONE failure a sandboxed
+        // agent actually hits — a read-only $HOME — escaped as a raw EACCES naming nothing. Refuse
+        // loudly, and name the way out.
+        log('reticle_daemon_state_unwritable', {
+            home: deps.home,
+            error: err instanceof Error ? err.message : String(err),
+            fix: `Reticle could not create its state directory. Set ${STATE_DIR_ENV} to a writable path and retry.`,
+        });
+        return false;
+    }
     const pidFilePath = join(deps.home, `daemon-${port}.pid`);
     const logFilePath = join(deps.home, `daemon-${port}.log`);
     // O_EXCL spawn-lock: only the FIRST racer to create the pidfile spawns. A concurrent second gets
     // EEXIST — if a LIVE daemon owns the port it skips (no duplicate detached daemon, no clobbered pid);
     // a stale pidfile from a crashed daemon is reclaimed. Returns false when it did not spawn.
+    /** Set when this start reclaimed a pidfile whose owner is gone — see unclean-predecessor.ts. */
+    let orphanPid = null;
     let lockFd;
     try {
         lockFd = deps.openFile(pidFilePath, 'wx');
@@ -212,6 +244,10 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
         const existing = readPid(port, deps.home);
         if (existing !== null && deps.pidAlive(existing))
             return false;
+        // This branch IS the crash detection — its own comment has always said so ("a stale pidfile from
+        // a crashed daemon is reclaimed"), it just never said it out loud. Captured before the unlink,
+        // because after it there is no trace left that the previous daemon died at all.
+        orphanPid = uncleanPredecessor(existing, false, process.pid);
         try {
             unlinkSync(pidFilePath);
             lockFd = deps.openFile(pidFilePath, 'wx');
@@ -220,6 +256,9 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
             return false; // lost a concurrent reclaim race
         }
     }
+    // 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);
     let logFd;
     try {
         logFd = deps.openFile(logFilePath, 'a');
@@ -235,6 +274,24 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
         }
         return false;
     }
+    // Into the daemon log itself, not the parent's stdout: `doctor` points the reader at this file, and
+    // a death recorded anywhere else is a death they will not find. Written through the fd the child is
+    // about to inherit, so it lands immediately before that child's first line — exactly where a reader
+    // comparing two `mcp_daemon_started` entries is already looking.
+    if (null !== orphanPid) {
+        try {
+            writeSync(logFd, `${JSON.stringify({
+                // Same convention as log(): the clock is read at the I/O boundary, not injected.
+                t: new Date().toISOString(),
+                event: 'reticle_daemon_previous_died_unclean',
+                port,
+                pid: orphanPid,
+            })}\n`);
+        }
+        catch {
+            // A log we cannot write is not a reason to refuse to start the daemon.
+        }
+    }
     let child;
     try {
         child = deps.spawnChild(nodeExec, [scriptPath, ...args], {

package/dist/daemon/heartbeat.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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";
+/** Written by installExitTrace when the process exits through Node. */
+export declare const DAEMON_EXIT_EVENT = "reticle_daemon_exiting";
+/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
+export declare const DAEMON_SIGNAL_EVENT = "reticle_daemon_signalled";
+/**
+ * How often a live daemon says so.
+ *
+ * The median daemon lives 28 minutes, so at 30s that is ~56 lines — 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;
+}
+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/daemon/heartbeat.js

@@ -0,0 +1,141 @@
+/**
+ * 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 const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
+/** Written by installExitTrace when the process exits through Node. */
+export const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
+/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
+export const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
+/**
+ * How often a live daemon says so.
+ *
+ * The median daemon lives 28 minutes, so at 30s that is ~56 lines — 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;
+    #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.#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() {
+        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 };
+}