@reticlehq/server 2.5.0 → 2.7.0

package/dist/init/snippets.js

@@ -50,7 +50,7 @@ export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
     const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     const ids = testids.map((t) => `'${t}'`).join(', ');
     const storeBlock = 0 === stores.length
-        ? '      // No state library detected. If you add one, register it here — see docs/usage.md.'
+        ? '      // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
         : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
     return `'use client';
 import { useEffect } from 'react';
@@ -174,7 +174,7 @@ Start the daemon BEFORE \`astro dev\`, so the token file exists when the config
 export function viteDevModuleFile(testids, stores) {
     const ids = testids.map((t) => `'${t}'`).join(', ');
     const storeBlock = 0 === stores.length
-        ? '  // No state library detected. If you add one, register it here — see docs/usage.md.'
+        ? '  // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
         : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
     return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
 // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
@@ -216,8 +216,22 @@ export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app
  * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
  * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
  */
-export function htmlManual(port, projectId) {
-    const arg = connectArg(port, projectId);
+export function htmlManual(port, projectId, pairingToken) {
+    const base = connectArg(port, projectId);
+    // The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
+    // it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); this path has
+    // none, so `init` inlines the literal it already read. Without it the bridge closes the socket
+    // with AUTH_FAILED and no session ever appears — see Bridge's hello handler.
+    const withToken = pairingToken === undefined || 0 === pairingToken.length
+        ? base
+        : `{ ${[base.length > 0 ? base.slice(1, -1).trim() : '', `token: '${pairingToken}'`]
+            .filter((p) => p.length > 0)
+            .join(', ')} }`;
+    const tokenNote = pairingToken === undefined || 0 === pairingToken.length
+        ? ''
+        : `\n\n  The \`token\` is this machine's pairing token, read from ~/.reticle/pairing-token. Keep it: the
+  bridge REJECTS a connect without it ("authentication failed") and no session appears. It is
+  per-machine and local-only, so do not commit it — a teammate's daemon mints their own.`;
     return `No Vite/Next plugin detected — wire the dev-only connect by hand. Pick the form for your setup:
 
   • Bundled app (Create React App, webpack, Parcel, Vue/Svelte CLI, etc.) — add to your ENTRY module
@@ -226,9 +240,9 @@ export function htmlManual(port, projectId) {
       if (window.location.hostname === 'localhost') {
         void import('@reticlehq/react').then(({ reticle, install }) => {
           install();
-          reticle.connect(${arg});
+          reticle.connect(${withToken});
         });
-      }
+      }${tokenNote}
 
   • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
     bundle the SDK once (e.g. \`npx esbuild\`) and point a dev-only <script type="module"> at the output,
@@ -282,6 +296,57 @@ declare const __RETICLE_ROOT__: string | undefined;
 declare const __RETICLE_SDK_VERSION__: string | undefined;
 `;
 }
+/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
+export const NUXT_PLUGIN_PATH = 'app/plugins/reticle.client.ts';
+/**
+ * The Nuxt recipe, written out in full because every trap in it is one somebody actually hit.
+ *
+ * Reported from the field, in the order they were hit: `init` classified a Nuxt 4 app as `html`, so
+ * it installed a package named `@reticlehq/react` (with `react` in its peer dependencies) into a Vue
+ * codebase — the reporter only continued after auditing our dist to confirm there are no React
+ * imports at runtime, which most people will not do. It then handed over a snippet guarded on
+ * `window.location.hostname === 'localhost'`, which fails twice over in Nuxt: `window` does not
+ * exist during SSR, and the dev host here was a hosts-file alias (required for the backend's
+ * white-label origin detection), so the guard was false and the connect never ran — no error, no log
+ * line, nothing to debug. And nothing said a running dev server does not pick up a new plugin.
+ *
+ * So: `import.meta.dev` (build-time, host-independent) instead of a hostname check, `.client.ts`
+ * instead of an SSR guard, the framework-neutral sensor instead of the React kit, the non-localhost
+ * flag named up front, and the restart said out loud.
+ */
+export function nuxtManual(port, projectId) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : base.slice(1, -1).trim();
+    const connect = '' === fields ? 'reticle.connect()' : `reticle.connect({ ${fields} })`;
+    return `Nuxt owns its own Vite instance and renders its own HTML, so there is no vite.config to patch
+and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which is Nuxt's own idiom:
+
+1. Create ${NUXT_PLUGIN_PATH}:
+
+     export default defineNuxtPlugin(() => {
+       // import.meta.dev is the correct guard: it is resolved at build time, so it does not care
+       // what hostname you develop on. Do NOT guard on window.location.hostname === 'localhost' —
+       // that is false on any hosts-file alias or LAN address, and window does not exist in SSR.
+       if (!import.meta.dev) return
+       void import('@reticlehq/browser').then(({ reticle }) => {
+         ${connect}
+       })
+     })
+
+   The .client.ts suffix is load-bearing: it is what keeps this out of the server bundle.
+
+2. Restart the dev server. A dev server that is already running does not pick up a new plugin —
+   it will not appear in .nuxt/plugins/client.mjs, and the app will come up with no SDK at all.
+
+3. If your dev host is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), add
+   allowNonLocalhost: true to that connect call. Without it the SDK loads and then refuses, and the
+   only sign is one line in the browser console.
+
+The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
+source file:line all work in Vue. What you do not get is React component identity, which is the only
+thing the React adapter adds. There is no Nuxt app in this project's CI, so this path is UNVERIFIED:
+if something does not work, please open an issue.`;
+}
 /**
  * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
  * and by tooling for the stable projectId (the app's identity across port changes).

package/dist/init/windows-quote.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+export declare function windowsShellArg(arg: string): string;

package/dist/init/windows-quote.js

@@ -0,0 +1,70 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+/**
+ * Characters that make cmd.exe do something other than pass the text along.
+ *
+ * Whitespace and `"` split or delimit; the rest are the shell's control operators. An argument
+ * containing any of them must be quoted, not just one containing a space.
+ */
+const NEEDS_QUOTING = /[\s"&|<>^()!%,;=]/;
+export function windowsShellArg(arg) {
+    // An empty argument must still occupy a slot in argv. Unquoted it disappears entirely, silently
+    // shifting every argument after it by one.
+    if (0 === arg.length)
+        return '""';
+    if (!NEEDS_QUOTING.test(arg))
+        return arg;
+    let out = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if ('\\' === ch) {
+            backslashes += 1;
+            continue;
+        }
+        if ('"' === ch) {
+            // 2n+1 backslashes → n literal backslashes and an escaped quote.
+            out += '\\'.repeat(2 * backslashes + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        out += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // A trailing run sits immediately before the closing quote, so it must be doubled or it escapes it.
+    return `${out}${'\\'.repeat(2 * backslashes)}"`;
+}

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

@@ -28,4 +28,5 @@ export declare function resetOutageReporting(): void;
 export declare function reportMcpOutage(stage: OutageStage, facts: {
     reason: string;
     attempts: number;
+    pendingLost?: number;
 }): void;

package/dist/mcp/mcp-outage.js

@@ -43,6 +43,13 @@ export function reportMcpOutage(stage, facts) {
         return;
     reported.add(stage);
     void getTelemetry().emit(TelemetryEventKind.MCP_CONNECTION_LOST, {
-        outage: { stage, reason: outageReason(facts.reason), attempts: facts.attempts },
+        outage: {
+            stage,
+            reason: outageReason(facts.reason),
+            attempts: facts.attempts,
+            // Always sent, including zero: zero is the finding — a drop no agent could feel. See
+            // McpOutageSchema.pendingLost.
+            pendingLost: facts.pendingLost ?? 0,
+        },
     });
 }

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

@@ -104,7 +104,17 @@ export declare class SseFrameParser {
 export declare function probeDaemon(port: number): Promise<boolean>;
 /** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
 export declare function waitForDaemon(port: number): Promise<void>;
-export declare function buildSessionUrl(rawData: string, port: number): string;
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * 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.

package/dist/mcp/mcp-proxy.js

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleDir, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
-import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, OnDrop, OnRequest, } from './proxy-lifecycle.js';
+import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy-lifecycle.js';
 import { log } from '../log.js';
 import { OutageStage, reportMcpOutage } from './mcp-outage.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
@@ -373,8 +373,21 @@ function postToSession(url, body) {
         req.end();
     });
 }
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * to reconnect and how to answer what it cannot send.
+ */
 export function buildSessionUrl(rawData, port) {
-    return rawData.startsWith('/') ? `http://${LOOPBACK_HOST}:${port}${rawData}` : rawData;
+    const trimmed = rawData.trim();
+    if ('' === trimmed)
+        return null;
+    return trimmed.startsWith('/') ? `http://${LOOPBACK_HOST}:${port}${trimmed}` : trimmed;
 }
 /**
  * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
@@ -428,9 +441,16 @@ ensureDaemon) {
                 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,
-                    note: 'answered queued requests instead of holding them for a daemon that never arrived',
+                    dormant,
+                    note: 'answered queued requests and went dormant; the next client request re-probes the port',
                 });
             }, QUEUE_WAIT_MS);
             queueTimer.unref();
@@ -469,6 +489,13 @@ ensureDaemon) {
         function onSseEvent(event, data, p) {
             if ('endpoint' === event) {
                 const url = buildSessionUrl(data, p);
+                if (null === url) {
+                    proxyLog('reticle_mcp_proxy_empty_endpoint', {
+                        port,
+                        note: 'endpoint frame carried no URL; staying disconnected rather than posting to nowhere',
+                    });
+                    return;
+                }
                 postUrl = url;
                 // A stream that reached `endpoint` is a USABLE session — that, not a set of response
                 // headers, is what earns a fresh retry budget. Resetting on headers let a daemon that
@@ -491,18 +518,19 @@ ensureDaemon) {
                 emit(data);
             }
         }
-        function scheduleReconnect(reason, detail) {
+        function scheduleReconnect(reason, detail, pendingLost = 0) {
             if (stopped)
                 return;
             postUrl = null;
             attempts++;
             // 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.
-            reportMcpOutage(OutageStage.FIRST, { reason, attempts });
+            // 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.
+            reportMcpOutage(OutageStage.FIRST, { reason, attempts, pendingLost });
             // The severe stage: we are about to stop retrying. Reported so the share of sessions where
             // MCP never came back on its own is a number rather than an anecdote.
             if (attempts > MAX_RECONNECT_ATTEMPTS) {
-                reportMcpOutage(OutageStage.BUDGET_SPENT, { reason, attempts });
+                reportMcpOutage(OutageStage.BUDGET_SPENT, { reason, attempts, pendingLost });
                 // Stop RETRYING, never stop SERVING. See onReconnectBudgetSpent: exiting here made the
                 // client mark the MCP server disconnected and left a human to reconnect it by hand.
                 dormant = onReconnectBudgetSpent() === OnDrop.DORMANT;
@@ -557,9 +585,11 @@ ensureDaemon) {
                     settled = true;
                     // Answer anything the dead session owed BEFORE reconnecting. The new session cannot know
                     // about it, so silence here is permanent.
-                    for (const reply of streamLossReplies(pending, reason))
+                    const lost = streamLossReplies(pending, reason);
+                    for (const reply of lost)
                         emit(reply);
-                    scheduleReconnect(reason, detail);
+                    // How many calls this drop actually killed. Zero means the agent could not feel it.
+                    scheduleReconnect(reason, detail, lost.length);
                 };
                 const sse = new SseFrameParser();
                 res.on('data', (chunk) => {

package/dist/mcp/mcp.js

@@ -18,6 +18,7 @@ import { SERVER_VERSION } from '../version/server-version.js';
 import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { parsePredicate } from '../events/predicate-parse.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
@@ -30,6 +31,27 @@ export function withSessionEnvelope(name, outputSchema) {
     return { ...sessionEnvelopeShape, ...outputSchema };
 }
 const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
+/**
+ * What every agent is told at `initialize`, before it has called a single tool.
+ *
+ * This is the only channel that reaches an agent with NO dependency on the project: no CLAUDE.md, no
+ * AGENTS.md, no pasted skill, no successful `reticle init`. An agent whose setup half-worked has read
+ * none of those files and is precisely the agent whose report we need — so the standing instruction
+ * to send feedback has to live here, where it arrives with the connection itself.
+ *
+ * Kept to a handful of lines: it is prepended to every session's context, so each sentence is paid
+ * for on every turn, forever.
+ */
+const SERVER_INSTRUCTIONS = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+
+Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. A verdict of verified:"unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
+
+Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`reticle_feedback\` the moment you notice, then carry on with your task:
+- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
+- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
+- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
+
+Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
 /** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
  * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
  * first clause retains the essentials (enum hints like "role | text | label" live there). */
@@ -251,6 +273,17 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
             // McpError.message already carries "MCP error -32602: "; re-wrapping would print it twice.
             const raw = error instanceof Error ? error.message : String(error);
             const detail = raw.replace(/^MCP error -?\d+:\s*/, '');
+            // A malformed PREDICATE gets the sentence, not the array. The SDK validates tool input against
+            // the same zod schema and throws a serialized issue list — so the readable message
+            // `parsePredicate` exists to produce was being generated only on paths that never run over
+            // MCP, which is every path a real agent uses. Found by driving a live app: `reticle_assert`
+            // answered a near-miss predicate with a raw zod array naming the unknown keys and not one
+            // field that would have worked. It already carries its own guidance, so the generic example is
+            // dropped rather than argued with.
+            const predicateHelp = predicateMessage(args);
+            if (predicateHelp !== undefined) {
+                throw new McpError(ErrorCode.InvalidParams, predicateHelp);
+            }
             const example = examples.get(toolName);
             const help = example === undefined
                 ? ` Call reticle_tools { names: ["${toolName}"] } for its parameters.`
@@ -259,6 +292,29 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         }
     };
 }
+/**
+ * The readable reason a predicate argument did not parse, or undefined when the predicate is fine.
+ *
+ * Undefined matters as much as the message: a call can fail validation for a reason that has nothing
+ * to do with the predicate (a bad `timeout_ms`, a missing `ref`), and replacing that error with a
+ * predicate explanation would be confidently wrong. Re-parsing is the honest test — if it parses,
+ * the predicate is not what broke.
+ */
+function predicateMessage(args) {
+    if (typeof args !== 'object' || null === args)
+        return undefined;
+    const record = args;
+    const predicate = record['predicate'] ?? record['until'];
+    if (predicate === undefined)
+        return undefined;
+    try {
+        parsePredicate(predicate);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : undefined;
+    }
+}
 /**
  * Answer a call for a real-but-un-advertised tool with the way to make it work.
  *
@@ -292,7 +348,11 @@ function toolNameOf(request) {
 }
 export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
-    const server = new McpServer(SERVER_INFO);
+    // Which surface this daemon advertises. The 18-tool default and the 48-tool full surface are
+    // different products from inside an agent's context, so outcomes are only comparable when the
+    // session says which one it saw.
+    getSessionMetrics().recordSurface(profile);
+    const server = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
     // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
     // hook rather than read here: the handshake has not happened yet at construction time, and a
     // feedback report filed twenty tool calls later is exactly when we want the answer.
@@ -300,8 +360,10 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
         const info = server.server.getClientVersion();
         // Record it as a side effect of the first read so the session summary can report WHICH agents
         // drove this daemon — the multi-agent story, visible without a second plumbing path.
+        // Name AND version: the version was already in this handshake and was being dropped, so a
+        // regression in agent behaviour could never be attributed to a client build.
         if (info?.name !== undefined)
-            getSessionMetrics().recordClient(info.name);
+            getSessionMetrics().recordClient(info.name, info.version);
         return info === undefined ? undefined : { name: info.name, version: info.version };
     });
     // Cast once to our bridge type so every per-tool call site is typed without `any`.

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

@@ -44,6 +44,25 @@ export declare function onStreamDrop(daemonListening: boolean): OnDrop;
  * whether the server survives.
  */
 export declare function onReconnectBudgetSpent(): OnDrop;
+/**
+ * What to do when queued requests expire with nothing connected. Always DORMANT.
+ *
+ * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
+ * proxy spent its budget against it, and from then on every call returned −32001 — including after
+ * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
+ * looked again.
+ *
+ * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
+ * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
+ * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
+ * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
+ * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
+ *
+ * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
+ * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
+ * arrived late, and it costs nothing when one has not.
+ */
+export declare function onQueueExpired(): OnDrop;
 /** What to do with a client message. */
 export declare const OnRequest: {
     /** Connected — post it straight through. */

package/dist/mcp/proxy-lifecycle.js

@@ -47,6 +47,27 @@ export function onStreamDrop(daemonListening) {
 export function onReconnectBudgetSpent() {
     return OnDrop.DORMANT;
 }
+/**
+ * What to do when queued requests expire with nothing connected. Always DORMANT.
+ *
+ * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
+ * proxy spent its budget against it, and from then on every call returned −32001 — including after
+ * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
+ * looked again.
+ *
+ * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
+ * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
+ * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
+ * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
+ * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
+ *
+ * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
+ * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
+ * arrived late, and it costs nothing when one has not.
+ */
+export function onQueueExpired() {
+    return OnDrop.DORMANT;
+}
 /** What to do with a client message. */
 export const OnRequest = {
     /** Connected — post it straight through. */

package/dist/pool/browser-pool.d.ts

@@ -77,6 +77,15 @@ export declare class BrowserPool {
      * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
      */
     sweepExpired(): Promise<string[]>;
+    /**
+     * How many leases this pool has reclaimed for going stale.
+     *
+     * Read by the no-session diagnosis: an aged-out lease used to be reported as "the tab was closed
+     * … ask the human to reopen the app", which is wrong on every clause and sent one reporter looking
+     * for a port mismatch (#157). A count is enough — the message says "likeliest", not "certainly",
+     * because nothing here knows WHICH session the caller just lost.
+     */
+    reapedLeaseCount(): number;
     /**
      * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
      * waits FIFO until a slot frees (or until `signal` aborts, if provided).

package/dist/pool/browser-pool.js

@@ -27,6 +27,8 @@ export class BrowserPool {
     #browser;
     #launching;
     #closed = false;
+    /** Leases reclaimed for going stale — see reapedLeaseCount(). */
+    #reapedLeases = 0;
     #active = new Map();
     /**
      * Slots claimed-or-active — the real concurrency gate. Incremented SYNCHRONOUSLY the instant an
@@ -85,8 +87,20 @@ export class BrowserPool {
             .map(([sessionId]) => sessionId);
         for (const sessionId of expired)
             await this.#release(sessionId);
+        this.#reapedLeases += expired.length;
         return expired;
     }
+    /**
+     * How many leases this pool has reclaimed for going stale.
+     *
+     * Read by the no-session diagnosis: an aged-out lease used to be reported as "the tab was closed
+     * … ask the human to reopen the app", which is wrong on every clause and sent one reporter looking
+     * for a port mismatch (#157). A count is enough — the message says "likeliest", not "certainly",
+     * because nothing here knows WHICH session the caller just lost.
+     */
+    reapedLeaseCount() {
+        return this.#reapedLeases;
+    }
     /**
      * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
      * waits FIFO until a slot frees (or until `signal` aborts, if provided).
@@ -138,6 +152,15 @@ export class BrowserPool {
         this.#active.clear();
         this.#occupied = 0;
         await Promise.all(contexts.map((c) => c.close().catch(() => undefined)));
+        // If a launch is in flight, await it so we can close the resulting browser — otherwise it
+        // resolves after shutdown returns and the Chromium process is orphaned (hundreds of MB leaked).
+        const inflight = this.#launching;
+        if (inflight !== undefined) {
+            const launched = await inflight.catch(() => undefined);
+            if (launched !== undefined && launched !== this.#browser) {
+                await launched.close().catch(() => undefined);
+            }
+        }
         const browser = this.#browser;
         this.#browser = undefined;
         if (browser !== undefined)
@@ -168,27 +191,33 @@ export class BrowserPool {
             const onFree = () => {
                 // The pool shut down while we waited → reject rather than relaunch a browser.
                 if (this.#closed) {
+                    if (signal !== undefined)
+                        signal.removeEventListener('abort', onAbort);
                     reject(new Error('browser pool is shut down'));
                     return;
                 }
                 // Claim the freed slot; if another woken waiter beat us to it, re-queue.
-                if (this.#tryClaim())
+                if (this.#tryClaim()) {
+                    if (signal !== undefined)
+                        signal.removeEventListener('abort', onAbort);
                     resolve();
-                else
+                }
+                else {
                     this.#waiters.push(onFree);
+                }
+            };
+            const onAbort = () => {
+                const i = this.#waiters.indexOf(onFree);
+                if (i >= 0)
+                    this.#waiters.splice(i, 1);
+                reject(new Error('acquire aborted'));
             };
             if (signal !== undefined) {
                 if (signal.aborted) {
                     reject(new Error('acquire aborted'));
                     return;
                 }
-                signal.addEventListener('abort', () => {
-                    // Remove ourselves from the queue so a later wake doesn't claim a slot we'll never use.
-                    const i = this.#waiters.indexOf(onFree);
-                    if (i >= 0)
-                        this.#waiters.splice(i, 1);
-                    reject(new Error('acquire aborted'));
-                }, { once: true });
+                signal.addEventListener('abort', onAbort, { once: true });
             }
             this.#waiters.push(onFree);
         });