@reticlehq/server 2.7.0 → 2.9.0

package/dist/mcp/mcp.js

@@ -5,11 +5,14 @@ import { PredicateSchema } from '../events/predicate.js';
 import { isToonable, resultToToon } from '@reticlehq/core';
 import { TOOLS } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { SHARED_PARAM_SHORT } from './shared-params.js';
 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 { 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';
@@ -31,27 +34,6 @@ export function withSessionEnvelope(name, outputSchema) {
     return { ...sessionEnvelopeShape, ...outputSchema };
 }
 const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
-/**
- * What every agent is told at `initialize`, before it has called a single tool.
- *
- * This is the only channel that reaches an agent with NO dependency on the project: no CLAUDE.md, no
- * AGENTS.md, no pasted skill, no successful `reticle init`. An agent whose setup half-worked has read
- * none of those files and is precisely the agent whose report we need — so the standing instruction
- * to send feedback has to live here, where it arrives with the connection itself.
- *
- * Kept to a handful of lines: it is prepended to every session's context, so each sentence is paid
- * for on every turn, forever.
- */
-const SERVER_INSTRUCTIONS = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
-
-Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. A verdict of verified:"unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
-
-Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`reticle_feedback\` the moment you notice, then carry on with your task:
-- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
-- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
-- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
-
-Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
 /** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
  * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
  * first clause retains the essentials (enum hints like "role | text | label" live there). */
@@ -144,8 +126,10 @@ 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), ' +
-    'console.absent:true (action completed with a CLEAN console), absent:true on element/text ' +
-    '(it should be gone). Call reticle_tools for the full field grammar of a kind.';
+    'net.bodyContains (a substring of what the SERVER answered — catches a UI that echoes the input ' +
+    'it sent instead of the result it got back), console.absent:true (action completed with a CLEAN ' +
+    'console), absent:true on element/text (it should be gone). Call reticle_tools for the full field ' +
+    'grammar of a kind.';
 const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMMAR_HINT}`;
 /**
  * Lean copy of a tool's zod input shape for lean profiles: each parameter's description is
@@ -170,6 +154,16 @@ function leanZodShape(shape, predicateAnchor) {
             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];
+        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
+            // thing this lean path is meant to do for predicates and nothing else.
+            out[key] = schema.describe(shared);
+            continue;
+        }
         const desc = schema.description;
         out[key] = 'string' === typeof desc ? schema.describe(firstSentence(desc)) : schema;
     }
@@ -228,10 +222,25 @@ export function advertisedConfig(tool, advertised, profile) {
     // sentence and the agent would have nothing left to learn the surface from. Measured when it
     // happened: dynamic's tools/list fell 1,543 -> 849 bytes, which looks like a saving and is a
     // capability loss.
-    const terse = profile === TOOL_SURFACE.DEFAULT;
+    //
+    // The two meta-tools are exempt, on every surface. Their descriptions are not a description OF a
+    // capability, they ARE the capability: the only place an agent is ever told that the tools it can
+    // see are not all the tools there are, and how to reach the rest. Trimmed to a first sentence,
+    // `reticle_tools` advertises as "Discover Reticle tools on demand." — which names no way to list
+    // anything, so a well-behaved agent has no reason to call it and the entire cold tail goes dark.
+    // The comment above already caught this for the retired `dynamic` profile; `default` is now both
+    // the lean surface and the one carrying the meta-tools, so the exemption follows it.
+    const isMetaTool = tool.name === ReticleTool.TOOLS || tool.name === ReticleTool.RUN;
+    // `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;
+    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;
-    const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
+    // Output schemas are dropped on every lean surface, meta-tools included: they are the single
+    // largest component and nothing on a lean surface validates against them.
+    const outputSchema = lean ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
     return {
         description: withExample(terse ? firstSentence(tool.description) : tool.description, tool.example),
         inputSchema: terse
@@ -346,22 +355,49 @@ function toolNameOf(request) {
     const name = params.name;
     return 'string' === typeof name ? name : undefined;
 }
-export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
+export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT, 
+/**
+ * Has an app ever connected for this project? Decides what the instructions LEAD with.
+ *
+ * Passed in rather than read here, so construction stays free of disk I/O and the decision is
+ * testable without a state directory. Defaulting to `false` is the deliberate safe side: an agent
+ * told to instrument a project that is already wired loses a paragraph, while an agent not told
+ * loses the entire install — and the second is what the field overwhelmingly shows.
+ */
+previouslyConnected = false) {
     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
     // session says which one it saw.
     getSessionMetrics().recordSurface(profile);
-    const server = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
-    // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
-    // hook rather than read here: the handshake has not happened yet at construction time, and a
-    // feedback report filed twenty tool calls later is exactly when we want the answer.
+    const server = new McpServer(SERVER_INFO, {
+        instructions: buildServerInstructions({ previouslyConnected }),
+    });
+    /**
+     * Record WHICH agent attached, at the handshake, for every session.
+     *
+     * `clients` and `clientVersions` were populated for almost nobody, and the reason was not that
+     * clients withhold `clientInfo` — they send it, and we read it. It was that the ONLY thing that
+     * ever called `recordClient` was the feedback hook below, which runs when a report is being built.
+     * So the field was really measuring "sessions that filed feedback", and a product whose users are
+     * agents could not say which agent, on which build, any of its numbers came from.
+     *
+     * `oninitialized` is the moment `clientInfo` first exists — reading it at construction time gets
+     * `undefined`, which is what made a lazy hook look like the only option.
+     */
+    server.server.oninitialized = () => {
+        const info = server.server.getClientVersion();
+        if (info?.name !== undefined)
+            getSessionMetrics().recordClient(info.name, info.version);
+    };
+    // Which agent is on the other end, for a feedback report. Registered as a lazy hook rather than
+    // read here: the handshake has not happened yet at construction time, and a report filed twenty
+    // tool calls later is exactly when we want the answer.
     setMcpClientNameHook(() => {
         const info = server.server.getClientVersion();
-        // Record it as a side effect of the first read so the session summary can report WHICH agents
-        // drove this daemon — the multi-agent story, visible without a second plumbing path.
-        // Name AND version: the version was already in this handshake and was being dropped, so a
-        // regression in agent behaviour could never be attributed to a client build.
+        // Still records, because a client that skipped the handshake path above (a replayed initialize
+        // through the proxy, a transport that reconnects) is a client we would otherwise lose entirely.
+        // `recordClient` is idempotent per name.
         if (info?.name !== undefined)
             getSessionMetrics().recordClient(info.name, info.version);
         return info === undefined ? undefined : { name: info.name, version: info.version };

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

@@ -1,3 +1,84 @@
+/**
+ * The protocol's own way to say "the tool list you have is out of date, fetch it again".
+ *
+ * Load-bearing here rather than a nicety. When we answer `initialize` ourselves the catalog we serve
+ * is one we made up, and it is usually empty. Nothing else in the protocol ever corrects that: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Without this the session is
+ * connected, initialized and toolless until a human notices.
+ */
+export declare const TOOLS_CHANGED_NOTIFICATION = "notifications/tools/list_changed";
 /** 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): string | null;
+export declare function localInitializeResponse(line: string, 
+/**
+ * What the daemon would have advertised, so the client is not left with none.
+ *
+ * A client reads `instructions` ONCE, at initialize, and this response is sent precisely when no
+ * daemon is up to send its own — which is the first run of a fresh install. So the block telling
+ * someone that having these tools is not the same as being set up was permanently absent for the
+ * exact population it addresses, and the daemon's later correct instructions arrive at a client
+ * that will never read the field again.
+ *
+ * Empty means "nothing to say", and the field is then omitted rather than sent blank.
+ */
+instructions?: string): string | null;
+/**
+ * The line that tells a client its tool list is stale, or null when there is nothing to correct.
+ *
+ * When a daemon arrives after we answered the handshake ourselves, the client is holding a tool list
+ * we invented, and on a cold start that list is empty. Nothing else in this protocol corrects it: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Connected, initialized and
+ * toolless for the rest of the session, with a human required to notice and reconnect by hand.
+ *
+ * Sent only when the catalog was ours. A client that completed a real handshake with the daemon
+ * already has the true list, and telling it to refetch would be a round trip for nothing.
+ *
+ * Lives here rather than in the proxy because it belongs to the locally-answered handshake, which is
+ * this module's subject.
+ *
+ * Worth knowing before relying on it: this is a best-effort correction, not the mechanism. Research
+ * into the four clients we target found that only some honour `notifications/tools/list_changed` at
+ * all, so the catalog still has to be right in the FIRST answer for the rest. This closes the gap
+ * where it is honoured and costs one line where it is not.
+ */
+export declare function toolsChangedNotification(catalogWasLocal: boolean): string | null;
+/**
+ * The largest single JSON-RPC line the proxy will accumulate from a client.
+ *
+ * Generous — a tool call with a big argument payload is legitimate — but finite, because without a
+ * ceiling the buffer grows to whatever is sent and the process is one `cat bigfile` away from an
+ * out-of-memory exit that would take the agent's whole tool surface with it.
+ */
+export declare const MAX_STDIN_LINE_BYTES: number;
+export interface DrainedLines {
+    /** Complete lines, in order. Empty when the chunk carried no newline. */
+    lines: string[];
+    /** The trailing partial line, carried into the next chunk. */
+    rest: string;
+    /** A single line exceeded the cap and was discarded rather than accumulated. */
+    overflowed: boolean;
+    /**
+     * Mid-discard: an oversized line was dropped and the REST of it is still arriving.
+     *
+     * Carried back in on the next call, and it is what makes dropping safe rather than merely tidy.
+     * Without it the tail of the discarded line arrives looking like a complete line and is forwarded
+     * as a JSON-RPC message — a fragment of something nobody sent, failing to parse, on a link where
+     * the client is waiting for answers to real requests.
+     */
+    discarding: boolean;
+}
+/**
+ * Append a chunk and split off whatever complete lines it produced.
+ *
+ * The reason this is not `(buffer + chunk).split('\n')` inline: that re-scans the WHOLE accumulated
+ * buffer on every chunk, so a single large line costs O(n²) in the size of the line. Measured
+ * against the real proxy, a 32 MB line took ~8s and a 50 MB line ~35s — with the event loop pinned
+ * throughout, so every other tool call on that link was frozen with no response and no error. The
+ * client sees the whole MCP surface hang.
+ *
+ * A chunk with no newline in it cannot complete a line, so there is nothing to split and the cost is
+ * the concatenation alone. Only a chunk that actually carries a newline pays for a scan.
+ */
+export declare function drainLines(buffer: string, chunk: string, maxLineBytes?: number, discarding?: boolean): DrainedLines;

package/dist/mcp/proxy-handshake.js

@@ -18,6 +18,16 @@ import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 /** The version we answer with if the client proposed none. */
 const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
+/**
+ * The protocol's own way to say "the tool list you have is out of date, fetch it again".
+ *
+ * Load-bearing here rather than a nicety. When we answer `initialize` ourselves the catalog we serve
+ * is one we made up, and it is usually empty. Nothing else in the protocol ever corrects that: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Without this the session is
+ * connected, initialized and toolless until a human notices.
+ */
+export const TOOLS_CHANGED_NOTIFICATION = 'notifications/tools/list_changed';
 function parseLine(line) {
     try {
         const parsed = JSON.parse(line);
@@ -32,7 +42,19 @@ export function isHandshakeLine(line) {
     const msg = parseLine(line);
     return 'initialize' === msg?.method || 'notifications/initialized' === msg?.method;
 }
-export function localInitializeResponse(line) {
+export function localInitializeResponse(line, 
+/**
+ * What the daemon would have advertised, so the client is not left with none.
+ *
+ * A client reads `instructions` ONCE, at initialize, and this response is sent precisely when no
+ * daemon is up to send its own — which is the first run of a fresh install. So the block telling
+ * someone that having these tools is not the same as being set up was permanently absent for the
+ * exact population it addresses, and the daemon's later correct instructions arrive at a client
+ * that will never read the field again.
+ *
+ * Empty means "nothing to say", and the field is then omitted rather than sent blank.
+ */
+instructions = '') {
     const msg = parseLine(line);
     if (null === msg || msg.method !== 'initialize')
         return null;
@@ -47,8 +69,93 @@ export function localInitializeResponse(line) {
             // Echo what the client asked for: answering with a version it did not offer is its own
             // handshake failure.
             protocolVersion: 'string' === typeof proposed ? proposed : FALLBACK_PROTOCOL_VERSION,
-            capabilities: { tools: {} },
+            // `listChanged` is not decoration: a client that was not told the list can change has no
+            // reason to honour the notification we send when the daemon finally arrives, and declaring a
+            // capability we then rely on is the difference between a fix and a message into the void.
+            capabilities: { tools: { listChanged: true } },
             serverInfo: { name: MCP_SERVER_NAME, version: SERVER_VERSION },
+            ...('' === instructions ? {} : { instructions }),
         },
     });
 }
+/**
+ * The line that tells a client its tool list is stale, or null when there is nothing to correct.
+ *
+ * When a daemon arrives after we answered the handshake ourselves, the client is holding a tool list
+ * we invented, and on a cold start that list is empty. Nothing else in this protocol corrects it: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Connected, initialized and
+ * toolless for the rest of the session, with a human required to notice and reconnect by hand.
+ *
+ * Sent only when the catalog was ours. A client that completed a real handshake with the daemon
+ * already has the true list, and telling it to refetch would be a round trip for nothing.
+ *
+ * Lives here rather than in the proxy because it belongs to the locally-answered handshake, which is
+ * this module's subject.
+ *
+ * Worth knowing before relying on it: this is a best-effort correction, not the mechanism. Research
+ * into the four clients we target found that only some honour `notifications/tools/list_changed` at
+ * all, so the catalog still has to be right in the FIRST answer for the rest. This closes the gap
+ * where it is honoured and costs one line where it is not.
+ */
+export function toolsChangedNotification(catalogWasLocal) {
+    if (!catalogWasLocal)
+        return null;
+    return JSON.stringify({ jsonrpc: '2.0', method: TOOLS_CHANGED_NOTIFICATION });
+}
+/**
+ * The largest single JSON-RPC line the proxy will accumulate from a client.
+ *
+ * Generous — a tool call with a big argument payload is legitimate — but finite, because without a
+ * ceiling the buffer grows to whatever is sent and the process is one `cat bigfile` away from an
+ * out-of-memory exit that would take the agent's whole tool surface with it.
+ */
+export const MAX_STDIN_LINE_BYTES = 16 * 1024 * 1024;
+/**
+ * Append a chunk and split off whatever complete lines it produced.
+ *
+ * The reason this is not `(buffer + chunk).split('\n')` inline: that re-scans the WHOLE accumulated
+ * buffer on every chunk, so a single large line costs O(n²) in the size of the line. Measured
+ * against the real proxy, a 32 MB line took ~8s and a 50 MB line ~35s — with the event loop pinned
+ * throughout, so every other tool call on that link was frozen with no response and no error. The
+ * client sees the whole MCP surface hang.
+ *
+ * A chunk with no newline in it cannot complete a line, so there is nothing to split and the cost is
+ * the concatenation alone. Only a chunk that actually carries a newline pays for a scan.
+ */
+export function drainLines(buffer, chunk, maxLineBytes = MAX_STDIN_LINE_BYTES, discarding = false) {
+    // Finish discarding first. Everything up to and including the next newline belongs to the line
+    // that was already dropped, and only what follows it is a message again.
+    if (discarding) {
+        const cut = chunk.indexOf('\n');
+        if (-1 === cut)
+            return { lines: [], rest: '', overflowed: true, discarding: true };
+        return {
+            ...drainLines('', chunk.slice(cut + 1), maxLineBytes),
+            overflowed: true,
+        };
+    }
+    const next = buffer + chunk;
+    if (!chunk.includes('\n')) {
+        // Nothing can be complete yet. Cap here rather than on the split path: this is the branch an
+        // oversized line stays on, so it is the only one that can grow without bound. Dropping the
+        // buffer is half the job — the rest of that line is still coming, hence `discarding`.
+        if (next.length > maxLineBytes) {
+            return { lines: [], rest: '', overflowed: true, discarding: true };
+        }
+        return { lines: [], rest: next, overflowed: false, discarding: false };
+    }
+    const parts = next.split('\n');
+    const rest = parts.pop() ?? '';
+    // A completed line over the cap is dropped, not truncated: half a JSON-RPC message is not a
+    // message, and forwarding a prefix would be a parse error attributed to the client. Its newline
+    // has already arrived, so there is nothing left to swallow for it.
+    const oversizedLine = parts.some((line) => line.length > maxLineBytes);
+    const restOversized = rest.length > maxLineBytes;
+    return {
+        lines: oversizedLine ? parts.filter((line) => line.length <= maxLineBytes) : parts,
+        rest: restOversized ? '' : rest,
+        overflowed: oversizedLine || restOversized,
+        discarding: restOversized,
+    };
+}

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

@@ -7,7 +7,7 @@
  * that crashed or was stopped used to take the agent's whole Reticle surface with it. Together they
  * loop: the daemon exits as useless, the proxy immediately brings back a daemon that is equally
  * useless, which exits, forever. Measured with a 4s grace: four processes in 200 seconds. At the
- * real 300s grace that is a new process every five minutes for the 74% of installs that never call a
+ * real 300s grace that is a new process every five minutes for the many installs that never call a
  * tool, for as long as the editor is open.
  *
  * The rule that resolves it: a dropped stream is not demand. Reattach to a daemon that is already
@@ -17,6 +17,7 @@
  * reach it — and a guard that re-implements the decision instead of calling it is insensitive to the
  * thing it claims to guard.
  */
+import { PortPresence } from '../daemon/port-presence.js';
 /** What to do when the SSE stream drops. */
 export declare const OnDrop: {
     /** A daemon is listening — reattach to it. */
@@ -28,8 +29,16 @@ export type OnDrop = (typeof OnDrop)[keyof typeof OnDrop];
 /**
  * A stream drop only ever justifies reattaching, never spawning. This is the whole fix: the proxy
  * used to spawn here, which turned a daemon's own idle shutdown into a permanent respawn loop.
+ *
+ * It takes the PRESENCE, not a boolean. It used to take `daemonListening`, filled from a bare TCP
+ * connect — a probe that cannot tell a Reticle daemon from anything else that accepts a socket. A
+ * stranger on the bridge port therefore read as "a daemon is there", and since a stranger answers
+ * and closes, every reattach dropped and reattached again: measured at nineteen reconnects in
+ * forty-eight seconds, each logged as `reticle_mcp_proxy_reconnected`, forever. `probePresence`
+ * already asks the second question and every human-facing command already uses it; this was the last
+ * decision point still guessing from the first.
  */
-export declare function onStreamDrop(daemonListening: boolean): OnDrop;
+export declare function onStreamDrop(presence: PortPresence): OnDrop;
 /**
  * What to do when the reconnect budget runs out. Always DORMANT — never exit.
  *

package/dist/mcp/proxy-lifecycle.js

@@ -7,7 +7,7 @@
  * that crashed or was stopped used to take the agent's whole Reticle surface with it. Together they
  * loop: the daemon exits as useless, the proxy immediately brings back a daemon that is equally
  * useless, which exits, forever. Measured with a 4s grace: four processes in 200 seconds. At the
- * real 300s grace that is a new process every five minutes for the 74% of installs that never call a
+ * real 300s grace that is a new process every five minutes for the many installs that never call a
  * tool, for as long as the editor is open.
  *
  * The rule that resolves it: a dropped stream is not demand. Reattach to a daemon that is already
@@ -17,6 +17,7 @@
  * reach it — and a guard that re-implements the decision instead of calling it is insensitive to the
  * thing it claims to guard.
  */
+import { PortPresence } from '../daemon/port-presence.js';
 /** What to do when the SSE stream drops. */
 export const OnDrop = {
     /** A daemon is listening — reattach to it. */
@@ -27,9 +28,17 @@ export const OnDrop = {
 /**
  * A stream drop only ever justifies reattaching, never spawning. This is the whole fix: the proxy
  * used to spawn here, which turned a daemon's own idle shutdown into a permanent respawn loop.
+ *
+ * It takes the PRESENCE, not a boolean. It used to take `daemonListening`, filled from a bare TCP
+ * connect — a probe that cannot tell a Reticle daemon from anything else that accepts a socket. A
+ * stranger on the bridge port therefore read as "a daemon is there", and since a stranger answers
+ * and closes, every reattach dropped and reattached again: measured at nineteen reconnects in
+ * forty-eight seconds, each logged as `reticle_mcp_proxy_reconnected`, forever. `probePresence`
+ * already asks the second question and every human-facing command already uses it; this was the last
+ * decision point still guessing from the first.
  */
-export function onStreamDrop(daemonListening) {
-    return daemonListening ? OnDrop.REATTACH : OnDrop.DORMANT;
+export function onStreamDrop(presence) {
+    return PortPresence.DAEMON === presence ? OnDrop.REATTACH : OnDrop.DORMANT;
 }
 /**
  * What to do when the reconnect budget runs out. Always DORMANT — never exit.

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

@@ -0,0 +1,63 @@
+/**
+ * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
+ *
+ * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
+ * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
+ * keep that file from becoming the largest thing on the user's disk.
+ */
+/**
+ * How much the proxy may append between size checks.
+ *
+ * Statting the file on every line would be a syscall per log line on a process that logs from a
+ * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
+ * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
+ */
+export declare const PROXY_LOG_CHECK_BYTES: number;
+/**
+ * Keep the proxy log under the same cap as the daemon log, without a stat per write.
+ *
+ * Returns the new "bytes since the last check" counter, so the accounting is testable without a
+ * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
+ * daemon log on the SAME machine stayed small, which is the whole of this defect.
+ */
+export declare function accountProxyLogWrite(bytesSinceCheck: number, written: number, path: string, deps: {
+    fileSize(p: string): number;
+    renameFile(from: string, to: string): void;
+}): number;
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
+ * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
+ * failure surfaced as the operating system refusing to write files. Files like that exist on real
+ * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
+ *
+ * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
+ * and a file that a running process still holds open keeps its blocks allocated after an unlink
+ * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
+ * and why that is the operation to copy here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
+ * housekeeping is strictly worse than a large file.
+ */
+export declare function recoverOversizedProxyLog(path: string, deps: {
+    fileSize(p: string): number;
+    truncateFile(p: string): void;
+}, max?: number): number;
+/** Name the proxy log after the port it serves. Called before anything can log. */
+export declare function setProxyLogPort(port: number): void;
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export declare function proxyLogPath(port?: number | undefined): string;
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
+ * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
+ * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
+ *
+ * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
+ * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
+ * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
+ * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
+ * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
+ * existed, and the one path that most needed it was not using it.
+ */
+export declare function proxyLog(event: string, fields?: Record<string, unknown>): void;

package/dist/mcp/proxy-log.js

@@ -0,0 +1,132 @@
+/**
+ * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
+ *
+ * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
+ * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
+ * keep that file from becoming the largest thing on the user's disk.
+ */
+import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { log } from '../log.js';
+import { MAX_DAEMON_LOG_BYTES, rotateDaemonLog } from '../daemon/daemon.js';
+/**
+ * Which port this proxy serves, for the log file name. Set once at startup.
+ *
+ * One file per port, matching `daemon-<port>.log`. A single shared file interleaved every proxy on
+ * the machine into one stream, so the first question anyone asks of it — "what happened to MY
+ * session?" — needed a filter before it could be answered.
+ */
+let logPort;
+/**
+ * How much the proxy may append between size checks.
+ *
+ * Statting the file on every line would be a syscall per log line on a process that logs from a
+ * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
+ * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
+ */
+export const PROXY_LOG_CHECK_BYTES = 256 * 1024;
+/** Appended since the last real size check. Reset by every check, whatever the check decides. */
+let bytesSinceProxyLogCheck = 0;
+/**
+ * Keep the proxy log under the same cap as the daemon log, without a stat per write.
+ *
+ * Returns the new "bytes since the last check" counter, so the accounting is testable without a
+ * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
+ * daemon log on the SAME machine stayed small, which is the whole of this defect.
+ */
+export function accountProxyLogWrite(bytesSinceCheck, written, path, deps) {
+    const total = bytesSinceCheck + written;
+    if (PROXY_LOG_CHECK_BYTES > total)
+        return total;
+    rotateDaemonLog(path, deps);
+    return 0;
+}
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
+ * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
+ * failure surfaced as the operating system refusing to write files. Files like that exist on real
+ * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
+ *
+ * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
+ * and a file that a running process still holds open keeps its blocks allocated after an unlink
+ * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
+ * and why that is the operation to copy here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
+ * housekeeping is strictly worse than a large file.
+ */
+export function recoverOversizedProxyLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        const size = deps.fileSize(path);
+        if (max >= size)
+            return 0;
+        deps.truncateFile(path);
+        return size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** The real filesystem behind the two rotation helpers. */
+const proxyLogFileOps = {
+    fileSize: (p) => statSync(p).size,
+    renameFile: (from, to) => renameSync(from, to),
+    truncateFile: (p) => truncateSync(p, 0),
+};
+/** Name the proxy log after the port it serves. Called before anything can log. */
+export function setProxyLogPort(port) {
+    logPort = port;
+    // The one moment we know a size check is worth its syscall, and the only place a file inherited
+    // from an older build can be brought back under control.
+    const reclaimed = recoverOversizedProxyLog(proxyLogPath(port), proxyLogFileOps);
+    if (0 < reclaimed) {
+        proxyLog('reticle_mcp_proxy_log_truncated', {
+            port,
+            reclaimedBytes: reclaimed,
+            note: 'the proxy log had grown past its cap and was truncated in place to reclaim the space',
+        });
+    }
+}
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export function proxyLogPath(port = logPort) {
+    const name = port === undefined ? 'mcp-proxy.log' : `proxy-${String(port)}.log`;
+    return join(homedir(), ReticleDir.ROOT, name);
+}
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
+ * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
+ * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
+ *
+ * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
+ * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
+ * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
+ * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
+ * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
+ * existed, and the one path that most needed it was not using it.
+ */
+export function proxyLog(event, fields = {}) {
+    log(event, fields);
+    try {
+        const dir = join(homedir(), ReticleDir.ROOT);
+        mkdirSync(dir, { recursive: true });
+        // WITH A TIMESTAMP. This file is the only record of an outage that survives the session, and
+        // without one it cannot answer the two questions anyone brings to it: when did this happen, and
+        // how often. A real 3,283-line log on a dev machine held a `gave_up` — the exact event that used
+        // to precede `process.exit(1)` and cost the human a manual /mcp reconnect — and it was
+        // impossible to tell whether it happened during that person's work or a test run hours earlier.
+        // Evidence you cannot place in time is an anecdote.
+        const path = proxyLogPath();
+        const line = `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`;
+        appendFileSync(path, line, 'utf8');
+        // A single proxy process is long-lived and logs from a reconnect loop, so rotating only at
+        // startup would leave the growth this file is capable of entirely unchecked while it runs.
+        bytesSinceProxyLogCheck = accountProxyLogWrite(bytesSinceProxyLogCheck, Buffer.byteLength(line, 'utf8'), path, proxyLogFileOps);
+    }
+    catch {
+        // Logging must never be the thing that kills the proxy.
+    }
+}