@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/mcp/proxy/mcp-post-transport.js

@@ -0,0 +1,109 @@
+/**
+ * The MCP proxy's POST leg: its own socket pool, and the one retry that is safe to make.
+ *
+ * Split out of `mcp-proxy.ts` when that file passed the 1000-line backstop after two independent
+ * hardenings of this path met in a merge. It earns its own module rather than being an arbitrary
+ * slice: everything here is about ONE thing — getting a single JSON-RPC line into the daemon, or
+ * saying honestly that it never arrived — and the file it came from is about the SSE stream.
+ */
+import * as http from 'node:http';
+import { log } from '../../../log.js';
+import { getSessionMetrics } from '../../../telemetry/session-metrics.js';
+import { reconnectDelayMs } from './proxy-backoff.js';
+/** One bounded pool for the short-lived POST side of each MCP SSE session. */
+export const MCP_PROXY_HTTP_AGENT_OPTIONS = {
+    keepAlive: true,
+    keepAliveMsecs: 30_000,
+    timeout: 60_000,
+    maxSockets: 8,
+    scheduling: 'lifo',
+};
+const MCP_PROXY_HTTP_AGENT = new http.Agent(MCP_PROXY_HTTP_AGENT_OPTIONS);
+/**
+ * POST one JSON-RPC line into the daemon's session. Resolves null on success, or a structured
+ * failure when the request never reached a server that will answer it.
+ *
+ * It used to resolve `void` in every case, logging the failure and moving on. That is the THIRD way
+ * a call goes unanswered, and the only one neither `streamLossReplies` nor the queue timer can see:
+ * the SSE stream is healthy (so nothing drops) and the request was forwarded (so nothing is queued),
+ * but the POST leg is its own TCP connection and an ECONNRESET on it means the daemon never received
+ * the call. Nobody was ever going to reply, and the caller waited for its own timeout.
+ */
+const RETRYABLE_UNSENT_POST_ERRORS = new Set(['ENOBUFS', 'ERR_NO_BUFFER_SPACE', 'EADDRNOTAVAIL']);
+export function shouldRetryUnsentPost(error, bytesWritten, retryCount) {
+    const code = error?.code;
+    return 0 === retryCount && 0 === bytesWritten && RETRYABLE_UNSENT_POST_ERRORS.has(String(code));
+}
+export function postToSession(url, body, request = (options, callback) => http.request(options, callback)) {
+    const send = (retryCount) => new Promise((resolve) => {
+        const parsed = new URL(url);
+        const bodyBuf = Buffer.from(body, 'utf8');
+        const options = {
+            host: parsed.hostname,
+            port: parsed.port !== '' ? parseInt(parsed.port, 10) : 80,
+            path: `${parsed.pathname}${parsed.search}`,
+            method: 'POST',
+            agent: MCP_PROXY_HTTP_AGENT,
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': bodyBuf.byteLength,
+            },
+        };
+        // A keep-alive socket carries historical bytes; retry safety depends on this request's delta.
+        let socket;
+        let socketBytesBeforeRequest = 0;
+        let settled = false;
+        const req = request(options, (res) => {
+            if (settled)
+                return;
+            settled = true;
+            const status = res.statusCode ?? 0;
+            const rejected = status < 200 || status >= 300;
+            if (rejected) {
+                // A non-2xx from the daemon MCP endpoint used to be swallowed, hanging the JSON-RPC call
+                // client-side with no diagnostic. It is a refusal: no response is coming over the stream.
+                log('reticle_mcp_proxy_post_non2xx', { status, path: options.path });
+            }
+            else if (retryCount > 0) {
+                getSessionMetrics().recordPostRetrySaved();
+            }
+            res.resume(); // drain so the socket is reused
+            resolve(rejected
+                ? {
+                    reason: `daemon rejected the call with HTTP ${String(status)}`,
+                    transport: false,
+                    attempts: retryCount + 1,
+                }
+                : null);
+        });
+        req.once('socket', (assigned) => {
+            socket = assigned;
+            socketBytesBeforeRequest = assigned.bytesWritten;
+        });
+        req.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            // Invisible to mcp_connection_lost (SSE is up) and to tool_refused (handler never ran).
+            getSessionMetrics().recordPostSocketFailure();
+            const bytesWritten = socket === undefined ? 0 : Math.max(0, socket.bytesWritten - socketBytesBeforeRequest);
+            if (shouldRetryUnsentPost(err, bytesWritten, retryCount)) {
+                const retryInMs = reconnectDelayMs(retryCount + 1);
+                log('reticle_mcp_proxy_post_retry', {
+                    code: err.code,
+                    retryInMs,
+                });
+                setTimeout(() => void send(retryCount + 1).then(resolve), retryInMs);
+                return;
+            }
+            log('reticle_mcp_proxy_post_error', { error: err.message });
+            resolve({
+                reason: `post failed: ${err.message}`,
+                transport: true,
+                attempts: retryCount + 1,
+            });
+        });
+        req.end(bodyBuf);
+    });
+    return send(0);
+}

package/dist/surface/mcp/proxy/proxy-daemon-probe.d.ts

@@ -0,0 +1,22 @@
+export declare function daemonPollDelayMs(attempt: number): number;
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export declare function probeDaemon(port: number): Promise<boolean>;
+/**
+ * Poll until a Reticle daemon is SERVING on `port`, or the deadline passes.
+ *
+ * "Accepts a TCP connection" is not the question. A daemon wedged mid-start accepts and never
+ * serves, and so does a stranger holding the port — `port-presence.ts` calls both FOREIGN for
+ * exactly this reason, and every other decision point in the codebase was migrated onto it. This
+ * one was not, so the wake path spawned a daemon, waited on a bare connect, and dialled a corpse.
+ *
+ * Probes are injected (defaulting to the real pair) so the rule is testable without a socket, which
+ * is the same shape `probePresence`'s own callers use.
+ */
+export declare function waitForDaemon(port: number, probes?: {
+    tcpOpen: (port: number) => Promise<boolean>;
+    status: (port: number) => Promise<unknown>;
+}): Promise<void>;

package/dist/surface/mcp/proxy/proxy-daemon-probe.js

@@ -0,0 +1,71 @@
+import * as net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+import { describePresence, presenceIsUsable, probePresence, PortPresence, } from '../../../command/daemon/binding/port-presence.js';
+import { fetchStatus } from '../../../command/daemon/binding/daemon-status-probe.js';
+const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
+/**
+ * How long to wait for the spawned daemon's port to accept connections before giving up. The default
+ * suits a normal machine; a slow CI/VM (heavy headless-browser launch) can raise it via the
+ * RETICLE_DAEMON_READY_TIMEOUT_MS env var. Invalid/absent values fall back to the default.
+ */
+const envDaemonReadyTimeoutMs = Number(process.env['RETICLE_DAEMON_READY_TIMEOUT_MS']);
+const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envDaemonReadyTimeoutMs > 0
+    ? envDaemonReadyTimeoutMs
+    : DEFAULT_DAEMON_READY_TIMEOUT_MS;
+const DAEMON_POLL_INTERVAL_MS = 100;
+const DAEMON_POLL_MAX_INTERVAL_MS = 1_000;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function daemonPollDelayMs(attempt) {
+    return Math.min(DAEMON_POLL_INTERVAL_MS * attempt, DAEMON_POLL_MAX_INTERVAL_MS);
+}
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export function probeDaemon(port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(500);
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, LOOPBACK_HOST);
+    });
+}
+/**
+ * Poll until a Reticle daemon is SERVING on `port`, or the deadline passes.
+ *
+ * "Accepts a TCP connection" is not the question. A daemon wedged mid-start accepts and never
+ * serves, and so does a stranger holding the port — `port-presence.ts` calls both FOREIGN for
+ * exactly this reason, and every other decision point in the codebase was migrated onto it. This
+ * one was not, so the wake path spawned a daemon, waited on a bare connect, and dialled a corpse.
+ *
+ * Probes are injected (defaulting to the real pair) so the rule is testable without a socket, which
+ * is the same shape `probePresence`'s own callers use.
+ */
+export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, status: fetchStatus }) {
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    let attempt = 0;
+    let presence = PortPresence.FREE;
+    while (Date.now() < deadline) {
+        presence = await probePresence(port, probes);
+        if (presenceIsUsable(presence))
+            return;
+        attempt++;
+        await delay(daemonPollDelayMs(attempt));
+    }
+    // The state we timed out in is the whole diagnosis — FREE means the daemon never came up, FOREIGN
+    // means something is squatting the port. Reporting only the timeout sent readers hunting the
+    // wrong one.
+    throw new Error(`reticle daemon did not become ready on port ${String(port)} within ` +
+        `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePresence(presence, port)}`);
+}

package/dist/surface/mcp/proxy/proxy-handshake.js

@@ -0,0 +1,192 @@
+/**
+ * Answer `initialize` when the daemon cannot.
+ *
+ * The proxy queues every client message until the daemon's SSE endpoint frame arrives. `initialize`
+ * is a client message, so when the daemon port is held by something that accepts connections and
+ * never serves SSE — a wedged daemon, a foreign process, a daemon leaked by another project — the
+ * handshake waits on a thing that is never coming. Reported from the field as "initialize never
+ * answers, no tools run at all"; reproduced with a listener that simply never responds.
+ *
+ * A hang is the worst possible outcome here: no tools, no diagnosis, nothing to retry. Completing
+ * the handshake locally gives the agent a working surface whose FIRST tool call reports the real
+ * problem through the no-session diagnostics that already exist.
+ *
+ * Safe because the proxy replays the client's own `initialize` to the daemon whenever a session is
+ * finally established (see `replayLines`), so the daemon still gets its handshake in order.
+ */
+import { SERVER_VERSION } from '../../../command/version/identity/server-version.js';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
+/** The version we answer with if the client proposed none. */
+const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
+/**
+ * The protocol's own way to say "the tool list you have is out of date, fetch it again".
+ *
+ * Load-bearing here rather than a nicety. When we answer `initialize` ourselves the catalog we serve
+ * is one we made up, and it is usually empty. Nothing else in the protocol ever corrects that: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Without this the session is
+ * connected, initialized and toolless until a human notices.
+ */
+export const TOOLS_CHANGED_NOTIFICATION = 'notifications/tools/list_changed';
+function parseLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return 'object' === typeof parsed && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when this queued client line is the handshake we answered ourselves. */
+export function isHandshakeLine(line) {
+    const msg = parseLine(line);
+    return 'initialize' === msg?.method || 'notifications/initialized' === msg?.method;
+}
+export function localInitializeResponse(line, 
+/**
+ * What the daemon would have advertised, so the client is not left with none.
+ *
+ * A client reads `instructions` ONCE, at initialize, and this response is sent precisely when no
+ * daemon is up to send its own — which is the first run of a fresh install. So the block telling
+ * someone that having these tools is not the same as being set up was permanently absent for the
+ * exact population it addresses, and the daemon's later correct instructions arrive at a client
+ * that will never read the field again.
+ *
+ * Empty means "nothing to say", and the field is then omitted rather than sent blank.
+ */
+instructions = '') {
+    const msg = parseLine(line);
+    if (null === msg || msg.method !== 'initialize')
+        return null;
+    // A notification carries no id and expects no reply; answering one is a protocol error.
+    if (msg.id === undefined || null === msg.id)
+        return null;
+    const proposed = msg.params?.protocolVersion;
+    return JSON.stringify({
+        jsonrpc: '2.0',
+        id: msg.id,
+        result: {
+            // Echo what the client asked for: answering with a version it did not offer is its own
+            // handshake failure.
+            protocolVersion: 'string' === typeof proposed ? proposed : FALLBACK_PROTOCOL_VERSION,
+            // `listChanged` is not decoration: a client that was not told the list can change has no
+            // reason to honour the notification we send when the daemon finally arrives, and declaring a
+            // capability we then rely on is the difference between a fix and a message into the void.
+            capabilities: { tools: { listChanged: true } },
+            serverInfo: { name: MCP_SERVER_NAME, version: SERVER_VERSION },
+            ...('' === instructions ? {} : { instructions }),
+        },
+    });
+}
+/**
+ * The line that tells a client its tool list is stale, or null when there is nothing to correct.
+ *
+ * When a daemon arrives after we answered the handshake ourselves, the client is holding a tool list
+ * we invented, and on a cold start that list is empty. Nothing else in this protocol corrects it: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Connected, initialized and
+ * toolless for the rest of the session, with a human required to notice and reconnect by hand.
+ *
+ * Sent only when the catalog was ours. A client that completed a real handshake with the daemon
+ * already has the true list, and telling it to refetch would be a round trip for nothing.
+ *
+ * Lives here rather than in the proxy because it belongs to the locally-answered handshake, which is
+ * this module's subject.
+ *
+ * Worth knowing before relying on it: this is a best-effort correction, not the mechanism. Research
+ * into the four clients we target found that only some honour `notifications/tools/list_changed` at
+ * all, so the catalog still has to be right in the FIRST answer for the rest. This closes the gap
+ * where it is honoured and costs one line where it is not.
+ */
+export function toolsChangedNotification(catalogWasLocal) {
+    if (!catalogWasLocal)
+        return null;
+    return JSON.stringify({ jsonrpc: '2.0', method: TOOLS_CHANGED_NOTIFICATION });
+}
+/**
+ * What a locally-answered handshake must say about itself.
+ *
+ * The proxy answering `initialize` is right — a hang gives the agent no tools AND no diagnosis — but
+ * the response it sent was INDISTINGUISHABLE from a daemon's. Same `serverInfo`, same capabilities,
+ * same `instructions`. So the client marked the server installed and enabled, the agent got a tool
+ * list that was cached at best and empty at worst, and nothing anywhere connected the two facts.
+ *
+ * Reported from the field, from two different agent hosts at once: the marketplace showed Reticle
+ * installed with the whole tool surface enabled, and the agent asked to verify a flow reported that
+ * RETICLE WAS NOT PRESENT ON THE MACHINE — while the daemon was running and a browser session was
+ * live. That conclusion is the reasonable reading of an empty surface with no explanation attached,
+ * and it is unrecoverable: the proxy's own recovery is "the next client request re-probes the port",
+ * and a client holding zero tools never makes another request.
+ *
+ * `instructions` is the channel because it is the only one that survives an empty catalog. It rides
+ * on the initialize result, which SUCCEEDED, and every host we target puts it in front of the model.
+ * A tool description cannot reach an agent that was handed no tools.
+ *
+ * The healthy block is kept underneath rather than replaced: an agent that IS about to get a working
+ * surface (the common case — the first call wakes a daemon) still needs to know how to drive it.
+ */
+export function degradedInstructions(healthy, port, reason) {
+    return `DEGRADED SURFACE — READ THIS BEFORE ANY reticle_* CALL: no Reticle daemon answered on port ${String(port)} (${reason}), so this handshake was completed by the Reticle MCP proxy itself, not by Reticle's daemon. Any tool list you were handed came from a cache or is empty — it is not evidence that anything is behind it.
+
+Reticle IS installed: this process is Reticle. Do NOT report it as missing, not present, or not installed — that is the wrong diagnosis and it is the one this state reliably produces. The right one is that the daemon is not reachable yet.
+
+Your next reticle_* call starts a daemon and then either works or fails with the specific reason. If you have NO reticle_* tools at all, say exactly that to the user and tell them to run \`reticle doctor\` in a terminal — it reports what is holding port ${String(port)} and whether a daemon can start at all.
+
+${healthy}`;
+}
+/**
+ * The largest single JSON-RPC line the proxy will accumulate from a client.
+ *
+ * Generous — a tool call with a big argument payload is legitimate — but finite, because without a
+ * ceiling the buffer grows to whatever is sent and the process is one `cat bigfile` away from an
+ * out-of-memory exit that would take the agent's whole tool surface with it.
+ */
+export const MAX_STDIN_LINE_BYTES = 16 * 1024 * 1024;
+/**
+ * Append a chunk and split off whatever complete lines it produced.
+ *
+ * The reason this is not `(buffer + chunk).split('\n')` inline: that re-scans the WHOLE accumulated
+ * buffer on every chunk, so a single large line costs O(n²) in the size of the line. Measured
+ * against the real proxy, a 32 MB line took ~8s and a 50 MB line ~35s — with the event loop pinned
+ * throughout, so every other tool call on that link was frozen with no response and no error. The
+ * client sees the whole MCP surface hang.
+ *
+ * A chunk with no newline in it cannot complete a line, so there is nothing to split and the cost is
+ * the concatenation alone. Only a chunk that actually carries a newline pays for a scan.
+ */
+export function drainLines(buffer, chunk, maxLineBytes = MAX_STDIN_LINE_BYTES, discarding = false) {
+    // Finish discarding first. Everything up to and including the next newline belongs to the line
+    // that was already dropped, and only what follows it is a message again.
+    if (discarding) {
+        const cut = chunk.indexOf('\n');
+        if (-1 === cut)
+            return { lines: [], rest: '', overflowed: true, discarding: true };
+        return {
+            ...drainLines('', chunk.slice(cut + 1), maxLineBytes),
+            overflowed: true,
+        };
+    }
+    const next = buffer + chunk;
+    if (!chunk.includes('\n')) {
+        // Nothing can be complete yet. Cap here rather than on the split path: this is the branch an
+        // oversized line stays on, so it is the only one that can grow without bound. Dropping the
+        // buffer is half the job — the rest of that line is still coming, hence `discarding`.
+        if (next.length > maxLineBytes) {
+            return { lines: [], rest: '', overflowed: true, discarding: true };
+        }
+        return { lines: [], rest: next, overflowed: false, discarding: false };
+    }
+    const parts = next.split('\n');
+    const rest = parts.pop() ?? '';
+    // A completed line over the cap is dropped, not truncated: half a JSON-RPC message is not a
+    // message, and forwarding a prefix would be a parse error attributed to the client. Its newline
+    // has already arrived, so there is nothing left to swallow for it.
+    const oversizedLine = parts.some((line) => line.length > maxLineBytes);
+    const restOversized = rest.length > maxLineBytes;
+    return {
+        lines: oversizedLine ? parts.filter((line) => line.length <= maxLineBytes) : parts,
+        rest: restOversized ? '' : rest,
+        overflowed: oversizedLine || restOversized,
+        discarding: restOversized,
+    };
+}

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

@@ -0,0 +1,90 @@
+/**
+ * When the proxy may start a daemon — the rule that keeps an idle install from looping forever.
+ *
+ * Two correct behaviours collide here, and this is the seam that keeps them from looping. A daemon
+ * may shut itself down when it has served nothing and no browser ever connected (see
+ * daemon-usefulness.ts); the proxy respawns a dead daemon, because one that crashed or was stopped
+ * otherwise takes the agent's whole Reticle surface with it. Together: the daemon exits as useless,
+ * the proxy immediately brings back a daemon that is equally useless, which exits, forever — one new
+ * process per grace period, for as long as the editor is open, on any install that never calls a
+ * tool.
+ *
+ * The rule that resolves it: A DROPPED STREAM IS NOT DEMAND. Reattach to a daemon that is already
+ * there; otherwise go dormant and let the next thing the CLIENT asks for bring Reticle back.
+ *
+ * Pure functions, so a test can reach the decision — a guard that re-implements it instead of
+ * calling it is insensitive to the thing it claims to guard.
+ */
+import { PortPresence } from '../../../command/daemon/binding/port-presence.js';
+/** What to do when the SSE stream drops. */
+export declare const OnDrop: {
+    /** A daemon is listening — reattach to it. */
+    readonly REATTACH: "reattach";
+    /** Nothing is listening. Do NOT spawn: wait to be needed. */
+    readonly DORMANT: "dormant";
+};
+export type OnDrop = (typeof OnDrop)[keyof typeof OnDrop];
+/**
+ * A stream drop only ever justifies reattaching, never spawning. This is the whole fix: the proxy
+ * used to spawn here, which turned a daemon's own idle shutdown into a permanent respawn loop.
+ *
+ * It takes the PRESENCE, not a boolean. It used to take `daemonListening`, filled from a bare TCP
+ * connect — a probe that cannot tell a Reticle daemon from anything else that accepts a socket. A
+ * stranger on the bridge port therefore read as "a daemon is there", and since a stranger answers
+ * and closes, every reattach dropped and reattached again: measured at nineteen reconnects in
+ * forty-eight seconds, each logged as `reticle_mcp_proxy_reconnected`, forever. `probePresence`
+ * already asks the second question and every human-facing command already uses it; this was the last
+ * decision point still guessing from the first.
+ */
+export declare function onStreamDrop(presence: PortPresence): OnDrop;
+/**
+ * What to do when the reconnect budget runs out. Always DORMANT — never exit.
+ *
+ * The proxy used to `process.exit(1)` here, justified as "let the agent host respawn the proxy". No
+ * host does that: a stdio MCP server that exits is marked DISCONNECTED, its tools disappear from the
+ * session, and a human has to open /mcp and reconnect by hand. That is the worst thing this product
+ * does to anyone, and it was deliberate.
+ *
+ * Exiting bought nothing. Dormant already covers every case exit was meant to: the handshake is
+ * answered locally, `tools/list` is answered from the catalog cache, and the next client request
+ * WAKES a daemon. The budget still exists — it decides when to stop burning CPU on retries, not
+ * 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. */
+    readonly SEND: "send";
+    /** Reconnecting already; hold it until the endpoint arrives. */
+    readonly QUEUE: "queue";
+    /** Dormant: this is demand. Start a daemon, reattach, then flush. */
+    readonly WAKE: "wake";
+};
+export type OnRequest = (typeof OnRequest)[keyof typeof OnRequest];
+/**
+ * The client asking for something is the ONLY event that may start a daemon.
+ *
+ * `connected` means a session endpoint is in hand. When it is not, a dormant proxy wakes (spawning
+ * if needed) and a merely-reconnecting one queues — the difference between "nothing is coming back
+ * on its own" and "something already is".
+ */
+export declare function onClientRequest(connected: boolean, dormant: boolean): OnRequest;

package/dist/surface/mcp/proxy/proxy-lifecycle.js

@@ -0,0 +1,98 @@
+/**
+ * When the proxy may start a daemon — the rule that keeps an idle install from looping forever.
+ *
+ * Two correct behaviours collide here, and this is the seam that keeps them from looping. A daemon
+ * may shut itself down when it has served nothing and no browser ever connected (see
+ * daemon-usefulness.ts); the proxy respawns a dead daemon, because one that crashed or was stopped
+ * otherwise takes the agent's whole Reticle surface with it. Together: the daemon exits as useless,
+ * the proxy immediately brings back a daemon that is equally useless, which exits, forever — one new
+ * process per grace period, for as long as the editor is open, on any install that never calls a
+ * tool.
+ *
+ * The rule that resolves it: A DROPPED STREAM IS NOT DEMAND. Reattach to a daemon that is already
+ * there; otherwise go dormant and let the next thing the CLIENT asks for bring Reticle back.
+ *
+ * Pure functions, so a test can reach the decision — a guard that re-implements it instead of
+ * calling it is insensitive to the thing it claims to guard.
+ */
+import { PortPresence } from '../../../command/daemon/binding/port-presence.js';
+/** What to do when the SSE stream drops. */
+export const OnDrop = {
+    /** A daemon is listening — reattach to it. */
+    REATTACH: 'reattach',
+    /** Nothing is listening. Do NOT spawn: wait to be needed. */
+    DORMANT: 'dormant',
+};
+/**
+ * A stream drop only ever justifies reattaching, never spawning. This is the whole fix: the proxy
+ * used to spawn here, which turned a daemon's own idle shutdown into a permanent respawn loop.
+ *
+ * It takes the PRESENCE, not a boolean. It used to take `daemonListening`, filled from a bare TCP
+ * connect — a probe that cannot tell a Reticle daemon from anything else that accepts a socket. A
+ * stranger on the bridge port therefore read as "a daemon is there", and since a stranger answers
+ * and closes, every reattach dropped and reattached again: measured at nineteen reconnects in
+ * forty-eight seconds, each logged as `reticle_mcp_proxy_reconnected`, forever. `probePresence`
+ * already asks the second question and every human-facing command already uses it; this was the last
+ * decision point still guessing from the first.
+ */
+export function onStreamDrop(presence) {
+    return PortPresence.DAEMON === presence ? OnDrop.REATTACH : OnDrop.DORMANT;
+}
+/**
+ * What to do when the reconnect budget runs out. Always DORMANT — never exit.
+ *
+ * The proxy used to `process.exit(1)` here, justified as "let the agent host respawn the proxy". No
+ * host does that: a stdio MCP server that exits is marked DISCONNECTED, its tools disappear from the
+ * session, and a human has to open /mcp and reconnect by hand. That is the worst thing this product
+ * does to anyone, and it was deliberate.
+ *
+ * Exiting bought nothing. Dormant already covers every case exit was meant to: the handshake is
+ * answered locally, `tools/list` is answered from the catalog cache, and the next client request
+ * WAKES a daemon. The budget still exists — it decides when to stop burning CPU on retries, not
+ * whether the server survives.
+ */
+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. */
+    SEND: 'send',
+    /** Reconnecting already; hold it until the endpoint arrives. */
+    QUEUE: 'queue',
+    /** Dormant: this is demand. Start a daemon, reattach, then flush. */
+    WAKE: 'wake',
+};
+/**
+ * The client asking for something is the ONLY event that may start a daemon.
+ *
+ * `connected` means a session endpoint is in hand. When it is not, a dormant proxy wakes (spawning
+ * if needed) and a merely-reconnecting one queues — the difference between "nothing is coming back
+ * on its own" and "something already is".
+ */
+export function onClientRequest(connected, dormant) {
+    if (connected)
+        return OnRequest.SEND;
+    return dormant ? OnRequest.WAKE : OnRequest.QUEUE;
+}

package/dist/surface/mcp/proxy/proxy-log.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
+ *
+ * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
+ * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
+ * keep that file from becoming the largest thing on the user's disk.
+ */
+/**
+ * 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 declare const PROXY_LOG_CHECK_BYTES: number;
+/**
+ * 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 declare function accountProxyLogWrite(bytesSinceCheck: number, written: number, path: string, deps: {
+    fileSize(p: string): number;
+    renameFile(from: string, to: string): void;
+}): number;
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Path-shaped wrapper over `recoverOversizedLog`, which is where the rule, the in-place truncation
+ * and the ENOSPC incident behind them are written down. Both of Reticle's logs are capped by that
+ * one function; this keeps the name and the `fileSize`/`truncateFile` deps its callers already pass.
+ *
+ * Such files already exist on machines that ran an older build, and the cap alone does not help
+ * them: nobody should have to find one with `du`.
+ */
+export declare function recoverOversizedProxyLog(path: string, deps: {
+    fileSize(p: string): number;
+    truncateFile(p: string): void;
+}, max?: number): number;
+/** Name the proxy log after the port it serves. Called before anything can log. */
+export declare function setProxyLogPort(port: number): void;
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export declare function proxyLogPath(port?: number | undefined): string;
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
+ * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
+ * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
+ *
+ * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
+ * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
+ * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
+ * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
+ * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
+ * existed, and the one path that most needed it was not using it.
+ */
+export declare function proxyLog(event: string, fields?: Record<string, unknown>): void;