@reticlehq/server 2.8.0 → 2.9.0

package/dist/journal/workspace-gitignore.js

@@ -0,0 +1,59 @@
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/**
+ * The `.reticle/` entries that are LOCAL state, and must never be committed by accident.
+ *
+ * Split from the durable half deliberately, and the split is the whole design: `contract.json`,
+ * `flows/`, `baselines/` and `capsules/` are meant to be checked in — a flow that cannot be shared
+ * is not a regression check anybody else can run — while everything below is per-machine churn.
+ *
+ * The reason this matters beyond tidiness: a session journal carries URLs, request and response
+ * bodies, and DOM text from the app under test. `.reticle/` is created by the daemon rather than by
+ * the user, so it arrives untracked and unexplained, and one `git add -A` puts an app's traffic into
+ * a shared repository. Reticle created the directory; the ignore for it is Reticle's to write.
+ */
+const TRANSIENT = [
+    `${ReticleDir.SESSIONS_SUBDIR}/`,
+    `${ReticleDir.RUNS_SUBDIR}/`,
+    `${ReticleDir.VISUAL_SUBDIR}/`,
+    ReticleDir.PROJECT_FILE,
+    ReticleDir.AMBIENT_FILE,
+    ReticleDir.ENVELOPES_FILE,
+    ReticleDir.FLAKE_FILE,
+    ReticleDir.TIERS_FILE,
+    '*.log',
+    '*.tmp',
+];
+const HEADER = [
+    '# Written by Reticle, and only about the directory Reticle owns.',
+    '#',
+    '# The entries below are per-machine state — session journals, run artifacts, learned envelopes.',
+    '# Journals contain URLs, request and response bodies and page text from the app under test, so',
+    '# they are worth keeping out of a shared repository on their own account.',
+    '#',
+    `# Deliberately NOT ignored: ${ReticleDir.CONTRACT_FILE}, ${ReticleDir.FLOWS_SUBDIR}/, ${ReticleDir.BASELINES_SUBDIR}/ and`,
+    `# ${ReticleDir.CAPSULES_SUBDIR}/. Those are meant to be committed — a saved flow only earns its keep`,
+    '# when a teammate or CI can replay it.',
+    '#',
+    '# Edit freely: Reticle writes this once and never rewrites it.',
+];
+/**
+ * Write `.reticle/.gitignore` if it is not already there.
+ *
+ * Never overwrites — once the file exists it belongs to whoever edited it last, and silently
+ * reverting somebody's change to a file we placed in their repository is worse than not having
+ * written it. Best-effort throughout: this runs on the daemon's start path, and a workspace that
+ * cannot be written must not stop a daemon coming up. Nothing about verification depends on it.
+ */
+export async function ensureWorkspaceGitignore(fs, root) {
+    const path = join(root, '.gitignore');
+    try {
+        if (await fs.exists(path))
+            return;
+        await fs.mkdir(root);
+        await fs.writeFile(path, `${[...HEADER, '', ...TRANSIENT].join('\n')}\n`);
+    }
+    catch {
+        /* a workspace we cannot write is not a reason to fail a session */
+    }
+}

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

@@ -1,3 +1,8 @@
+/**
+ * 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';
 /**
  * Overridable so the survival spec can reach exhaustion in seconds instead of minutes — the same
  * reason the idle windows take an env override. A positive integer only; anything else falls back,
@@ -7,62 +12,6 @@ export declare const MAX_RECONNECT_ATTEMPTS: number;
 export declare function reconnectDelayMs(attempt: number): number;
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export declare const RECONNECT_INITIALIZE_ID = "__reticle_proxy_reinit";
-/**
- * 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;
 /**
  * JSON-RPC requests forwarded on behalf of the client that have not been answered yet.
  *
@@ -181,15 +130,6 @@ export declare function waitForDaemon(port: number): Promise<void>;
  * to reconnect and how to answer what it cannot send.
  */
 export declare function buildSessionUrl(rawData: string, port: number): string | null;
-/**
- * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
- * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until stdin closes.
- *
- * A dropped SSE stream used to exit the process, which is what made the agent's `reticle_*` tools
- * vanish mid-session with no message and no way for the agent to get them back — only a human running
- * `/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.
- */
 export declare function startMcpProxy(port: number, 
 /**
  * Bring a daemon back before reconnecting. Without it the proxy retried a DEAD port until the
@@ -197,4 +137,3 @@ export declare function startMcpProxy(port: number,
  * failure mode for a daemon that crashed, was stopped, or shut itself down as idle.
  */
 ensureDaemon?: () => Promise<void>): Promise<never>;
-export {};

package/dist/mcp/mcp-proxy.js

@@ -1,17 +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, 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 { 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 { MAX_DAEMON_LOG_BYTES, rotateDaemonLog } from '../daemon/daemon.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
@@ -52,125 +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;
-/**
- * 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);
@@ -510,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
@@ -531,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,
@@ -542,29 +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', 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 +513,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 +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.
@@ -631,9 +575,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 +602,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 +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();
         }
@@ -797,6 +770,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 +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
@@ -823,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;
@@ -869,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;