@reticlehq/server 3.7.0 → 3.8.1

package/dist/surface/mcp/mcp.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { type ToolDeps } from '../tools/tools.js';
 import type { ToolDef } from '../tools/tools.js';
@@ -17,7 +18,7 @@ export declare const CALL_TOOL_METHOD = "tools/call";
  * tool with a strict schema (`reticle_context`) failed the whole call on a validating client the
  * first time one of them rode on it.
  */
-export declare function withSessionEnvelope(_name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
+export declare function withSessionEnvelope(_name: string, outputSchema: Record<string, z.ZodType> | undefined): Record<string, z.ZodType> | undefined;
 /**
  * Abbreviations whose internal period is NOT a sentence end.
  *
@@ -92,10 +93,26 @@ tools?: readonly ToolDef[]): ToolDef[];
  */
 export declare function advertisedConfig(tool: ToolDef, advertised: readonly ToolDef[], profile: ToolSurface): {
     description: string;
-    inputSchema: z.ZodRawShape;
-    outputSchema?: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
+    outputSchema?: Record<string, z.ZodType>;
+    annotations: ToolAnnotations;
 };
 export declare function installFriendlyArgErrors(server: McpServer, examples: Map<string, string>, allowedKeys?: Map<string, ReadonlySet<string>>): void;
+/**
+ * The daemon's factory for one MCP server for each attach. A proxy's id is its agent identity, so a
+ * reconnect from the same proxy is the same owner and keeps its leases. An attach with no proxy id
+ * gets a new random id from `createMcpServer`.
+ *
+ * `instructions` is read for each attach, not once: a project that gets wired while the daemon is
+ * alive must stop being told to wire itself on the next agent that connects.
+ */
+export declare function mcpServerFactoryFor(deps: ToolDeps, profile: ToolSurface, instructions: () => boolean | Omit<InstructionState, 'advertised'>): (peerSkew?: string, proxyId?: string, agentSession?: string) => McpServer;
+/**
+ * The `tools/list` result this server serves on `surface`, built with no daemon and no deps. The
+ * proxy answers with it while its daemon starts. The same table, the same per-tool config and the
+ * same SDK conversion make it the same list; `proxy-cold-start.test.ts` holds the two equal.
+ */
+export declare function staticToolCatalog(surface: ToolSurface): Promise<unknown[]>;
 export declare function createMcpServer(rawDeps: ToolDeps, profile?: ToolSurface, 
 /**
  * Has an app ever connected for this project? Decides what the instructions LEAD with.

package/dist/surface/mcp/mcp.js

@@ -5,14 +5,14 @@ import { z } from 'zod';
 import { isPredicateParam } from '@reticlehq/engine/question/predicate/predicate-eval.js';
 import { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { tableForSurface } from '../tools/tools.js';
-import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
+import { filterTools, describeToolSurface, TOOL_SURFACE, toolAnnotations, } from '../tools/tool-surface.js';
 import { ReticleTool } from '@reticlehq/core';
-import { SHARED_PARAM_SHORT } from './shared-params.js';
-import { buildDynamicTools } from '../tools/dynamic-tools.js';
+import { sharedParamShort } from './shared-params.js';
+import { buildDynamicTools, descriptionOf } from '../tools/dynamic-tools.js';
 import { runTool } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape, newSnapshotCache } from '../tools/tool-kit.js';
-import { buildErrorPayload } from '../tools/error-recovery.js';
-import { takeVersionSkewOnto } from '../../command/version/version-nudge.js';
+import { buildErrorPayload, codedRefusalOf } from '../tools/error-recovery.js';
+import { connectionSkew, takeVersionSkewOnto } from '../../command/version/version-nudge.js';
 import { resultIsError } from './faults/mcp-is-error.js';
 import { consumerVerdictRefusal, reservedVerdictKeysIn } from './consumer-verdict-guard.js';
 import { buildServerInstructions } from './server-instructions.js';
@@ -38,7 +38,7 @@ import { SERVER_VERSION } from '../../command/version/identity/server-version.js
 import { setMcpClientNameHook } from '../../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { reportMcpConnected } from '../../telemetry/mcp-connection.js';
-import { noteAgentAttached, noteAgentDetached, runAsAgent } from '../../hooks/coding-agents.js';
+import { noteAgentAttached, noteAgentDetached, noteAgentSession, runAsAgent, } from '../../hooks/coding-agents.js';
 import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 /**
  * Merge the runtime-spliced envelope into a tool's declared outputSchema so structuredContent
@@ -51,8 +51,9 @@ import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-p
  * first time one of them rode on it.
  */
 export function withSessionEnvelope(_name, outputSchema) {
-    if (outputSchema === undefined)
+    if (outputSchema === undefined) {
         return outputSchema;
+    }
     return { ...sessionEnvelopeShape, ...outputSchema };
 }
 const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
@@ -124,7 +125,7 @@ const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of e
  * paying for six.
  */
 const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
-    'net.bodyMatches (a JSON field match on what the SERVER answered — say the FIELD (a dotted path reaches nested ones) and its value, ' +
+    'net.bodyMatches (a JSON field match on what the SERVER answered, keyed by the field: { status: "completed" }, never { field, value }; a dotted key reaches a nested field; ' +
     'because a substring of the body matches key names too), net.requestBodyMatches (the same on what ' +
     'the UI SENT — the verdict for "applying this filter actually puts it in the payload"), ' +
     'compare (page text vs server answer, no expected value: { left:{from:"text",scope}, ' +
@@ -149,16 +150,14 @@ function leanZodShape(shape, advertised, predicateAnchor) {
     for (const [key, schema] of Object.entries(shape)) {
         if (isPredicateParam(schema)) {
             // Every tool keeps the kinds; only the navigation hint is anchored.
-            const compact = z
-                .record(z.unknown())
-                .describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
+            const compact = z.record(z.string(), z.unknown());
+            out[key] = (schema.isOptional() ? compact.optional() : compact).describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
             hintSpent = true;
-            out[key] = schema.isOptional() ? compact.optional() : compact;
             continue;
         }
         // Shared boilerplate is documented once in the initialize instructions instead of on every
         // tool, every turn. `sessionId` alone was 2,076 bytes of identical text across 16 tools.
-        const shared = SHARED_PARAM_SHORT[key];
+        const shared = sharedParamShort(key, schema);
         if (shared !== undefined) {
             // `.describe` returns the same schema with new prose, so optionality carries over. Re-wrapping
             // in `.optional()` would nest one inside another and change the parameter's TYPE, which is a
@@ -168,7 +167,7 @@ function leanZodShape(shape, advertised, predicateAnchor) {
         }
         // Through the same rewrite as tool descriptions: a parameter that says "a ref from
         // reticle_snapshot" names a tool this surface does not have.
-        const desc = schema.description;
+        const desc = descriptionOf(schema);
         out[key] =
             'string' === typeof desc
                 ? schema.describe(liveCallText(firstSentence(desc), advertised))
@@ -333,12 +332,14 @@ export function advertisedConfig(tool, advertised, profile) {
             ? leanZodShape(tool.inputSchema, new Set(advertised.map((each) => each.name)), tool.name === anchor ? undefined : anchor)
             : tool.inputSchema,
         ...(outputSchema !== undefined ? { outputSchema } : {}),
+        annotations: toolAnnotations(tool.name),
     };
 }
 /** Argument keys the tool never declared. Empty when the tool's shape is unknown to us. */
 function unknownKeys(args, allowed) {
-    if (allowed === undefined || typeof args !== 'object' || null === args)
+    if (allowed === undefined || typeof args !== 'object' || null === args) {
         return [];
+    }
     return Object.keys(args).filter((key) => !allowed.has(key));
 }
 export function installFriendlyArgErrors(server, examples, allowedKeys = new Map()) {
@@ -404,12 +405,14 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
  * the predicate is not what broke.
  */
 function predicateMessage(args) {
-    if (typeof args !== 'object' || null === args)
+    if (typeof args !== 'object' || null === args) {
         return undefined;
+    }
     const record = args;
     const predicate = record['predicate'] ?? record['until'];
-    if (predicate === undefined)
+    if (predicate === undefined) {
         return undefined;
+    }
     try {
         parsePredicate(predicate);
         return undefined;
@@ -454,8 +457,9 @@ function installUnadvertisedToolHelp(server, advertised, known) {
         const help = name === undefined ? undefined : unadvertisedToolHelp(name, advertised, known);
         // A failed RESULT, not a JSON-RPC error: a client that reads only `result` rendered the error
         // as an empty success, and the agent believed `reticle_flow_save` had saved its flow.
-        if (help !== undefined)
+        if (help !== undefined) {
             return { content: [{ type: 'text', text: help }], isError: true };
+        }
         return original(request, extra);
     });
 }
@@ -477,14 +481,32 @@ function asCallOf(request, tool, action) {
 }
 /** The requested tool name, when the request has the shape we expect. */
 function toolNameOf(request) {
-    if (typeof request !== 'object' || null === request)
+    if (typeof request !== 'object' || null === request) {
         return undefined;
+    }
     const params = request.params;
-    if (typeof params !== 'object' || null === params)
+    if (typeof params !== 'object' || null === params) {
         return undefined;
+    }
     const name = params.name;
     return 'string' === typeof name ? name : undefined;
 }
+/**
+ * The daemon's factory for one MCP server for each attach. A proxy's id is its agent identity, so a
+ * reconnect from the same proxy is the same owner and keeps its leases. An attach with no proxy id
+ * gets a new random id from `createMcpServer`.
+ *
+ * `instructions` is read for each attach, not once: a project that gets wired while the daemon is
+ * alive must stop being told to wire itself on the next agent that connects.
+ */
+export function mcpServerFactoryFor(deps, profile, instructions) {
+    return (peerSkew, proxyId, agentSession) => createMcpServer({
+        ...deps,
+        ...(peerSkew === undefined ? {} : { peerSkew: connectionSkew(peerSkew) }),
+        ...(proxyId === undefined ? {} : { attachId: proxyId }),
+        ...(agentSession === undefined ? {} : { agentSession }),
+    }, profile, instructions());
+}
 /**
  * The tools this codebase ships. Anything outside it came from a host via the `tools` parameter, and
  * is held to the verdict rule below.
@@ -500,6 +522,35 @@ function toolNameOf(request) {
  * covered the day it is added instead of the day somebody notices.
  */
 const FIRST_PARTY_TOOL_NAMES = new Set(Object.values(ReticleTool));
+/**
+ * The `tools/list` result this server serves on `surface`, built with no daemon and no deps. The
+ * proxy answers with it while its daemon starts. The same table, the same per-tool config and the
+ * same SDK conversion make it the same list; `proxy-cold-start.test.ts` holds the two equal.
+ */
+export async function staticToolCatalog(surface) {
+    const [{ Client }, { InMemoryTransport }] = await Promise.all([
+        import('@modelcontextprotocol/sdk/client/index.js'),
+        import('@modelcontextprotocol/sdk/inMemory.js'),
+    ]);
+    const server = new McpServer(SERVER_INFO);
+    const register = server.registerTool.bind(server);
+    const advertised = advertisedTools(surface);
+    for (const tool of advertised) {
+        // Never called: this server only lists.
+        register(tool.name, advertisedConfig(tool, advertised, surface), () => ({ content: [] }));
+    }
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    const client = new Client(SERVER_INFO);
+    await client.connect(clientTransport);
+    try {
+        return (await client.listTools()).tools;
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
 export function createMcpServer(rawDeps, profile = TOOL_SURFACE.DEFAULT, 
 /**
  * Has an app ever connected for this project? Decides what the instructions LEAD with.
@@ -530,6 +581,12 @@ tools = tableForSurface(profile)) {
      * store keeps it.
      */
     const deps = { snapshots: newSnapshotCache(), attachId: randomUUID(), ...rawDeps };
+    // A proxy that reconnects brings its own id as `attachId`, so this is the same owner coming back:
+    // take its leases out of their grace. A new random id owns no leases, so this does nothing.
+    deps.pool?.reattachOwner(deps.attachId);
+    if (deps.agentSession !== undefined) {
+        noteAgentSession(deps.attachId, deps.agentSession);
+    }
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     // Which surface this daemon advertises. The 18-tool default and the 48-tool full surface are
     // different products from inside an agent's context, so outcomes are only comparable when the
@@ -558,8 +615,9 @@ tools = tableForSurface(profile)) {
      */
     server.server.oninitialized = () => {
         const info = server.server.getClientVersion();
-        if (info?.name === undefined)
+        if (info?.name === undefined) {
             return;
+        }
         getSessionMetrics().recordClient(info.name, info.version);
         // So the HUD can say which agent is connected, and credit a note to the one that read it.
         noteAgentAttached(deps.attachId, info.name);
@@ -567,9 +625,13 @@ tools = tableForSurface(profile)) {
         // the first moment it can carry WHO. It used to fire from the SSE `connect()` resolution, which
         // happens before the handshake — so every connect row was anonymous, and the field meant to say
         // which agent client converts best was empty on every event ever sent.
-        void runAsAgent(deps.attachId, () => Promise.resolve(reportMcpConnected(info.name)));
+        void runAsAgent(deps.attachId, () => Promise.resolve(reportMcpConnected(info.name, deps.attachId)));
+    };
+    server.server.onclose = () => {
+        noteAgentDetached(deps.attachId);
+        // Start the leases' short grace. A reconnect from the same proxy takes them back (see above).
+        deps.pool?.detachOwner(deps.attachId);
     };
-    server.server.onclose = () => noteAgentDetached(deps.attachId);
     // Which agent is on the other end, for a feedback report. Registered as a lazy hook rather than
     // read here: the handshake has not happened yet at construction time, and a report filed twenty
     // tool calls later is exactly when we want the answer.
@@ -578,8 +640,9 @@ tools = tableForSurface(profile)) {
         // Still records, because a client that skipped the handshake path above (a replayed initialize
         // through the proxy, a transport that reconnects) is a client we would otherwise lose entirely.
         // `recordClient` is idempotent per name.
-        if (info?.name !== undefined)
+        if (info?.name !== undefined) {
             getSessionMetrics().recordClient(info.name, info.version);
+        }
         return info === undefined ? undefined : { name: info.name, version: info.version };
     });
     // Cast once to our bridge type so every per-tool call site is typed without `any`.
@@ -706,7 +769,7 @@ tools = tableForSurface(profile)) {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(buildErrorPayload(message), deps.peerSkew), advertisedNames)),
+                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(buildErrorPayload(message, codedRefusalOf(error)), deps.peerSkew), advertisedNames)),
                         },
                     ],
                 };

package/dist/surface/mcp/proxy/drive-calls.d.ts

@@ -8,3 +8,47 @@ export declare function isHarnessDriveCall(msg: {
  * call as if it had not run pays for a second drive.
  */
 export declare const MSG_DRIVE_MAY_BE_RUNNING: string;
+/**
+ * JSON-RPC requests forwarded on behalf of the client that have not been answered yet.
+ *
+ * Only used at shutdown, where it is the difference between "the client closed stdin" and "the client
+ * closed stdin and we dropped its `tools/list` on the floor while reporting exit 0". A request has an
+ * id AND a method; a notification has no id and is owed nothing; a response has an id and no method.
+ */
+export declare class PendingRequests {
+    #private;
+    observeOutbound(line: string): void;
+    /** Whether this unanswered request asked for a Harness drive. */
+    isDrive(id: unknown): boolean;
+    observeInbound(line: string): void;
+    get unanswered(): string[];
+    /**
+     * Claim ONE unanswered id, so exactly one path may answer it. False means somebody already did —
+     * a duplicate response to one id is a protocol violation, not a belt-and-braces retry.
+     */
+    take(id: unknown): boolean;
+    /** Take every unanswered id and forget them, so the same request is failed at most once. */
+    drain(): string[];
+    /** Forget which requests were drives, once their replies are written. */
+    clearDrives(): void;
+}
+/**
+ * JSON-RPC errors for every request that was in flight when the stream died.
+ *
+ * These are unrecoverable BY CONSTRUCTION: the daemon builds a fresh MCP session per SSE
+ * connection, so the reconnected session has never seen them. Re-sending them is not an option
+ * either — a `reticle_act` that already clicked would click twice, and inventing a second action in
+ * somebody's app is worse than reporting a failure.
+ *
+ * So the proxy answers them itself, under each request's own id. Found by brute force: killing the
+ * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
+ * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
+ */
+export 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, drive?: boolean): string;

package/dist/surface/mcp/proxy/drive-calls.js

@@ -1,19 +1,27 @@
-/** Which proxied calls are Harness drives, and what to tell an agent whose drive call was lost. */
+/**
+ * The proxied calls still in flight, which of them are Harness drives, and what each one is told
+ * when the transport under it is lost.
+ */
 import { ReticleTool } from '@reticlehq/core';
+import { parseLine as parseJsonRpc } from './proxy-handshake.js';
 const TOOLS_CALL = 'tools/call';
 const EXPLORE_ACTION = 'explore';
 /** A `tools/call` of reticle_verify explore, directly or through the reticle_run hatch. */
 export function isHarnessDriveCall(msg) {
-    if (TOOLS_CALL !== msg.method)
+    if (TOOLS_CALL !== msg.method) {
         return false;
+    }
     const params = (msg.params ?? {});
     const args = (params.arguments ?? {});
-    if (ReticleTool.VERIFY_EXPLORE === params.name)
+    if (ReticleTool.VERIFY_EXPLORE === params.name) {
         return true;
-    if (ReticleTool.VERIFY === params.name)
+    }
+    if (ReticleTool.VERIFY === params.name) {
         return EXPLORE_ACTION === args['action'];
-    if (ReticleTool.RUN !== params.name)
+    }
+    if (ReticleTool.RUN !== params.name) {
         return false;
+    }
     const inner = (args['args'] ?? {});
     return (ReticleTool.VERIFY_EXPLORE === args['tool'] ||
         (ReticleTool.VERIFY === args['tool'] && EXPLORE_ACTION === inner['action']));
@@ -25,3 +33,104 @@ export function isHarnessDriveCall(msg) {
 export const MSG_DRIVE_MAY_BE_RUNNING = `The Harness drive this call started or polled may still be running in the daemon. Once ` +
     `Reticle reconnects, call ${ReticleTool.VERIFY} {action:"explore"} with no runId to get the ` +
     `running drive back (it will not start a second), then poll it by runId.`;
+/**
+ * JSON-RPC requests forwarded on behalf of the client that have not been answered yet.
+ *
+ * Only used at shutdown, where it is the difference between "the client closed stdin" and "the client
+ * closed stdin and we dropped its `tools/list` on the floor while reporting exit 0". A request has an
+ * id AND a method; a notification has no id and is owed nothing; a response has an id and no method.
+ */
+export class PendingRequests {
+    #ids = new Set();
+    /** The pending requests that start or poll a Harness drive, which outlives a lost connection. */
+    #drives = new Set();
+    observeOutbound(line) {
+        const msg = parseJsonRpc(line);
+        if (null === msg || msg.id === undefined || msg.method === undefined) {
+            return;
+        }
+        const id = JSON.stringify(msg.id);
+        this.#ids.add(id);
+        if (isHarnessDriveCall(msg)) {
+            this.#drives.add(id);
+        }
+    }
+    /** Whether this unanswered request asked for a Harness drive. */
+    isDrive(id) {
+        return this.#drives.has(JSON.stringify(id));
+    }
+    observeInbound(line) {
+        const msg = parseJsonRpc(line);
+        if (null === msg || msg.id === undefined) {
+            return;
+        }
+        this.#ids.delete(JSON.stringify(msg.id));
+    }
+    get unanswered() {
+        return [...this.#ids];
+    }
+    /**
+     * Claim ONE unanswered id, so exactly one path may answer it. False means somebody already did —
+     * a duplicate response to one id is a protocol violation, not a belt-and-braces retry.
+     */
+    take(id) {
+        this.#drives.delete(JSON.stringify(id));
+        return this.#ids.delete(JSON.stringify(id));
+    }
+    /** Take every unanswered id and forget them, so the same request is failed at most once. */
+    drain() {
+        const ids = [...this.#ids];
+        this.#ids.clear();
+        return ids;
+    }
+    /** Forget which requests were drives, once their replies are written. */
+    clearDrives() {
+        this.#drives.clear();
+    }
+}
+/**
+ * JSON-RPC errors for every request that was in flight when the stream died.
+ *
+ * These are unrecoverable BY CONSTRUCTION: the daemon builds a fresh MCP session per SSE
+ * connection, so the reconnected session has never seen them. Re-sending them is not an option
+ * either — a `reticle_act` that already clicked would click twice, and inventing a second action in
+ * somebody's app is worse than reporting a failure.
+ *
+ * So the proxy answers them itself, under each request's own id. Found by brute force: killing the
+ * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
+ * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
+ */
+export function streamLossReplies(pending, reason, nextStep) {
+    const replies = pending.drain().map((id) => {
+        const parsed = JSON.parse(id);
+        return transportLossReply(parsed, reason, nextStep, pending.isDrive(parsed));
+    });
+    pending.clearDrives();
+    return replies;
+}
+/**
+ * -32001: a server-defined error. Not -32603 (internal): nothing went wrong INSIDE the call, the
+ * transport under it went away, and the distinction is what tells a caller the action may be safe
+ * to retry.
+ */
+const TRANSPORT_LOSS_CODE = -32001;
+/**
+ * The one shape every "the transport ate your call" answer takes, whichever leg died.
+ *
+ * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
+ * stops there, which is all a first-run user got out of their first ever tool call.
+ */
+export function transportLossReply(id, reason, nextStep, drive = false) {
+    return JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code: TRANSPORT_LOSS_CODE,
+            message: (drive
+                ? `the daemon connection dropped (${reason}) before this call was answered. ${MSG_DRIVE_MAY_BE_RUNNING}`
+                : `the daemon connection dropped (${reason}) before this call was answered — it did NOT ` +
+                    'complete. Reticle is recovering the connection; retry if the action is safe to repeat.') +
+                (nextStep === undefined ? '' : ` ${nextStep}`),
+        },
+    });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The daemon that `reticle mcp` starts beside the proxy. `ready` settles when the start is done,
+ * with the port to dial. `spawning` resolves when a new daemon process is started: the port was
+ * free, so no stranger holds it, and the proxy can answer the handshake at once with `tools()`,
+ * the daemon's own tool list built in this process.
+ */
+export interface ProxyBoot {
+    readonly ready: Promise<number | void>;
+    readonly spawning: Promise<void>;
+    readonly tools: () => Promise<unknown[]>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -19,11 +19,17 @@ export declare function probeDaemon(port: number, host?: string): Promise<boolea
  *
  * 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.
+ *
+ * `alive` says if the daemon process in the pid file still runs. When it does not, no daemon can
+ * come up, so the wait stops at once and does not poll to the deadline.
  */
 export declare function waitForDaemon(port: number, probes?: {
     tcpOpen: (port: number) => Promise<boolean>;
     status: (port: number) => Promise<unknown>;
+    alive?: () => boolean;
 }): Promise<void>;
+/** True while the process in the daemon pid file for `port` runs. */
+export declare function daemonProcessAlive(port: number): boolean;
 /**
  * Poll until `/status` on `port` answers as a Reticle daemon; false once the bound passes.
  *

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

@@ -2,6 +2,7 @@ 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';
+import { isAlive, readPid } from '../../../command/daemon/daemon.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
@@ -55,8 +56,11 @@ export function probeDaemon(port, host = LOOPBACK_HOST) {
  *
  * 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.
+ *
+ * `alive` says if the daemon process in the pid file still runs. When it does not, no daemon can
+ * come up, so the wait stops at once and does not poll to the deadline.
  */
-export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, status: fetchStatus }) {
+export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, status: fetchStatus, alive: () => daemonProcessAlive(port) }) {
     const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
     let attempt = 0;
     let presence = PortPresence.FREE;
@@ -64,6 +68,10 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
         presence = await probePresence(port, probes);
         if (presenceIsUsable(presence))
             return;
+        if (false === probes.alive?.()) {
+            throw new Error(`the reticle daemon on port ${String(port)} exited before it was ready — ` +
+                describePresence(presence, port));
+        }
         attempt++;
         await delay(daemonPollDelayMs(attempt));
     }
@@ -73,6 +81,11 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
     throw new Error(`reticle daemon did not become ready on port ${String(port)} within ` +
         `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePresence(presence, port)}`);
 }
+/** True while the process in the daemon pid file for `port` runs. */
+export function daemonProcessAlive(port) {
+    const pid = readPid(port);
+    return null !== pid && isAlive(pid);
+}
 /** How long a spawned daemon gets to bind before `serve`, `restart` or `init` gives up on it. */
 const BIND_TIMEOUT_MS = 15_000;
 const BIND_POLL_MS = 150;

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

@@ -8,6 +8,15 @@
  * connected, initialized and toolless until a human notices.
  */
 export declare const TOOLS_CHANGED_NOTIFICATION = "notifications/tools/list_changed";
+interface JsonRpcLike {
+    id?: unknown;
+    method?: unknown;
+    params?: {
+        protocolVersion?: unknown;
+    };
+}
+/** A line as a JSON-RPC object, or null when it is not JSON or not an object. */
+export declare function parseLine(line: string): JsonRpcLike | null;
 /** True when this queued client line is the handshake we answered ourselves. */
 export declare function isHandshakeLine(line: string): boolean;
 export declare function localInitializeResponse(line: string, 
@@ -63,8 +72,11 @@ export declare function toolsChangedNotification(catalogWasLocal: boolean): stri
  * 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.
+ * The healthy block is kept underneath: 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. Only its part up to the
+ * writing rule is kept. Claude Code shows about the first 4,096 characters, and the notice plus the
+ * whole block came to about 4,600, so the client cut the writing rule. The text says what it left
+ * out, so the cut is not silent.
  */
 export declare function degradedInstructions(healthy: string, port: number, reason: string): string;
 /**
@@ -105,4 +117,24 @@ interface DrainedLines {
  * the concatenation alone. Only a chunk that actually carries a newline pays for a scan.
  */
 export declare function drainLines(buffer: string, chunk: string, maxLineBytes?: number, discarding?: boolean): DrainedLines;
+/** 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";
+/**
+ * Makes a reconnect invisible to the client.
+ *
+ * The daemon builds a FRESH `McpServer` per SSE connection, so a reconnected session has never seen
+ * the client's `initialize` — every subsequent `tools/call` would hit an uninitialized server. The
+ * proxy therefore remembers the handshake the client sent once and replays it into each new session.
+ * The replay is re-issued under a reserved id so the daemon's response to it can be dropped rather
+ * than reaching the client's stdout, where a duplicate JSON-RPC id would be a protocol violation.
+ */
+export declare class HandshakeReplay {
+    #private;
+    /** Record one outbound client line. Cheap enough to call for every stdin message. */
+    observeOutbound(line: string): void;
+    /** Lines to POST into a freshly-established session, before any queued client traffic. */
+    replayLines(): string[];
+    /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
+    shouldSuppressInbound(line: string): boolean;
+}
 export {};