@reticlehq/server 2.6.0 → 2.8.0

package/dist/mcp/mcp-proxy.js

@@ -2,14 +2,15 @@ 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';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
-import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, OnDrop, OnRequest, } from './proxy-lifecycle.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,11 +551,19 @@ 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
+                // NEXT request re-probe the port instead of queueing behind a reconnect that will never
+                // land, and it is the only path by which a daemon started AFTER we gave up is ever found.
+                dormant = onQueueExpired() === OnDrop.DORMANT;
                 proxyLog('reticle_mcp_proxy_queue_expired', {
                     port,
-                    note: 'answered queued requests instead of holding them for a daemon that never arrived',
+                    dormant,
+                    note: 'answered queued requests and went dormant; the next client request re-probes the port',
                 });
             }, QUEUE_WAIT_MS);
             queueTimer.unref();
@@ -457,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.
          *
@@ -502,6 +631,7 @@ ensureDaemon) {
                 clearQueueTimer();
                 for (const queued of stdinQueue.splice(0))
                     forward(url, queued);
+                handshakeAnswered = true;
                 return;
             }
             if ('message' === event && !replay.shouldSuppressInbound(data)) {
@@ -511,14 +641,30 @@ 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 — 320 of 321 measured drops killed nothing in flight.
+            // part an agent can FEEL — almost every measured drop killed nothing in flight.
             reportMcpOutage(OutageStage.FIRST, { reason, attempts, pendingLost });
             // The severe stage: we are about to stop retrying. Reported so the share of sessions where
             // MCP never came back on its own is a number rather than an anecdote.
@@ -566,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) => {
@@ -599,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

@@ -18,6 +18,7 @@ import { SERVER_VERSION } from '../version/server-version.js';
 import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { parsePredicate } from '../events/predicate-parse.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
@@ -272,6 +273,17 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
             // McpError.message already carries "MCP error -32602: "; re-wrapping would print it twice.
             const raw = error instanceof Error ? error.message : String(error);
             const detail = raw.replace(/^MCP error -?\d+:\s*/, '');
+            // A malformed PREDICATE gets the sentence, not the array. The SDK validates tool input against
+            // the same zod schema and throws a serialized issue list — so the readable message
+            // `parsePredicate` exists to produce was being generated only on paths that never run over
+            // MCP, which is every path a real agent uses. Found by driving a live app: `reticle_assert`
+            // answered a near-miss predicate with a raw zod array naming the unknown keys and not one
+            // field that would have worked. It already carries its own guidance, so the generic example is
+            // dropped rather than argued with.
+            const predicateHelp = predicateMessage(args);
+            if (predicateHelp !== undefined) {
+                throw new McpError(ErrorCode.InvalidParams, predicateHelp);
+            }
             const example = examples.get(toolName);
             const help = example === undefined
                 ? ` Call reticle_tools { names: ["${toolName}"] } for its parameters.`
@@ -280,6 +292,29 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         }
     };
 }
+/**
+ * The readable reason a predicate argument did not parse, or undefined when the predicate is fine.
+ *
+ * Undefined matters as much as the message: a call can fail validation for a reason that has nothing
+ * to do with the predicate (a bad `timeout_ms`, a missing `ref`), and replacing that error with a
+ * predicate explanation would be confidently wrong. Re-parsing is the honest test — if it parses,
+ * the predicate is not what broke.
+ */
+function predicateMessage(args) {
+    if (typeof args !== 'object' || null === args)
+        return undefined;
+    const record = args;
+    const predicate = record['predicate'] ?? record['until'];
+    if (predicate === undefined)
+        return undefined;
+    try {
+        parsePredicate(predicate);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : undefined;
+    }
+}
 /**
  * Answer a call for a real-but-un-advertised tool with the way to make it work.
  *
@@ -318,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
@@ -44,6 +44,25 @@ export declare function onStreamDrop(daemonListening: boolean): OnDrop;
  * whether the server survives.
  */
 export declare function onReconnectBudgetSpent(): OnDrop;
+/**
+ * What to do when queued requests expire with nothing connected. Always DORMANT.
+ *
+ * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
+ * proxy spent its budget against it, and from then on every call returned −32001 — including after
+ * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
+ * looked again.
+ *
+ * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
+ * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
+ * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
+ * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
+ * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
+ *
+ * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
+ * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
+ * arrived late, and it costs nothing when one has not.
+ */
+export declare function onQueueExpired(): OnDrop;
 /** What to do with a client message. */
 export declare const OnRequest: {
     /** Connected — post it straight through. */

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
@@ -47,6 +47,27 @@ export function onStreamDrop(daemonListening) {
 export function onReconnectBudgetSpent() {
     return OnDrop.DORMANT;
 }
+/**
+ * What to do when queued requests expire with nothing connected. Always DORMANT.
+ *
+ * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
+ * proxy spent its budget against it, and from then on every call returned −32001 — including after
+ * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
+ * looked again.
+ *
+ * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
+ * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
+ * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
+ * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
+ * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
+ *
+ * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
+ * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
+ * arrived late, and it costs nothing when one has not.
+ */
+export function onQueueExpired() {
+    return OnDrop.DORMANT;
+}
 /** What to do with a client message. */
 export const OnRequest = {
     /** Connected — post it straight through. */

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();
     }