@reticlehq/server 2.12.0 → 2.13.0

package/dist/license/license-env.js

@@ -0,0 +1,148 @@
+/**
+ * Find an enterprise licence key the customer actually placed, wherever they reasonably placed it.
+ *
+ * The daemon folded in `<cwd>/.env` and nothing else. It is spawned without an explicit `cwd`, so it
+ * inherits whatever directory the editor launched the MCP server from — in a monorepo that is the
+ * workspace root while the key sits in the app's own `.env`, and under some editors it is the user's
+ * home. The key was never read, `describeLicense` reported `missing`, and every event that customer
+ * produced said they had no licence, which is indistinguishable from a customer who has none.
+ *
+ * That is the worst shape a licensing bug can take. A key that fails LOUDLY gets reported by the
+ * customer within the hour. A key that silently fails to register leaves them believing they are
+ * licensed and us believing they are not, and neither side finds out.
+ *
+ * Two directions, because the field hits both: DOWN one level into app directories (the daemon
+ * starts at the workspace root) and UP to the project root (the editor starts inside the app).
+ *
+ * ONLY the licence key is ever taken out of a file found this way, and that restriction is the point
+ * rather than an optimisation. Bulk-importing a `.env` discovered by walking would let a directory
+ * the caller never named rebind the daemon's port, its telemetry gate or its allowed origins — a far
+ * worse bug than the one this fixes. `loadDotEnv` still owns the local file, where importing
+ * everything is what the caller asked for.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LICENSE_KEY_ENV } from './license.js';
+import { discoverProjectConfigs } from '../cli/config-discovery.js';
+/** The files a framework tells people to put secrets in, most specific first. */
+const ENV_FILES = ['.env.local', '.env'];
+/** Stop the upward walk here: a licence belongs to a project, not to a machine. */
+const ROOT_MARKERS = ['.git', 'package.json', 'pnpm-workspace.yaml'];
+/** A bound on the upward walk, so a pathological path cannot spin. */
+const MAX_DEPTH = 12;
+function readKey(file) {
+    try {
+        if (!existsSync(file))
+            return undefined;
+        for (const raw of readFileSync(file, 'utf8').split('\n')) {
+            const line = raw.trim();
+            if (0 === line.length || line.startsWith('#'))
+                continue;
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                continue;
+            if (line.slice(0, eq).trim() !== LICENSE_KEY_ENV)
+                continue;
+            const value = line.slice(eq + 1).trim();
+            const first = value[0];
+            const unquoted = ('"' === first || "'" === first) && value.endsWith(first) && value.length >= 2
+                ? value.slice(1, -1)
+                : value;
+            if (unquoted.length > 0)
+                return unquoted;
+        }
+    }
+    catch {
+        // A licence probe may never take the daemon down, and an unreadable file is not an error here.
+    }
+    return undefined;
+}
+function inDir(dir) {
+    for (const name of ENV_FILES) {
+        const found = readKey(join(dir, name));
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function isRoot(dir) {
+    return ROOT_MARKERS.some((marker) => existsSync(join(dir, marker)));
+}
+/**
+ * The directories that hold a `.reticle.json`: the apps that were actually instrumented.
+ *
+ * This is the closest thing the daemon has to "the session's project directory", and it is the same
+ * discovery the no-session diagnosis uses to tell an agent where the app really is. Reusing it means
+ * the licence search and that diagnosis can never disagree about where the project lives.
+ *
+ * It replaced a guess at `apps/*` and `packages/*`, which missed exactly the repo shape
+ * `findWorkspaceApps` was written for: three apps at `web/`, `admin/` and `space/`.
+ */
+/**
+ * The conventional layout, kept as a fallback beside the declaration-driven search above.
+ *
+ * `discoverProjectConfigs` descends only into DECLARED workspaces, which is right and is what a real
+ * monorepo has. But `apps/web` with no `workspaces` entry is a shape people genuinely ship, and for
+ * a licence key the cost of one extra `readdir` is nothing against reporting a paying customer as
+ * unlicensed. Strictly widens coverage; it can never contradict the discovery, only add to it.
+ */
+const CONVENTIONAL_DIRS = ['apps', 'packages'];
+function inConventionalChildren(dir) {
+    for (const group of CONVENTIONAL_DIRS) {
+        const base = join(dir, group);
+        let entries;
+        try {
+            if (!existsSync(base) || !statSync(base).isDirectory())
+                continue;
+            entries = readdirSync(base);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const found = inDir(join(base, entry));
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+function inDiscoveredProjects(dir) {
+    let found;
+    try {
+        found = discoverProjectConfigs(dir).found;
+    }
+    catch {
+        return undefined;
+    }
+    for (const config of found) {
+        const key = inDir(config.directory);
+        if (key !== undefined)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * The key, or undefined. Never throws, never mutates anything the caller did not ask it to.
+ *
+ * A key already present in `env` always wins: that is the operator stating it explicitly, and a file
+ * silently overriding it is the surprise `loadDotEnv` already refuses to cause.
+ */
+export function licenseKeyFromEnvFiles(startDir, env = process.env) {
+    const existing = env[LICENSE_KEY_ENV];
+    if (existing !== undefined && existing.length > 0)
+        return existing;
+    let dir = startDir;
+    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+        const here = inDir(dir) ?? inDiscoveredProjects(dir) ?? inConventionalChildren(dir);
+        if (here !== undefined)
+            return here;
+        if (isRoot(dir))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}

package/dist/loopback-agent.d.ts

@@ -0,0 +1,31 @@
+import * as http from 'node:http';
+/**
+ * The one HTTP agent every loopback call in this process goes through.
+ *
+ * Without an `agent:`, Node hands the request to `http.globalAgent`, whose idle timeout is 5
+ * seconds. The MCP proxy's POST leg is one request per JSON-RPC message and an agent thinks for
+ * longer than five seconds between tool calls essentially always — so every single tool call opened
+ * a fresh TCP socket. On Windows that is the ephemeral-port / non-paged-pool exhaustion pattern, and
+ * the `ENOBUFS` it eventually raises killed the call outright.
+ *
+ * The numbers, each one a decision and not a taste:
+ *
+ * - `keepAlive: true` — the whole point: hold the socket open between calls so there is no churn to
+ *   exhaust anything with.
+ * - `timeout: LOOPBACK_IDLE_MS` (45s) — how long an idle socket is kept for reuse. It has to outlast
+ *   a model's think-time between two tool calls (which is what 5s failed to do) and it has to stay
+ *   BELOW the daemon's own keep-alive timeout, so that the client is always the side that retires a
+ *   socket. If the server closed first we would keep picking up sockets it had already closed, and
+ *   that failure looks exactly like the one case we refuse to retry (see `isRetryableConnectError`).
+ *   The daemon's side of that pact is `HTTP_KEEP_ALIVE_TIMEOUT_MS` in `http-server.ts`.
+ * - `keepAliveMsecs: 10_000` — TCP-level keep-alive probes on an idle socket, so a daemon that died
+ *   without a FIN is noticed rather than handed back out as a live connection.
+ * - `maxSockets: 8` — the proxy multiplexes ONE MCP client, whose calls are near enough serial; 8 is
+ *   generous headroom for overlapping notifications while capping the worst case far below anything
+ *   a port table would notice. Exceeding it queues rather than fails.
+ */
+export declare const LOOPBACK_IDLE_MS = 45000;
+/** Named separately because `http.Agent` does not expose its options back to a caller (or a test). */
+export declare const LOOPBACK_AGENT_OPTIONS: http.AgentOptions;
+export declare const loopbackAgent: http.Agent;
+export declare function isRetryableConnectError(err: unknown): boolean;

package/dist/loopback-agent.js

@@ -0,0 +1,57 @@
+import * as http from 'node:http';
+/**
+ * The one HTTP agent every loopback call in this process goes through.
+ *
+ * Without an `agent:`, Node hands the request to `http.globalAgent`, whose idle timeout is 5
+ * seconds. The MCP proxy's POST leg is one request per JSON-RPC message and an agent thinks for
+ * longer than five seconds between tool calls essentially always — so every single tool call opened
+ * a fresh TCP socket. On Windows that is the ephemeral-port / non-paged-pool exhaustion pattern, and
+ * the `ENOBUFS` it eventually raises killed the call outright.
+ *
+ * The numbers, each one a decision and not a taste:
+ *
+ * - `keepAlive: true` — the whole point: hold the socket open between calls so there is no churn to
+ *   exhaust anything with.
+ * - `timeout: LOOPBACK_IDLE_MS` (45s) — how long an idle socket is kept for reuse. It has to outlast
+ *   a model's think-time between two tool calls (which is what 5s failed to do) and it has to stay
+ *   BELOW the daemon's own keep-alive timeout, so that the client is always the side that retires a
+ *   socket. If the server closed first we would keep picking up sockets it had already closed, and
+ *   that failure looks exactly like the one case we refuse to retry (see `isRetryableConnectError`).
+ *   The daemon's side of that pact is `HTTP_KEEP_ALIVE_TIMEOUT_MS` in `http-server.ts`.
+ * - `keepAliveMsecs: 10_000` — TCP-level keep-alive probes on an idle socket, so a daemon that died
+ *   without a FIN is noticed rather than handed back out as a live connection.
+ * - `maxSockets: 8` — the proxy multiplexes ONE MCP client, whose calls are near enough serial; 8 is
+ *   generous headroom for overlapping notifications while capping the worst case far below anything
+ *   a port table would notice. Exceeding it queues rather than fails.
+ */
+export const LOOPBACK_IDLE_MS = 45_000;
+/** Named separately because `http.Agent` does not expose its options back to a caller (or a test). */
+export const LOOPBACK_AGENT_OPTIONS = {
+    keepAlive: true,
+    keepAliveMsecs: 10_000,
+    timeout: LOOPBACK_IDLE_MS,
+    maxSockets: 8,
+};
+export const loopbackAgent = new http.Agent(LOOPBACK_AGENT_OPTIONS);
+/**
+ * Socket-level failures worth another attempt — every one of them a statement about this machine's
+ * networking stack, not about the request.
+ *
+ * The list is deliberately narrow. It is not the retry decision on its own: the caller must ALSO
+ * know the request never reached the daemon. What the code check buys is that a programming error
+ * (`ERR_INVALID_URL`, a bad argument) cannot be retried — those fail before a socket too, and would
+ * otherwise burn the whole attempt budget on a bug that will never succeed.
+ */
+const RETRYABLE_CODES = new Set([
+    'ENOBUFS', // Windows: non-paged pool / ephemeral port exhaustion — the reported failure
+    'EADDRNOTAVAIL', // no ephemeral port left to bind
+    'EMFILE', // per-process fd limit
+    'ENFILE', // system-wide fd limit
+    'ECONNREFUSED', // daemon restarting, listener not back yet
+    'ECONNRESET', // peer closed the connection
+    'ETIMEDOUT', // connect never completed
+]);
+export function isRetryableConnectError(err) {
+    const code = err?.code;
+    return 'string' === typeof code && RETRYABLE_CODES.has(code);
+}

package/dist/mcp/attach-memory.d.ts

@@ -29,12 +29,28 @@ export declare const AttachState: {
     readonly NEVER_ATTACHED: "never-attached";
     /** A client started it and never asked for the tool list — the state that needs a restart. */
     readonly NEVER_ENUMERATED: "never-enumerated";
-    /** Started and enumerated. Nothing to say. */
+    /**
+     * The catalogue was read and no tool was ever called: both ends healthy, nothing crossing.
+     *
+     * Reported from the field as the hardest state to diagnose, and it is the one every component
+     * check passes. The browser SDK is injected, the daemon has a live session, the client lists all
+     * the tools, and the agent still reports Reticle as absent. `enumerated` used to cover this, which
+     * meant the most-broken install we know of read identically to a perfect one.
+     */
+    readonly NEVER_CALLED: "never-called";
+    /** Started, enumerated, and actually used. Nothing to say. */
     readonly ENUMERATED: "enumerated";
 };
 export type AttachState = (typeof AttachState)[keyof typeof AttachState];
 /** Record that an MCP client started the proxy on this port. */
 export declare function rememberProxyStarted(stateDir: string, port: number): void;
+/**
+ * Record that a client actually CALLED a tool here, not merely listed them.
+ *
+ * Written once and then skipped, like the other two: this runs on the hot path of every tool call,
+ * and a diagnostic that writes a file per call would cost more than it tells anybody.
+ */
+export declare function rememberToolCalled(stateDir: string, port: number): void;
 /**
  * Record that a client asked for the tool list on this port.
  *
@@ -43,7 +59,7 @@ export declare function rememberProxyStarted(stateDir: string, port: number): vo
  * correctly.
  */
 export declare function rememberEnumerated(stateDir: string, port: number): void;
-/** Which of the three client-side states this port is in. */
+/** Which of the four client-side states this port is in. */
 export declare function attachState(stateDir: string, port: number): AttachState;
 /**
  * The sentence to print for a state, or `undefined` when there is nothing to fix.

package/dist/mcp/attach-memory.js

@@ -31,7 +31,16 @@ export const AttachState = {
     NEVER_ATTACHED: 'never-attached',
     /** A client started it and never asked for the tool list — the state that needs a restart. */
     NEVER_ENUMERATED: 'never-enumerated',
-    /** Started and enumerated. Nothing to say. */
+    /**
+     * The catalogue was read and no tool was ever called: both ends healthy, nothing crossing.
+     *
+     * Reported from the field as the hardest state to diagnose, and it is the one every component
+     * check passes. The browser SDK is injected, the daemon has a live session, the client lists all
+     * the tools, and the agent still reports Reticle as absent. `enumerated` used to cover this, which
+     * meant the most-broken install we know of read identically to a perfect one.
+     */
+    NEVER_CALLED: 'never-called',
+    /** Started, enumerated, and actually used. Nothing to say. */
     ENUMERATED: 'enumerated',
 };
 /**
@@ -53,10 +62,25 @@ const NEVER_ENUMERATED_ACTION = 'an MCP client started Reticle on this port and
  * client next starts Reticle — and telling that user their server is unregistered would send them
  * to re-run `init` over a working setup.
  */
+/**
+ * The link that is broken, named as a link rather than as a component.
+ *
+ * Every other check in this product is about a PIECE: is the daemon up, is the SDK injected, is a
+ * session live, are the tools registered. This state is the one where every piece passes and the
+ * chain still does not carry anything, so the message has to say which hop failed and what to do
+ * about it, not repeat that the pieces are fine.
+ */
+const NEVER_CALLED_ACTION = "an MCP client listed Reticle's tools on this port and has never called one, so the tools are " +
+    'registered and no request has reached the daemon. That is the agent-to-daemon hop, not the ' +
+    'browser or the daemon: both of those can look healthy while this one is broken. Ask your agent ' +
+    'to run `reticle_sessions` explicitly. If it answers, the link is fine and the agent simply had ' +
+    'no reason to call it; if it says Reticle is unavailable, the client is talking to a different ' +
+    'server than the one this record belongs to, so re-check which command and port it launches. ' +
+    'This record is per port, not per client.';
 const NEVER_ATTACHED_ACTION = 'no MCP client has started Reticle on this port, so either the server is not registered with your ' +
     'client or nothing has attached since this record began — register it with `npx ' +
     '@reticlehq/server init`, then restart your MCP client and run status again.';
-const EMPTY = { attached: false, enumerated: false };
+const EMPTY = { attached: false, enumerated: false, called: false };
 function memoryPath(stateDir, port) {
     return join(stateDir, `attach-${String(port)}.json`);
 }
@@ -70,6 +94,7 @@ function read(stateDir, port) {
         return {
             attached: true === record.attached,
             enumerated: true === record.enumerated,
+            called: true === record.called,
         };
     }
     catch {
@@ -93,6 +118,18 @@ export function rememberProxyStarted(stateDir, port) {
         return;
     write(stateDir, port, { ...known, attached: true });
 }
+/**
+ * Record that a client actually CALLED a tool here, not merely listed them.
+ *
+ * Written once and then skipped, like the other two: this runs on the hot path of every tool call,
+ * and a diagnostic that writes a file per call would cost more than it tells anybody.
+ */
+export function rememberToolCalled(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.called)
+        return;
+    write(stateDir, port, { ...known, called: true });
+}
 /**
  * Record that a client asked for the tool list on this port.
  *
@@ -104,14 +141,18 @@ export function rememberEnumerated(stateDir, port) {
     const known = read(stateDir, port);
     if (known.enumerated)
         return;
-    write(stateDir, port, { attached: true, enumerated: true });
+    write(stateDir, port, { ...known, attached: true, enumerated: true });
 }
-/** Which of the three client-side states this port is in. */
+/** Which of the four client-side states this port is in. */
 export function attachState(stateDir, port) {
     const known = read(stateDir, port);
-    if (known.enumerated)
-        return AttachState.ENUMERATED;
-    return known.attached ? AttachState.NEVER_ENUMERATED : AttachState.NEVER_ATTACHED;
+    // Ordered outward along the chain: attached, then listed, then actually used. The last hop is
+    // the one every component check misses, so it is asked last and answered explicitly.
+    if (!known.attached)
+        return AttachState.NEVER_ATTACHED;
+    if (!known.enumerated)
+        return AttachState.NEVER_ENUMERATED;
+    return known.called ? AttachState.ENUMERATED : AttachState.NEVER_CALLED;
 }
 /**
  * The sentence to print for a state, or `undefined` when there is nothing to fix.
@@ -124,6 +165,8 @@ export function describeAttachState(state) {
         return NEVER_ENUMERATED_ACTION;
     if (state === AttachState.NEVER_ATTACHED)
         return NEVER_ATTACHED_ACTION;
+    if (state === AttachState.NEVER_CALLED)
+        return NEVER_CALLED_ACTION;
     return undefined;
 }
 /**

package/dist/mcp/client-identity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * WHICH agent is on the other end of this daemon.
+ *
+ * MCP clients announce themselves in the `initialize` handshake — `claude-code`, `cursor-vscode`,
+ * `windsurf`, and so on. That claim is the ONLY honest source for this: an env-var table
+ * (`CLAUDECODE`, `CURSOR_TRACE_ID`, …) is a guess that silently rots every time a vendor renames a
+ * variable, and it cannot see a client nobody has added to the table yet.
+ *
+ * Read through a hook rather than a stored value because the handshake happens after the server is
+ * constructed, and a session can reconnect under a different client entirely.
+ *
+ * Lives here, not in telemetry, because it stopped being a telemetry detail the moment a
+ * verification RUN needed to record which agent produced it — and `runs/` must not import
+ * `telemetry/` to find out.
+ *
+ * Note what is NOT available and cannot be: the MODEL. `clientInfo` carries a name, a title and a
+ * version; MCP has no concept of a model, so the transport genuinely cannot tell us. Anything
+ * claiming to know it would be inventing it.
+ */
+export interface McpClientIdentity {
+    name?: string;
+    version?: string;
+}
+export declare function setMcpClientIdentityHook(next: () => McpClientIdentity | undefined): void;
+/** For tests, and for a daemon that is reused across transports. */
+export declare function clearMcpClientIdentityHook(): void;
+/**
+ * The client's own name and version, trimmed and bounded. Empty object when no MCP peer has
+ * introduced itself — a plain CLI run has no client, and reporting one would be a fabrication.
+ */
+export declare function mcpClientIdentity(): McpClientIdentity;

package/dist/mcp/client-identity.js

@@ -0,0 +1,51 @@
+/**
+ * WHICH agent is on the other end of this daemon.
+ *
+ * MCP clients announce themselves in the `initialize` handshake — `claude-code`, `cursor-vscode`,
+ * `windsurf`, and so on. That claim is the ONLY honest source for this: an env-var table
+ * (`CLAUDECODE`, `CURSOR_TRACE_ID`, …) is a guess that silently rots every time a vendor renames a
+ * variable, and it cannot see a client nobody has added to the table yet.
+ *
+ * Read through a hook rather than a stored value because the handshake happens after the server is
+ * constructed, and a session can reconnect under a different client entirely.
+ *
+ * Lives here, not in telemetry, because it stopped being a telemetry detail the moment a
+ * verification RUN needed to record which agent produced it — and `runs/` must not import
+ * `telemetry/` to find out.
+ *
+ * Note what is NOT available and cannot be: the MODEL. `clientInfo` carries a name, a title and a
+ * version; MCP has no concept of a model, so the transport genuinely cannot tell us. Anything
+ * claiming to know it would be inventing it.
+ */
+/** Caps, so a hostile or broken client cannot write unbounded strings into an artifact. */
+const MAX_NAME = 64;
+const MAX_VERSION = 32;
+let hook;
+export function setMcpClientIdentityHook(next) {
+    hook = next;
+}
+/** For tests, and for a daemon that is reused across transports. */
+export function clearMcpClientIdentityHook() {
+    hook = undefined;
+}
+/**
+ * The client's own name and version, trimmed and bounded. Empty object when no MCP peer has
+ * introduced itself — a plain CLI run has no client, and reporting one would be a fabrication.
+ */
+export function mcpClientIdentity() {
+    try {
+        const info = hook?.();
+        const name = info?.name;
+        const version = info?.version;
+        return {
+            ...(name !== undefined && '' !== name ? { name: name.slice(0, MAX_NAME) } : {}),
+            ...(version !== undefined && '' !== version
+                ? { version: version.slice(0, MAX_VERSION) }
+                : {}),
+        };
+    }
+    catch {
+        // A hook that throws must never fail the thing that asked — this is descriptive, not load-bearing.
+        return {};
+    }
+}

package/dist/mcp/mcp-post-transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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';
+/** One bounded pool for the short-lived POST side of each MCP SSE session. */
+export declare const MCP_PROXY_HTTP_AGENT_OPTIONS: {
+    readonly keepAlive: true;
+    readonly keepAliveMsecs: 30000;
+    readonly timeout: 60000;
+    readonly maxSockets: 8;
+    readonly scheduling: "lifo";
+};
+export declare function shouldRetryUnsentPost(error: unknown, bytesWritten: number, retryCount: number): boolean;
+export interface PostFailure {
+    reason: string;
+    transport: boolean;
+    attempts: number;
+}
+type HttpRequest = (options: http.RequestOptions, callback: (response: http.IncomingMessage) => void) => http.ClientRequest;
+export declare function postToSession(url: string, body: string, request?: HttpRequest): Promise<PostFailure | null>;
+export {};

package/dist/mcp/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/mcp/mcp-proxy.d.ts

@@ -5,13 +5,14 @@ export { probeDaemon, waitForDaemon } from './proxy-daemon-probe.js';
  * proxy. Where the code lives is a file-size decision; where it is imported from is an API.
  */
 export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy-log.js';
+export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy-backoff.js';
+export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, type PostFailure, } from './mcp-post-transport.js';
 /**
  * Overridable so the survival spec can reach exhaustion in seconds instead of minutes — the same
  * reason the idle windows take an env override. A positive integer only; anything else falls back,
  * so a typo cannot silently disable the retry loop.
  */
 export declare const MAX_RECONNECT_ATTEMPTS: number;
-export declare function reconnectDelayMs(attempt: number): number;
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export declare const RECONNECT_INITIALIZE_ID = "__reticle_proxy_reinit";
 /**