@reticlehq/server 3.2.0 → 3.4.0

package/dist/portal/session/session-manager.js

@@ -3,7 +3,7 @@ import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
-import { pickDocumentSuccessor } from './session-successor.js';
+import { openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
 import { SESSION_DISCONNECTED_REASON } from './facts/session-replaced.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
@@ -87,6 +87,8 @@ export class SessionManager {
      * id forgets its tombstone — the live session is the answer then.
      */
     #tombstones = new Map();
+    /** The tabs already open when each tombstoned session departed: siblings, never its successor. */
+    #siblingsAtDeparture = new Map();
     /**
      * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
      * without passing its own scope, this is applied — so auto-selection is project-scoped by default
@@ -128,6 +130,7 @@ export class SessionManager {
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
         this.#tombstones.delete(session.id);
+        this.#siblingsAtDeparture.delete(session.id);
         return previous;
     }
     /**
@@ -158,6 +161,9 @@ export class SessionManager {
             return;
         if (this.#tombstones.has(session.id))
             this.#tombstones.delete(session.id);
+        this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
+            .filter((s) => s !== session && openedBeforeDeparture(s, session))
+            .map((s) => s.id)));
         this.#tombstones.set(session.id, {
             id: session.id,
             url: session.url,
@@ -168,13 +174,17 @@ export class SessionManager {
             if (oldest === undefined)
                 break;
             this.#tombstones.delete(oldest);
+            this.#siblingsAtDeparture.delete(oldest);
         }
     }
     #successorOf(sessionId) {
         const departed = this.#tombstones.get(sessionId);
         if (departed === undefined)
             return undefined;
-        const picked = pickDocumentSuccessor(this.all().map((s) => ({
+        const siblings = this.#siblingsAtDeparture.get(sessionId);
+        const picked = pickDocumentSuccessor(this.all()
+            .filter((s) => true !== siblings?.has(s.id))
+            .map((s) => ({
             id: s.id,
             url: s.url,
             ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
@@ -186,6 +196,17 @@ export class SessionManager {
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
+    /**
+     * Did this id belong to a session that has since disconnected?
+     *
+     * `resolve` answers a departed id with its live SUCCESSOR, which is what keeps a reload working
+     * for everything that observes. A caller that is about to do something DESTRUCTIVE needs the
+     * other answer: whether the thing it named is still there. Ending a session it did not name is
+     * not a recoverable mistake (#983).
+     */
+    departed(sessionId) {
+        return this.#tombstones.get(sessionId);
+    }
     list() {
         return [...this.#sessions.values()].map((s) => {
             const info = s.info();
@@ -304,9 +325,15 @@ export class SessionManager {
     everConnected() {
         return this.#everConnected;
     }
-    /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
-    noteClosure(reason, at) {
-        this.#recentClosures.push({ at, reason });
+    /**
+     * Record a bridge-initiated close so `resolve` can explain a session that vanished.
+     *
+     * `page` is what the refused hello said about itself, when it said anything. A refusal is the one
+     * piece of positive evidence the no-session diagnosis has, and "a page was refused" without WHICH
+     * page leaves the reader unable to tell their app from another project's tab on the same port.
+     */
+    noteClosure(reason, at, page) {
+        this.#recentClosures.push({ at, reason, ...(page === undefined ? {} : { page }) });
         if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES)
             this.#recentClosures.shift();
         this.#connectedSinceLastClosure = false;
@@ -491,6 +518,16 @@ export class SessionManager {
         const allThrottled = bestScore >= 1;
         const RECENCY_GAP_MS = allThrottled ? 0 : 1_000;
         const clearWinner = runnerUp === undefined || best.ms + RECENCY_GAP_MS < runnerUp.ms;
+        // Healthy tabs heartbeat on the same cadence, so the recency gap between two of them is noise.
+        // When exactly one has the window focus it is the one a human is looking at: tabs piled up one
+        // per `init` run, and every tool called without a sessionId was refused while one of them was
+        // plainly the tab in front. Only among healthy ones — focus says nothing about a wedged tab.
+        const focused = allThrottled ? [] : candidates.filter((x) => x.s.health().focused);
+        const [onlyFocused, secondFocused] = focused;
+        if (!clearWinner && onlyFocused !== undefined && secondFocused === undefined) {
+            onlyFocused.s.markAgentActivity();
+            return onlyFocused.s;
+        }
         if (!clearWinner) {
             // Ambiguous: list sessions with their health so the agent can choose.
             const detail = all

package/dist/portal/session/session-reaper.d.ts

@@ -22,6 +22,34 @@ export declare function composeEndedNotice(base: string, undelivered: string[]):
  * not a crash, since the agent is still connected and revives on its next action. Returns the ids.
  */
 export declare function reapIdleSessions(sessions: SessionManager): string[];
+/**
+ * Drop sessions that have ENDED, gone quiet and lost their socket, so a listing stops offering them.
+ *
+ * `reticle_session { action: "end" }` sets state and nothing else -- it never calls
+ * `sessions.remove`. `SessionManager.list()` does not filter by state, and `reapIdleSessions`
+ * above skips ended sessions by design. The only code path in the whole server that removes a
+ * session is the socket `close` handler in bridge.ts. So an ended session whose socket is already
+ * gone has nothing left that can remove it, and the row is listed for the life of the daemon
+ * (#938).
+ *
+ * That is what the field report describes: `{ ended: true }` three times, the row back on the next
+ * `reticle_sessions` call each time, still there after every tab on the origin was closed, 17 hours
+ * attached. And Reticle's own advice for a stale session is
+ * `Call reticle_session{action:"end"} to free this session` -- which is the one thing that does not
+ * free it.
+ *
+ * Deliberately NOT "remove on end". The panel is client-side, so `setState` has already pushed the
+ * ended state to the browser and the HUD keeps it; but `end` is documented idempotent, and removing
+ * immediately would make a second call fail to resolve. Waiting for the session to go quiet keeps
+ * that, keeps a just-ended session inspectable, and still collects the case that actually hurts: a
+ * row nobody can get rid of.
+ *
+ * Only once the socket is no longer open. An ended session whose tab is still connected but quiet
+ * belongs to a page that holds a live connection; dropping the record would orphan that socket,
+ * leaving a connection the daemon no longer tracks. Such a session is still removed the ordinary
+ * way, by the `close` handler, when the tab goes.
+ */
+export declare function reapEndedSessions(sessions: SessionManager, staleAfterMs?: number): string[];
 /** End every active session immediately (the agent / MCP client disconnected → WARN). Returns ended ids. */
 export declare function endAllSessions(sessions: SessionManager, reason: string): string[];
 /**

package/dist/portal/session/session-reaper.js

@@ -1,4 +1,4 @@
-import { PresenterTone, SESSION_LIFECYCLE, UNDELIVERED_NOTES_LABEL } from '@reticlehq/core';
+import { PresenterTone, SESSION_LEASE, SESSION_LIFECYCLE, UNDELIVERED_NOTES_LABEL, } from '@reticlehq/core';
 import { log } from '../../log.js';
 /**
  * Server-authoritative session liveness. The browser idle timer is throttled in a backgrounded tab
@@ -51,6 +51,50 @@ export function reapIdleSessions(sessions) {
         log('session_reaped_idle', { sessions: ended });
     return ended;
 }
+/**
+ * Drop sessions that have ENDED, gone quiet and lost their socket, so a listing stops offering them.
+ *
+ * `reticle_session { action: "end" }` sets state and nothing else -- it never calls
+ * `sessions.remove`. `SessionManager.list()` does not filter by state, and `reapIdleSessions`
+ * above skips ended sessions by design. The only code path in the whole server that removes a
+ * session is the socket `close` handler in bridge.ts. So an ended session whose socket is already
+ * gone has nothing left that can remove it, and the row is listed for the life of the daemon
+ * (#938).
+ *
+ * That is what the field report describes: `{ ended: true }` three times, the row back on the next
+ * `reticle_sessions` call each time, still there after every tab on the origin was closed, 17 hours
+ * attached. And Reticle's own advice for a stale session is
+ * `Call reticle_session{action:"end"} to free this session` -- which is the one thing that does not
+ * free it.
+ *
+ * Deliberately NOT "remove on end". The panel is client-side, so `setState` has already pushed the
+ * ended state to the browser and the HUD keeps it; but `end` is documented idempotent, and removing
+ * immediately would make a second call fail to resolve. Waiting for the session to go quiet keeps
+ * that, keeps a just-ended session inspectable, and still collects the case that actually hurts: a
+ * row nobody can get rid of.
+ *
+ * Only once the socket is no longer open. An ended session whose tab is still connected but quiet
+ * belongs to a page that holds a live connection; dropping the record would orphan that socket,
+ * leaving a connection the daemon no longer tracks. Such a session is still removed the ordinary
+ * way, by the `close` handler, when the tab goes.
+ */
+export function reapEndedSessions(sessions, staleAfterMs = SESSION_LEASE.STALE_AFTER_MS) {
+    const dropped = [];
+    // Snapshot first: `remove` mutates the map this iterates.
+    for (const session of [...sessions.all()]) {
+        if (!session.isEnded())
+            continue;
+        if (session.socketOpen())
+            continue;
+        if (session.staleMs() < staleAfterMs)
+            continue;
+        if (sessions.remove(session))
+            dropped.push(session.id);
+    }
+    if (dropped.length > 0)
+        log('session_reaped_ended', { sessions: dropped });
+    return dropped;
+}
 /** End every active session immediately (the agent / MCP client disconnected → WARN). Returns ended ids. */
 export function endAllSessions(sessions, reason) {
     const ended = [];
@@ -81,6 +125,10 @@ export class SessionReaper {
             return;
         this.#timer = setInterval(() => {
             reapIdleSessions(this.#sessions);
+            // Second rule, same sweep, kept as its own function: one ends a live session that went
+            // quiet, the other collects one that already ended. Merging them would put "end this" and
+            // "forget this" behind a single condition.
+            reapEndedSessions(this.#sessions);
         }, this.#intervalMs);
         this.#timer.unref();
     }

package/dist/portal/session/session-successor.d.ts

@@ -26,6 +26,17 @@ export interface SuccessorClock {
  * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
  */
 export declare function pickDocumentSuccessor(live: readonly SessionIdentity[], departed: SessionIdentity): SessionIdentity | undefined;
+/**
+ * Whether `candidate` was already connected before the agent last drove `departed`.
+ *
+ * Such a tab is a SIBLING, never the document the departed tab's navigation produced: that document
+ * can only have connected after the command that caused it. Without this, two tabs of one project
+ * were resolved as "unique at the origin" in the gap before the departed tab came back, and a verdict
+ * for tab A was graded on tab B (#983, reproduced by driving). Measured as ages rather than instants,
+ * so both sides read the same clock at the same moment and the comparison does not drift while a
+ * caller polls.
+ */
+export declare function openedBeforeDeparture(candidate: Pick<Session, 'staleMs'>, departed: Pick<Session, 'agentIdleMs'>): boolean;
 export interface SuccessorRegistry {
     get(id: string): Session | undefined;
     all(): readonly Session[];

package/dist/portal/session/session-successor.js

@@ -100,6 +100,19 @@ export function pickDocumentSuccessor(live, departed) {
         return undefined;
     return others[0];
 }
+/**
+ * Whether `candidate` was already connected before the agent last drove `departed`.
+ *
+ * Such a tab is a SIBLING, never the document the departed tab's navigation produced: that document
+ * can only have connected after the command that caused it. Without this, two tabs of one project
+ * were resolved as "unique at the origin" in the gap before the departed tab came back, and a verdict
+ * for tab A was graded on tab B (#983, reproduced by driving). Measured as ages rather than instants,
+ * so both sides read the same clock at the same moment and the comparison does not drift while a
+ * caller polls.
+ */
+export function openedBeforeDeparture(candidate, departed) {
+    return candidate.staleMs() > departed.agentIdleMs();
+}
 /**
  * Poll until a successor of `departed` is live, or the budget runs out. Null on timeout — never
  * throws, because failing to follow is a legitimate `observation_lost`, not an error.
@@ -115,7 +128,7 @@ export async function awaitDocumentSuccessor(sessions, departed, timeoutMs, cloc
         // out of the pick, or same-id-first would keep returning the page that just unloaded.
         const picked = pickDocumentSuccessor(sessions
             .all()
-            .filter((s) => s !== departed)
+            .filter((s) => s !== departed && !openedBeforeDeparture(s, departed))
             .map(identityOf), departedIdentity);
         if (picked !== undefined) {
             const live = sessions.get(picked.id);

package/dist/portal/session/session-verdict-facts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The facts a SESSION contributes to a verdict, in the shape `decideVerified` takes.
+ *
+ * `decideVerified` is pure and has no session, so anything it needs about the link has to be
+ * threaded in. Two tools produce verdicts — `reticle_assert` and `reticle_act_and_wait` — and both
+ * were threading the same fields with the same conditional-spread idiom and the same comment
+ * beside it. A third fact (`versionSkew`) would have been a third copy.
+ *
+ * One function instead, for the ordinary reason: when a fourth fact arrives, a verdict surface that
+ * learns it in one place cannot half-learn it. That failure mode is not hypothetical here — the
+ * repo already records `net` assertions being discarded on one half of a surface because a filter
+ * was updated on the other.
+ *
+ * Every field is omitted rather than defaulted when absent. An SDK too old to declare sends
+ * nothing, and an empty value is a claim nobody made.
+ */
+/** What a session can tell a verdict. Optional throughout: absent means nobody said. */
+export interface SessionVerdictFacts {
+    readonly sdkVersion?: string;
+    readonly versionSkew?: string;
+}
+/** The shape read here — structural, so a test double needs no session. */
+export interface VerdictRelevantSession {
+    readonly sdkVersion?: string | undefined;
+    readonly versionSkew?: string | undefined;
+    readonly channels?: readonly string[] | undefined;
+}
+export declare function sessionVerdictFacts(session: VerdictRelevantSession): SessionVerdictFacts;

package/dist/portal/session/session-verdict-facts.js

@@ -0,0 +1,15 @@
+export function sessionVerdictFacts(session) {
+    const facts = {};
+    // So the unread-body remedy can check it applies to THIS page.
+    if (session.sdkVersion !== undefined)
+        facts.sdkVersion = session.sdkVersion;
+    /*
+     * An empty string is NOT a skew. The bridge sets this only on a real mismatch, but a defaulted
+     * or cleared field reaching the verdict would cost every call a `yes` it had earned — which is a
+     * worse failure than the one this exists to fix.
+     */
+    if (session.versionSkew !== undefined && session.versionSkew.length > 0) {
+        facts.versionSkew = session.versionSkew;
+    }
+    return facts;
+}

package/dist/portal/session/session.d.ts

@@ -44,6 +44,11 @@ export declare class Session implements HandshakeFacts {
      * root, which is what every counter did unconditionally before this existed.
      */
     artifactRoot: string | undefined;
+    /**
+     * Same-origin endpoints this session's project declared as background (`.reticle.json`
+     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
+     */
+    background: readonly string[];
     url: string;
     title: string;
     adapters: string[];
@@ -86,6 +91,8 @@ export declare class Session implements HandshakeFacts {
      * `reticle_session{action:"end"}` — a flag on the record, not on the page — could not help.
      */
     unresponsive(): boolean;
+    /** False once the socket is closing or closed: dropping this record then orphans nothing. */
+    socketOpen(): boolean;
     /** Wall-clock age of the session in milliseconds. */
     staleMs(): number;
     /** The document the most recent stamped event was observed under. See `#documentId`. */
@@ -109,6 +116,9 @@ export declare class Session implements HandshakeFacts {
      * against the same control after a re-render gave it a different ref.
      */
     private recordActedLabelFrom;
+    /** A control whose action PROVED its declared consequence — the coverage ledger's `proved`. */
+    recordProvedFrom(actPayload: unknown): void;
+    provedLabels(): ReadonlySet<string>;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;

package/dist/portal/session/session.js

@@ -5,19 +5,19 @@ 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 { 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 { ObservedState, controlLabelsOf } from './facts/observed-state.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';
@@ -63,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;
@@ -188,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({
@@ -237,6 +241,10 @@ export class Session {
     unresponsive() {
         return this.#unansweredCommands >= UNRESPONSIVE_AFTER_TIMEOUTS;
     }
+    /** False once the socket is closing or closed: dropping this record then orphans nothing. */
+    socketOpen() {
+        return this.#socket.readyState === WS_OPEN;
+    }
     /** Wall-clock age of the session in milliseconds. */
     staleMs() {
         return this.#clock() - this.#startedAt;
@@ -261,6 +269,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)
@@ -340,24 +356,16 @@ export class Session {
      * against the same control after a re-render gave it a different ref.
      */
     recordActedLabelFrom(result) {
-        const payload = result.result;
-        if (typeof payload !== 'object' || null === payload)
-            return;
-        const record = payload;
-        // The TESTID first: it is the strongest identity a control has and it survives any re-render.
-        // Coverage previously matched only on `role "name"`, so a control with a testid but no accessible
-        // name — or on a stack where the act reply carried neither — was unrecognisable after a
-        // re-render, and coverage read `exercised: 0` however much work had been done.
-        const testid = record['testid'];
-        if ('string' === typeof testid && testid.length > 0)
-            this.#observed.recordActedLabel(testid);
-        const role = record['role'];
-        const name = record['name'];
-        if (typeof role !== 'string' || typeof name !== 'string')
-            return;
-        if (0 === role.length || 0 === name.length)
-            return;
-        this.#observed.recordActedLabel(`${role} "${name}"`);
+        for (const label of controlLabelsOf(result.result))
+            this.#observed.recordActedLabel(label);
+    }
+    /** A control whose action PROVED its declared consequence — the coverage ledger's `proved`. */
+    recordProvedFrom(actPayload) {
+        for (const label of controlLabelsOf(actPayload))
+            this.#observed.recordProvedLabel(label);
+    }
+    provedLabels() {
+        return this.#observed.provedLabels();
     }
     actedRefs() {
         return this.#observed.actedRefs();

package/dist/surface/http-server.d.ts

@@ -10,7 +10,8 @@ export interface SharedServer {
      */
     attachMcp(factory: () => McpServer): void;
     /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
-    attachStatus(provider: () => unknown): void;
+    /** `held`: the request carried STATUS_HOLD_QUERY — a setup run is waiting on this daemon. */
+    attachStatus(provider: (held: boolean) => unknown): void;
     /**
      * Register the handler behind POST /drive: open a driveable browser at `url` and answer with the
      * session it registered.

package/dist/surface/http-server.js

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, DRIVE_PATH, } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, STATUS_HOLD_QUERY, DRIVE_PATH, } from '@reticlehq/core';
 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';
@@ -76,7 +76,9 @@ export function createSharedServer(options = {}) {
             }
         }
         if ('GET' === req.method && path === STATUS_PATH) {
-            const body = JSON.stringify(statusProvider?.() ?? { running: true });
+            // A setup run waiting on this daemon says so on its polls; see daemon-usefulness.
+            const held = url.searchParams.has(STATUS_HOLD_QUERY);
+            const body = JSON.stringify(statusProvider?.(held) ?? { running: true });
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(body);
             return;

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

@@ -1,11 +1,11 @@
 export { SseFrameParser, type SseFrame } from './sse-frame-parser.js';
-export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
+export { probeDaemon, waitForDaemon, waitForDaemonBind } from './proxy/proxy-daemon-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.
  */
 export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy/proxy-log.js';
-export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy/proxy-backoff.js';
+export { reconnectDelayMs } from './proxy/proxy-backoff.js';
 export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, type PostFailure, } from './proxy/mcp-post-transport.js';
 /**
  * Overridable so the survival spec can reach exhaustion in seconds instead of minutes — the same

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

@@ -6,13 +6,13 @@ import { toolsChangedNotification } from './proxy/proxy-handshake.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { SseFrameParser } from './sse-frame-parser.js';
 export { SseFrameParser } from './sse-frame-parser.js';
-export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
+export { probeDaemon, waitForDaemon, waitForDaemonBind } 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';
@@ -33,7 +33,7 @@ import { OutageReason, OutageStage, reportMcpOutage } from './faults/mcp-outage.
 import { postToSession } from './proxy/mcp-post-transport.js';
 import { reconnectDelayMs } from './proxy/proxy-backoff.js';
 import { PROXY_IDLE_EXIT_EVENT, ProxyIdleExit, resolveProxyIdleExitMs } from './proxy-idle-exit.js';
-export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy/proxy-backoff.js';
+export { reconnectDelayMs } from './proxy/proxy-backoff.js';
 export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, } from './proxy/mcp-post-transport.js';
 /**
  * How many consecutive failed reconnects before the proxy stops RETRYING. It does not stop serving:
@@ -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 {

package/dist/surface/mcp/mcp.js

@@ -103,7 +103,7 @@ import { firstSentence } from '../tools/first-sentence.js';
  * making it a pointer costs nothing.
  */
 const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
-    'animation | signal | state | settled | allOf | anyOf | not.';
+    'animation | signal | state | settled | compare | allOf | anyOf | not.';
 /**
  * Said once per turn: the bug-catching options, and where to get the rest of the field grammar.
  *
@@ -118,9 +118,11 @@ 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.bodyMatches (a shallow JSON match on what the SERVER answered — say the FIELD and its value, ' +
+    'net.bodyMatches (a JSON field match on what the SERVER answered — say the FIELD (a dotted path reaches nested ones) 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"), ' +
+    '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 ' +
     'grammar of a kind.';

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

@@ -3,8 +3,12 @@ export declare function daemonPollDelayMs(attempt: number): number;
  * 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
  * inside the daemon just to check reachability.
+ *
+ * `host` defaults to loopback, which is every caller's actual target — except `bootSession`
+ * (reticlehq/reticle#1165 review), whose Bridge can bind a non-default host via `RETICLE_HOST`.
+ * Hardcoding loopback here made that preflight check the wrong address.
  */
-export declare function probeDaemon(port: number): Promise<boolean>;
+export declare function probeDaemon(port: number, host?: string): Promise<boolean>;
 /**
  * Poll until a Reticle daemon is SERVING on `port`, or the deadline passes.
  *
@@ -20,3 +24,11 @@ export declare function waitForDaemon(port: number, probes?: {
     tcpOpen: (port: number) => Promise<boolean>;
     status: (port: number) => Promise<unknown>;
 }): Promise<void>;
+/**
+ * Poll until `/status` on `port` answers as a Reticle daemon; false once the bound passes.
+ *
+ * One rule for the three commands that start a daemon. `init` used to borrow `waitForDaemon`'s
+ * shorter reconnect budget, and on a cold fresh HOME it printed "could not start the Reticle
+ * daemon" over a daemon that bound seconds later. Bounded polling, never a fixed sleep.
+ */
+export declare function waitForDaemonBind(port: number): Promise<boolean>;

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

@@ -24,8 +24,12 @@ export function daemonPollDelayMs(attempt) {
  * 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
  * inside the daemon just to check reachability.
+ *
+ * `host` defaults to loopback, which is every caller's actual target — except `bootSession`
+ * (reticlehq/reticle#1165 review), whose Bridge can bind a non-default host via `RETICLE_HOST`.
+ * Hardcoding loopback here made that preflight check the wrong address.
  */
-export function probeDaemon(port) {
+export function probeDaemon(port, host = LOOPBACK_HOST) {
     return new Promise((resolve) => {
         const socket = new net.Socket();
         socket.setTimeout(500);
@@ -38,7 +42,7 @@ export function probeDaemon(port) {
             socket.destroy();
             resolve(false);
         });
-        socket.connect(port, LOOPBACK_HOST);
+        socket.connect(port, host);
     });
 }
 /**
@@ -69,3 +73,24 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
     throw new Error(`reticle daemon did not become ready on port ${String(port)} within ` +
         `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePresence(presence, port)}`);
 }
+/** How long a spawned daemon gets to bind before `serve`, `restart` or `init` gives up on it. */
+const BIND_TIMEOUT_MS = 15_000;
+const BIND_POLL_MS = 150;
+/**
+ * Poll until `/status` on `port` answers as a Reticle daemon; false once the bound passes.
+ *
+ * One rule for the three commands that start a daemon. `init` used to borrow `waitForDaemon`'s
+ * shorter reconnect budget, and on a cold fresh HOME it printed "could not start the Reticle
+ * daemon" over a daemon that bound seconds later. Bounded polling, never a fixed sleep.
+ */
+export async function waitForDaemonBind(port) {
+    const deadline = Date.now() + BIND_TIMEOUT_MS;
+    for (;;) {
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presence === PortPresence.DAEMON)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await delay(BIND_POLL_MS);
+    }
+}