@reticlehq/server 3.1.0 → 3.3.0

package/dist/portal/session/session.js

@@ -1,58 +1,33 @@
+import { asProjectId } from '@reticlehq/core';
 import { refusedResult } from './page-commands/undeclared-command.js';
 import { recordImpact } from '../../memory/impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { commandTimeoutMessage } from './timing/command-timeout.js';
-import { readHealthEvent, pendingNavigationMs } from './session-health.js';
+import { readHealthEvent, healthNotices } from './session-health.js';
 import { MIRRORED_COMMANDS, mirroredNarration } from './presence/session-mirror.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
 const IMPACT_PUSH_DEBOUNCE_MS = 700;
 import { PendingCommands, CommandTimeoutError } from './page-commands/pending-commands.js';
 import { span } from '../../trace.js';
 import { keepCallerContextInDaemon, noteToDaemonLog } from './daemon-answers.js';
-import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
-import { filterEvents, mergeEventsBySeq, } from '../../memory/journal/journal-query.js';
+import { readJournalWriteLoss, readQueryEvents, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
 import { ObservedState } from './facts/observed-state.js';
-import { recordBrowserLatency, recordSdkFailure } from '../../telemetry/session-metrics.js';
+import { recordBrowserLatency, recordHudUse, recordSdkFailure, } from '../../telemetry/session-metrics.js';
 import { LiveControl } from './human/live-control.js';
 import { ReviewStore } from './human/review-store.js';
 import { buildSessionRecommendation } from './presence/session-recommendation.js';
 import { buildPresenterArgs } from './human/presenter-args.js';
 import { buildSessionLease } from './presence/session-lease.js';
 import { buildSessionInfo } from './session-info.js';
+import { MAX_SUCCESSOR_HOPS, REBINDABLE_COMMANDS } from './rebind.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
-/**
- * Commands that may be re-issued against the connection that replaced this session.
- *
- * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
- * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
- * page that went away, and performing it a second time behind the caller's back is a double submit
- * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
- * which is still the right one — is the safe path.
- */
-/**
- * How far to walk a chain of replacements before giving up.
- *
- * Generous for the real case (a page reloading a handful of times while a call is in flight) and
- * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
- * than this means something is re-dialling in a loop, and that is a different problem.
- */
-const MAX_SUCCESSOR_HOPS = 32;
-const REBINDABLE_COMMANDS = new Set([
-    ReticleCommand.SNAPSHOT,
-    ReticleCommand.QUERY,
-    ReticleCommand.MATCH,
-    ReticleCommand.INSPECT,
-    ReticleCommand.STATE_READ,
-    ReticleCommand.STORAGE_READ,
-    ReticleCommand.CAPABILITIES,
-    ReticleCommand.ANIMATIONS,
-]);
 /** Prefix on minted action ids (a1, a2, …) — the journal's action identity, independent of commands. */
 const ACTION_ID_PREFIX = 'a';
 /**
@@ -69,7 +44,13 @@ const WS_OPEN = 1;
  */
 export class Session {
     id;
-    /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
+    /**
+     * Stable build-stamped project identity; undefined for SDKs old enough to omit it.
+     *
+     * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
+     * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
+     * downstream reader takes the brand from this property rather than re-blessing a string.
+     */
     projectId;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
@@ -82,6 +63,11 @@ export class Session {
      * root, which is what every counter did unconditionally before this existed.
      */
     artifactRoot;
+    /**
+     * Same-origin endpoints this session's project declared as background (`.reticle.json`
+     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
+     */
+    background = [];
     url;
     title;
     adapters;
@@ -145,7 +131,7 @@ export class Session {
     #editEpoch;
     constructor(hello, socket, clock) {
         this.id = hello.sessionId;
-        this.projectId = hello.projectId;
+        this.projectId = hello.projectId === undefined ? undefined : asProjectId(hello.projectId);
         this.url = hello.url;
         this.title = hello.title;
         this.adapters = hello.adapters;
@@ -207,17 +193,16 @@ export class Session {
     }
     /** The attachable health block — single source of truth for the tools. */
     health() {
-        // From event t=0, not a cursor: a wedge that began before the current action is exactly the
-        // case a per-window reading cannot see, and is the one both reporters hit.
-        const stuck = pendingNavigationMs(this.eventsSince(0), this.elapsed());
         const base = {
             lastSeenMs: this.lastSeenMs(),
             throttled: this.throttled(),
             focused: this.#focused,
-            ...(stuck === undefined ? {} : { pendingNavigationMs: stuck }),
             // Carried onto every act/assert result, not just reticle_sessions: skew drops actions
             // SILENTLY, and the fields it contradicts are on the act verdict.
             ...(this.versionSkew === undefined ? {} : { versionSkew: this.versionSkew }),
+            // The absence-gated facts: a stuck navigation and an ledger worth naming. Both are absent on
+            // a healthy session, and `healthNotices` owns which is which.
+            ...healthNotices(this.eventsSince(0), this.elapsed(), this.#journalReader?.ledger?.()),
         };
         // attach the escape-hatch hint only when un-scriptable (keeps field absent otherwise).
         const recommendation = buildSessionRecommendation({
@@ -280,6 +265,14 @@ export class Session {
     keepCallerContext = keepCallerContextInDaemon;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event, byteSize) {
+        // Telemetry about the HUD, not evidence about the app: taken off here, before the buffer, so no
+        // verdict, settle window or agent read can ever see a person's clicks on Reticle's own panel.
+        if (event.type === EventType.HUD_USED) {
+            const use = HudUseDataSchema.safeParse(event.data);
+            if (use.success)
+                recordHudUse(use.data);
+            return;
+        }
         if (event.documentId !== undefined)
             this.#documentId = event.documentId;
         if (event.editEpoch !== undefined)
@@ -408,17 +401,16 @@ export class Session {
         this.#journalReader = reader;
     }
     /**
-     * Journal-backed event query: the ring buffer's events, merged with the durable journal **only when
-     * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by since/until/
-     * actionId. This is how "what did action N cause" is answered after the buffer has dropped the
-     * evidence — the substrate's whole point. The sync `eventsSince`/`window` stay for the hot path.
+     * Journal-backed event query — the rule itself lives in `readQueryEvents`, beside the merge and
+     * filter it is made of. This is how "what did action N cause" is answered after the buffer has
+     * dropped the evidence. The sync `eventsSince`/`window` stay for the hot path.
      */
     async queryEvents(options) {
-        if (this.#journalReader !== undefined && this.#buffer.bufferHealth().dropped > 0) {
-            const durable = await this.#journalReader.readEvents();
-            return filterEvents(mergeEventsBySeq(durable, this.#buffer.since(0)), options);
-        }
-        return filterEvents(this.#buffer.since(options.since ?? 0), options);
+        return readQueryEvents(this.#journalReader, this.#buffer, options);
+    }
+    /** What the durable ledger could not WRITE — see `readJournalWriteLoss` for the rule and why. */
+    async journalWriteLoss() {
+        return readJournalWriteLoss(this.#journalReader, this.#buffer);
     }
     /**
      * Open an action-attribution window: events observed until finishAction attribute to the returned
@@ -541,12 +533,19 @@ export class Session {
         return this.#buffer.bufferHealth();
     }
     /**
-     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
      * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
-     * moves for the age and churn evictions that every live page produces continuously.
+     * moves for the age and churn evictions that every live page produces continuously. The journal is
+     * the other half of that store, so a durable read that could not reach back to `cursor` lost
+     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+     * conservative direction, both times.
      */
     lostSince(cursor) {
-        return this.#buffer.lostSince(cursor);
+        if (this.#buffer.lostSince(cursor))
+            return true;
+        const lost = this.#journalReader?.readLoss?.();
+        return lost !== undefined && (lost.lostThroughT === undefined || lost.lostThroughT >= cursor);
     }
     onEvent(listener) {
         this.#listeners.add(listener);

package/dist/status-payload.d.ts

@@ -19,12 +19,23 @@ interface StatusPayload {
      * beside a live session.
      */
     why?: string;
+    /**
+     * The same diagnosis with the differential left off: the lead and the next action.
+     *
+     * Two fields because there are two readers. `why` is for an agent about to spend a drive on a
+     * guess, and carries the ranked causes, the port-scan caveat and the lease offer. `whyLead` is
+     * for a surface a PERSON reads: `reticle init` prints the daemon's account of a failed connect,
+     * and was printing roughly five hundred words of it in one paragraph.
+     */
+    whyLead?: string;
     /** Port of the verify HTTP endpoint this daemon serves — present only when started with `--http`. */
     verifyPort?: number;
 }
 export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why?: string, verifyPort?: number): StatusPayload;
+why?: string, verifyPort?: number, 
+/** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
+whyLead?: string): StatusPayload;
 /**
  * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
  * that daemon already serves the verify HTTP endpoint on the wanted port.

package/dist/status-payload.js

@@ -2,7 +2,9 @@ import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './command/version/identity/server-version.js';
 export function statusPayload(sessionCount, sessions, 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why, verifyPort) {
+why, verifyPort, 
+/** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
+whyLead) {
     return {
         running: true,
         version: SERVER_VERSION,
@@ -12,6 +14,7 @@ why, verifyPort) {
         // Only when there is nothing to explain away: a diagnosis printed beside a live session would
         // contradict it.
         ...(0 === sessionCount && why !== undefined ? { why } : {}),
+        ...(0 === sessionCount && whyLead !== undefined ? { whyLead } : {}),
         ...(verifyPort === undefined ? {} : { verifyPort }),
     };
 }

package/dist/surface/http-server.js

@@ -4,7 +4,6 @@ import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, DRIVE_
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
 import { log } from '../log.js';
-import { reportMcpConnected } from '../telemetry/mcp-connection.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from '../portal/bridge/token-auth.js';
 import { LOOPBACK_IDLE_MS } from './loopback-agent.js';
 /**
@@ -177,10 +176,9 @@ export function createSharedServer(options = {}) {
                 .connect(transport)
                 .then(() => {
                 log('mcp_client_connected', { sessionId: sid });
-                // The one signal that separates "Reticle is running" from "somebody is USING it": a daemon
-                // can sit up for days with nothing attached. It also exposes reconnect churn, which is
-                // indistinguishable from healthy usage in every other metric.
-                reportMcpConnected();
+                // The telemetry for this moved to `oninitialized`, where the client has said its name.
+                // An SSE stream that opens here and never handshakes is a probe, not a client, and
+                // reporting it from this point produced a row that could never name who attached.
             })
                 .catch((err) => {
                 const message = err instanceof Error ? err.message : String(err);

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

@@ -6,7 +6,8 @@
  * often does a real user's MCP server go down, and does it come back — had no answer outside the
  * machine it happened on.
  *
- * Capped at two events per proxy process, and the cap is the design rather than a limitation. One
+ * Capped at one benign and one fault event PER STAGE per proxy process, and the cap is the design
+ * rather than a limitation. One
  * measured afternoon produced 547 proxy reconnects; an event per reconnect would bill for the
  * pathology instead of measuring it, which is the same mistake the per-call `tool` event made before
  * it was removed. What a dashboard needs is the SHARE OF SESSIONS that lose MCP at all (the first

package/dist/surface/mcp/faults/mcp-outage.js

@@ -6,7 +6,8 @@
  * often does a real user's MCP server go down, and does it come back — had no answer outside the
  * machine it happened on.
  *
- * Capped at two events per proxy process, and the cap is the design rather than a limitation. One
+ * Capped at one benign and one fault event PER STAGE per proxy process, and the cap is the design
+ * rather than a limitation. One
  * measured afternoon produced 547 proxy reconnects; an event per reconnect would bill for the
  * pathology instead of measuring it, which is the same mistake the per-call `tool` event made before
  * it was removed. What a dashboard needs is the SHARE OF SESSIONS that lose MCP at all (the first
@@ -28,6 +29,19 @@ const KNOWN_REASONS = new Set(Object.values(OutageReason));
 function outageReason(raw) {
     return KNOWN_REASONS.has(raw) ? raw : OutageReason.OTHER;
 }
+/**
+ * The daemon retiring on schedule is not a fault, and it is by far the commonest drop.
+ *
+ * Kept as the CLASS rather than the reason itself, because the cap is keyed on it: one benign drop
+ * and one fault per stage, not one event per reason. Keying on the reason would put the volume the
+ * cap exists to prevent straight back — a flapping proxy has several reasons available to it and
+ * would bill for each of them — while keying on the stage alone is what let a scheduled shutdown at
+ * minute one permanently suppress a real outage at minute forty, biasing the metric toward exactly
+ * the rows `daemon_shutdown` was introduced to exclude.
+ */
+function isBenign(reason) {
+    return OutageReason.DAEMON_SHUTDOWN === reason;
+}
 const reported = new Set();
 /** Reset between tests; a real process reports each stage at most once. */
 export function resetOutageReporting() {
@@ -39,13 +53,15 @@ export function resetOutageReporting() {
  * fails — the reconnect it is describing.
  */
 export function reportMcpOutage(stage, facts) {
-    if (reported.has(stage))
+    const reason = outageReason(facts.reason);
+    const slot = `${stage}:${isBenign(reason) ? 'benign' : 'fault'}`;
+    if (reported.has(slot))
         return;
-    reported.add(stage);
+    reported.add(slot);
     void getTelemetry().emit(TelemetryEventKind.MCP_CONNECTION_LOST, {
         outage: {
             stage,
-            reason: outageReason(facts.reason),
+            reason,
             attempts: facts.attempts,
             // Always sent, including zero: zero is the finding — a drop no agent could feel. See
             // McpOutageSchema.pendingLost.

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

@@ -107,4 +107,13 @@ export declare function startMcpProxy(port: number,
  */
 ensureDaemon?: () => Promise<void>, 
 /** Observe the real shutdown boundary in transport tests without terminating their worker. */
-exitProcess?: (code: number) => void): Promise<never>;
+exitProcess?: (code: number) => void, 
+/**
+ * Tell the resilience layer this session proved itself usable.
+ *
+ * The same `endpoint` frame that earns a fresh retry budget below also clears the disconnect-storm
+ * counter, and for the same reason: response headers are produced by a daemon that accepts SSE and
+ * drops it, and an `endpoint` frame is not. Optional, because a transport test drives this
+ * function with no resilience installed.
+ */
+onUsableSession?: () => void): Promise<never>;

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

@@ -10,9 +10,9 @@ export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
 import { probeDaemon } from './proxy/proxy-daemon-probe.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
 import { buildServerInstructions } from './server-instructions.js';
-import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
+import { hasAnyProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
-import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { projectIdsAt } from '../../command/cli/ports/resolve/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } 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';
@@ -22,7 +22,7 @@ import { flushProxySessionMetrics } from '../../telemetry/proxy-telemetry.js';
  * 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 '../../command/cli/launch/cli-launch.js';
+import { fetchStatus as fetchDaemonStatus } from '../../command/daemon/binding/daemon-status-probe.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.
@@ -289,7 +289,7 @@ export function buildSessionUrl(rawData, port) {
 function proxyInstructions(port) {
     try {
         return buildServerInstructions({
-            previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd())),
+            previouslyConnected: hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())),
         });
     }
     catch {
@@ -304,7 +304,16 @@ export function startMcpProxy(port,
  */
 ensureDaemon, 
 /** Observe the real shutdown boundary in transport tests without terminating their worker. */
-exitProcess = (code) => process.exit(code)) {
+exitProcess = (code) => process.exit(code), 
+/**
+ * Tell the resilience layer this session proved itself usable.
+ *
+ * The same `endpoint` frame that earns a fresh retry budget below also clears the disconnect-storm
+ * counter, and for the same reason: response headers are produced by a daemon that accepts SSE and
+ * drops it, and an `endpoint` frame is not. Optional, because a transport test drives this
+ * function with no resilience installed.
+ */
+onUsableSession = () => undefined) {
     return new Promise((_resolve, reject) => {
         // A client just started us, which is the only honest evidence that Reticle is registered with
         // one at all: a config entry proves somebody wrote JSON, not that a client ever read it. Paired
@@ -452,13 +461,11 @@ exitProcess = (code) => process.exit(code)) {
                 const msg = parseJsonRpc(line);
                 if (null === msg || msg.id === undefined || !pending.take(msg.id))
                     return;
-                if (failure.transport) {
-                    reportMcpOutage(OutageStage.FIRST, {
-                        reason: OutageReason.CONNECT_ERROR,
-                        attempts: failure.attempts,
-                        pendingLost: 1,
-                    });
-                }
+                // No outage is reported here, deliberately. A POST leg that died while the SSE stream is
+                // still up is not the agent losing its tools: `postSocketFailures` on the session summary
+                // already counts it, and reporting it as a lost stream both double-counted and — because
+                // the outage cap is per process — let a transient POST failure in the first minute suppress
+                // the real stream outage in the fortieth.
                 proxyLog('reticle_mcp_proxy_post_unanswered', {
                     port,
                     method: String(msg.method),
@@ -490,6 +497,10 @@ exitProcess = (code) => process.exit(code)) {
                     reportMcpOutage(OutageStage.RECOVERED, { reason: lastDropReason, attempts: cost });
                 attempts = 0;
                 attemptsBeforeDormant = 0;
+                // The disconnects behind us were reconnects, not a runaway. Counting them for the life of
+                // the process made twenty daemon restarts over a working week indistinguishable from twenty
+                // in eight seconds, and the proxy left on the former.
+                onUsableSession();
                 // 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.
                 for (const line of replay.replayLines())

package/dist/surface/mcp/mcp.d.ts

@@ -12,7 +12,16 @@ export declare const CALL_TOOL_METHOD = "tools/call";
  * Non-session-bound tools (and tools with no outputSchema) are returned unchanged.
  */
 export declare function withSessionEnvelope(name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
-export declare function firstSentence(description: string): string;
+/**
+ * Abbreviations whose internal period is NOT a sentence end.
+ *
+ * The splitter looked for the first `". "`, which "e.g. " satisfies — so every lean-profile
+ * description containing one was cut off mid-abbreviation. `reticle_act`'s ref parameter reached the
+ * agent as "Element ref from reticle_snapshot or reticle_query (e.g." and stopped: the example gone,
+ * and any contract stated after it gone too. Silent, and it degraded the DEFAULT profile only, which
+ * is the one nobody reads the raw strings for.
+ */
+export { firstSentence } from '../tools/first-sentence.js';
 /**
  * Serialize a tool result to the MCP `text` content block. The agent consumes this text — the
  * typed contract travels separately as `structuredContent`, unchanged by encoding — so the text

package/dist/surface/mcp/mcp.js

@@ -36,6 +36,7 @@ import { log } from '../../log.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
 import { setMcpClientNameHook } from '../../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
+import { reportMcpConnected } from '../../telemetry/mcp-connection.js';
 import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
@@ -70,16 +71,9 @@ function withExample(description, example) {
  * and any contract stated after it gone too. Silent, and it degraded the DEFAULT profile only, which
  * is the one nobody reads the raw strings for.
  */
-const ABBREVIATIONS = ['e.g.', 'i.e.', 'etc.', 'vs.', 'cf.'];
-export function firstSentence(description) {
-    const nl = description.indexOf('\n');
-    const base = nl >= 0 ? description.slice(0, nl) : description;
-    // Mask abbreviations with an equal-length filler so offsets stay valid in the original string.
-    const masked = ABBREVIATIONS.reduce((text, abbr) => text.split(abbr).join('\u0000'.repeat(abbr.length)), base);
-    const dot = masked.search(/\.\s/);
-    const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
-    return sentence.length > 160 ? `${sentence.slice(0, 159)}…` : sentence;
-}
+// Re-exported because callers (and `mcp.test.ts`) have imported it from here since it lived here.
+export { firstSentence } from '../tools/first-sentence.js';
+import { firstSentence } from '../tools/first-sentence.js';
 /**
  * Parameters carrying the recursive predicate grammar. Advertised compactly in lean profiles.
  *
@@ -124,8 +118,8 @@ const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of e
  * paying for six.
  */
 const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
-    'net.bodyContains (a substring of what the SERVER answered — catches a UI that echoes the input ' +
-    'it sent instead of the result it got back), net.requestBodyMatches (a shallow JSON match on what ' +
+    'net.bodyMatches (a shallow JSON match on what the SERVER answered — say the FIELD and its value, ' +
+    'because a substring of the body matches key names too), net.requestBodyMatches (the same on what ' +
     'the UI SENT — the verdict for "applying this filter actually puts it in the payload"), ' +
     '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 ' +
@@ -218,21 +212,33 @@ tools = tableForSurface(surface)) {
     const shipped = new Set(tableForSurface(surface).map((tool) => tool.name));
     const ours = tools.filter((tool) => shipped.has(tool.name));
     const theirs = tools.filter((tool) => !shipped.has(tool.name));
-    // The `merged` surface keeps `reticle_tools` and drops `reticle_run`, which is not symmetry for
-    // its own sake. `reticle_run` exists to DISPATCH to a tool the surface does not advertise, and
-    // this surface advertises everything, so it has no job left. `reticle_tools` has a second job that
-    // survives: every input schema on a trimmed surface is LEAN, and `{ names: [...] }` is the only
-    // way to get a tool's full parameters — which matters more here than anywhere, because a merged
-    // tool's schema is the union of its members' fields with all of them optional. Recovery messages
-    // across this server also say "Call reticle_tools", and a surface without it turns that advice
-    // into a dead end (see surface-sizes.test.ts).
-    // A surface with no `reticle_run` can invoke only what it advertises, so the catalogue is told to
-    // list exactly that. Anything else is a menu of names the agent cannot order from.
+    /*
+     * `merged` used to drop `reticle_run`, on the reasoning that the hatch "exists to DISPATCH to a
+     * tool the surface does not advertise, and this surface advertises everything, so it has no job
+     * left".
+     *
+     * THE PREMISE WAS FALSE, and it had been false for some time. `MERGED_TOOL_NAMES` is
+     * `CORE_TOOL_NAMES` minus the merged-away names plus `LOOK`; `EXTENDED_TOOL_NAMES` — screenshot,
+     * visual diff, clock, network mock, storage, record, the flow pair, intent, context, capabilities
+     * — is not in it. So eleven registered tools were advertised by nothing, callable by nothing, and
+     * catalogued by nothing: `reticle_tools { names: ["reticle_screenshot"] }` answered `unknown
+     * tool`, on a build where the tool exists and is registered.
+     *
+     * The extended set's own comments say each demoted tool is "still one `reticle_run` hop from any
+     * agent that wants it". That is the trade the demotion was justified by, and dropping the hatch
+     * silently cancelled the half of it we owed the caller. One of the casualties was
+     * `reticle_visual_diff`, which covers the only bug class the registry marks as one Reticle cannot
+     * otherwise see.
+     *
+     * So the hatch stays, and the catalogue lists everything the hatch can reach. `reticle_tools`
+     * keeps its second job either way: every input schema on a trimmed surface is LEAN, and
+     * `{ names: [...] }` is the only way to get full parameters — which matters most here, because a
+     * merged tool's schema is the union of its members' fields with all of them optional. Recovery
+     * messages across this server also say "Call reticle_tools", and a surface without it turns that
+     * advice into a dead end (see surface-sizes.test.ts).
+     */
     const advertisedHere = filterTools([...ours], surface);
-    const callable = surface === TOOL_SURFACE.MERGED
-        ? new Set([...advertisedHere, ...theirs].map((tool) => tool.name))
-        : undefined;
-    const meta = buildDynamicTools([...tools], origin, callable).filter((tool) => surface !== TOOL_SURFACE.MERGED || tool.name !== ReticleTool.RUN);
+    const meta = buildDynamicTools([...tools], origin, undefined);
     return [...advertisedHere, ...theirs, ...meta];
 }
 /**
@@ -512,8 +518,14 @@ tools = tableForSurface(profile)) {
      */
     server.server.oninitialized = () => {
         const info = server.server.getClientVersion();
-        if (info?.name !== undefined)
-            getSessionMetrics().recordClient(info.name, info.version);
+        if (info?.name === undefined)
+            return;
+        getSessionMetrics().recordClient(info.name, info.version);
+        // The one signal that separates "Reticle is running" from "somebody is USING it", reported from
+        // the first moment it can carry WHO. It used to fire from the SSE `connect()` resolution, which
+        // happens before the handshake — so every connect row was anonymous, and the field meant to say
+        // which agent client converts best was empty on every event ever sent.
+        reportMcpConnected(info.name);
     };
     // Which agent is on the other end, for a feedback report. Registered as a lazy hook rather than
     // read here: the handshake has not happened yet at construction time, and a report filed twenty
@@ -540,7 +552,25 @@ tools = tableForSurface(profile)) {
     const advertised = advertisedTools(profile, tools);
     // The names this surface actually hands the agent. Every piece of advice leaving this server is
     // rewritten against it, so a static string cannot route a reader to a tool they were not given.
-    const advertisedNames = new Set(advertised.map((tool) => tool.name));
+    /**
+     * What a name in advice can actually REACH, which is not the same as what is advertised.
+     *
+     * `liveCallText` rewrites mentions of tools this surface cannot reach — it exists because advice
+     * naming `reticle_flow_save` on a surface without it sent agents at a tool that answered "not
+     * reachable on this tool surface". Gated on the ADVERTISED set, it kept firing once the dispatch
+     * hatch came back: `reticle_flow_save` and `reticle_record` are reachable through
+     * `reticle_run` but not advertised, so every mention of them — INCLUDING their own names and the
+     * parameter docs that name the recording to save — was rewritten to
+     * `reticle_verify { action: "explore", persona }`. Two tools with the same wrong name, and a
+     * `flowName` description telling the reader to pass the name that a tool which is not the one
+     * they called was called with.
+     *
+     * With a hatch, every registered tool is reachable and no rewriting is owed. Without one,
+     * advertised IS reachable, which is the case this was written for.
+     */
+    const advertisedNames = advertised.some((tool) => ReticleTool.RUN === tool.name)
+        ? new Set(tools.map((tool) => tool.name))
+        : new Set(advertised.map((tool) => tool.name));
     installFriendlyArgErrors(server, new Map(advertised
         .filter((tool) => tool.example !== undefined)
         .map((tool) => [tool.name, JSON.stringify(tool.example)])), 

package/dist/surface/mcp/proxy/proxy-daemon-probe.d.ts

@@ -5,5 +5,18 @@ export declare function daemonPollDelayMs(attempt: number): number;
  * inside the daemon just to check reachability.
  */
 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>;
+/**
+ * Poll until a Reticle daemon is SERVING on `port`, or the deadline passes.
+ *
+ * "Accepts a TCP connection" is not the question. A daemon wedged mid-start accepts and never
+ * serves, and so does a stranger holding the port — `port-presence.ts` calls both FOREIGN for
+ * exactly this reason, and every other decision point in the codebase was migrated onto it. This
+ * one was not, so the wake path spawned a daemon, waited on a bare connect, and dialled a corpse.
+ *
+ * Probes are injected (defaulting to the real pair) so the rule is testable without a socket, which
+ * is the same shape `probePresence`'s own callers use.
+ */
+export declare function waitForDaemon(port: number, probes?: {
+    tcpOpen: (port: number) => Promise<boolean>;
+    status: (port: number) => Promise<unknown>;
+}): Promise<void>;

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

@@ -1,5 +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 { fetchStatus } from '../../../command/daemon/binding/daemon-status-probe.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
@@ -39,16 +41,31 @@ export function probeDaemon(port) {
         socket.connect(port, LOOPBACK_HOST);
     });
 }
-/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
-export async function waitForDaemon(port) {
+/**
+ * Poll until a Reticle daemon is SERVING on `port`, or the deadline passes.
+ *
+ * "Accepts a TCP connection" is not the question. A daemon wedged mid-start accepts and never
+ * serves, and so does a stranger holding the port — `port-presence.ts` calls both FOREIGN for
+ * exactly this reason, and every other decision point in the codebase was migrated onto it. This
+ * one was not, so the wake path spawned a daemon, waited on a bare connect, and dialled a corpse.
+ *
+ * Probes are injected (defaulting to the real pair) so the rule is testable without a socket, which
+ * is the same shape `probePresence`'s own callers use.
+ */
+export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, status: fetchStatus }) {
     const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
     let attempt = 0;
+    let presence = PortPresence.FREE;
     while (Date.now() < deadline) {
-        const reachable = await probeDaemon(port);
-        if (reachable)
+        presence = await probePresence(port, probes);
+        if (presenceIsUsable(presence))
             return;
         attempt++;
         await delay(daemonPollDelayMs(attempt));
     }
-    throw new Error(`reticle daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
+    // The state we timed out in is the whole diagnosis — FREE means the daemon never came up, FOREIGN
+    // 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)}`);
 }