@reticlehq/server 2.7.0 → 2.9.0

package/dist/mcp/mcp-proxy.js

@@ -1,16 +1,31 @@
 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 { toolsChangedNotification } from './proxy-handshake.js';
 import * as net from 'node:net';
-import { appendFileSync, mkdirSync } 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 { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 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 { describePresence, probePresence } from '../daemon/port-presence.js';
+/**
+ * The same `/status` probe `doctor`, `status` and `kill` ask with. Reused rather than re-written:
+ * the whole defect this import closes was the proxy answering a DIFFERENT question from every other
+ * surface, and a second copy of the probe is how that comes back.
+ */
+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 { OutageStage, reportMcpOutage } from './mcp-outage.js';
+import { OutageReason, OutageStage, reportMcpOutage } from './mcp-outage.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
 /**
  * How long to wait for the spawned daemon's port to accept connections before giving up. The default
@@ -51,52 +66,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;
-/** Name the proxy log after the port it serves. Called before anything can log. */
-export function setProxyLogPort(port) {
-    logPort = port;
-}
-/** 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.
-        appendFileSync(proxyLogPath(), `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`, 'utf8');
-    }
-    catch {
-        // Logging must never be the thing that kills the proxy.
-    }
-}
 function parseJsonRpc(line) {
     try {
         const parsed = JSON.parse(line);
@@ -166,8 +135,10 @@ export class PendingRequests {
  * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
-export function streamLossReplies(pending, reason) {
-    return pending.drain().map((id) => transportLossReply(JSON.parse(id), reason));
+export function streamLossReplies(pending, reason, nextStep) {
+    return pending
+        .drain()
+        .map((id) => transportLossReply(JSON.parse(id), reason, nextStep));
 }
 /**
  * -32001: a server-defined error. Not -32603 (internal): nothing went wrong INSIDE the call, the
@@ -175,15 +146,21 @@ export function streamLossReplies(pending, reason) {
  * to retry.
  */
 const TRANSPORT_LOSS_CODE = -32001;
-/** The one shape every "the transport ate your call" answer takes, whichever leg died. */
-export function transportLossReply(id, reason) {
+/**
+ * The one shape every "the transport ate your call" answer takes, whichever leg died.
+ *
+ * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
+ * stops there, which is all a first-run user got out of their first ever tool call.
+ */
+export function transportLossReply(id, reason, nextStep) {
     return JSON.stringify({
         jsonrpc: '2.0',
         id,
         error: {
             code: TRANSPORT_LOSS_CODE,
             message: `the daemon connection dropped (${reason}) before this call was answered — it did NOT ` +
-                'complete. Reticle is recovering the connection; retry if the action is safe to repeat.',
+                'complete. Reticle is recovering the connection; retry if the action is safe to repeat.' +
+                (nextStep === undefined ? '' : ` ${nextStep}`),
         },
     });
 }
@@ -207,8 +184,38 @@ const SHUTDOWN_DRAIN_MS = 5_000;
  * well under the 60s an MCP client typically allows, so the answer comes from us with a reason
  * rather than from their timer with none.
  */
-const QUEUE_WAIT_MS = 20_000;
+export const QUEUE_WAIT_MS = 20_000;
 const SHUTDOWN_DRAIN_POLL_MS = 25;
+/** A port that refuses is a port nothing is listening on YET — not a port that answered badly. */
+const CONNECTION_REFUSED = 'ECONNREFUSED';
+/**
+ * How long the FIRST connect keeps chasing a refused port before calling it a startup failure.
+ *
+ * It used to get exactly one attempt. Reported from a Windows first bootstrap: the daemon was still
+ * booting, the single connect was refused, and nothing tried again — only a fresh CLIENT request
+ * re-probes the port, and the client was already blocked on the call that then expired with -32001.
+ * The first tool call of somebody's first ever session is the worst place available to lose one.
+ *
+ * Deliberately longer than QUEUE_WAIT_MS: a retry that stops before the queue does cannot rescue the
+ * request it exists for, and a daemon found afterwards at least restores service for the next call.
+ */
+const FIRST_CONNECT_WINDOW_MS = QUEUE_WAIT_MS + 15_000;
+/** Retry a first connect, or report it? Pure, so the window can be held against the queue's. */
+export function shouldRetryFirstConnect(error, elapsedMs) {
+    const code = error?.code;
+    return CONNECTION_REFUSED === code && FIRST_CONNECT_WINDOW_MS > elapsedMs;
+}
+/**
+ * What to do about it, carried on the reply the queue expiry sends.
+ *
+ * A bare -32001 on the first call after an install says nothing a user can act on: not whether to
+ * wait, not whether to retry, not whether the install itself is broken.
+ */
+export function queueExpiryNextStep(port) {
+    return (`No Reticle daemon answered on port ${String(port)}. Retry the call — the next request starts ` +
+        'one. If it keeps failing, run `reticle doctor` in a terminal: it reports what is holding the ' +
+        'port and whether the daemon can start at all.');
+}
 /**
  * Makes a reconnect invisible to the client.
  *
@@ -398,6 +405,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
@@ -419,6 +444,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,
@@ -430,28 +465,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'))
-                    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();
         };
@@ -464,6 +513,19 @@ 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.
+         *
+         * The clock is read at this boundary rather than injected, matching the shutdown drain below:
+         * it measures how long a real daemon has had to boot, which is a wall-clock fact about the
+         * machine and not a decision the caller could supply.
+         */
+        const startedAt = Date.now();
+        let firstConnectAttempts = 0;
         /**
          * The ONE way a line leaves for the daemon — so a POST that never lands still owes an answer.
          *
@@ -501,6 +563,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.
@@ -509,6 +575,24 @@ 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)) {
@@ -518,11 +602,33 @@ ensureDaemon) {
                 emit(data);
             }
         }
-        function scheduleReconnect(reason, detail, pendingLost = 0) {
+        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
+            // on BOTH halves of the request, so whichever handler wins decides what gets paid — the same
+            // shape as the reconnect fan-out, and it left the other half paying nothing.
+            //
+            // Order matters between the two. Drain the queue FIRST: a queued request is tracked in
+            // `pending` as well, so answering without draining leaves the next `endpoint` frame free to
+            // flush it into the fresh session, where the daemon answers the same id a second time and the
+            // client sees two responses for one request. Then answer, because the new session cannot know
+            // what the old one owed and silence here is permanent.
+            stdinQueue.splice(0);
+            const lost = streamLossReplies(pending, reason);
+            for (const reply of lost)
+                emit(reply);
+            // How many calls this drop actually killed. Zero means the agent could not feel it.
+            const pendingLost = lost.length;
             // Once per process: this session has now lost its tools at least once, which is the number
             // that says whether the transport work actually landed for real users. `pendingLost` is the
             // part an agent can FEEL — almost every measured drop killed nothing in flight.
@@ -556,16 +662,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();
         }
@@ -573,23 +685,45 @@ ensureDaemon) {
             // Announce this process to the daemon on the connect we already make — it is the single judge
             // of version skew, and this is the only moment it learns the agent's MCP server exists.
             const announce = `${MCP_SSE_PATH}?${PEER_VERSION_PARAM}=${encodeURIComponent(SERVER_VERSION)}&${PEER_CONTRACT_PARAM}=${encodeURIComponent(CONTRACT_FINGERPRINT)}`;
+            /**
+             * ONE reconnect per connect attempt, whoever notices the failure first.
+             *
+             * A dead socket emits on BOTH halves — `req`'s `error` and the response's `aborted`/`close`
+             * for the same TCP death — and this latch used to live inside the response callback, so
+             * `req.on('error')` scheduled a SECOND reconnect that the drop path could not see. Two chains
+             * came back, both died the same way, and both split again. The retry budget cannot stop that
+             * either: any one chain reaching an `endpoint` frame resets `attempts` to zero for all of
+             * them. It is the runaway behind a proxy log large enough to fill a disk, and the doubling is
+             * visible in the field logs as roughly two `reconnecting` lines per `reconnected` one.
+             */
+            let settled = false;
+            /**
+             * Whether this attempt ever got a response, as opposed to never reaching the daemon.
+             *
+             * `first` alone conflates two different situations, and the `req.on('error')` branch below
+             * treats both as a startup failure the caller handles. Before any stream exists that is right:
+             * there is no daemon, so rejecting is the honest answer. Once the FIRST stream has connected
+             * and is serving, a socket reset is a DROP, and rejecting it kills the proxy outright instead
+             * of reconnecting. The agent loses Reticle for the rest of the session, on its first stream,
+             * with nothing to retry it.
+             *
+             * It is also a race rather than a certainty, which is worse: a reset emits on both halves, so
+             * whether the proxy reconnects or dies depended on whether `res`'s `close` or `req`'s `error`
+             * won. Every later stream recovers correctly; you simply have to survive the first one.
+             */
+            let responded = false;
             const req = http.get({ host: LOOPBACK_HOST, port, path: announce }, (res) => {
+                responded = true;
                 if (!first)
                     proxyLog('reticle_mcp_proxy_reconnected', { port });
                 res.setEncoding('utf8');
-                // `end` and `error` can both fire on one response; only the first should drive a reconnect.
-                let settled = false;
                 const drop = (reason, detail) => {
                     if (settled)
                         return;
                     settled = true;
-                    // Answer anything the dead session owed BEFORE reconnecting. The new session cannot know
-                    // about it, so silence here is permanent.
-                    const lost = streamLossReplies(pending, reason);
-                    for (const reply of lost)
-                        emit(reply);
-                    // How many calls this drop actually killed. Zero means the agent could not feel it.
-                    scheduleReconnect(reason, detail, lost.length);
+                    // What the dead session owed is settled inside scheduleReconnect, so the other half of the
+                    // socket's death pays exactly the same debt when it is the one that notices first.
+                    scheduleReconnect(reason, detail);
                 };
                 const sse = new SseFrameParser();
                 res.on('data', (chunk) => {
@@ -606,12 +740,44 @@ ensureDaemon) {
             });
             // The very first connect failing means there is no daemon to talk to — that is a startup
             // failure the caller handles. Later ones are just the daemon bouncing: keep retrying.
-            req.on('error', (err) => first ? reject(err) : scheduleReconnect('connect_error', err.message));
+            req.on('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (first && !responded) {
+                    // A refused port on the very first connect is a daemon still booting, not a failure. Keep
+                    // chasing it: nothing else will, because only a fresh client request re-probes the port
+                    // and the client is already blocked on the call this would rescue.
+                    if (shouldRetryFirstConnect(err, Date.now() - startedAt)) {
+                        firstConnectAttempts++;
+                        const retryInMs = reconnectDelayMs(firstConnectAttempts);
+                        proxyLog('reticle_mcp_proxy_first_connect_retry', {
+                            port,
+                            attempt: firstConnectAttempts,
+                            retryInMs,
+                            note: 'the daemon has not finished booting; still waiting for it to accept',
+                        });
+                        setTimeout(() => connect(true), retryInMs).unref();
+                        return;
+                    }
+                    reject(err);
+                    return;
+                }
+                scheduleReconnect('connect_error', err.message);
+            });
         }
         connect(true);
         // ── 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.
          *
@@ -622,13 +788,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
@@ -638,16 +824,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;
@@ -684,10 +882,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

@@ -50,4 +50,13 @@ 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): McpServer;