@reticlehq/server 2.7.0 → 2.8.0

package/dist/mcp/mcp-proxy.js

@@ -2,7 +2,7 @@ import * as http from 'node:http';
 import { localInitializeResponse, isHandshakeLine } from './proxy-handshake.js';
 import { ToolCatalogCache } from './tool-catalog-cache.js';
 import * as net from 'node:net';
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleDir, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
@@ -10,6 +10,7 @@ import { SERVER_VERSION } from '../version/server-version.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy-lifecycle.js';
 import { log } from '../log.js';
+import { MAX_DAEMON_LOG_BYTES, rotateDaemonLog } from '../daemon/daemon.js';
 import { OutageStage, reportMcpOutage } from './mcp-outage.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
 /**
@@ -59,9 +60,77 @@ export const RECONNECT_INITIALIZE_ID = '__reticle_proxy_reinit';
  * session?" — needed a filter before it could be answered.
  */
 let logPort;
+/**
+ * How much the proxy may append between size checks.
+ *
+ * Statting the file on every line would be a syscall per log line on a process that logs from a
+ * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
+ * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
+ */
+export const PROXY_LOG_CHECK_BYTES = 256 * 1024;
+/** Appended since the last real size check. Reset by every check, whatever the check decides. */
+let bytesSinceProxyLogCheck = 0;
+/**
+ * Keep the proxy log under the same cap as the daemon log, without a stat per write.
+ *
+ * Returns the new "bytes since the last check" counter, so the accounting is testable without a
+ * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
+ * daemon log on the SAME machine stayed small, which is the whole of this defect.
+ */
+export function accountProxyLogWrite(bytesSinceCheck, written, path, deps) {
+    const total = bytesSinceCheck + written;
+    if (PROXY_LOG_CHECK_BYTES > total)
+        return total;
+    rotateDaemonLog(path, deps);
+    return 0;
+}
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
+ * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
+ * failure surfaced as the operating system refusing to write files. Files like that exist on real
+ * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
+ *
+ * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
+ * and a file that a running process still holds open keeps its blocks allocated after an unlink
+ * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
+ * and why that is the operation to copy here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
+ * housekeeping is strictly worse than a large file.
+ */
+export function recoverOversizedProxyLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        const size = deps.fileSize(path);
+        if (max >= size)
+            return 0;
+        deps.truncateFile(path);
+        return size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** The real filesystem behind the two rotation helpers. */
+const proxyLogFileOps = {
+    fileSize: (p) => statSync(p).size,
+    renameFile: (from, to) => renameSync(from, to),
+    truncateFile: (p) => truncateSync(p, 0),
+};
 /** Name the proxy log after the port it serves. Called before anything can log. */
 export function setProxyLogPort(port) {
     logPort = port;
+    // The one moment we know a size check is worth its syscall, and the only place a file inherited
+    // from an older build can be brought back under control.
+    const reclaimed = recoverOversizedProxyLog(proxyLogPath(port), proxyLogFileOps);
+    if (0 < reclaimed) {
+        proxyLog('reticle_mcp_proxy_log_truncated', {
+            port,
+            reclaimedBytes: reclaimed,
+            note: 'the proxy log had grown past its cap and was truncated in place to reclaim the space',
+        });
+    }
 }
 /** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
 export function proxyLogPath(port = logPort) {
@@ -91,7 +160,12 @@ export function proxyLog(event, fields = {}) {
         // to precede `process.exit(1)` and cost the human a manual /mcp reconnect — and it was
         // impossible to tell whether it happened during that person's work or a test run hours earlier.
         // Evidence you cannot place in time is an anecdote.
-        appendFileSync(proxyLogPath(), `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`, 'utf8');
+        const path = proxyLogPath();
+        const line = `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`;
+        appendFileSync(path, line, 'utf8');
+        // A single proxy process is long-lived and logs from a reconnect loop, so rotating only at
+        // startup would leave the growth this file is capable of entirely unchecked while it runs.
+        bytesSinceProxyLogCheck = accountProxyLogWrite(bytesSinceProxyLogCheck, Buffer.byteLength(line, 'utf8'), path, proxyLogFileOps);
     }
     catch {
         // Logging must never be the thing that kills the proxy.
@@ -166,8 +240,10 @@ export class PendingRequests {
  * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
-export function streamLossReplies(pending, reason) {
-    return pending.drain().map((id) => transportLossReply(JSON.parse(id), reason));
+export function streamLossReplies(pending, reason, nextStep) {
+    return pending
+        .drain()
+        .map((id) => transportLossReply(JSON.parse(id), reason, nextStep));
 }
 /**
  * -32001: a server-defined error. Not -32603 (internal): nothing went wrong INSIDE the call, the
@@ -175,15 +251,21 @@ export function streamLossReplies(pending, reason) {
  * to retry.
  */
 const TRANSPORT_LOSS_CODE = -32001;
-/** The one shape every "the transport ate your call" answer takes, whichever leg died. */
-export function transportLossReply(id, reason) {
+/**
+ * The one shape every "the transport ate your call" answer takes, whichever leg died.
+ *
+ * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
+ * stops there, which is all a first-run user got out of their first ever tool call.
+ */
+export function transportLossReply(id, reason, nextStep) {
     return JSON.stringify({
         jsonrpc: '2.0',
         id,
         error: {
             code: TRANSPORT_LOSS_CODE,
             message: `the daemon connection dropped (${reason}) before this call was answered — it did NOT ` +
-                'complete. Reticle is recovering the connection; retry if the action is safe to repeat.',
+                'complete. Reticle is recovering the connection; retry if the action is safe to repeat.' +
+                (nextStep === undefined ? '' : ` ${nextStep}`),
         },
     });
 }
@@ -207,8 +289,38 @@ const SHUTDOWN_DRAIN_MS = 5_000;
  * well under the 60s an MCP client typically allows, so the answer comes from us with a reason
  * rather than from their timer with none.
  */
-const QUEUE_WAIT_MS = 20_000;
+export const QUEUE_WAIT_MS = 20_000;
 const SHUTDOWN_DRAIN_POLL_MS = 25;
+/** A port that refuses is a port nothing is listening on YET — not a port that answered badly. */
+const CONNECTION_REFUSED = 'ECONNREFUSED';
+/**
+ * How long the FIRST connect keeps chasing a refused port before calling it a startup failure.
+ *
+ * It used to get exactly one attempt. Reported from a Windows first bootstrap: the daemon was still
+ * booting, the single connect was refused, and nothing tried again — only a fresh CLIENT request
+ * re-probes the port, and the client was already blocked on the call that then expired with -32001.
+ * The first tool call of somebody's first ever session is the worst place available to lose one.
+ *
+ * Deliberately longer than QUEUE_WAIT_MS: a retry that stops before the queue does cannot rescue the
+ * request it exists for, and a daemon found afterwards at least restores service for the next call.
+ */
+const FIRST_CONNECT_WINDOW_MS = QUEUE_WAIT_MS + 15_000;
+/** Retry a first connect, or report it? Pure, so the window can be held against the queue's. */
+export function shouldRetryFirstConnect(error, elapsedMs) {
+    const code = error?.code;
+    return CONNECTION_REFUSED === code && FIRST_CONNECT_WINDOW_MS > elapsedMs;
+}
+/**
+ * What to do about it, carried on the reply the queue expiry sends.
+ *
+ * A bare -32001 on the first call after an install says nothing a user can act on: not whether to
+ * wait, not whether to retry, not whether the install itself is broken.
+ */
+export function queueExpiryNextStep(port) {
+    return (`No Reticle daemon answered on port ${String(port)}. Retry the call — the next request starts ` +
+        'one. If it keeps failing, run `reticle doctor` in a terminal: it reports what is holding the ' +
+        'port and whether the daemon can start at all.');
+}
 /**
  * Makes a reconnect invisible to the client.
  *
@@ -439,8 +551,9 @@ ensureDaemon) {
                     return;
                 // Drop what we could never send, and answer it, so the caller is never left guessing.
                 stdinQueue.splice(0);
-                for (const reply of streamLossReplies(pending, 'no daemon could be reached'))
+                for (const reply of streamLossReplies(pending, 'no daemon could be reached', queueExpiryNextStep(port))) {
                     emit(reply);
+                }
                 // The expiry is the proof that the reconnect we believed was in flight is not coming — a
                 // wedged port accepts the socket and never serves SSE, so `connect` neither resolves nor
                 // rejects and `dormant` would otherwise stay false forever. Going dormant is what makes the
@@ -464,6 +577,15 @@ ensureDaemon) {
         };
         let stopped = false;
         let attempts = 0;
+        /**
+         * When the proxy started, and how many times the first connect has been refused since.
+         *
+         * The clock is read at this boundary rather than injected, matching the shutdown drain below:
+         * it measures how long a real daemon has had to boot, which is a wall-clock fact about the
+         * machine and not a decision the caller could supply.
+         */
+        const startedAt = Date.now();
+        let firstConnectAttempts = 0;
         /**
          * The ONE way a line leaves for the daemon — so a POST that never lands still owes an answer.
          *
@@ -509,6 +631,7 @@ ensureDaemon) {
                 clearQueueTimer();
                 for (const queued of stdinQueue.splice(0))
                     forward(url, queued);
+                handshakeAnswered = true;
                 return;
             }
             if ('message' === event && !replay.shouldSuppressInbound(data)) {
@@ -518,11 +641,27 @@ ensureDaemon) {
                 emit(data);
             }
         }
-        function scheduleReconnect(reason, detail, pendingLost = 0) {
+        function scheduleReconnect(reason, detail) {
             if (stopped)
                 return;
             postUrl = null;
             attempts++;
+            // Everything the dead session owed is settled HERE, in the one place every drop funnels
+            // through, and not in the response callback that first noticed the socket die. A reset emits
+            // on BOTH halves of the request, so whichever handler wins decides what gets paid — the same
+            // shape as the reconnect fan-out, and it left the other half paying nothing.
+            //
+            // Order matters between the two. Drain the queue FIRST: a queued request is tracked in
+            // `pending` as well, so answering without draining leaves the next `endpoint` frame free to
+            // flush it into the fresh session, where the daemon answers the same id a second time and the
+            // client sees two responses for one request. Then answer, because the new session cannot know
+            // what the old one owed and silence here is permanent.
+            stdinQueue.splice(0);
+            const lost = streamLossReplies(pending, reason);
+            for (const reply of lost)
+                emit(reply);
+            // How many calls this drop actually killed. Zero means the agent could not feel it.
+            const pendingLost = lost.length;
             // Once per process: this session has now lost its tools at least once, which is the number
             // that says whether the transport work actually landed for real users. `pendingLost` is the
             // part an agent can FEEL — almost every measured drop killed nothing in flight.
@@ -573,23 +712,45 @@ ensureDaemon) {
             // Announce this process to the daemon on the connect we already make — it is the single judge
             // of version skew, and this is the only moment it learns the agent's MCP server exists.
             const announce = `${MCP_SSE_PATH}?${PEER_VERSION_PARAM}=${encodeURIComponent(SERVER_VERSION)}&${PEER_CONTRACT_PARAM}=${encodeURIComponent(CONTRACT_FINGERPRINT)}`;
+            /**
+             * ONE reconnect per connect attempt, whoever notices the failure first.
+             *
+             * A dead socket emits on BOTH halves — `req`'s `error` and the response's `aborted`/`close`
+             * for the same TCP death — and this latch used to live inside the response callback, so
+             * `req.on('error')` scheduled a SECOND reconnect that the drop path could not see. Two chains
+             * came back, both died the same way, and both split again. The retry budget cannot stop that
+             * either: any one chain reaching an `endpoint` frame resets `attempts` to zero for all of
+             * them. It is the runaway behind a proxy log large enough to fill a disk, and the doubling is
+             * visible in the field logs as roughly two `reconnecting` lines per `reconnected` one.
+             */
+            let settled = false;
+            /**
+             * Whether this attempt ever got a response, as opposed to never reaching the daemon.
+             *
+             * `first` alone conflates two different situations, and the `req.on('error')` branch below
+             * treats both as a startup failure the caller handles. Before any stream exists that is right:
+             * there is no daemon, so rejecting is the honest answer. Once the FIRST stream has connected
+             * and is serving, a socket reset is a DROP, and rejecting it kills the proxy outright instead
+             * of reconnecting. The agent loses Reticle for the rest of the session, on its first stream,
+             * with nothing to retry it.
+             *
+             * It is also a race rather than a certainty, which is worse: a reset emits on both halves, so
+             * whether the proxy reconnects or dies depended on whether `res`'s `close` or `req`'s `error`
+             * won. Every later stream recovers correctly; you simply have to survive the first one.
+             */
+            let responded = false;
             const req = http.get({ host: LOOPBACK_HOST, port, path: announce }, (res) => {
+                responded = true;
                 if (!first)
                     proxyLog('reticle_mcp_proxy_reconnected', { port });
                 res.setEncoding('utf8');
-                // `end` and `error` can both fire on one response; only the first should drive a reconnect.
-                let settled = false;
                 const drop = (reason, detail) => {
                     if (settled)
                         return;
                     settled = true;
-                    // Answer anything the dead session owed BEFORE reconnecting. The new session cannot know
-                    // about it, so silence here is permanent.
-                    const lost = streamLossReplies(pending, reason);
-                    for (const reply of lost)
-                        emit(reply);
-                    // How many calls this drop actually killed. Zero means the agent could not feel it.
-                    scheduleReconnect(reason, detail, lost.length);
+                    // What the dead session owed is settled inside scheduleReconnect, so the other half of the
+                    // socket's death pays exactly the same debt when it is the one that notices first.
+                    scheduleReconnect(reason, detail);
                 };
                 const sse = new SseFrameParser();
                 res.on('data', (chunk) => {
@@ -606,7 +767,31 @@ ensureDaemon) {
             });
             // The very first connect failing means there is no daemon to talk to — that is a startup
             // failure the caller handles. Later ones are just the daemon bouncing: keep retrying.
-            req.on('error', (err) => first ? reject(err) : scheduleReconnect('connect_error', err.message));
+            req.on('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (first && !responded) {
+                    // A refused port on the very first connect is a daemon still booting, not a failure. Keep
+                    // chasing it: nothing else will, because only a fresh client request re-probes the port
+                    // and the client is already blocked on the call this would rescue.
+                    if (shouldRetryFirstConnect(err, Date.now() - startedAt)) {
+                        firstConnectAttempts++;
+                        const retryInMs = reconnectDelayMs(firstConnectAttempts);
+                        proxyLog('reticle_mcp_proxy_first_connect_retry', {
+                            port,
+                            attempt: firstConnectAttempts,
+                            retryInMs,
+                            note: 'the daemon has not finished booting; still waiting for it to accept',
+                        });
+                        setTimeout(() => connect(true), retryInMs).unref();
+                        return;
+                    }
+                    reject(err);
+                    return;
+                }
+                scheduleReconnect('connect_error', err.message);
+            });
         }
         connect(true);
         // ── stdin reader ─────────────────────────────────────────────────────────

package/dist/mcp/mcp.js

@@ -353,15 +353,31 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
     // session says which one it saw.
     getSessionMetrics().recordSurface(profile);
     const server = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
-    // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
-    // hook rather than read here: the handshake has not happened yet at construction time, and a
-    // feedback report filed twenty tool calls later is exactly when we want the answer.
+    /**
+     * Record WHICH agent attached, at the handshake, for every session.
+     *
+     * `clients` and `clientVersions` were populated for almost nobody, and the reason was not that
+     * clients withhold `clientInfo` — they send it, and we read it. It was that the ONLY thing that
+     * ever called `recordClient` was the feedback hook below, which runs when a report is being built.
+     * So the field was really measuring "sessions that filed feedback", and a product whose users are
+     * agents could not say which agent, on which build, any of its numbers came from.
+     *
+     * `oninitialized` is the moment `clientInfo` first exists — reading it at construction time gets
+     * `undefined`, which is what made a lazy hook look like the only option.
+     */
+    server.server.oninitialized = () => {
+        const info = server.server.getClientVersion();
+        if (info?.name !== undefined)
+            getSessionMetrics().recordClient(info.name, info.version);
+    };
+    // Which agent is on the other end, for a feedback report. Registered as a lazy hook rather than
+    // read here: the handshake has not happened yet at construction time, and a report filed twenty
+    // tool calls later is exactly when we want the answer.
     setMcpClientNameHook(() => {
         const info = server.server.getClientVersion();
-        // Record it as a side effect of the first read so the session summary can report WHICH agents
-        // drove this daemon — the multi-agent story, visible without a second plumbing path.
-        // Name AND version: the version was already in this handshake and was being dropped, so a
-        // regression in agent behaviour could never be attributed to a client build.
+        // Still records, because a client that skipped the handshake path above (a replayed initialize
+        // through the proxy, a transport that reconnects) is a client we would otherwise lose entirely.
+        // `recordClient` is idempotent per name.
         if (info?.name !== undefined)
             getSessionMetrics().recordClient(info.name, info.version);
         return info === undefined ? undefined : { name: info.name, version: info.version };

package/dist/mcp/proxy-lifecycle.d.ts

@@ -7,7 +7,7 @@
  * that crashed or was stopped used to take the agent's whole Reticle surface with it. Together they
  * loop: the daemon exits as useless, the proxy immediately brings back a daemon that is equally
  * useless, which exits, forever. Measured with a 4s grace: four processes in 200 seconds. At the
- * real 300s grace that is a new process every five minutes for the 74% of installs that never call a
+ * real 300s grace that is a new process every five minutes for the many installs that never call a
  * tool, for as long as the editor is open.
  *
  * The rule that resolves it: a dropped stream is not demand. Reattach to a daemon that is already

package/dist/mcp/proxy-lifecycle.js

@@ -7,7 +7,7 @@
  * that crashed or was stopped used to take the agent's whole Reticle surface with it. Together they
  * loop: the daemon exits as useless, the proxy immediately brings back a daemon that is equally
  * useless, which exits, forever. Measured with a 4s grace: four processes in 200 seconds. At the
- * real 300s grace that is a new process every five minutes for the 74% of installs that never call a
+ * real 300s grace that is a new process every five minutes for the many installs that never call a
  * tool, for as long as the editor is open.
  *
  * The rule that resolves it: a dropped stream is not demand. Reattach to a daemon that is already

package/dist/pool/browser-pool.d.ts

@@ -60,7 +60,8 @@ interface BrowserPoolOptions {
 export declare class BrowserPool {
     #private;
     constructor(launch: Launcher, opts: BrowserPoolOptions);
-    /** Currently leased contexts. */
+    /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
+    leaseTtlMs(): number;
     /** Max simultaneous leases — the ceiling the parallel suite sizes its concurrency to. */
     capacity(): number;
     activeCount(): number;
@@ -68,8 +69,27 @@ export declare class BrowserPool {
     queuedCount(): number;
     /** The sessionIds of every currently leased context — used to report/group leased sessions. */
     leasedSessionIds(): string[];
-    /** Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown. */
+    /**
+     * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
+     *
+     * Resolves an alias first, because the agent releases with the id it was GIVEN, which for an app
+     * that named its own session is not the id the pool navigated with. Releasing by that name used to
+     * be a silent no-op that left the slot held until the reaper took it.
+     */
     release(sessionId: string): Promise<void>;
+    /**
+     * Record that a lease is also known by the name the APP registered.
+     *
+     * Leases are keyed by the id the pool navigated with, and the SDK normally adopts that id off the
+     * URL so the two agree. An app that passes an explicit `session` to `connect()` keeps its own name
+     * instead, which is legitimate, and the lease tool then hands the agent THAT name because it is the
+     * one it has to drive with. Every later touch and release arrives under it.
+     *
+     * Without this the touches hit nothing, the lease ages out despite continuous activity, and the
+     * reaper closes the context mid-flow — the failure in #157, where a session died on the very call
+     * that would have read a computed value.
+     */
+    alias(registeredId: string, leaseId: string): void;
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId: string): void;
     /**

package/dist/pool/browser-pool.js

@@ -30,6 +30,8 @@ export class BrowserPool {
     /** Leases reclaimed for going stale — see reapedLeaseCount(). */
     #reapedLeases = 0;
     #active = new Map();
+    /** Registered-session-id → lease id, for apps that keep their own session name. See `alias`. */
+    #aliases = new Map();
     /**
      * Slots claimed-or-active — the real concurrency gate. Incremented SYNCHRONOUSLY the instant an
      * acquire passes the cap check, BEFORE the async context creation, so a burst of concurrent
@@ -50,7 +52,10 @@ export class BrowserPool {
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
     }
-    /** Currently leased contexts. */
+    /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
+    leaseTtlMs() {
+        return this.#ttl;
+    }
     /** Max simultaneous leases — the ceiling the parallel suite sizes its concurrency to. */
     capacity() {
         return this.#max;
@@ -66,13 +71,42 @@ export class BrowserPool {
     leasedSessionIds() {
         return [...this.#active.keys()];
     }
-    /** Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown. */
+    /**
+     * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
+     *
+     * Resolves an alias first, because the agent releases with the id it was GIVEN, which for an app
+     * that named its own session is not the id the pool navigated with. Releasing by that name used to
+     * be a silent no-op that left the slot held until the reaper took it.
+     */
     release(sessionId) {
-        return this.#release(sessionId);
+        return this.#release(this.#leaseIdOf(sessionId));
+    }
+    /**
+     * Record that a lease is also known by the name the APP registered.
+     *
+     * Leases are keyed by the id the pool navigated with, and the SDK normally adopts that id off the
+     * URL so the two agree. An app that passes an explicit `session` to `connect()` keeps its own name
+     * instead, which is legitimate, and the lease tool then hands the agent THAT name because it is the
+     * one it has to drive with. Every later touch and release arrives under it.
+     *
+     * Without this the touches hit nothing, the lease ages out despite continuous activity, and the
+     * reaper closes the context mid-flow — the failure in #157, where a session died on the very call
+     * that would have read a computed value.
+     */
+    alias(registeredId, leaseId) {
+        if (registeredId === leaseId)
+            return;
+        if (!this.#active.has(leaseId))
+            return;
+        this.#aliases.set(registeredId, leaseId);
+    }
+    /** The lease this id refers to: itself, or whatever it is an alias for. */
+    #leaseIdOf(sessionId) {
+        return this.#active.has(sessionId) ? sessionId : (this.#aliases.get(sessionId) ?? sessionId);
     }
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId) {
-        const lease = this.#active.get(sessionId);
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
         if (lease !== undefined)
             lease.touchedAt = this.#now();
     }
@@ -173,6 +207,12 @@ export class BrowserPool {
         if (lease === undefined)
             return; // already released or lost to a crash
         this.#active.delete(sessionId);
+        // Drop any alias pointing here, or the map grows for the life of the daemon and a later lease
+        // reusing that registered name would resolve to a context that is already closed.
+        for (const [registered, leaseId] of this.#aliases) {
+            if (leaseId === sessionId)
+                this.#aliases.delete(registered);
+        }
         await lease.context.close().catch(() => undefined);
         this.#releaseSlot();
     }

package/dist/project/learned-routes.d.ts

@@ -0,0 +1,24 @@
+import { type ReticleEvent } from '@reticlehq/core';
+interface RouteLearningSession {
+    url: string;
+    onEvent(handler: (event: ReticleEvent) => void): () => void;
+}
+interface RouteLearningBridge {
+    sessions: {
+        all(): RouteLearningSession[];
+    };
+    attachSessionReady(handler: (session: RouteLearningSession) => void): void;
+}
+interface RouteLearningStore {
+    recordRoutes(routes: readonly string[]): Promise<void>;
+}
+/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
+export declare const ROUTE_PERSIST_DEBOUNCE_MS = 50;
+/** Convert a validated route-change payload into a bounded route identity. */
+export declare function routeFromEvent(event: ReticleEvent): string | undefined;
+/** Read the same route shape from a session's absolute URL. */
+export declare function routeFromUrl(value: string): string | undefined;
+export declare function routesFromEvents(events: readonly ReticleEvent[]): string[];
+/** Persist initial and subsequent routes for existing and future browser sessions. */
+export declare function attachRouteLearning(bridge: RouteLearningBridge, project: RouteLearningStore): void;
+export {};

package/dist/project/learned-routes.js

@@ -0,0 +1,63 @@
+import { EventType } from '@reticlehq/core';
+/** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
+export const ROUTE_PERSIST_DEBOUNCE_MS = 50;
+/** Convert a validated route-change payload into a bounded route identity. */
+export function routeFromEvent(event) {
+    if (event.type !== EventType.ROUTE_CHANGE)
+        return undefined;
+    const pathname = event.data['pathname'];
+    if ('string' !== typeof pathname || 0 === pathname.length)
+        return undefined;
+    return pathname;
+}
+/** Read the same route shape from a session's absolute URL. */
+export function routeFromUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function routesFromEvents(events) {
+    return events.flatMap((event) => {
+        const route = routeFromEvent(event);
+        return route === undefined ? [] : [route];
+    });
+}
+/** Persist initial and subsequent routes for existing and future browser sessions. */
+export function attachRouteLearning(bridge, project) {
+    const attached = new WeakSet();
+    const pending = new Set();
+    let flushTimer;
+    const flush = () => {
+        flushTimer = undefined;
+        const routes = [...pending];
+        pending.clear();
+        if (routes.length > 0)
+            void project.recordRoutes(routes).catch(() => undefined);
+    };
+    const queue = (route) => {
+        pending.add(route);
+        if (flushTimer !== undefined)
+            clearTimeout(flushTimer);
+        flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
+    };
+    const attach = (session) => {
+        if (attached.has(session))
+            return;
+        attached.add(session);
+        const initial = routeFromUrl(session.url);
+        if (initial !== undefined)
+            queue(initial);
+        session.onEvent((event) => {
+            const route = routeFromEvent(event);
+            if (route !== undefined)
+                queue(route);
+        });
+    };
+    for (const session of bridge.sessions.all())
+        attach(session);
+    bridge.attachSessionReady(attach);
+}

package/dist/project/project-store.d.ts

@@ -26,6 +26,12 @@ export declare class ProjectStore {
      * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
      */
     recordRun(record: Omit<RunRecord, 'at'>): Promise<void>;
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    recordRoutes(routes: readonly string[]): Promise<void>;
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }

package/dist/project/project-store.js

@@ -1,4 +1,4 @@
-import { PROJECT_FILE_VERSION, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
+import { PROJECT_FILE_VERSION, PROJECT_ROUTE_CAP, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
 import { reticleDirPaths } from './reticle-dir.js';
 import { withFileLock } from './file-lock.js';
 const JSON_INDENT = 2;
@@ -77,6 +77,30 @@ export class ProjectStore {
             await this.#fs.writeFile(path, this.#serialize(next));
         });
     }
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    async recordRoutes(routes) {
+        const additions = routes.filter((route) => route.length > 0);
+        if (0 === additions.length)
+            return;
+        const path = reticleDirPaths(this.#root).project;
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const current = base.learned?.routes ?? [];
+            const merged = [...new Set([...current, ...additions])].slice(0, PROJECT_ROUTE_CAP);
+            if (merged.length === current.length &&
+                merged.every((route, index) => route === current[index]))
+                return;
+            const learned = { ...base.learned, routes: merged };
+            const next = { ...base, learned };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            await this.#fs.writeFile(path, this.#serialize(next));
+        });
+    }
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     async lastRun(name) {
         const read = await this.read();