@reticlehq/server 2.8.0 → 2.10.0

package/dist/mcp/mcp-proxy.js

@@ -1,31 +1,34 @@
 import * as http from 'node:http';
-import { localInitializeResponse, isHandshakeLine } from './proxy-handshake.js';
+import { localInitializeResponse, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
 import { ToolCatalogCache } from './tool-catalog-cache.js';
-import * as net from 'node:net';
-import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleDir, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
+import { toolsChangedNotification } from './proxy-handshake.js';
+import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
+import { SseFrameParser } from './sse-frame-parser.js';
+export { SseFrameParser } from './sse-frame-parser.js';
+export { probeDaemon, waitForDaemon } from './proxy-daemon-probe.js';
+import { probeDaemon } from './proxy-daemon-probe.js';
 import { SERVER_VERSION } from '../version/server-version.js';
+import { buildServerInstructions } from './server-instructions.js';
+import { hasProjectConnectedBefore } from '../session/connection-memory.js';
+import { reticleStateHome } from '../daemon/daemon.js';
+import { readProjectId } from '../cli/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy-lifecycle.js';
-import { log } from '../log.js';
-import { MAX_DAEMON_LOG_BYTES, rotateDaemonLog } from '../daemon/daemon.js';
-import { OutageStage, reportMcpOutage } from './mcp-outage.js';
-const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
+import { describePresence, probePresence } from '../daemon/port-presence.js';
 /**
- * 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.
+ * The same `/status` probe `doctor`, `status` and `kill` ask with. Reused rather than re-written:
+ * the whole defect this import closes was the proxy answering a DIFFERENT question from every other
+ * surface, and a second copy of the probe is how that comes back.
  */
-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));
-}
+import { fetchStatus as fetchDaemonStatus } from '../cli/cli-launch.js';
+/**
+ * Re-exported so every existing caller (and every spec) keeps importing the proxy's log from the
+ * proxy. Where the code lives is a file-size decision; where it is imported from is an API.
+ */
+export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy-log.js';
+import { proxyLog } from './proxy-log.js';
+import { log } from '../log.js';
+import { OutageReason, OutageStage, reportMcpOutage } from './mcp-outage.js';
 /** Reconnect backoff: linear, capped, so a briefly-restarting daemon is picked up fast. */
 const RECONNECT_BASE_MS = 250;
 const RECONNECT_CAP_MS = 5_000;
@@ -52,125 +55,6 @@ export function reconnectDelayMs(attempt) {
 }
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export const RECONNECT_INITIALIZE_ID = '__reticle_proxy_reinit';
-/**
- * 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.
-    }
-}
 function parseJsonRpc(line) {
     try {
         const parsed = JSON.parse(line);
@@ -369,79 +253,6 @@ export class HandshakeReplay {
         return true;
     }
 }
-/**
- * Incremental SSE frame parser for the MCP front door.
- *
- * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
- * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
- * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
- * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
- * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
- * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
- */
-export class SseFrameParser {
-    #buffer = '';
-    #event = '';
-    #data = '';
-    push(chunk) {
-        this.#buffer += chunk;
-        // Normalise CRLF/CR so the splitter only handles \n, then hold the trailing partial line for the
-        // next chunk (it may complete later).
-        const normalised = this.#buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-        const lines = normalised.split('\n');
-        this.#buffer = lines.pop() ?? '';
-        const frames = [];
-        for (const line of lines) {
-            if ('' === line) {
-                if (this.#data !== '') {
-                    frames.push({ event: this.#event !== '' ? this.#event : 'message', data: this.#data });
-                }
-                this.#event = '';
-                this.#data = '';
-            }
-            else if (line.startsWith('event:')) {
-                this.#event = line.slice(6).trim();
-            }
-            else if (line.startsWith('data:')) {
-                const val = line.slice(5).trim();
-                this.#data = this.#data !== '' ? `${this.#data}\n${val}` : val;
-            }
-        }
-        return frames;
-    }
-}
-/**
- * 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`);
-}
 /**
  * POST one JSON-RPC line into the daemon's session. Resolves null on success, or a short reason
  * when the request never reached a server that will answer it.
@@ -510,6 +321,24 @@ export function buildSessionUrl(rawData, port) {
  * `/mcp` could. The daemon demonstrably stays up across these drops, so the stream ending is a
  * transport event, not a shutdown: reconnect to it and replay the handshake instead of dying.
  */
+/**
+ * The instructions this proxy should advertise when it answers the handshake itself.
+ *
+ * Same inputs the daemon uses, read from the same durable memory, so a client that happens to meet
+ * the proxy first is not told something different from one that meets the daemon first. Best-effort:
+ * an unreadable state home must never be the reason a handshake fails, so it degrades to the
+ * fresh-install wording rather than throwing.
+ */
+function proxyInstructions(port) {
+    try {
+        return buildServerInstructions({
+            previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd())),
+        });
+    }
+    catch {
+        return buildServerInstructions({ previouslyConnected: false });
+    }
+}
 export function startMcpProxy(port, 
 /**
  * Bring a daemon back before reconnecting. Without it the proxy retried a DEAD port until the
@@ -531,6 +360,16 @@ ensureDaemon) {
          * Dormant means the next thing the CLIENT asks for is what brings Reticle back.
          */
         let dormant = false;
+        /**
+         * Deliver the proxy's own answer to a queued `initialize`, now, for a stated reason.
+         *
+         * Set by `armLocalHandshake` while the client's handshake is unanswered, and cleared once it is.
+         * It exists because the 12-second timer down there is a timeout for a question the proxy could
+         * not answer — "is a daemon coming?" — and the drop path CAN answer it: a port a stranger holds
+         * will never serve SSE, however long anybody waits. Declared up here with the other closure
+         * state so the drop path can reach it without a temporal-dead-zone hazard.
+         */
+        let deliverHandshakeLocally;
         const stdinQueue = [];
         /**
          * Fail anything still queued after QUEUE_WAIT_MS. Re-armed on every push and cleared on flush,
@@ -542,29 +381,42 @@ ensureDaemon) {
                 clearTimeout(queueTimer);
             queueTimer = undefined;
         };
+        /**
+         * Answer everything queued, drop it, and go dormant.
+         *
+         * `reason` is what goes on the wire. The timer below passes the only thing a timeout can know —
+         * that nothing arrived — but a wake that FAILED knows something much better: exactly why it
+         * failed. Both used to end here after the same twenty seconds of silence, because only the timer
+         * could reach this code.
+         */
+        const expireQueue = (reason) => {
+            clearQueueTimer();
+            if (stopped || 0 === stdinQueue.length)
+                return;
+            // Drop what we could never send, and answer it, so the caller is never left guessing.
+            stdinQueue.splice(0);
+            for (const reply of streamLossReplies(pending, reason, queueExpiryNextStep(port))) {
+                emit(reply);
+            }
+            // The expiry is the proof that the reconnect we believed was in flight is not coming — a
+            // wedged port accepts the socket and never serves SSE, so `connect` neither resolves nor
+            // rejects and `dormant` would otherwise stay false forever. Going dormant is what makes the
+            // NEXT request re-probe the port instead of queueing behind a reconnect that will never
+            // land, and it is the only path by which a daemon started AFTER we gave up is ever found.
+            dormant = onQueueExpired() === OnDrop.DORMANT;
+            proxyLog('reticle_mcp_proxy_queue_expired', {
+                port,
+                dormant,
+                reason,
+                note: 'answered queued requests and went dormant; the next client request re-probes the port',
+            });
+        };
         const armQueueTimer = () => {
             if (queueTimer !== undefined)
                 return; // the oldest entry owns the deadline
             queueTimer = setTimeout(() => {
                 queueTimer = undefined;
-                if (stopped || 0 === stdinQueue.length)
-                    return;
-                // Drop what we could never send, and answer it, so the caller is never left guessing.
-                stdinQueue.splice(0);
-                for (const reply of streamLossReplies(pending, 'no daemon could be reached', queueExpiryNextStep(port))) {
-                    emit(reply);
-                }
-                // The expiry is the proof that the reconnect we believed was in flight is not coming — a
-                // wedged port accepts the socket and never serves SSE, so `connect` neither resolves nor
-                // rejects and `dormant` would otherwise stay false forever. Going dormant is what makes the
-                // NEXT request re-probe the port instead of queueing behind a reconnect that will never
-                // land, and it is the only path by which a daemon started AFTER we gave up is ever found.
-                dormant = onQueueExpired() === OnDrop.DORMANT;
-                proxyLog('reticle_mcp_proxy_queue_expired', {
-                    port,
-                    dormant,
-                    note: 'answered queued requests and went dormant; the next client request re-probes the port',
-                });
+                expireQueue('no daemon could be reached');
             }, QUEUE_WAIT_MS);
             queueTimer.unref();
         };
@@ -577,6 +429,10 @@ ensureDaemon) {
         };
         let stopped = false;
         let attempts = 0;
+        /** The daemon announced a planned shutdown; the next drop is that, not a fault. */
+        let daemonRetiring = false;
+        /** Why the stream we are currently trying to replace went away — carried onto the recovery. */
+        let lastDropReason = OutageReason.OTHER;
         /**
          * When the proxy started, and how many times the first connect has been refused since.
          *
@@ -623,6 +479,10 @@ ensureDaemon) {
                 // headers, is what earns a fresh retry budget. Resetting on headers let a daemon that
                 // accepts SSE and drops it spin the reconnect loop at the 250ms floor forever, never backing
                 // off and never reaching the budget that puts the proxy dormant. Measured: 32 retries in 8s.
+                // Report the recovery BEFORE the counter is cleared: `attempts` is what coming back actually
+                // cost, and it is the only number that can falsify the drop event. See OutageStage.RECOVERED.
+                if (attempts > 0)
+                    reportMcpOutage(OutageStage.RECOVERED, { reason: lastDropReason, attempts });
                 attempts = 0;
                 // The new session's McpServer has never seen the client's initialize — replay it first, then
                 // flush whatever the client sent while we were reconnecting.
@@ -631,9 +491,26 @@ ensureDaemon) {
                 clearQueueTimer();
                 for (const queued of stdinQueue.splice(0))
                     forward(url, queued);
+                // The client may be holding a tool list we invented. See toolsChangedNotification.
+                const relist = toolsChangedNotification(toolsAnnouncedLocally);
+                if (relist !== null) {
+                    toolsAnnouncedLocally = false;
+                    emit(relist);
+                    proxyLog('reticle_mcp_proxy_tools_relisted', { port });
+                }
                 handshakeAnswered = true;
                 return;
             }
+            // The daemon telling us it is retiring. Not forwarded: it is addressed to this proxy, and the
+            // client behind it has no use for a frame it cannot parse.
+            if (MCP_SHUTDOWN_EVENT === event) {
+                daemonRetiring = true;
+                proxyLog('reticle_mcp_proxy_daemon_retiring', {
+                    port,
+                    note: 'the daemon announced a planned shutdown; the drop that follows is not an outage',
+                });
+                return;
+            }
             if ('message' === event && !replay.shouldSuppressInbound(data)) {
                 // Remember the tool catalog as it goes past: it is what makes a locally-answered handshake
                 // useful rather than toolless. See tool-catalog-cache.
@@ -641,10 +518,16 @@ ensureDaemon) {
                 emit(data);
             }
         }
-        function scheduleReconnect(reason, detail) {
+        function scheduleReconnect(rawReason, detail) {
             if (stopped)
                 return;
             postUrl = null;
+            // A stream the daemon warned us about is a planned shutdown, not a fault. The socket looks
+            // identical either way from here, so this flag is the only thing that can tell them apart —
+            // and without it every scheduled retirement was counted as an outage the agent suffered.
+            const reason = daemonRetiring ? OutageReason.DAEMON_SHUTDOWN : rawReason;
+            daemonRetiring = false;
+            lastDropReason = reason;
             attempts++;
             // Everything the dead session owed is settled HERE, in the one place every drop funnels
             // through, and not in the response callback that first noticed the socket die. A reset emits
@@ -695,16 +578,22 @@ ensureDaemon) {
                 // shut itself down as idle would be respawned instantly, sit unused, shut down again, and
                 // loop forever — measured at four processes in 200s before this. If nothing is listening the
                 // proxy goes DORMANT and the next client request brings a daemon back (see the stdin reader).
-                void probeDaemon(port).then((listening) => {
-                    if (onStreamDrop(listening) === OnDrop.REATTACH) {
+                void probePresence(port, { tcpOpen: probeDaemon, status: fetchDaemonStatus }).then((presence) => {
+                    if (onStreamDrop(presence) === OnDrop.REATTACH) {
                         connect(false);
                         return;
                     }
                     dormant = true;
-                    proxyLog('reticle_mcp_proxy_dormant', {
-                        port,
-                        note: 'no daemon listening; will start one when the client next sends a request',
-                    });
+                    // The sentence `doctor` has always been able to say, in the log the agent's own process
+                    // writes. A FOREIGN holder used to be indistinguishable from a free port here, and the
+                    // proxy spun against it instead of saying which one it was.
+                    const sentence = describePresence(presence, port);
+                    proxyLog('reticle_mcp_proxy_dormant', { port, presence, note: sentence });
+                    // Nothing is coming that could answer the client's handshake through this port, and the
+                    // proxy now knows that rather than merely suspecting it. Waiting out LOCAL_HANDSHAKE_MS
+                    // would be waiting for information already in hand — and #125 measured what that costs:
+                    // a client whose initialize budget is under ~12s loses Reticle for the whole session.
+                    deliverHandshakeLocally?.(sentence);
                 });
             }, wait).unref();
         }
@@ -797,6 +686,14 @@ ensureDaemon) {
         // ── stdin reader ─────────────────────────────────────────────────────────
         process.stdin.setEncoding('utf8');
         let handshakeAnswered = false;
+        /**
+         * True while the client is holding a tool list WE made up rather than one the daemon sent.
+         *
+         * Set when we answer `initialize` locally, cleared the moment we tell the client to re-list. It
+         * is not the same question as `handshakeAnswered`, which is also true after a real daemon
+         * handshake — and a client that already has the daemon's catalog must not be sent chasing it.
+         */
+        let toolsAnnouncedLocally = false;
         /**
          * Answer a queued `initialize` locally if the daemon has not produced an endpoint in time.
          *
@@ -807,13 +704,33 @@ ensureDaemon) {
         const armLocalHandshake = (line) => {
             if (handshakeAnswered)
                 return;
-            const response = localInitializeResponse(line);
+            // Ask the same question the daemon would, from the same durable memory, so the client gets
+            // the same answer it would have got had a daemon been up to give it.
+            const response = localInitializeResponse(line, proxyInstructions(port));
             if (null === response)
                 return;
-            setTimeout(() => {
+            // Take the debt NOW, not when the timer fires.
+            //
+            // Three paths can answer this id — the daemon, the stream-loss drain, and the timer below —
+            // and `take` is the coordination between them. This was the one answerer that never claimed,
+            // so a drop before the timer fired paid the handshake a -32001 and the timer then paid it a
+            // result, under the same id. Both halves are fatal: a client that gets an error for
+            // `initialize` marks the whole MCP server failed, and one that survives that sees two
+            // responses for one request. Claiming it here says out loud what has always been true — the
+            // proxy owns this answer and will deliver it — so the drain stops owing it. If a session is
+            // established first, the `endpoint` handler sets `handshakeAnswered` before the queue is
+            // flushed, which disarms the timer and leaves the daemon's own reply the only one.
+            const claimed = parseJsonRpc(line);
+            if (claimed?.id !== undefined)
+                pending.take(claimed.id);
+            deliverHandshakeLocally = (reason) => {
                 if (handshakeAnswered || postUrl !== null)
                     return;
                 handshakeAnswered = true;
+                deliverHandshakeLocally = undefined;
+                // The catalog we are about to serve is ours, not the daemon's, so it has to be corrected
+                // the moment a real one exists. See the endpoint handler.
+                toolsAnnouncedLocally = true;
                 // Drop the handshake from the queue. Otherwise the daemon, whenever it finally arrives,
                 // answers the SAME id a second time and the client sees two responses to one request — a
                 // corrupted stream, which is worse than the hang this replaces. The daemon still gets its own
@@ -823,16 +740,28 @@ ensureDaemon) {
                     if (queued !== undefined && isHandshakeLine(queued))
                         stdinQueue.splice(i, 1);
                 }
-                proxyLog('reticle_mcp_local_handshake', { port, reason: 'daemon did not answer in time' });
+                proxyLog('reticle_mcp_local_handshake', { port, reason });
                 emit(response);
-            }, LOCAL_HANDSHAKE_MS).unref();
+            };
+            setTimeout(() => deliverHandshakeLocally?.('daemon did not answer in time'), LOCAL_HANDSHAKE_MS).unref();
         };
         let stdinBuffer = '';
+        let stdinDiscarding = false;
         process.stdin.on('data', (chunk) => {
-            stdinBuffer += chunk;
-            const lines = stdinBuffer.split('\n');
-            stdinBuffer = lines.pop() ?? '';
-            for (const line of lines) {
+            // Not `(buffer + chunk).split()` inline — that rescans everything held on every chunk, so one
+            // large line cost O(n²) in its own size and pinned the event loop for tens of seconds, during
+            // which every other tool call on this link hung with no response and no error. See drainLines.
+            const drained = drainLines(stdinBuffer, chunk, MAX_STDIN_LINE_BYTES, stdinDiscarding);
+            stdinBuffer = drained.rest;
+            // Carried across chunks: an oversized line is dropped, and the REST of it is still arriving.
+            // Without this its tail reads as a complete line and gets forwarded as a message nobody sent.
+            stdinDiscarding = drained.discarding;
+            if (drained.overflowed) {
+                // Logged rather than answered: an unparsed line has no id to answer against, and inventing
+                // one would put a reply on the wire that no request is waiting for.
+                proxyLog('mcp_stdin_line_too_large', { limitBytes: MAX_STDIN_LINE_BYTES });
+            }
+            for (const line of drained.lines) {
                 const trimmed = line.trim();
                 if ('' === trimmed)
                     continue;
@@ -869,10 +798,14 @@ ensureDaemon) {
                         .then(() => connect(false))
                         .catch((err) => {
                         dormant = true;
-                        proxyLog('reticle_mcp_proxy_wake_failed', {
-                            port,
-                            error: err instanceof Error ? err.message : String(err),
-                        });
+                        const reason = err instanceof Error ? err.message : String(err);
+                        proxyLog('reticle_mcp_proxy_wake_failed', { port, error: reason });
+                        // The wake is the only thing that can start a daemon, so its failure IS the answer to
+                        // everything it was woken for. It used to be logged and nothing else: the request sat
+                        // out the full QUEUE_WAIT_MS and was then refused by a timer that could only say "no
+                        // daemon could be reached" — twenty seconds later, and less true, than the sentence
+                        // already in hand.
+                        expireQueue(reason);
                     });
                 }
             }

package/dist/mcp/mcp.d.ts

@@ -35,7 +35,14 @@ export declare function encodeResult(result: unknown, encoding: string): string;
  * "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 declare function advertisedTools(surface: ToolSurface): ToolDef[];
+export declare function advertisedTools(surface: ToolSurface, 
+/**
+ * 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?: readonly ToolDef[]): ToolDef[];
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
  * and (non-lean only) the output schema.
@@ -50,4 +57,22 @@ export declare function advertisedConfig(tool: ToolDef, advertised: readonly Too
     outputSchema?: z.ZodRawShape;
 };
 export declare function installFriendlyArgErrors(server: McpServer, examples: Map<string, string>, allowedKeys?: Map<string, ReadonlySet<string>>): void;
-export declare function createMcpServer(deps: ToolDeps, profile?: ToolSurface): McpServer;
+export declare function createMcpServer(deps: ToolDeps, profile?: ToolSurface, 
+/**
+ * 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?: boolean, 
+/**
+ * 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?: readonly ToolDef[]): McpServer;