@reticlehq/server 2.11.0 → 2.13.0

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";
 /**
@@ -47,13 +48,6 @@ export declare class PendingRequests {
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
 export declare function streamLossReplies(pending: PendingRequests, reason: string, nextStep?: string): string[];
-/**
- * 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 declare function transportLossReply(id: unknown, reason: string, nextStep?: string): string;
 /**
  * How long a request may sit in the queue, unsent, before the proxy answers it itself.
  *

package/dist/mcp/mcp-proxy.js

@@ -1,6 +1,7 @@
 import * as http from 'node:http';
-import { localInitializeResponse, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
-import { ToolCatalogCache } from './tool-catalog-cache.js';
+import { localInitializeResponse, degradedInstructions, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
+import { isToolCallRequest, isToolsListRequest, ToolCatalogCache } from './tool-catalog-cache.js';
+import { rememberEnumerated, rememberProxyStarted, rememberToolCalled } from './attach-memory.js';
 import { toolsChangedNotification } from './proxy-handshake.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { SseFrameParser } from './sse-frame-parser.js';
@@ -15,6 +16,7 @@ import { readProjectId } from '../cli/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy-lifecycle.js';
 import { describePresence, probePresence } from '../daemon/port-presence.js';
+import { flushProxySessionMetrics } from '../telemetry/proxy-telemetry.js';
 /**
  * The same `/status` probe `doctor`, `status` and `kill` ask with. Reused rather than re-written:
  * the whole defect this import closes was the proxy answering a DIFFERENT question from every other
@@ -27,11 +29,11 @@ import { fetchStatus as fetchDaemonStatus } from '../cli/cli-launch.js';
  */
 export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy-log.js';
 import { proxyLog } from './proxy-log.js';
-import { log } from '../log.js';
 import { OutageReason, OutageStage, reportMcpOutage } from './mcp-outage.js';
-/** Reconnect backoff: linear, capped, so a briefly-restarting daemon is picked up fast. */
-const RECONNECT_BASE_MS = 250;
-const RECONNECT_CAP_MS = 5_000;
+import { postToSession } from './mcp-post-transport.js';
+import { reconnectDelayMs } from './proxy-backoff.js';
+export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy-backoff.js';
+export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, } from './mcp-post-transport.js';
 /**
  * How many consecutive failed reconnects before the proxy stops RETRYING. It does not stop serving:
  * the budget ends the retry loop and the proxy goes dormant, where the handshake and `tools/list`
@@ -50,9 +52,6 @@ export const MAX_RECONNECT_ATTEMPTS = (() => {
     const raw = Number(process.env[ReticleEnv.RECONNECT_ATTEMPTS]);
     return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_MAX_RECONNECT_ATTEMPTS;
 })();
-export function reconnectDelayMs(attempt) {
-    return Math.min(RECONNECT_BASE_MS * attempt, RECONNECT_CAP_MS);
-}
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export const RECONNECT_INITIALIZE_ID = '__reticle_proxy_reinit';
 function parseJsonRpc(line) {
@@ -141,7 +140,7 @@ const TRANSPORT_LOSS_CODE = -32001;
  * `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) {
+function transportLossReply(id, reason, nextStep) {
     return JSON.stringify({
         jsonrpc: '2.0',
         id,
@@ -253,49 +252,6 @@ export class HandshakeReplay {
         return true;
     }
 }
-/**
- * POST one JSON-RPC line into the daemon's session. Resolves null on success, or a short reason
- * 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.
- */
-function postToSession(url, body) {
-    return 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',
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': bodyBuf.byteLength,
-            },
-        };
-        const req = http.request(options, (res) => {
-            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 });
-            }
-            res.resume(); // drain so the socket is reused
-            resolve(rejected ? `daemon rejected the call with HTTP ${String(status)}` : null);
-        });
-        req.on('error', (err) => {
-            log('reticle_mcp_proxy_post_error', { error: err.message });
-            resolve(`post failed: ${err.message}`);
-        });
-        req.write(bodyBuf);
-        req.end();
-    });
-}
 /**
  * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
  *
@@ -347,6 +303,11 @@ export function startMcpProxy(port,
  */
 ensureDaemon) {
     return new Promise((_resolve, reject) => {
+        // A client just started us, which is the only honest evidence that Reticle is registered with
+        // one at all: a config entry proves somebody wrote JSON, not that a client ever read it. Paired
+        // with the `tools/list` record below, this is what lets `status` name the state in between
+        // "never registered" and "connected" — see attach-memory.ts.
+        rememberProxyStarted(reticleStateHome(), port);
         // Declared before the SSE handler that fills it: the handler is a closure created below but
         // invoked on the first daemon frame, and a `const` referenced before its declaration executes is
         // a runtime throw, not a type error.
@@ -433,6 +394,17 @@ ensureDaemon) {
         let daemonRetiring = false;
         /** Why the stream we are currently trying to replace went away — carried onto the recovery. */
         let lastDropReason = OutageReason.OTHER;
+        /**
+         * What the outage had already cost when the proxy went dormant.
+         *
+         * The wake path clears `attempts` before dialling, and it must: a wake is a fresh retry budget,
+         * and sharing the previous outage's spent budget would put the proxy dormant again on its first
+         * failure. But the recovery report is guarded on `attempts > 0`, so clearing it also erased the
+         * evidence that there was anything to recover FROM — and dormancy is the commonest outage class
+         * we have, which made every recovery of that class invisible. Carried across the wake so the
+         * budget resets and the accounting does not.
+         */
+        let attemptsBeforeDormant = 0;
         /**
          * When the proxy started, and how many times the first connect has been refused since.
          *
@@ -455,13 +427,20 @@ ensureDaemon) {
                 const msg = parseJsonRpc(line);
                 if (null === msg || msg.id === undefined || !pending.take(msg.id))
                     return;
+                if (failure.transport) {
+                    reportMcpOutage(OutageStage.FIRST, {
+                        reason: OutageReason.CONNECT_ERROR,
+                        attempts: failure.attempts,
+                        pendingLost: 1,
+                    });
+                }
                 proxyLog('reticle_mcp_proxy_post_unanswered', {
                     port,
                     method: String(msg.method),
-                    reason: failure,
+                    reason: failure.reason,
                     note: 'the stream is still up, so nothing else would ever have answered this call',
                 });
-                emit(transportLossReply(msg.id, failure));
+                emit(transportLossReply(msg.id, failure.reason));
             });
         };
         function onSseEvent(event, data, p) {
@@ -481,9 +460,11 @@ ensureDaemon) {
                 // off and never reaching the budget that puts the proxy dormant. Measured: 32 retries in 8s.
                 // Report the recovery BEFORE the counter is cleared: `attempts` is what coming back actually
                 // cost, and it is the only number that can falsify the drop event. See OutageStage.RECOVERED.
-                if (attempts > 0)
-                    reportMcpOutage(OutageStage.RECOVERED, { reason: lastDropReason, attempts });
+                const cost = attempts + attemptsBeforeDormant;
+                if (cost > 0)
+                    reportMcpOutage(OutageStage.RECOVERED, { reason: lastDropReason, attempts: cost });
                 attempts = 0;
+                attemptsBeforeDormant = 0;
                 // The new session's McpServer has never seen the client's initialize — replay it first, then
                 // flush whatever the client sent while we were reconnecting.
                 for (const line of replay.replayLines())
@@ -704,10 +685,10 @@ ensureDaemon) {
         const armLocalHandshake = (line) => {
             if (handshakeAnswered)
                 return;
-            // Ask the same question the daemon would, from the same durable memory, so the client gets
-            // the same answer it would have got had a daemon been up to give it.
-            const response = localInitializeResponse(line, proxyInstructions(port));
-            if (null === response)
+            // Only an `initialize` REQUEST is ours to answer. Asked with no instructions because the ones
+            // we will actually send name the reason the daemon failed, and the reason is not known until
+            // the deliver closure runs — see degradedInstructions.
+            if (null === localInitializeResponse(line, ''))
                 return;
             // Take the debt NOW, not when the timer fires.
             //
@@ -726,6 +707,13 @@ ensureDaemon) {
             deliverHandshakeLocally = (reason) => {
                 if (handshakeAnswered || postUrl !== null)
                     return;
+                // Built here, not at arm time, so the notice can name WHY no daemon answered. The client
+                // reads `instructions` exactly once, at initialize, and this response is the only one it
+                // will ever get — so a handshake that does not say it is unbacked never says it at all.
+                // See degradedInstructions for the field report this closes.
+                const response = localInitializeResponse(line, degradedInstructions(proxyInstructions(port), port, reason));
+                if (null === response)
+                    return;
                 handshakeAnswered = true;
                 deliverHandshakeLocally = undefined;
                 // The catalog we are about to serve is ours, not the daemon's, so it has to be corrected
@@ -767,6 +755,17 @@ ensureDaemon) {
                     continue;
                 replay.observeOutbound(trimmed);
                 pending.observeOutbound(trimmed);
+                // The ARRIVAL of the request, not the delivery of an answer: "this client asked for the tool
+                // list" is the fact `status` reports on, and a request that arrived and then failed is a
+                // different problem with its own diagnosis. Recording the answer instead would let a host
+                // that never asks look identical to one that asked and was refused.
+                if (isToolsListRequest(trimmed))
+                    rememberEnumerated(reticleStateHome(), port);
+                // The hop every other check misses. Recorded on the REQUEST rather than a reply, because
+                // the question is whether anything ever left the agent — a call that leaves and gets no
+                // answer is a different fault from one that was never made, and only this side sees it.
+                if (isToolCallRequest(trimmed))
+                    rememberToolCalled(reticleStateHome(), port);
                 const action = onClientRequest(postUrl !== null, dormant);
                 if (action === OnRequest.SEND && postUrl !== null) {
                     forward(postUrl, trimmed);
@@ -793,6 +792,8 @@ ensureDaemon) {
                 // flushed once the new session's `endpoint` frame arrives.
                 if (action === OnRequest.WAKE) {
                     dormant = false;
+                    // Budget reset, accounting preserved. See attemptsBeforeDormant.
+                    attemptsBeforeDormant += attempts;
                     attempts = 0;
                     void (ensureDaemon?.() ?? Promise.resolve())
                         .then(() => connect(false))
@@ -820,7 +821,8 @@ ensureDaemon) {
         process.stdin.on('end', () => {
             const quit = (code) => {
                 stopped = true;
-                process.exit(code);
+                // Await: fire-and-forget here is how daemon_stopped never arrived.
+                void flushProxySessionMetrics().finally(() => process.exit(code));
             };
             if (0 === pending.unanswered.length) {
                 quit(0);

package/dist/mcp/mcp.d.ts

@@ -3,6 +3,8 @@ import { z } from 'zod';
 import { type ToolDeps } from '../tools/tools.js';
 import type { ToolDef } from '../tools/tools.js';
 import { type ToolSurface } from '../tools/tool-surface.js';
+/** The JSON-RPC method the SDK registers its tool dispatcher under. */
+export declare const CALL_TOOL_METHOD = "tools/call";
 /**
  * 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

package/dist/mcp/mcp.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { PredicateSchema } from '../events/predicate.js';
+import { isPredicateParam } from '../events/predicate-eval.js';
 import { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { TOOLS } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
@@ -11,11 +11,24 @@ import { buildDynamicTools } from '../tools/dynamic-tools.js';
 import { runTool, SESSION_BOUND_TOOLS } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape } from '../tools/tool-kit.js';
 import { buildErrorPayload } from '../tools/error-recovery.js';
+import { takeVersionSkewOnto } from '../version/version-nudge.js';
 import { resultIsError } from './mcp-is-error.js';
 import { buildServerInstructions } from './server-instructions.js';
 import { unadvertisedToolHelp } from '../tools/unadvertised-help.js';
 /** The JSON-RPC method the SDK registers its tool dispatcher under. */
-const CALL_TOOL_METHOD = 'tools/call';
+export const CALL_TOOL_METHOD = 'tools/call';
+/**
+ * What we say when an SDK internal these patches ride on is no longer there.
+ *
+ * LOG rather than THROW, deliberately. Both patches improve an ERROR MESSAGE; neither is load
+ * bearing for a single tool call, and a throw here runs at server construction, so a renamed
+ * internal in a minor SDK bump would take the whole MCP server down for every user rather than
+ * degrade one message. That trade is backwards. The place a shape change must fail is the gate —
+ * `sdk-private-shape.test.ts` asserts both shapes and reddens CI on the bump — and this line is the
+ * backstop for the one case the gate cannot see: a user whose installed SDK is not the one CI
+ * resolved. The old behaviour, a bare `return`, gave neither.
+ */
+const SDK_SHAPE_MISSING = 'sdk_internal_missing';
 import { log } from '../log.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
@@ -73,23 +86,6 @@ export function firstSentence(description) {
  * Across the three tools that take a predicate that is 72% of the entire advertised input schema — a
  * cost re-sent on every request, forever, to describe a grammar most calls use one variant of.
  */
-/**
- * Is this parameter ACTUALLY the predicate union?
- *
- * This used to be a name check — `new Set(['predicate', 'until'])` — and `until` is overloaded on
- * this surface: the act/assert family means a predicate by it, while reticle_observe / _network /
- * _console mean a NUMBER, an upper cursor bound. So all three had their numeric parameter advertised
- * to the agent as `Predicate object: { kind, ...fields }`, typed as a record, under the DEFAULT
- * profile. An agent believing the schema passes an object, `asNumber` yields undefined, the bound is
- * silently dropped and the tool answers over the wrong window — a wrong answer wearing the shape of
- * an answer.
- *
- * Keying on the schema cannot make that mistake: a parameter is compacted because it IS a predicate.
- */
-function isPredicateParam(schema) {
-    const inner = schema instanceof z.ZodOptional ? schema.unwrap() : schema;
-    return inner === PredicateSchema || inner === PredicateSchema.optional();
-}
 /**
  * What a lean profile advertises in place of the full predicate union.
  *
@@ -246,7 +242,12 @@ export function advertisedConfig(tool, advertised, profile) {
     // `verify` is lean for the same reason `default` is, and more so: it exists to make a verdict
     // cheap, and it was serving FULL descriptions plus outputSchema because the check named only the
     // default. That put 8,207 bytes on the wire for three tools.
-    const lean = profile === TOOL_SURFACE.DEFAULT || profile === TOOL_SURFACE.VERIFY;
+    // `lean` here is the ADJECTIVE (terse descriptions, no output schemas), which every trimmed surface
+    // wants — including TOOL_SURFACE.LEAN, the profile that borrows the word. A trimmed surface serving
+    // full prose plus output schemas is the exact defect that put 8,207 bytes on `verify`'s three tools.
+    const lean = profile === TOOL_SURFACE.DEFAULT ||
+        profile === TOOL_SURFACE.VERIFY ||
+        profile === TOOL_SURFACE.LEAN;
     const terse = lean && !isMetaTool;
     // The first advertised tool carrying a predicate spells the grammar out; the rest point at it.
     const anchor = advertised.find((t) => Object.values(t.inputSchema).some((schema) => isPredicateParam(schema)))?.name;
@@ -270,8 +271,10 @@ function unknownKeys(args, allowed) {
 export function installFriendlyArgErrors(server, examples, allowedKeys = new Map()) {
     const target = server;
     const original = target.validateToolInput;
-    if (typeof original !== 'function')
+    if (typeof original !== 'function') {
+        log(SDK_SHAPE_MISSING, { internal: 'validateToolInput', lost: 'friendly argument errors' });
         return;
+    }
     target.validateToolInput = async (tool, args, toolName) => {
         // An UNKNOWN key is the failure zod cannot catch, because object schemas are non-strict: the key
         // is silently dropped and the tool answers as if it had not been asked. Measured live —
@@ -281,8 +284,14 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         const unknown = unknownKeys(args, allowedKeys.get(toolName));
         if (unknown.length > 0) {
             const example = examples.get(toolName);
+            // What the tool DOES declare, in the same breath as what it does not. Naming only the bad key
+            // leaves the caller guessing again, and the next guess costs another round trip — which is the
+            // whole shape of the failure being fixed here. The list is already in hand, and for a tool
+            // with no example (the meta-tools) it is the only thing standing between a typo and a retry.
+            const declared = [...(allowedKeys.get(toolName) ?? [])].join(', ');
             throw new McpError(ErrorCode.InvalidParams, `Unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
                 `They were NOT applied — a result computed without them would look like an answer. ` +
+                (0 === declared.length ? '' : `${toolName} declares: ${declared}. `) +
                 (example === undefined
                     ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
                     : `A valid call looks like: ${toolName} ${example}`));
@@ -347,8 +356,13 @@ function installUnadvertisedToolHelp(server, advertised, known) {
     const inner = server.server;
     const handlers = inner._requestHandlers;
     const original = handlers?.get(CALL_TOOL_METHOD);
-    if (handlers === undefined || original === undefined)
+    if (handlers === undefined || original === undefined) {
+        log(SDK_SHAPE_MISSING, {
+            internal: handlers === undefined ? '_requestHandlers' : CALL_TOOL_METHOD,
+            lost: 'unadvertised-tool help',
+        });
         return;
+    }
     handlers.set(CALL_TOOL_METHOD, async (request, extra) => {
         const name = toolNameOf(request);
         const help = name === undefined ? undefined : unadvertisedToolHelp(name, advertised, known);
@@ -439,7 +453,16 @@ tools = TOOLS) {
         .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
     // Every tool in the table, not just the advertised ones: reticle_run dispatches to the full
     // table, so an unadvertised tool reached through the hatch must be just as strict.
-    new Map(tools.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
+    //
+    // ...and the advertised list on top of it, because the two META-tools are not in the table — they
+    // are composed onto the surface — so they had no entry, and no entry means no declared keys means
+    // every key allowed. `reticle_tools` took a misnamed argument, dropped it, and answered with the
+    // whole catalogue: a well-formed answer to a question nobody asked, on the one tool whose entire
+    // job is telling an agent what the surface is.
+    new Map([...tools, ...advertised].map((tool) => [
+        tool.name,
+        new Set(Object.keys(tool.inputSchema)),
+    ])));
     for (const tool of advertised) {
         // Output schemas are now the largest slice of the per-request tax (55.6% of the hybrid payload
         // after the predicate fix) and we are the only one of the three MCP servers that sends them.
@@ -492,7 +515,12 @@ tools = TOOLS) {
                 // Every error the agent hits should answer "what next?", not just "what broke".
                 return {
                     isError: true,
-                    content: [{ type: 'text', text: JSON.stringify(buildErrorPayload(message)) }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(takeVersionSkewOnto(buildErrorPayload(message))),
+                        },
+                    ],
                 };
             }
         });

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

@@ -0,0 +1,11 @@
+/**
+ * Reconnect backoff, shared by the SSE stream and the POST leg.
+ *
+ * Its own module only because both halves need it and they must not import each other: the proxy
+ * owns the stream, the post transport owns the request, and a cycle between them to reach three
+ * lines of arithmetic would be the wrong price.
+ */
+/** Linear and capped, so a briefly-restarting daemon is picked up fast. */
+export declare const RECONNECT_BASE_MS = 250;
+export declare const RECONNECT_CAP_MS = 5000;
+export declare function reconnectDelayMs(attempt: number): number;

package/dist/mcp/proxy-backoff.js

@@ -0,0 +1,13 @@
+/**
+ * Reconnect backoff, shared by the SSE stream and the POST leg.
+ *
+ * Its own module only because both halves need it and they must not import each other: the proxy
+ * owns the stream, the post transport owns the request, and a cycle between them to reach three
+ * lines of arithmetic would be the wrong price.
+ */
+/** Linear and capped, so a briefly-restarting daemon is picked up fast. */
+export const RECONNECT_BASE_MS = 250;
+export const RECONNECT_CAP_MS = 5_000;
+export function reconnectDelayMs(attempt) {
+    return Math.min(RECONNECT_BASE_MS * attempt, RECONNECT_CAP_MS);
+}

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

@@ -1,3 +1,4 @@
+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

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

@@ -11,9 +11,13 @@ const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envD
     ? 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
@@ -38,11 +42,13 @@ export function probeDaemon(port) {
 /** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
 export async function waitForDaemon(port) {
     const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    let attempt = 0;
     while (Date.now() < deadline) {
         const reachable = await probeDaemon(port);
         if (reachable)
             return;
-        await delay(DAEMON_POLL_INTERVAL_MS);
+        attempt++;
+        await delay(daemonPollDelayMs(attempt));
     }
     throw new Error(`reticle daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
 }

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

@@ -44,6 +44,29 @@ instructions?: string): string | null;
  * where it is honoured and costs one line where it is not.
  */
 export declare function toolsChangedNotification(catalogWasLocal: boolean): string | null;
+/**
+ * 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 declare function degradedInstructions(healthy: string, port: number, reason: string): string;
 /**
  * The largest single JSON-RPC line the proxy will accumulate from a client.
  *