@reticlehq/server 2.4.0 → 2.5.0

package/dist/cloud/cloud-sync.js

@@ -15,18 +15,18 @@ export const CloudEnv = {
     KEY: 'RETICLE_CLOUD_KEY',
 };
 /** Paths the OSS server pushes to (match the cloud app's contract). */
-export const CLOUD_FLOWS_PATH = '/v1/flows';
-export const CLOUD_RUNS_PATH = '/v1/runs';
-export const CLOUD_PROJECT_RUNS_PATH = '/v1/project/runs';
-export const CLOUD_PROJECT_REGRESSION_PATH = '/v1/project/regression';
-export const CLOUD_VERIFICATIONS_PATH = '/v1/verifications';
+const CLOUD_FLOWS_PATH = '/v1/flows';
+const CLOUD_RUNS_PATH = '/v1/runs';
+const CLOUD_PROJECT_RUNS_PATH = '/v1/project/runs';
+const CLOUD_PROJECT_REGRESSION_PATH = '/v1/project/regression';
+const CLOUD_VERIFICATIONS_PATH = '/v1/verifications';
 /** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
 export function resolveCloudConfig(env) {
     const url = env[CloudEnv.URL];
     const apiKey = env[CloudEnv.KEY];
-    if (typeof url !== 'string' || url.length === 0)
+    if (typeof url !== 'string' || 0 === url.length)
         return null;
-    if (typeof apiKey !== 'string' || apiKey.length === 0)
+    if (typeof apiKey !== 'string' || 0 === apiKey.length)
         return null;
     return { url: url.replace(/\/+$/, ''), apiKey };
 }
@@ -40,7 +40,7 @@ export const SyncOutcome = {
  * throws — a failure is reported, not propagated, so the local save is authoritative.
  */
 export async function syncFlowToCloud(flow, config, projectId, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return { outcome: SyncOutcome.SKIPPED };
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_FLOWS_PATH}`, {
@@ -67,7 +67,7 @@ export async function syncFlowToCloud(flow, config, projectId, fetchImpl) {
  * built it), so the body is the run itself, not a wrapper. Best-effort: never throws, never blocks exit.
  */
 export async function syncRunToCloud(run, config, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return { outcome: SyncOutcome.SKIPPED };
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_RUNS_PATH}`, {
@@ -93,7 +93,7 @@ export async function syncRunToCloud(run, config, fetchImpl) {
  * truth). `projectId` scopes an org's multiple suites. Best-effort: never throws, never blocks the tool.
  */
 export async function syncRunRecordToCloud(record, projectId, config, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return { outcome: SyncOutcome.SKIPPED };
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_PROJECT_RUNS_PATH}`, {
@@ -127,7 +127,7 @@ export async function syncRunRecordToCloud(record, projectId, config, fetchImpl)
  * cloud), or null when not logged in / unreachable — so the caller degrades to local-only, never fails.
  */
 export async function fetchProjectRegressionFromCloud(config, projectId, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return null;
     try {
         const query = projectId === undefined ? '' : `?projectId=${encodeURIComponent(projectId)}`;
@@ -156,7 +156,7 @@ const ServerVerificationSchema = z.object({
  * submit fails, so the caller falls back to a local replay. Never throws.
  */
 export async function submitServerVerification(body, config, fetchImpl) {
-    if (config === null)
+    if (null === config)
         return null;
     try {
         const res = await fetchImpl(`${config.url}${CLOUD_VERIFICATIONS_PATH}`, {

package/dist/crawl/crawl-empty.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Why a crawl clicked nothing.
+ *
+ * `stepsRun: 0` came back with no `error` and nothing else, so "the page had no controls" and "it had
+ * 34 and none were clicked" were the same answer. Reported from a sweep on a page with 34 of them,
+ * and not reproducible here — crawl drives the bench app correctly — so the honest move is to make
+ * the zero carry its own diagnosis rather than guess at a cause.
+ */
+interface CrawlOutcome {
+    interactiveFound: number;
+    stepsRun: number;
+    maxSteps: number;
+    truncated: boolean;
+}
+export declare function crawlEmptyNote(outcome: CrawlOutcome): string | undefined;
+export {};

package/dist/crawl/crawl-empty.js

@@ -0,0 +1,24 @@
+/**
+ * Why a crawl clicked nothing.
+ *
+ * `stepsRun: 0` came back with no `error` and nothing else, so "the page had no controls" and "it had
+ * 34 and none were clicked" were the same answer. Reported from a sweep on a page with 34 of them,
+ * and not reproducible here — crawl drives the bench app correctly — so the honest move is to make
+ * the zero carry its own diagnosis rather than guess at a cause.
+ */
+export function crawlEmptyNote(outcome) {
+    if (outcome.stepsRun > 0)
+        return undefined;
+    if (outcome.maxSteps <= 0) {
+        return 'nothing was clicked because maxSteps is 0 — raise it to crawl at all';
+    }
+    if (0 === outcome.interactiveFound) {
+        const capped = outcome.truncated
+            ? ' The snapshot was also truncated, so controls past the cap were never seen — narrow `scope` and retry.'
+            : '';
+        return `no interactive controls were found on this page, so nothing was clicked — the crawl ran and found none, which is a result rather than a failure.${capped}`;
+    }
+    return (`${String(outcome.interactiveFound)} interactive controls were found and none of them were clicked. ` +
+        `That is not an empty page, so something stopped the loop — report it with reticle_feedback, ` +
+        `including this page's URL and one control's ref.`);
+}

package/dist/crawl/crawl-tools.js

@@ -37,6 +37,9 @@ export const CRAWL_TOOLS = [
         outputSchema: {
             interactiveFound: z.number(),
             stepsRun: z.number(),
+            // Present only when nothing was clicked, saying WHICH zero this is — an empty page, a step
+            // budget of zero, or controls found and none driven. A bare zero was unactionable.
+            note: z.string().optional(),
             anomalies: z.array(z.object({
                 kind: z.string(),
                 ref: z.string(),
@@ -64,7 +67,7 @@ export const CRAWL_TOOLS = [
                 ...(maxSteps !== undefined ? { maxSteps } : {}),
                 ...(settleMs !== undefined ? { settleMs } : {}),
                 ...(scope !== undefined ? { scope } : {}),
-                ...(args['confirmDangerous'] === true ? { confirmDangerous: true } : {}),
+                ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
             };
             return crawl(session, opts, nodeSleep);
         },

package/dist/crawl/crawl.js

@@ -1,4 +1,6 @@
+import { span } from '../trace.js';
 import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, ContradictionKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { crawlEmptyNote } from './crawl-empty.js';
 import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { findContradictions } from '../events/contradictions.js';
@@ -62,7 +64,7 @@ export async function crawl(session, opts, sleep) {
     // the controls it never reached are not merely unclicked — they were never seen. Reporting
     // `interactiveFound` without this would state a control count that is really a cap, and
     // `truncated:false` would positively assert that nothing was cut.
-    const coverageCapped = snapshot.truncated === true;
+    const coverageCapped = true === snapshot.truncated;
     const anomalies = [];
     const visited = [];
     const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
@@ -83,12 +85,18 @@ export async function crawl(session, opts, sleep) {
         session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
         let act;
         try {
-            act = await session.command(ReticleCommand.ACT, {
-                ref: item.ref,
-                action: ActionType.CLICK,
-                args: opts.confirmDangerous === true ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+            // One span per control clicked, so a slow crawl names the control rather than reporting a
+            // single multi-second total. The settle sleep below is INSIDE it deliberately: it is part of
+            // what a step costs, and hiding it would make the fixed budget look free.
+            act = await span('crawl.step', { ref: item.ref, desc: item.desc }, async () => {
+                const clicked = await session.command(ReticleCommand.ACT, {
+                    ref: item.ref,
+                    action: ActionType.CLICK,
+                    args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+                });
+                await sleep(settleMs);
+                return clicked;
             });
-            await sleep(settleMs);
         }
         finally {
             // Close on every exit so a throw cannot leak the window onto the next control's events.
@@ -147,7 +155,7 @@ export async function crawl(session, opts, sleep) {
         // noise for the false negative this check exists to catch.
         const dispatched = asRecord(act.result)['dispatched'] !== false && act.ok;
         if (dispatched &&
-            errs.length === 0 &&
+            0 === errs.length &&
             !events.some(isActivity) &&
             !legitimatelyInert(item.desc)) {
             counts.deadControls += 1;
@@ -171,5 +179,16 @@ export async function crawl(session, opts, sleep) {
         // partial sweep into "all controls healthy".
         truncated: items.length > stepsRun || coverageCapped,
         ...(coverageCapped ? { coverageNote: CAPPED_SNAPSHOT_NOTE } : {}),
+        // A bare `stepsRun: 0` made "the page had no controls" and "it had 34 and none were clicked" the
+        // same answer. See crawl-empty.
+        ...(() => {
+            const note = crawlEmptyNote({
+                interactiveFound: items.length,
+                stepsRun,
+                maxSteps,
+                truncated: coverageCapped,
+            });
+            return note === undefined ? {} : { note };
+        })(),
     };
 }

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

@@ -0,0 +1,49 @@
+/**
+ * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
+ * single stray error must not take the whole fleet down:
+ *
+ * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
+ * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
+ * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
+ * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
+ * daemon, which beats crashing silently or limping along corrupt.
+ */
+export interface ProcessLike {
+    on(event: string, listener: (arg: unknown) => void): unknown;
+}
+type LogFn = (event: string, data: Record<string, unknown>) => void;
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export declare const CrashKind: {
+    readonly UNHANDLED_REJECTION: "unhandled_rejection";
+    readonly UNCAUGHT_EXCEPTION: "uncaught_exception";
+};
+export type CrashKind = (typeof CrashKind)[keyof typeof CrashKind];
+/**
+ * Log EVERY way this process can leave, so a death always leaves a line.
+ *
+ * Reported from the field: a 115-line daemon log containing zero of `reticle_daemon_idle_exit`,
+ * `reticle_daemon_close_error`, `daemon_stopped`, `uncaught` or `unhandled` — the daemon simply
+ * stopped existing mid-wait. Both crash handlers below already log before exiting, so their silence
+ * ruled themselves out and left nothing else to read: no shutdown path had run at all.
+ *
+ * `exit` fires for every in-process exit including an explicit `process.exit`, and carries the code.
+ * The signals cover an external kill. What neither can catch is SIGKILL or an OOM abort — and that
+ * is the point: after this, silence in the log is itself the finding, because every other door is
+ * now instrumented.
+ */
+export declare function installExitTrace(proc: ProcessLike, log: LogFn): void;
+export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, onFatal: () => void): void;
+/**
+ * Process-level resilience for the MCP PROXY, whose rule is the opposite of the daemon's.
+ *
+ * The daemon exits on an uncaught throw because the next `reticle mcp` respawns it. Nothing respawns
+ * the proxy — it is the stdio server the editor launched, and its exit is what the user experiences
+ * as "the MCP server disconnected, open /mcp and reconnect". So it logs and keeps serving: its whole
+ * state is a socket and a queue, and it already knows how to rebuild both (see the reconnect and
+ * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
+ * dead one answers nothing and needs a human.
+ *
+ * `onCrash` is for reporting only — it must not end the process.
+ */
+export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void): void;
+export {};

package/dist/daemon/daemon-resilience.js

@@ -0,0 +1,191 @@
+/**
+ * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
+ * single stray error must not take the whole fleet down:
+ *
+ * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
+ * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
+ * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
+ * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
+ * daemon, which beats crashing silently or limping along corrupt.
+ */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { errorSkeleton, errorTypeOf, fingerprintCrash, MAX_REPORTED_FRAMES, reticleFrames, } from '../telemetry/error-fingerprint.js';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { machineSnapshot } from '../telemetry/machine-snapshot.js';
+import { getTelemetry } from '../telemetry/telemetry.js';
+function describe(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+/**
+ * Node error codes that mean THE OTHER END WENT AWAY, not "we broke".
+ *
+ * One real session produced nine `runtime_crashed` events, all `write EPIPE`: the MCP client closed
+ * its half of the stdio pipe and the very next `process.stdout.write` failed, which is the ordinary
+ * way a client leaves. Counted as uncaught exceptions they poison the only metric that answers "is
+ * Reticle stable?" — and they recur every single time an editor is closed.
+ *
+ * Matched on `err.code`, never on the message: a message is prose, gets wrapped, localised and
+ * rewritten, and matching it would eventually swallow a real crash that merely mentioned a pipe.
+ *
+ * - `EPIPE` — wrote to a pipe whose reader is gone. The stdio case, and the nine.
+ * - `ECONNRESET` — the peer reset the socket; stdio is a socket when the parent piped it, and the
+ *   HTTP/SSE surface produces it when a client vanishes mid-response.
+ * - `ERR_STREAM_DESTROYED` — the same race one tick later: the stream was already torn down when
+ *   the write landed.
+ */
+const DISCONNECT_CODES = new Set([
+    'EPIPE',
+    'ECONNRESET',
+    'ERR_STREAM_DESTROYED',
+]);
+/** The disconnect code this failure carries, if that is all it was. */
+function disconnectCode(value) {
+    const code = value?.code;
+    return 'string' === typeof code && DISCONNECT_CODES.has(code) ? code : undefined;
+}
+/**
+ * Log an expected disconnect and report `true`, so the caller skips the crash report.
+ *
+ * It is still WRITTEN DOWN. A client leaving is normal, but a daemon that suddenly logs a hundred of
+ * these is a finding — the difference between "not a crash" and "not worth knowing" is the whole
+ * reason this logs instead of returning early in silence.
+ */
+function absorbDisconnect(value, log, event) {
+    const code = disconnectCode(value);
+    if (code === undefined)
+        return false;
+    log(event, { code, note: 'the client went away — expected, not a crash' });
+    return true;
+}
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export const CrashKind = {
+    UNHANDLED_REJECTION: 'unhandled_rejection',
+    UNCAUGHT_EXCEPTION: 'uncaught_exception',
+};
+/**
+ * Report a crash with enough detail to actually diagnose it.
+ *
+ * This is the only place in the product that learns about a crash at all. An uncaught exception in a
+ * long-running daemon takes down every agent attached to it, and the only other record is a line in a
+ * local log nobody sends us.
+ *
+ * The first version sent a hash and nothing else, which made crashes rankable and undiagnosable — you
+ * could see that forty machines hit `a3f2c1d8e9b0` and had no way to learn what that was. So it now
+ * carries the four things an RCA needs: WHERE (our own frames, with function names and line numbers),
+ * WHAT (the message with every variable part stripped), WHEN (the tool in flight), and WHY-ish (the
+ * agent's approach run before it). All of it is our code and our vocabulary; the user's stack frames,
+ * their paths, and the contents of their message are removed before any of it is built.
+ *
+ * Best-effort and wrapped: reporting a crash must never be the reason a crash gets worse.
+ */
+function reportCrash(kind, value) {
+    try {
+        const errorType = errorTypeOf(value);
+        const stack = value instanceof Error ? (value.stack ?? '') : '';
+        const message = describe(value);
+        const { breadcrumb, inFlight } = getSessionMetrics().trail;
+        const machine = machineSnapshot();
+        void getTelemetry().emit(TelemetryEventKind.RUNTIME_CRASHED, {
+            // A crash is ALWAYS reached through something the agent asked for — the daemon does nothing on
+            // its own — so attributing it to the agent is accurate rather than a guess.
+            actor: TelemetryActor.AGENT,
+            crash: {
+                kind,
+                errorType,
+                fingerprint: fingerprintCrash(errorType, stack, message),
+                // The skeleton, not the message: every quoted string, path, URL, id and number is replaced
+                // by `*` first. This is what makes the fingerprint mean something to a human reading a chart.
+                message: errorSkeleton(message).slice(0, 300),
+                // Our own frames, our own published code. The file, the line, and the function — which is the
+                // whole of "where did it break". Frames from the user's app never survive this.
+                frames: reticleFrames(stack).slice(0, MAX_REPORTED_FRAMES),
+                ...(inFlight !== undefined ? { tool: inFlight } : {}),
+                ...(breadcrumb.length > 0 ? { breadcrumb } : {}),
+                // Crashes cluster hard by runtime version and architecture, and we were recording neither.
+                nodeVersion: process.versions.node,
+                arch: process.arch,
+                // "Out of memory" and "our bug" look identical in a stack trace. This is what tells them apart.
+                ...(machine !== undefined ? { machine } : {}),
+            },
+        });
+    }
+    catch {
+        /* a crash report must never be the reason a crash gets worse */
+    }
+}
+/**
+ * Log EVERY way this process can leave, so a death always leaves a line.
+ *
+ * Reported from the field: a 115-line daemon log containing zero of `reticle_daemon_idle_exit`,
+ * `reticle_daemon_close_error`, `daemon_stopped`, `uncaught` or `unhandled` — the daemon simply
+ * stopped existing mid-wait. Both crash handlers below already log before exiting, so their silence
+ * ruled themselves out and left nothing else to read: no shutdown path had run at all.
+ *
+ * `exit` fires for every in-process exit including an explicit `process.exit`, and carries the code.
+ * The signals cover an external kill. What neither can catch is SIGKILL or an OOM abort — and that
+ * is the point: after this, silence in the log is itself the finding, because every other door is
+ * now instrumented.
+ */
+export function installExitTrace(proc, log) {
+    proc.on('exit', (code) => {
+        log('reticle_daemon_exiting', { code: 'number' === typeof code ? code : null });
+    });
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+        proc.on(signal, () => {
+            // Log only. Whatever installed a real handler for this signal still runs; adding an exit here
+            // would race the shutdown that flushes the session summary.
+            log('reticle_daemon_signalled', { signal });
+        });
+    }
+}
+export function installDaemonResilience(proc, log, onFatal) {
+    installExitTrace(proc, log);
+    const disconnected = 'reticle_daemon_client_disconnected';
+    proc.on('unhandledRejection', (reason) => {
+        if (absorbDisconnect(reason, log, disconnected))
+            return;
+        log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
+        reportCrash(CrashKind.UNHANDLED_REJECTION, reason);
+    });
+    proc.on('uncaughtException', (err) => {
+        // Not fatal either: Node's "the process state is undefined" guidance is about a throw that
+        // escaped everything, not about a write to a socket somebody closed. Exiting here would let one
+        // departing client take down the daemon serving every other agent.
+        if (absorbDisconnect(err, log, disconnected))
+            return;
+        log('reticle_daemon_uncaught_exception', { error: describe(err) });
+        reportCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
+        onFatal();
+    });
+}
+/**
+ * Process-level resilience for the MCP PROXY, whose rule is the opposite of the daemon's.
+ *
+ * The daemon exits on an uncaught throw because the next `reticle mcp` respawns it. Nothing respawns
+ * the proxy — it is the stdio server the editor launched, and its exit is what the user experiences
+ * as "the MCP server disconnected, open /mcp and reconnect". So it logs and keeps serving: its whole
+ * state is a socket and a queue, and it already knows how to rebuild both (see the reconnect and
+ * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
+ * dead one answers nothing and needs a human.
+ *
+ * `onCrash` is for reporting only — it must not end the process.
+ */
+export function installProxyResilience(proc, log, onCrash = reportCrash) {
+    const disconnected = 'reticle_mcp_proxy_client_disconnected';
+    proc.on('unhandledRejection', (reason) => {
+        if (absorbDisconnect(reason, log, disconnected))
+            return;
+        log('reticle_mcp_proxy_unhandled_rejection', { reason: describe(reason) });
+        onCrash(CrashKind.UNHANDLED_REJECTION, reason);
+    });
+    proc.on('uncaughtException', (err) => {
+        // The client closing its end of stdio is how this process is SUPPOSED to end its day.
+        if (absorbDisconnect(err, log, disconnected))
+            return;
+        log('reticle_mcp_proxy_uncaught_exception', {
+            error: describe(err),
+            note: 'still serving — exiting here would disconnect the MCP client',
+        });
+        onCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
+    });
+}

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

@@ -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 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

@@ -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