@reticlehq/server 3.8.2 → 3.10.0

package/dist/portal/session/zero-install-first-call.d.ts

@@ -22,10 +22,28 @@ export declare function within(child: string | undefined, parent: string): boole
 export declare function projectAppUrlFinder(io: Pick<FirstCallIo, 'project' | 'serving' | 'servingDirectory'>): () => Promise<string | undefined>;
 /** One lease per project for the daemon's life: a failure is reported once, never retried. */
 export declare function firstCallOpener(io: FirstCallIo): () => Promise<FirstCallOpened | undefined>;
+/**
+ * The first-session offer, on the first tool call of each agent connection.
+ *
+ * The plugin's SessionStart hook says it when a session starts. A plugin installed in an open
+ * session and loaded with `/reload-plugins` fires no SessionStart, so the server says it too. Only
+ * the first call of a connection looks: an offer on a later call reads as noise.
+ */
+export interface FirstSessionOfferIo {
+    /** The unwired web app this call is about; undefined when wired, not a web app, or no project. */
+    project: () => string | undefined;
+    /** Whether an app is attached now. */
+    connected: () => boolean;
+    /** Called once for each offer that goes out, with its project. */
+    offered: (dir: string) => void;
+}
+/** The offer for this connection's first call, or undefined. Each attach id gets one look. */
+export declare function firstSessionOfferGate(io: FirstSessionOfferIo): (attachId: string) => string | undefined;
 /**
  * The daemon's two answers to an app nobody wired, built together because both ask the same
  * question first — which unwired web app is this caller in. `firstRun` names it when the agent
- * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
+ * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call;
+ * `firstSessionOffer` says the offer on the first call of each agent connection.
  */
 export declare function agentWiring(sessions: {
     list(): readonly unknown[];
@@ -33,4 +51,5 @@ export declare function agentWiring(sessions: {
     firstRun: FirstRunWiring;
     openUnwiredApp: () => Promise<FirstCallOpened | undefined>;
     projectAppUrl: () => Promise<string | undefined>;
+    firstSessionOffer: (attachId: string) => string | undefined;
 };

package/dist/portal/session/zero-install-first-call.js

@@ -21,8 +21,11 @@ import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
 import { callingClientDirectory } from '../../hooks/client-directory.js';
 import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
 import { probeDevServerStates } from './dev-server/dev-server-probe.js';
+import { NextStepOffered } from '@reticlehq/core';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { noteNextStepOffered } from '../../telemetry/onboarding-firsts.js';
 import { firstRunWiring } from './first-run-wiring.js';
-import { wiringConsent } from './no-session-next-action.js';
+import { firstSessionOffer, wiringConsent } from './no-session-next-action.js';
 import { servingDirectoryOf } from './serving-directory.js';
 const LOCALHOST = 'http://localhost';
 /** The path with symlinks resolved when it exists (lsof reports `/private/tmp`, callers `/tmp`). */
@@ -87,10 +90,32 @@ export function firstCallOpener(io) {
         return { url, notice: openedNotice(url, initCommandIn(dir)) };
     };
 }
+/** The offer for this connection's first call, or undefined. Each attach id gets one look. */
+export function firstSessionOfferGate(io) {
+    // ponytail: one short id per MCP connection for the daemon's life; bound it if a daemon ever
+    // serves connections by the million.
+    const looked = new Set();
+    return (attachId) => {
+        if (looked.has(attachId)) {
+            return undefined;
+        }
+        looked.add(attachId);
+        if (io.connected()) {
+            return undefined;
+        }
+        const dir = io.project();
+        if (dir === undefined) {
+            return undefined;
+        }
+        io.offered(dir);
+        return firstSessionOffer(initCommandIn(dir));
+    };
+}
 /**
  * The daemon's two answers to an app nobody wired, built together because both ask the same
  * question first — which unwired web app is this caller in. `firstRun` names it when the agent
- * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
+ * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call;
+ * `firstSessionOffer` says the offer on the first call of each agent connection.
  */
 export function agentWiring(sessions, lease) {
     const firstRun = firstRunWiring();
@@ -107,5 +132,12 @@ export function agentWiring(sessions, lease) {
         firstRun,
         openUnwiredApp: firstCallOpener(io),
         projectAppUrl: projectAppUrlFinder({ ...io, project: callerFolder }),
+        firstSessionOffer: firstSessionOfferGate({
+            ...io,
+            // The offer leads with the lease, so it is counted as a lease offer.
+            offered: (dir) => {
+                noteNextStepOffered(NextStepOffered.LEASE, () => readProjectId(dir) !== undefined);
+            },
+        }),
     };
 }

package/dist/start-wiring.d.ts

@@ -3,14 +3,40 @@ import type { StartOptions } from './start-options.js';
 import type { Bridge } from './portal/bridge/bridge.js';
 import type { RealInputProvider } from './portal/input/real-input.js';
 import { BrowserPool } from './portal/pool/browser-pool.js';
+import { type PageErrorJournal } from './portal/pool/page-error-journal.js';
+import type { PooledPageError } from './portal/pool/pool-contract.js';
+import type { BrowserPoolOptions } from './portal/pool/pool-lease.js';
 import { type InjectedConnect } from './portal/pool/zero-install.js';
+import type { NonceMinter } from './portal/production/production-activation.js';
 /**
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
  */
 /** Where the zero-install reader connects: this daemon's own bridge, with its pairing token. */
 export declare function readerConnect(port: number, token: string | undefined): InjectedConnect;
-export declare function createBrowserPool(headless: boolean, reader: InjectedConnect): BrowserPool;
+/**
+ * The zero-install script for pages that connect to `reader`, built on first use and kept: the
+ * page that needs it is one whose app never connected. Undefined when this install has no reader.
+ *
+ * A page that is not on loopback gets a nonce minted for its origin in place of the pairing token.
+ * The bridge admits a WebSocket from an origin only while a nonce names it, so the reader on a
+ * deployed page was refused with a 403 (#2016). The nonce also keeps the machine's pairing token
+ * out of a page that somebody else serves.
+ *
+ * ponytail: the nonce lives for one drive (SESSION_NONCE_TTL_MS). A lease reloaded after that
+ * dials with a dead nonce; mint per navigation if that is ever seen.
+ */
+export declare function zeroInstallLoader(reader: InjectedConnect, nonces?: Pick<NonceMinter, 'mint'>): (url?: string) => string | undefined;
+export declare function createBrowserPool(headless: boolean, reader: InjectedConnect, onPageError?: (leaseId: string, error: PooledPageError) => void, onLeaseClosed?: (leaseId: string) => void, nonces?: Pick<NonceMinter, 'mint'>, onDialog?: BrowserPoolOptions['onDialog']): BrowserPool;
+/**
+ * Journal the uncaught page errors the pool hears into the session that connects for that lease.
+ *
+ * The pool sees every throw its pages make from before the first navigation; the SDK only exists
+ * afterwards. Without this wiring an import-time crash — a blank page with no error text anywhere
+ * (#1966) — was invisible to the agent driving it. Returns the journal so the pool's sink can be
+ * handed over; the bridge hook is registered here.
+ */
+export declare function attachPageErrorJournal(bridge: Bridge): PageErrorJournal;
 /**
  * Route CDP-authoritative network detail onto the driven session's journal.
  *
@@ -26,7 +52,9 @@ export declare function makeNetworkDetailRouter(bridge: Bridge, driveUrl: string
  * so a failed launch never leaks a WS port. A past divergence between the two paths let daemon mode
  * run with a different setup — this removes that risk.
  */
-export declare function resolveRealInput(options: StartOptions, onNavigateError: () => Promise<void>, onNetworkDetail?: (detail: NetworkDetail) => void): Promise<{
+export declare function resolveRealInput(options: StartOptions, onNavigateError: () => Promise<void>, onNetworkDetail?: (detail: NetworkDetail) => void, 
+/** Where a driven page with no SDK connects the zero-install reader. Absent: it gets none. */
+reader?: InjectedConnect): Promise<{
     realInput?: RealInputProvider;
     owned?: {
         dispose: () => Promise<void>;

package/dist/start-wiring.js

@@ -23,7 +23,10 @@ import { SERVER_VERSION } from './command/version/identity/server-version.js';
 import { CdpRealInputProvider, LaunchedRealInputProvider } from './portal/input/real-input.js';
 import { BrowserPool } from './portal/pool/browser-pool.js';
 import { playwrightLauncher, resolveMaxContexts } from './portal/pool/playwright-launcher.js';
+import { makePageErrorJournal } from './portal/pool/page-error-journal.js';
+import { resolveLeasedSessionId } from './surface/tools/lease-tools.js';
 import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './portal/pool/zero-install.js';
+import { offLoopbackOrigin } from './portal/pool/context-permissions.js';
 /**
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
@@ -32,26 +35,85 @@ import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './
 export function readerConnect(port, token) {
     return { url: bridgeWsUrl(port), ...(token === undefined ? {} : { token }) };
 }
-export function createBrowserPool(headless, reader) {
-    const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
-    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
-        ? globalThis.crypto.randomUUID()
-        : String(Date.now())}`;
-    // Built on first use and kept: the page that needs it is one whose app never connected.
+/**
+ * The zero-install script for pages that connect to `reader`, built on first use and kept: the
+ * page that needs it is one whose app never connected. Undefined when this install has no reader.
+ *
+ * A page that is not on loopback gets a nonce minted for its origin in place of the pairing token.
+ * The bridge admits a WebSocket from an origin only while a nonce names it, so the reader on a
+ * deployed page was refused with a 403 (#2016). The nonce also keeps the machine's pairing token
+ * out of a page that somebody else serves.
+ *
+ * ponytail: the nonce lives for one drive (SESSION_NONCE_TTL_MS). A lease reloaded after that
+ * dials with a dead nonce; mint per navigation if that is ever seen.
+ */
+export function zeroInstallLoader(reader, nonces) {
     let script;
-    const zeroInstallScript = () => {
+    return (url) => {
+        const origin = offLoopbackOrigin(url);
+        if (origin !== undefined && nonces !== undefined) {
+            const bundle = readReaderBundle();
+            if (bundle === undefined) {
+                return undefined;
+            }
+            return zeroInstallScriptFor(bundle, {
+                url: reader.url,
+                token: nonces.mint({ origin }).nonce,
+            });
+        }
         if (script === undefined) {
             const bundle = readReaderBundle();
             script = bundle === undefined ? null : zeroInstallScriptFor(bundle, reader);
         }
         return script ?? undefined;
     };
+}
+export function createBrowserPool(headless, reader, onPageError, onLeaseClosed, nonces, onDialog) {
+    const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
+    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
+        ? globalThis.crypto.randomUUID()
+        : String(Date.now())}`;
     return new BrowserPool(playwrightLauncher({ headless }), {
         maxContexts,
         genSessionId,
-        zeroInstallScript,
+        zeroInstallScript: zeroInstallLoader(reader, nonces),
+        // The reader dials this origin; a lease off loopback adds it to the page CSP (#2016).
+        daemonOrigin: new URL(reader.url).origin,
         launchHeaded: playwrightLauncher({ headless: false }),
+        ...(onPageError === undefined ? {} : { onPageError }),
+        ...(onLeaseClosed === undefined ? {} : { onLeaseClosed }),
+        ...(onDialog === undefined ? {} : { onDialog }),
+    });
+}
+/**
+ * Journal the uncaught page errors the pool hears into the session that connects for that lease.
+ *
+ * The pool sees every throw its pages make from before the first navigation; the SDK only exists
+ * afterwards. Without this wiring an import-time crash — a blank page with no error text anywhere
+ * (#1966) — was invisible to the agent driving it. Returns the journal so the pool's sink can be
+ * handed over; the bridge hook is registered here.
+ */
+export function attachPageErrorJournal(bridge) {
+    const journal = makePageErrorJournal({
+        resolveSession: (leaseId) => {
+            // Same resolution the lease tool uses: the lease id, or the id of a session whose URL
+            // carries the lease marker — an app that registered under its own name still reaches its lease.
+            const id = resolveLeasedSessionId(bridge.sessions, leaseId);
+            if (id === undefined) {
+                return undefined;
+            }
+            const session = bridge.sessions.get(id);
+            return session === undefined ? undefined : session;
+        },
+    });
+    bridge.attachSessionCreate((session) => journal.onSessionCreate(session));
+    // The daemon runs for days; both of the journal's maps are keyed by things that end, so both
+    // endings are hooked. The bridge's end hook is additive — the durable journal's teardown runs too.
+    bridge.attachSessionEnd((session) => {
+        journal.onSessionEnd(session.id);
+        return Promise.resolve();
     });
+    return journal;
 }
 /**
  * Route CDP-authoritative network detail onto the driven session's journal.
@@ -98,7 +160,9 @@ export function makeNetworkDetailRouter(bridge, driveUrl) {
  * so a failed launch never leaks a WS port. A past divergence between the two paths let daemon mode
  * run with a different setup — this removes that risk.
  */
-export async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
+export async function resolveRealInput(options, onNavigateError, onNetworkDetail, 
+/** Where a driven page with no SDK connects the zero-install reader. Absent: it gets none. */
+reader) {
     const driveUrl = options.driveUrl;
     if (driveUrl !== undefined && driveUrl.length > 0) {
         const headless = options.headless ?? true;
@@ -114,6 +178,7 @@ export async function resolveRealInput(options, onNavigateError, onNetworkDetail
                 ...(injectConnect !== undefined ? { injectConnect } : {}),
                 ...(storageState !== undefined ? { storageState } : {}),
                 ...(onNetworkDetail !== undefined ? { onNetworkDetail } : {}),
+                ...(reader !== undefined ? { zeroInstallScript: zeroInstallLoader(reader) } : {}),
             }));
         const launched = factory({ driveUrl, headless });
         try {

package/dist/surface/mcp/mcp-proxy.js

@@ -5,6 +5,8 @@ import { localInitializeResponse, degradedInstructions, isHandshakeLine, drainLi
 export { HandshakeReplay, RECONNECT_INITIALIZE_ID } from './proxy/proxy-handshake.js';
 import { isToolCallRequest, isToolsListRequest, ToolCatalogCache } from './tool-catalog-cache.js';
 import { rememberEnumerated, rememberProxyStarted, rememberToolCalled } from './attach-memory.js';
+import { initializeClientName, rememberAgentConnected } from './peer/agents-connected.js';
+import { agentClientOf } from '../../hooks/coding-agents.js';
 import { toolsChangedNotification } from './proxy/proxy-handshake.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, ProxyExitReason, PROXY_ID_PARAM, } from '@reticlehq/core';
 import { SseFrameParser, buildSessionUrl } from './sse-frame-parser.js';
@@ -17,7 +19,8 @@ import { hasAnyProjectConnectedBefore } from '../../memory/recall/prior/connecti
 import { projectIdsAt } from '../../command/cli/ports/resolve/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, agentSessionQuery, } from '../../command/version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy/proxy-lifecycle.js';
-import { describePresence, probePresence } from '../../command/daemon/binding/port-presence.js';
+import { probePresence } from '../../command/daemon/binding/port-presence.js';
+import { describePortState } from '../../command/daemon/port-state.js';
 import { PROXY_ID, flushProxyExit, noteProxyDrop, noteProxyToolCall, } from '../../telemetry/proxy-telemetry.js';
 export { flushProxyExit, reportWakeRefused } from '../../telemetry/proxy-telemetry.js';
 import { detectStack } from '../../telemetry/feedback-context.js';
@@ -513,7 +516,7 @@ boot) {
                     // 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);
+                    const sentence = describePortState(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
@@ -792,6 +795,11 @@ boot) {
                 if (isToolsListRequest(trimmed)) {
                     rememberEnumerated(reticleStateHome(), port);
                 }
+                // WHICH agent connected, so the installer and `status` can say "Connected: Cursor ✓".
+                const client = agentClientOf(initializeClientName(trimmed));
+                if (client !== undefined) {
+                    rememberAgentConnected(reticleStateHome(), client);
+                }
                 // The hop every other check misses. Recorded on the REQUEST rather than a reply, because
                 // the question is whether anything ever left the agent — a call that leaves and gets no
                 // answer is a different fault from one that was never made, and only this side sees it.

package/dist/surface/mcp/mcp.js

@@ -7,11 +7,12 @@ import { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { tableForSurface } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, toolAnnotations, } from '../tools/tool-surface.js';
 import { ReticleTool } from '@reticlehq/core';
-import { sharedParamShort } from './shared-params.js';
+import { refusedKeyRedirect, sharedParamShort } from './shared-params.js';
 import { buildDynamicTools, descriptionOf } from '../tools/dynamic-tools.js';
 import { runTool } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape, newSnapshotCache } from '../tools/tool-kit.js';
 import { buildErrorPayload, codedRefusalOf } from '../tools/error-recovery.js';
+import { withRepeatHint } from '../tools/repeat-hint.js';
 import { connectionSkew, takeVersionSkewOnto } from '../../command/version/version-nudge.js';
 import { resultIsError } from './faults/mcp-is-error.js';
 import { consumerVerdictRefusal, reservedVerdictKeysIn } from './consumer-verdict-guard.js';
@@ -131,7 +132,7 @@ const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact re
     'compare (page text vs server answer, no expected value: { left:{from:"text",scope}, ' +
     'right:{from:"net",urlContains,path}, as:"number" }), ' +
     'console.absent:true (action completed with a CLEAN ' +
-    'console), absent:true on element/text (it should be gone). Call reticle_tools for the full field ' +
+    'console), absent:true on element/text (gone from the DOM; add visible:true for "not shown"). Call reticle_tools for the full field ' +
     'grammar of a kind.';
 const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMMAR_HINT}`;
 /**
@@ -149,8 +150,9 @@ function leanZodShape(shape, advertised, predicateAnchor) {
     let hintSpent = predicateAnchor !== undefined;
     for (const [key, schema] of Object.entries(shape)) {
         if (isPredicateParam(schema)) {
-            // Every tool keeps the kinds; only the navigation hint is anchored.
-            const compact = z.record(z.string(), z.unknown());
+            // Every tool keeps the kinds; only the navigation hint is anchored. A bare string is visible
+            // text (core's `PredicateSchema`), so the SDK must let it through to that parse.
+            const compact = z.union([z.string(), z.record(z.string(), z.unknown())]);
             out[key] = (schema.isOptional() ? compact.optional() : compact).describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
             hintSpent = true;
             continue;
@@ -365,6 +367,7 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
             const declared = [...(allowedKeys.get(toolName) ?? [])].join(', ');
             throw new McpError(ErrorCode.InvalidParams, `Unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
                 `They were NOT applied — a result computed without them would look like an answer. ` +
+                refusedKeyRedirect(toolName, unknown) +
                 (0 === declared.length ? '' : `${toolName} declares: ${declared}. `) +
                 (example === undefined
                     ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
@@ -769,7 +772,7 @@ tools = tableForSurface(profile)) {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(buildErrorPayload(message, codedRefusalOf(error)), deps.peerSkew), advertisedNames)),
+                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(withRepeatHint(buildErrorPayload(message, codedRefusalOf(error)), error), deps.peerSkew), advertisedNames)),
                         },
                     ],
                 };

package/dist/surface/mcp/peer/agents-connected.d.ts

@@ -0,0 +1,6 @@
+/** The `AgentClient` values of every agent that has connected. Empty on a missing or broken file. */
+export declare function connectedAgentClients(stateDir: string): ReadonlySet<string>;
+/** Record that `client` (an `AgentClient` value) connected. Written once per client. */
+export declare function rememberAgentConnected(stateDir: string, client: string): void;
+/** `clientInfo.name` of an MCP `initialize` request line, or undefined for any other line. */
+export declare function initializeClientName(line: string): string | undefined;

package/dist/surface/mcp/peer/agents-connected.js

@@ -0,0 +1,58 @@
+/**
+ * Which coding agents have connected to Reticle on this machine, by name.
+ *
+ * `attach-memory.ts` records that SOME client attached on a port. It cannot say which one, so with
+ * two agents a healthy one hides a broken one. This record keeps the client that the MCP
+ * `initialize` handshake names, as its closed `AgentClient` value. It is machine wide, because the
+ * installer runs before there is a project and therefore before there is a port.
+ *
+ * The proxy writes it when the request arrives. It records a fact that happened, never an inference
+ * from a config file. Best-effort in both directions: a hint never breaks the client path.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const RECORD_FILE = 'agents-connected.json';
+const INITIALIZE_METHOD = 'initialize';
+/** The `AgentClient` values of every agent that has connected. Empty on a missing or broken file. */
+export function connectedAgentClients(stateDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(stateDir, RECORD_FILE), 'utf8'));
+        return new Set(Array.isArray(parsed) ? parsed.filter((v) => 'string' === typeof v) : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Record that `client` (an `AgentClient` value) connected. Written once per client. */
+export function rememberAgentConnected(stateDir, client) {
+    const known = connectedAgentClients(stateDir);
+    if (known.has(client)) {
+        return;
+    }
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, RECORD_FILE), JSON.stringify([...known, client]), 'utf8');
+    }
+    catch {
+        // An unwritable state home is reported elsewhere; it must not break the client path.
+    }
+}
+/** `clientInfo.name` of an MCP `initialize` request line, or undefined for any other line. */
+export function initializeClientName(line) {
+    try {
+        const msg = JSON.parse(line);
+        if ('object' !== typeof msg || null === msg) {
+            return undefined;
+        }
+        const { method, params } = msg;
+        if (INITIALIZE_METHOD !== method || 'object' !== typeof params || null === params) {
+            return undefined;
+        }
+        const info = params.clientInfo;
+        const name = 'object' === typeof info && null !== info ? info.name : undefined;
+        return 'string' === typeof name && 0 < name.length ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,6 +1,7 @@
 import * as net from 'node:net';
 import { LOOPBACK_HOST } from '@reticlehq/core';
-import { describePresence, presenceIsUsable, probePresence, PortPresence, } from '../../../command/daemon/binding/port-presence.js';
+import { presenceIsUsable, probePresence, PortPresence, } from '../../../command/daemon/binding/port-presence.js';
+import { describePortState } from '../../../command/daemon/port-state.js';
 import { fetchStatus } from '../../../command/daemon/binding/daemon-status-probe.js';
 import { isAlive, readPid } from '../../../command/daemon/daemon.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
@@ -21,6 +22,16 @@ function delay(ms) {
 export function daemonPollDelayMs(attempt) {
     return Math.min(DAEMON_POLL_INTERVAL_MS * attempt, DAEMON_POLL_MAX_INTERVAL_MS);
 }
+const CONNECTION_RESET = 'ECONNRESET';
+/**
+ * A loopback connect to a port with no listener is refused at once. A timeout means a listener
+ * whose queue is full because it accepts nothing: a daemon stuck in its exit (#1937). Read as
+ * "free", that made `status` say the port was free while a process held it.
+ *
+ * Not on Windows: it retries a refused loopback connect for about two seconds, so there a timeout
+ * is also what a free port gives.
+ */
+const TIMEOUT_MEANS_HELD = 'win32' !== process.platform;
 /**
  * Returns true if something is already listening on the reticle port.
  * Uses a plain TCP probe so we don't create a side-effectful SSE session
@@ -38,10 +49,11 @@ export function probeDaemon(port, host = LOOPBACK_HOST) {
             socket.destroy();
             resolve(true);
         });
-        socket.on('error', () => resolve(false));
+        // A reset is an answer from a listener, not "nothing listens".
+        socket.on('error', (err) => resolve(CONNECTION_RESET === err.code));
         socket.on('timeout', () => {
             socket.destroy();
-            resolve(false);
+            resolve(TIMEOUT_MEANS_HELD);
         });
         socket.connect(port, host);
     });
@@ -70,7 +82,7 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
             return;
         if (false === probes.alive?.()) {
             throw new Error(`the reticle daemon on port ${String(port)} exited before it was ready — ` +
-                describePresence(presence, port));
+                describePortState(presence, port));
         }
         attempt++;
         await delay(daemonPollDelayMs(attempt));
@@ -79,7 +91,7 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
     // means something is squatting the port. Reporting only the timeout sent readers hunting the
     // wrong one.
     throw new Error(`reticle daemon did not become ready on port ${String(port)} within ` +
-        `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePresence(presence, port)}`);
+        `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePortState(presence, port)}`);
 }
 /** True while the process in the daemon pid file for `port` runs. */
 export function daemonProcessAlive(port) {

package/dist/surface/mcp/shared-params.d.ts

@@ -33,3 +33,5 @@ export declare const SHARED_PARAM_GUIDANCE: string;
 export declare function sharedParamShort(name: string, schema: z.ZodTypeAny): string | undefined;
 /** Is this a parameter whose guidance now lives in the instructions block? */
 export declare function isSharedParam(name: string): boolean;
+/** The sentences that name the tool for each refused key, or an empty string. */
+export declare function refusedKeyRedirect(toolName: string, refused: readonly string[]): string;

package/dist/surface/mcp/shared-params.js

@@ -1,3 +1,4 @@
+import { ReticleTool } from '@reticlehq/core';
 /**
  * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
  *
@@ -48,3 +49,33 @@ export function sharedParamShort(name, schema) {
 export function isSharedParam(name) {
     return Object.hasOwn(SHARED_PARAM_SHORT, name);
 }
+/**
+ * Where to go when a tool refuses a parameter that another tool takes (#1944).
+ *
+ * An agent proved a click with `reticle_act_and_wait`, saw a request missing from the act's window,
+ * and asked for a wider window with `since`. The refusal listed what the tool declares and stopped
+ * there, so the agent did not learn that `reticle_assert` reads any window it is given. The refusal
+ * now names that tool.
+ *
+ * A lookup table, keyed by tool and then by the refused parameter. Add a row only where another
+ * tool really does what the refused parameter asked for.
+ */
+const REDIRECTS = {
+    [ReticleTool.ACT_AND_WAIT]: {
+        since: `${ReticleTool.ACT_AND_WAIT} always reads the window that its own action opens. To check a ` +
+            `window that starts earlier, call ${ReticleTool.ASSERT} { predicate, since } with the cursor ` +
+            'from an earlier result.',
+    },
+};
+/** The sentences that name the tool for each refused key, or an empty string. */
+export function refusedKeyRedirect(toolName, refused) {
+    const forTool = REDIRECTS[toolName];
+    if (forTool === undefined) {
+        return '';
+    }
+    return refused
+        .map((key) => (Object.hasOwn(forTool, key) ? forTool[key] : undefined))
+        .filter((line) => line !== undefined)
+        .map((line) => `${line} `)
+        .join('');
+}

package/dist/surface/tools/act/act-observation.d.ts

@@ -10,10 +10,12 @@
  * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
  * cut off mid-predicate.
  */
-import { type ReticleEvent } from '@reticlehq/core';
+import { type Drift, type ReticleEvent } from '@reticlehq/core';
 import type { Session } from '../../../portal/session/session.js';
-import { type SuccessorRegistry } from '../../../portal/session/session-successor.js';
+import { type SuccessorClock, type SuccessorRegistry } from '../../../portal/session/session-successor.js';
 import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate-eval.js';
+/** How long an act whose page navigated away waits for the lease's successor to connect. */
+export declare const NAVIGATION_FOLLOW_GRACE_MS = 8000;
 interface FollowSuccessor {
     sessions: SuccessorRegistry;
     session: Session;
@@ -24,12 +26,27 @@ interface FollowSuccessor {
     predicateStarted: number;
     /** Re-ask the declared consequence on `next`, with whatever budget is left. */
     reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
+    /**
+     * Grace for the OTHER navigation shape (#2009): a FAILURE graded while the action's own form
+     * POST / link navigation was still in flight. The wait spent its budget on the document BEFORE
+     * it left, so nothing was "lost" and no successor was looked for — and the verdict then reads
+     * "still on /login" for a sign-in that worked. When set, a failed verdict waits this long for
+     * the document's successor and re-asks there; when it never connects, the verdict says the page
+     * navigated instead of leaving the failure standing. Undefined keeps the old behaviour.
+     */
+    failedFollowGraceMs?: number;
+    /** The act's own event cursor: the window the departure evidence is read from. */
+    since?: number;
+    /** Injected so tests do not sleep; defaults to the real clock. */
+    clock?: SuccessorClock;
 }
 interface FollowedOutcome {
     session: Session;
     verdict: EvalResult;
     /** True when the wait moved to a new document, so the caller must reset its event cursor. */
     followed: boolean;
+    /** The re-ask ran on the caller's grace — a budget extension declared in the result (#2009). */
+    budgetExtendedMs?: number;
 }
 /**
  * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
@@ -56,8 +73,29 @@ export declare function disabledTargetNote(pass: boolean, actResult: unknown): s
  * failure, whichever way the consequence went.
  */
 export declare function unreachableTargetNote(actResult: unknown): string | undefined;
+/**
+ * The drift for the first sub-step of an `ACT_SEQUENCE` result whose target no person could have
+ * clicked, or undefined. The page reports one effect for each sub-step it ran, in order. Synthetic
+ * dispatch reaches an unreachable target all the same, so a sequence is read sub-step by sub-step, as
+ * a single act is. `labelOf` names the sub-step, by its index in this result.
+ */
+export declare function unreachableSubStepDrift(sequenceResult: unknown, labelOf: (at: number) => string): Drift | undefined;
 /** Why the acted target leaves the verdict undecided: no person could reach it, or it was disabled. */
 export declare function actTargetNote(pass: boolean, actResult: unknown): string | undefined;
+/**
+ * The cause and the one fix for a read that came back `unknown`, in place of a bare fact (#1990).
+ * A page whose SDK is behind this daemon may not serve `match` at all, so the fix is the same
+ * SDK-behind sentence the listing shows. On a current page the read ran out of the assertion's own
+ * budget, and the fix is more of it. Any reason that is not a command timeout is returned as it came.
+ */
+export declare function diagnoseTimeout(reason: string | undefined, session: {
+    readonly sdkVersion?: string | undefined;
+}): string | undefined;
+/** Why an act's verdict is `unknown`: a read that timed out, else an unreachable or disabled target. */
+export declare const actInconclusive: (verdict: {
+    pass: boolean;
+    inconclusive?: string | undefined;
+}, actResult: unknown, session: Session) => string | undefined;
 /**
  * The requests of a failed check's window, as its record carries them: method, url, status and the
  * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.