@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,61 +0,0 @@
-/**
- * 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.
- */
-export declare function noteToolCall(): void;
-export declare function everServedToolCall(): boolean;
-/** Tests only. */
-export declare function resetDaemonUsefulness(): void;
-interface UsefulnessFacts {
-    /** Has any tool been dispatched since this daemon booted? */
-    servedToolCall: boolean;
-    /** Has any browser session ever connected? */
-    everConnected: boolean;
-    /** Active pool leases — a lease means somebody is mid-flight even with no session yet. */
-    activeLeases: number;
-}
-/**
- * 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 declare function isUselessDaemon(facts: UsefulnessFacts): boolean;
-/** The little of SessionManager the idle predicate reads — structural, so a fake needs two methods. */
-interface IdleSessions {
-    count(): number;
-    everConnected(): boolean;
-}
-/** The little of BrowserPool it reads. */
-interface IdlePool {
-    activeCount(): number;
-}
-/**
- * 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 declare function buildIdlePredicate(agentConnected: () => boolean, sessions: IdleSessions, pool: IdlePool): () => boolean;
-export {};

package/dist/daemon/daemon-usefulness.js

@@ -1,62 +0,0 @@
-/**
- * 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/daemon.d.ts

@@ -1,95 +0,0 @@
-/** 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;
-/**
- * Pure decision: may `expectedPid` remove a pidfile owned by `owner` (alive = is that owner running)?
- * Yes when we own it, it's empty, or its daemon is dead — never when a LIVE sibling owns it. This is
- * the orphan-race guard: a losing childB (EADDRINUSE) must not delete the winning childA's live pidfile.
- */
-export declare function shouldRemovePid(owner: number | null, expectedPid: number, alive: boolean): boolean;
-export declare function removePid(port: number, expectedPid?: number): void;
-/**
- * Publish this daemon to the discovery registry so a build-time plugin can find it by projectId. Called
- * from the daemon CHILD on ready (only it knows its cwd/projectId). Best-effort: a write failure must
- * never fail daemon startup — discovery just falls back to the default port.
- */
-export declare function writeDaemonRegistry(port: number, meta: {
-    pid: number;
-    cwd: string;
-    projectId?: string;
-    startedAt: number;
-}): void;
-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`
- * can "find the port" itself instead of making the user reconcile it. Returns the first live one
- * (lowest port, deterministic), or null when none is running.
- */
-export declare function discoverDaemonPort(): number | null;
-/**
- * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
- * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
- * 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 declare function reclaimStaleDaemons(home?: string, pidAlive?: (pid: number) => boolean): number[];
-/** The minimal shape of a spawned child that spawnDaemon uses. */
-export interface SpawnedChild {
-    readonly pid?: number | undefined;
-    on(event: string, handler: (...args: unknown[]) => void): unknown;
-    unref(): void;
-}
-/** Injectable deps for spawnDaemon — the testability seam. Defaults to the real implementations. */
-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;
-}
-/**
- * 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
- * immediately without a race window.
- *
- * `deps` is injectable for testing (default: real fs/spawn against ~/.reticle). The same seam
- * pattern as reclaimStaleDaemons(home, pidAlive).
- */
-export declare function spawnDaemon(nodeExec: string, scriptPath: string, args: string[], port: number, deps?: SpawnDaemonDeps): boolean;

package/dist/daemon/daemon.js

@@ -1,336 +0,0 @@
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, writeSync, } from 'node:fs';
-import { spawn } from 'node:child_process';
-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(reticleStateHome(), daemonRegistryFileName(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.
- */
-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;
-    const n = parseInt(readFileSync(path, 'utf8').trim(), 10);
-    return isNaN(n) ? null : n;
-}
-export function isAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function writePid(port) {
-    mkdirSync(reticleStateHome(), { recursive: true });
-    writeFileSync(pidPath(port), String(process.pid), 'utf8');
-}
-/**
- * Pure decision: may `expectedPid` remove a pidfile owned by `owner` (alive = is that owner running)?
- * Yes when we own it, it's empty, or its daemon is dead — never when a LIVE sibling owns it. This is
- * the orphan-race guard: a losing childB (EADDRINUSE) must not delete the winning childA's live pidfile.
- */
-export function shouldRemovePid(owner, expectedPid, alive) {
-    return null === owner || owner === expectedPid || !alive;
-}
-export function removePid(port, expectedPid = process.pid) {
-    const path = pidPath(port);
-    if (existsSync(path)) {
-        const owner = readPid(port);
-        if (shouldRemovePid(owner, expectedPid, owner !== null && isAlive(owner)))
-            unlinkSync(path);
-    }
-    // The discovery registry entry shares this daemon's lifetime — clean both so a dead daemon never
-    // lingers in discovery. Keyed by port, so this is safe from the parent (stop) or the child (shutdown).
-    removeDaemonRegistry(port);
-}
-/**
- * Publish this daemon to the discovery registry so a build-time plugin can find it by projectId. Called
- * from the daemon CHILD on ready (only it knows its cwd/projectId). Best-effort: a write failure must
- * never fail daemon startup — discovery just falls back to the default port.
- */
-export function writeDaemonRegistry(port, meta) {
-    const entry = {
-        port,
-        pid: meta.pid,
-        cwd: meta.cwd,
-        startedAt: meta.startedAt,
-        ...(meta.projectId !== undefined ? { projectId: meta.projectId } : {}),
-    };
-    try {
-        mkdirSync(reticleStateHome(), { recursive: true });
-        writeFileSync(registryPath(port), JSON.stringify(entry), 'utf8');
-    }
-    catch {
-        // discovery is a convenience — never block startup on it
-    }
-}
-function removeDaemonRegistry(port) {
-    const path = registryPath(port);
-    try {
-        if (existsSync(path))
-            unlinkSync(path);
-    }
-    catch {
-        // racing another cleaner — already gone
-    }
-}
-export function isRunning(port) {
-    const pid = readPid(port);
-    return pid !== null && isAlive(pid);
-}
-/**
- * Find the port of a live reticle daemon by scanning ~/.reticle/daemon-<port>.pid files — so `reticle open`
- * can "find the port" itself instead of making the user reconcile it. Returns the first live one
- * (lowest port, deterministic), or null when none is running.
- */
-export function discoverDaemonPort() {
-    reclaimStaleDaemons(); // sweep crashed daemons' stale pidfiles before scanning for live ones
-    let found = null;
-    try {
-        for (const file of readdirSync(reticleStateHome())) {
-            const m = /^daemon-(\d+)\.pid$/.exec(file);
-            if (null === m)
-                continue;
-            const port = Number(m[1]);
-            if (isRunning(port) && (null === found || port < found))
-                found = port;
-        }
-    }
-    catch {
-        // no ~/.reticle yet → nothing running
-    }
-    return found;
-}
-/**
- * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
- * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
- * 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 = reticleStateHome(), pidAlive = isAlive) {
-    const reclaimed = [];
-    let files;
-    try {
-        files = readdirSync(home);
-    }
-    catch {
-        return reclaimed; // no ~/.reticle yet → nothing to reclaim
-    }
-    for (const file of files) {
-        const match = /^daemon-(\d+)\.pid$/.exec(file);
-        if (null === match)
-            continue;
-        const path = join(home, file);
-        let pid = null;
-        try {
-            pid = parseInt(readFileSync(path, 'utf8').trim(), 10);
-            if (isNaN(pid))
-                pid = null;
-        }
-        catch {
-            pid = null; // unreadable pidfile counts as stale
-        }
-        if (null === pid || !pidAlive(pid)) {
-            try {
-                unlinkSync(path);
-                removeDaemonRegistry(Number(match[1])); // drop the sidecar discovery entry too
-                reclaimed.push(Number(match[1]));
-            }
-            catch {
-                // racing another reclaimer — fine, it's already gone
-            }
-        }
-    }
-    return reclaimed;
-}
-function defaultSpawnDaemonDeps() {
-    return {
-        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,
-    };
-}
-/**
- * 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
- * immediately without a race window.
- *
- * `deps` is injectable for testing (default: real fs/spawn against ~/.reticle). The same seam
- * pattern as reclaimStaleDaemons(home, pidAlive).
- */
-export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpawnDaemonDeps()) {
-    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');
-    }
-    catch {
-        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');
-        }
-        catch {
-            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');
-    }
-    catch {
-        // Log path unwritable (permissions, disk full). Clean up the lock so we don't leave a ghost.
-        deps.closeFile(lockFd);
-        try {
-            unlinkSync(pidFilePath);
-        }
-        catch {
-            // racing another reclaimer — fine
-        }
-        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], {
-            detached: true,
-            stdio: ['ignore', logFd, logFd],
-        });
-    }
-    catch {
-        // spawn can throw synchronously on some platforms (e.g. ENOMEM, invalid args).
-        deps.closeFile(logFd);
-        deps.closeFile(lockFd);
-        try {
-            unlinkSync(pidFilePath);
-        }
-        catch {
-            // racing another reclaimer — fine
-        }
-        return false;
-    }
-    // The parent's copy of logFd is no longer needed — spawn duplicated it into the child.
-    deps.closeFile(logFd);
-    // Suppress the async ENOENT/EACCES that fires when the executable is missing or unexecutable.
-    // The failure is already detected synchronously via `child.pid === undefined`; without this
-    // handler the error propagates as an uncaught exception and crashes the parent process.
-    child.on('error', () => undefined);
-    if (child.pid === undefined) {
-        // Spawn failed silently (resource exhaustion, invalid executable on some platforms). The pidfile
-        // is empty — clean it up so discovery doesn't see a ghost, and report failure honestly.
-        deps.closeFile(lockFd);
-        try {
-            unlinkSync(pidFilePath);
-        }
-        catch {
-            // racing another reclaimer — fine
-        }
-        return false;
-    }
-    writeFileSync(lockFd, String(child.pid), 'utf8');
-    deps.closeFile(lockFd);
-    child.unref();
-    return true;
-}

package/dist/daemon/heartbeat.d.ts

@@ -1,111 +0,0 @@
-/**
- * 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.
- *
- * 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 {};