@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/daemon/daemon.js

@@ -0,0 +1,333 @@
+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 './lifetime/unclean-predecessor.js';
+import { MAX_DAEMON_LOG_BYTES, pruneOldDaemonLogs } from './lifetime/log-cap.js';
+// Re-exported from their owner so callers outside this directory — the proxy log, the rotation
+// tests — keep reaching `daemon` rather than `lifetime`, which is a sink. See lifetime/log-cap.ts.
+export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
+/** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
+export const STATE_DIR_ENV = ReticleEnv.STATE_DIR;
+/**
+ * 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`);
+}
+/**
+ * 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. The cap itself, the mid-run check and the prune live in lifetime/log-cap.ts.
+ */
+export function rotateDaemonLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        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);
+    // Every OTHER port's leftovers, while we are already here and holding the directory. The clock is
+    // read at this I/O boundary rather than injected, same as the timestamp written below.
+    pruneOldDaemonLogs(deps.home, Date.now());
+    let logFd;
+    try {
+        logFd = deps.openFile(logFilePath, 'a');
+    }
+    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/command/daemon/idle-shutdown.d.ts

@@ -0,0 +1,54 @@
+export interface IdleShutdownOptions {
+    /** True when nothing is using the daemon: no agent connected, no browser session, no pool lease. */
+    isIdle: () => boolean;
+    /** Clean teardown + process exit. Called at most once. */
+    onShutdown: () => void;
+    /** Continuous-idle window before shutdown. `0` (or negative) disables the watcher entirely. */
+    graceMs: number;
+    /**
+     * Is an agent's MCP client attached right now? An attached daemon gets a much longer grace — quiet
+     * with a client present means a slow install or a thinking human, not an unwanted daemon. It still
+     * exits. See idle-grace.
+     */
+    agentAttached?: () => boolean;
+    /** Explicit attached grace (RETICLE_IDLE_ATTACHED_MS); derived from graceMs when absent. */
+    attachedGraceMs?: number;
+    /** How often to re-check idleness. */
+    checkIntervalMs?: number;
+    /** Injected clock — never read wall-clock time in logic (repo rule). */
+    clock?: () => number;
+}
+/**
+ * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
+ * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
+ * proxy spawns the daemon DETACHED so it survives between turns — which means nothing else will ever
+ * stop it; this watcher is that missing stop. Idle = `isIdle` true continuously for `graceMs` (long
+ * enough to ride out brief agent reconnects between turns). On fire it calls `onShutdown` exactly once.
+ * The interval is `unref`'d, so it never keeps the process alive on its own; `start` is idempotent.
+ */
+export declare class IdleShutdown {
+    #private;
+    constructor(opts: IdleShutdownOptions);
+    /** Run one idle check. Exposed so a test can drive it deterministically with an injected clock. */
+    check(): void;
+    start(): void;
+    stop(): void;
+}
+/**
+ * The idle re-check cadence, from the environment. Same shape as the grace resolver, with one
+ * deliberate difference: `0` is not a legal cadence here (it would spin), so `<= 0` falls back to
+ * the default rather than meaning anything.
+ */
+export declare function resolveIdleCheckMs(raw: string | undefined): number;
+/**
+ * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of
+ * milliseconds, `0` to disable. Anything missing or invalid falls back to the default. Pure.
+ *
+ * The disable is NOT implemented here — 0 is passed through as 0, and `IdleShutdown` treats
+ * `graceMs <= 0` as "never self-shut-down" in both `start()` and `check()`. Said out loud because
+ * this docblock had drifted onto the function above it, leaving this one undocumented next to a
+ * bare `Math.floor`. A reader then meets a documented option with no branch implementing it, and
+ * files the gate that depends on it as inverted — the behaviour is correct, only the code reads as
+ * broken.
+ */
+export declare function resolveIdleShutdownMs(raw: string | undefined): number;

package/dist/command/daemon/idle-shutdown.js

@@ -0,0 +1,98 @@
+import { SESSION_LIFECYCLE } from '@reticlehq/core';
+import { idleGraceMs } from './lifetime/idle-grace.js';
+import { log } from '../../log.js';
+/**
+ * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
+ * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
+ * proxy spawns the daemon DETACHED so it survives between turns — which means nothing else will ever
+ * stop it; this watcher is that missing stop. Idle = `isIdle` true continuously for `graceMs` (long
+ * enough to ride out brief agent reconnects between turns). On fire it calls `onShutdown` exactly once.
+ * The interval is `unref`'d, so it never keeps the process alive on its own; `start` is idempotent.
+ */
+export class IdleShutdown {
+    #timer;
+    #idleSince = null;
+    #fired = false;
+    #isIdle;
+    #onShutdown;
+    #graceMs;
+    #agentAttached;
+    #attachedGraceMs;
+    #checkMs;
+    #clock;
+    constructor(opts) {
+        this.#isIdle = opts.isIdle;
+        this.#onShutdown = opts.onShutdown;
+        this.#graceMs = opts.graceMs;
+        this.#agentAttached = opts.agentAttached;
+        this.#attachedGraceMs = opts.attachedGraceMs;
+        this.#checkMs = opts.checkIntervalMs ?? SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+        this.#clock = opts.clock ?? (() => Date.now());
+    }
+    /** Run one idle check. Exposed so a test can drive it deterministically with an injected clock. */
+    check() {
+        if (this.#fired || this.#graceMs <= 0)
+            return; // graceMs <= 0 ⇒ disabled (never self-shut-down)
+        if (!this.#isIdle()) {
+            this.#idleSince = null;
+            return;
+        }
+        const now = this.#clock();
+        this.#idleSince ??= now;
+        // Read per CHECK, not at construction: a client attaches and detaches during a daemon's life, and
+        // the question "how long should this quiet be tolerated" is only answerable now. See idle-grace.
+        const grace = idleGraceMs(this.#graceMs, this.#agentAttached?.() ?? false, this.#attachedGraceMs);
+        if (now - this.#idleSince >= grace) {
+            this.#fired = true;
+            log('reticle_daemon_idle_shutdown', {
+                idleMs: now - this.#idleSince,
+                attached: this.#agentAttached?.() ?? false,
+            });
+            this.#onShutdown();
+        }
+    }
+    start() {
+        if (this.#graceMs <= 0 || this.#timer !== undefined)
+            return; // 0 = disabled
+        this.#timer = setInterval(() => this.check(), this.#checkMs);
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+/**
+ * The idle re-check cadence, from the environment. Same shape as the grace resolver, with one
+ * deliberate difference: `0` is not a legal cadence here (it would spin), so `<= 0` falls back to
+ * the default rather than meaning anything.
+ */
+export function resolveIdleCheckMs(raw) {
+    if (raw === undefined || '' === raw.trim())
+        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+    return Math.floor(n);
+}
+/**
+ * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of
+ * milliseconds, `0` to disable. Anything missing or invalid falls back to the default. Pure.
+ *
+ * The disable is NOT implemented here — 0 is passed through as 0, and `IdleShutdown` treats
+ * `graceMs <= 0` as "never self-shut-down" in both `start()` and `check()`. Said out loud because
+ * this docblock had drifted onto the function above it, leaving this one undocumented next to a
+ * bare `Math.floor`. A reader then meets a documented option with no branch implementing it, and
+ * files the gate that depends on it as inverted — the behaviour is correct, only the code reads as
+ * broken.
+ */
+export function resolveIdleShutdownMs(raw) {
+    if (raw === undefined || '' === raw.trim())
+        return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
+    return Math.floor(n);
+}

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

@@ -0,0 +1,60 @@
+/**
+ * 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 many directories that are not web apps at all. Most profiled projects
+ * had no detectable stack, a large share were not even git repositories, and most daemon sessions
+ * never called a single tool. Their total uptime was orders of magnitude larger than the work they
+ * did.
+ *
+ * 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 there, in a directory with no app, doing nothing, holding memory and a
+ * port, for as long as the editor stayed open.
+ *
+ * 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 many daemons that spawn in a directory with
+ * no app and sit there for the length of an editor session.
+ */
+export declare function buildIdlePredicate(agentConnected: () => boolean, sessions: IdleSessions, pool: IdlePool): () => boolean;
+export {};

package/dist/command/daemon/lifetime/daemon-usefulness.js

@@ -0,0 +1,61 @@
+/**
+ * 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 many directories that are not web apps at all. Most profiled projects
+ * had no detectable stack, a large share were not even git repositories, and most daemon sessions
+ * never called a single tool. Their total uptime was orders of magnitude larger than the work they
+ * did.
+ *
+ * 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 there, in a directory with no app, doing nothing, holding memory and a
+ * port, for as long as the editor stayed open.
+ *
+ * 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 many daemons that spawn in a directory with
+ * no app and sit there for the length of an editor session.
+ */
+export function buildIdlePredicate(agentConnected, sessions, pool) {
+    return () => (!agentConnected() ||
+        isUselessDaemon({
+            servedToolCall: everServedToolCall(),
+            everConnected: sessions.everConnected(),
+            activeLeases: pool.activeCount(),
+        })) &&
+        0 === sessions.count() &&
+        0 === pool.activeCount();
+}