@reticlehq/server 2.8.0 → 2.10.0

package/dist/mcp/mcp.js

@@ -2,20 +2,22 @@ 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 { isToonable, resultToToon } from '@reticlehq/core';
+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';
+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';
 import { log } from '../log.js';
 import { SERVER_VERSION } from '../version/server-version.js';
-import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { parsePredicate } from '../events/predicate-parse.js';
@@ -31,27 +33,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 +125,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 +153,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;
     }
@@ -207,11 +200,24 @@ export function encodeResult(result, encoding) {
  * "Call reticle_tools { names: [...] } for its parameters" — leaving it out made our own advice a
  * dead end on the one surface that advertises everything.
  */
-export function advertisedTools(surface) {
+export function advertisedTools(surface, 
+/**
+ * The full table to advertise from. Defaults to what this package ships.
+ *
+ * A consumer embedding the engine passes its own composition — ours plus its own — so its tools
+ * reach the wire without editing the shipped array.
+ */
+tools = TOOLS) {
     // The catalog reports which surface is live and what chose it — the only way an agent can see that
     // a setting did not take (the daemon read the value it started with).
     const origin = describeToolSurface(surface);
-    return [...filterTools(TOOLS, surface), ...buildDynamicTools(TOOLS, origin)];
+    // The profile trims OUR table only. A tool this package does not ship was appended deliberately by
+    // whoever is embedding us, and our `CORE_TOOL_NAMES` was never going to contain its name — so
+    // filtering it would drop every consumer tool and look exactly like the feature not working.
+    const shipped = new Set(TOOLS.map((tool) => tool.name));
+    const ours = tools.filter((tool) => shipped.has(tool.name));
+    const theirs = tools.filter((tool) => !shipped.has(tool.name));
+    return [...filterTools([...ours], surface), ...theirs, ...buildDynamicTools([...tools], origin)];
 }
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
@@ -228,10 +234,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,13 +367,33 @@ 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, 
+/**
+ * The full tool table this server serves. Defaults to what this package ships.
+ *
+ * Threaded rather than read from the module so a consumer can serve its own tools on one surface
+ * with ours. It reaches all three places that need the WHOLE table and not just the advertised
+ * slice: the profile filter, the `reticle_run` hatch, and the unadvertised-tool help — a consumer
+ * tool missing from either of the last two is a tool the agent is actively told does not exist.
+ */
+tools = TOOLS) {
     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 });
+    const server = new McpServer(SERVER_INFO, {
+        instructions: buildServerInstructions({ previouslyConnected }),
+    });
     /**
      * Record WHICH agent attached, at the handshake, for every session.
      *
@@ -392,13 +433,13 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
     // 11 tools were unreachable with no escape hatch — including reticle_annotate, which
     // reticle_flow_save's own description instructs the agent to call. `full` advertises everything
     // directly and needs no hatch.
-    const advertised = advertisedTools(profile);
+    const advertised = advertisedTools(profile, tools);
     installFriendlyArgErrors(server, new Map(advertised
         .filter((tool) => tool.example !== undefined)
         .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
-    // Every tool in TOOLS, 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))])));
+    // 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))])));
     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.
@@ -460,6 +501,6 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
     // `tools/call` dispatcher lazily on the FIRST registerTool, so wrapping before this point finds
     // nothing to wrap and silently does nothing. Verified live rather than assumed — the first attempt
     // sat here doing exactly that.
-    installUnadvertisedToolHelp(server, new Set(advertised.map((tool) => tool.name)), new Set(TOOLS.map((tool) => tool.name)));
+    installUnadvertisedToolHelp(server, new Set(advertised.map((tool) => tool.name)), new Set(tools.map((tool) => tool.name)));
     return server;
 }

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

@@ -0,0 +1,8 @@
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export declare function probeDaemon(port: number): Promise<boolean>;
+/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
+export declare function waitForDaemon(port: number): Promise<void>;

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

@@ -0,0 +1,48 @@
+import * as net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
+/**
+ * How long to wait for the spawned daemon's port to accept connections before giving up. The default
+ * suits a normal machine; a slow CI/VM (heavy headless-browser launch) can raise it via the
+ * RETICLE_DAEMON_READY_TIMEOUT_MS env var. Invalid/absent values fall back to the default.
+ */
+const envDaemonReadyTimeoutMs = Number(process.env['RETICLE_DAEMON_READY_TIMEOUT_MS']);
+const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envDaemonReadyTimeoutMs > 0
+    ? envDaemonReadyTimeoutMs
+    : DEFAULT_DAEMON_READY_TIMEOUT_MS;
+const DAEMON_POLL_INTERVAL_MS = 100;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export function probeDaemon(port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(500);
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, LOOPBACK_HOST);
+    });
+}
+/** Poll until 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;
+    while (Date.now() < deadline) {
+        const reachable = await probeDaemon(port);
+        if (reachable)
+            return;
+        await delay(DAEMON_POLL_INTERVAL_MS);
+    }
+    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

@@ -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

@@ -14,10 +14,20 @@
  * Safe because the proxy replays the client's own `initialize` to the daemon whenever a session is
  * finally established (see `replayLines`), so the daemon still gets its handshake in order.
  */
-import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { SERVER_VERSION } from '../version/server-version.js';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
 /** The version we answer with if the client proposed none. */
 const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
+/**
+ * The protocol's own way to say "the tool list you have is out of date, fetch it again".
+ *
+ * Load-bearing here rather than a nicety. When we answer `initialize` ourselves the catalog we serve
+ * is one we made up, and it is usually empty. Nothing else in the protocol ever corrects that: a
+ * client re-lists only when told to, and every other recovery path in the proxy is driven by the
+ * NEXT client request, which a client holding no tools never makes. Without this the session is
+ * connected, initialized and toolless until a human notices.
+ */
+export const TOOLS_CHANGED_NOTIFICATION = 'notifications/tools/list_changed';
 function parseLine(line) {
     try {
         const parsed = JSON.parse(line);
@@ -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

@@ -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

@@ -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;