@reticlehq/server 2.4.0 → 2.6.0

package/dist/session/session-health.js

@@ -1,4 +1,4 @@
-import { BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
+import { BrowserBrand, BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
 /**
  * Buffer-honesty envelope for observe/network/console. When the ring buffer has evicted anything
  * (age/size cap), a "no such event" answer may be a false negative — so we attach the drop count and
@@ -7,7 +7,7 @@ import { BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
  */
 export function bufferEnvelope(session) {
     const { total, dropped } = session.bufferHealth();
-    if (dropped === 0)
+    if (0 === dropped)
         return {};
     return { buffer: { held: total, dropped, note: BUFFER_EVICTION_WARNING } };
 }
@@ -31,7 +31,7 @@ export function healthEnvelope(session) {
  * warn-only so background testing never breaks.
  */
 export function refuseIfThrottled(session, refuse) {
-    if (refuse === true && session.throttled()) {
+    if (true === refuse && session.throttled()) {
         throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
     }
 }
@@ -42,9 +42,10 @@ export function refuseIfThrottled(session, refuse) {
  */
 export function readHealthEvent(data) {
     return {
-        hidden: typeof data['hidden'] === 'boolean' ? data['hidden'] : undefined,
-        focused: typeof data['focused'] === 'boolean' ? data['focused'] : undefined,
-        runtime: typeof data['runtime'] === 'string' ? data['runtime'] : undefined,
-        engine: typeof data['engine'] === 'string' ? data['engine'] : undefined,
+        hidden: 'boolean' === typeof data['hidden'] ? data['hidden'] : undefined,
+        focused: 'boolean' === typeof data['focused'] ? data['focused'] : undefined,
+        runtime: 'string' === typeof data['runtime'] ? data['runtime'] : undefined,
+        engine: 'string' === typeof data['engine'] ? data['engine'] : undefined,
+        brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
     };
 }

package/dist/session/session-info.d.ts

@@ -1,18 +1,15 @@
-/**
- * The shape `reticle_sessions` returns for one connected tab.
- *
- * Split from session.ts when that file crossed the 600-line cap. A pure description of what a
- * session looks like from the outside has no reason to live inside the class that happens to build
- * it, and separating them keeps the wire-facing shape reviewable on its own.
- */
+import type { SessionHealth } from './session-health.js';
 export interface SessionInfo {
     sessionId: string;
     url: string;
     /** Stable build-stamped project identity; absent for v1.0 SDKs that don't send it. */
     projectId?: string;
-    title: string;
+    /** Absent when the page has no title — never the empty string. Fall back to `url`. */
+    title?: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
+    versionSkew?: string;
     /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
     lastSeenMs: number;
     hidden: boolean;
@@ -26,4 +23,42 @@ export interface SessionInfo {
     pendingMarks?: number;
     /** present with pendingMarks — nudges the agent to drain them with reticle_review. */
     review_suggestion?: string;
+    /**
+     * Continuity of this attachment — `{ connectedSinceMs, outages, lastOutage? }`.
+     *
+     * A tab that dropped for four seconds and came back is indistinguishable from one that never left
+     * (#117), and that difference decides whether a verdict over the window can be trusted. Attached
+     * by `SessionManager.list()`, which is the layer that sees every connect and disconnect.
+     */
+    attachment?: {
+        connectedSinceMs: number;
+        outages: number;
+        lastOutage?: {
+            startedMs: number;
+            durationMs: number;
+        };
+    };
 }
+/** The read-only slice of a Session that the projection needs. Keeps this module class-free. */
+interface SessionView {
+    id: string;
+    url: string;
+    projectId: string | undefined;
+    title: string;
+    adapters: string[];
+    hasCapabilities: boolean;
+    versionSkew: string | undefined;
+    hidden: boolean;
+    health: () => SessionHealth;
+    staleMs: () => number;
+    pendingMarkCount: () => number;
+}
+/**
+ * Project a live Session into the shape the tools return.
+ *
+ * Lives beside the SessionInfo type rather than on the class: it is a pure read of already-computed
+ * state, it is where every "what does the agent see about this tab" decision belongs, and Session is
+ * a stateful class already at its size cap — every field added to a listing was costing a line there.
+ */
+export declare function buildSessionInfo(session: SessionView): SessionInfo;
+export {};

package/dist/session/session-info.js

@@ -1 +1,46 @@
-export {};
+/**
+ * The shape `reticle_sessions` returns for one connected tab.
+ *
+ * Split from session.ts when that file crossed the 600-line cap. A pure description of what a
+ * session looks like from the outside has no reason to live inside the class that happens to build
+ * it, and separating them keeps the wire-facing shape reviewable on its own.
+ */
+import { SESSION_LEASE } from '@reticlehq/core';
+/**
+ * Project a live Session into the shape the tools return.
+ *
+ * Lives beside the SessionInfo type rather than on the class: it is a pure read of already-computed
+ * state, it is where every "what does the agent see about this tab" decision belongs, and Session is
+ * a stateful class already at its size cap — every field added to a listing was costing a line there.
+ */
+export function buildSessionInfo(session) {
+    const base = {
+        sessionId: session.id,
+        url: session.url,
+        ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+        // Omitted when blank, never `""`. An empty title cannot be told apart from "we sampled before
+        // the page set one", and two such tabs make the listing unusable. Moving the sample later does
+        // not fix it — a page may set its title after connect, or never — so the projection refuses the
+        // bad answer and the reader falls back to `url`, which is right here in the same record.
+        ...('' === session.title.trim() ? {} : { title: session.title }),
+        adapters: session.adapters,
+        hasCapabilities: session.hasCapabilities,
+        // On every listing, not buried in a log — skew explains failures that read as app bugs.
+        ...(session.versionSkew === undefined ? {} : { versionSkew: session.versionSkew }),
+        hidden: session.hidden,
+        ...session.health(),
+    };
+    if (session.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
+        base.stale = true;
+        base.cleanup_suggestion =
+            'Call reticle_session{action:"end"} to free this session before starting new work.';
+    }
+    // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).
+    const marks = session.pendingMarkCount();
+    if (marks > 0) {
+        base.pendingMarks = marks;
+        const s = 1 === marks ? '' : 's';
+        base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_session{action:"review"} to see and fix ${1 === marks ? 'it' : 'them'}.`;
+    }
+    return base;
+}

package/dist/session/session-lease.d.ts

@@ -11,15 +11,4 @@ export interface SessionLease {
     opened_at: number;
     IMPORTANT: string;
 }
-/**
- * Kept SHORT on purpose, and this is the reason to read before editing it.
- *
- * This block is a fixed, identical cost paid by EVERY session. The long-form version was 433 bytes
- * on a `reticle_query` whose actual answer was 259 — 57% of the first call of every session spent
- * re-explaining something that never varies. Measured at 815 → 1058 average observation tokens, and
- * the benchmark's fresh-session-per-scenario shape pays it ten times over.
- *
- * Any edit here is a per-session tax on every user: say it in as few words as still work.
- */
-export declare const SESSION_LEASE_NOTICE = "When you stop driving, call reticle_session {action:\"yield\", mode:\"waiting\"|\"ask\"} \u2014 the panel reads \"live\" until you do. {action:\"end\"} when the task is done; it revives on your next action.";
 export declare function buildSessionLease(sessionId: string, openedAt: number): SessionLease;

package/dist/session/session-lease.js

@@ -8,7 +8,7 @@
  *
  * Any edit here is a per-session tax on every user: say it in as few words as still work.
  */
-export const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"} — the panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
+const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"} — the panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
 export function buildSessionLease(sessionId, openedAt) {
     return { sessionId, opened_at: openedAt, IMPORTANT: SESSION_LEASE_NOTICE };
 }

package/dist/session/session-manager.d.ts

@@ -1,4 +1,5 @@
 import { Session, type SessionInfo } from './session.js';
+import { AttachmentHistory } from './attachment-history.js';
 /**
  * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
  * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
@@ -18,9 +19,14 @@ export declare class SessionManager {
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
     list(): SessionInfo[];
+    /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
+    attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
     count(): number;
+    /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
+    setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    everConnected(): boolean;
     /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
     noteClosure(reason: string, at: number): void;
     /** The most recent bridge-initiated close, if any. */

package/dist/session/session-manager.js

@@ -1,6 +1,7 @@
 import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
+import { AttachmentHistory } from './attachment-history.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
     if (url === undefined)
@@ -29,14 +30,29 @@ function scopeSessions(sessions, scope) {
     }
     return sessions;
 }
-/** Honest, scoped error when sessions exist but none match the agent's project. */
-function scopeMissError(scope) {
+/**
+ * Honest, scoped error when sessions exist but none match the agent's project.
+ *
+ * The daemon takes its default scope from the `.reticle.json` of whichever directory started it, so
+ * attaching from a second project — or another worktree of the SAME project — makes every tool
+ * refuse while `reticle_sessions` shows the tab sitting right there. The old message asked "is that
+ * app running with @reticlehq/core enabled?", which is the one thing that is definitely true, so the
+ * reader goes looking at their app instead of at the scope. Name what IS connected and how to
+ * target it: both facts are already in hand here.
+ */
+function scopeMissError(connected, scope) {
     const who = scope?.projectId !== undefined
         ? `project '${scope.projectId}'`
         : scope?.url !== undefined
             ? `your app at ${scope.url}`
             : 'the active project';
-    return `no browser session for ${who} — is that app running with @reticlehq/core enabled? (other apps may be connected, but they won't be driven by mistake)`;
+    const listed = connected
+        .map((s) => `'${s.projectId ?? 'untagged'}' (${s.url}, sessionId '${s.id}')`)
+        .join(', ');
+    return (`no browser session for ${who}, but ${String(connected.length)} session(s) ARE connected under a ` +
+        `different project: ${listed}. The daemon scopes to the .reticle.json of the directory it was ` +
+        `started in, so this is a scope mismatch, not a dead app. Pass the sessionId above to target one, ` +
+        `or restart the daemon from that app's directory.`);
 }
 /**
  * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
@@ -47,6 +63,12 @@ function scopeMissError(scope) {
 const MAX_REMEMBERED_CLOSURES = 5;
 export class SessionManager {
     #sessions = new Map();
+    /**
+     * Continuity per session, so a listing can answer "was this attached the whole time".
+     *
+     * Owned here because this is the one place that sees both halves — every add and every remove.
+     */
+    #attachment = new AttachmentHistory();
     /**
      * 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
@@ -58,12 +80,14 @@ export class SessionManager {
         this.#defaultScope = scope;
     }
     add(session) {
+        this.#everConnected = true;
         const previous = this.#sessions.get(session.id);
         this.#sessions.set(session.id, session);
         // Publish what this app declared sensitive to the driven-path rule. Here rather than in the
         // bridge because EVERY path that registers a session goes through this method, and a declaration
         // that silently fails to register is a leak nothing would report.
         declareDrivenRedactionKeys(session.id, session.redactKeys);
+        this.#attachment.attached(session.id);
         return previous;
     }
     remove(session) {
@@ -71,13 +95,24 @@ export class SessionManager {
             return false;
         session.rejectAll('session disconnected');
         forgetDrivenRedactionKeys(session.id);
+        // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
+        // the reconnect is exactly where that matters.
+        this.#attachment.detached(session.id);
         return this.#sessions.delete(session.id);
     }
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
     list() {
-        return [...this.#sessions.values()].map((s) => s.info());
+        return [...this.#sessions.values()].map((s) => {
+            const info = s.info();
+            const attachment = this.#attachment.of(s.id);
+            return attachment === undefined ? info : { ...info, attachment };
+        });
+    }
+    /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
+    attachmentOf(sessionId) {
+        return this.#attachment.of(sessionId);
     }
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all() {
@@ -112,6 +147,25 @@ export class SessionManager {
      * was hung up on. Keeping the last few reasons turns an unexplained disappearance into a fact.
      */
     #recentClosures = [];
+    /**
+     * What the daemon knows about WHY nothing is connected, refreshed in the background.
+     *
+     * Measured: of the sessions that call any tool, half make exactly one call — usually
+     * reticle_sessions — and stop, because the answer they get names two things they cannot check and
+     * nothing they can do. The daemon can tell "no app is running" from "an app is running and never
+     * dialled us" from "one was connected and left", and each has a different fix. Optional so a
+     * bridge constructed without a daemon (every unit test) keeps the plain message.
+     */
+    #noSessionHint;
+    /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
+    setNoSessionHint(hint) {
+        this.#noSessionHint = hint;
+    }
+    /** Whether any session has connected since this daemon booted — half the diagnosis. */
+    #everConnected = false;
+    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 });
@@ -122,38 +176,96 @@ export class SessionManager {
     lastClosure() {
         return this.#recentClosures[this.#recentClosures.length - 1];
     }
+    /**
+     * A dead `sessionId`, answered with what the caller needs to recover — not with an errand.
+     *
+     * Telemetry, 2026-08-10: one agent called `reticle_navigate` twelve times against an id that was
+     * no longer connected. That single loop is **12 of the 58 tool errors recorded all day, 21%**. The
+     * refusal said only `no connected session with id 'x'`, and the recovery hint told it to call
+     * `reticle_sessions` and retry — two extra round trips to learn something this method already
+     * knows at the moment it refuses. An agent charged two calls to recover will often just repeat the
+     * one it made.
+     *
+     * So: name the live ids inline, and when there are none say that instead, because "retry with a
+     * valid one" is advice nobody can act on when no valid one exists.
+     */
+    #unknownSessionError(sessionId) {
+        const live = [...this.#sessions.values()];
+        if (0 === live.length) {
+            return (`no connected session with id '${sessionId}', and no sessions are connected at all — so ` +
+                'there is no other id to retry with. The app is not dialling this daemon; call ' +
+                'reticle_sessions for the diagnosis rather than retrying this call.');
+        }
+        const named = live.map((s) => `'${s.id}' (${s.url})`).join(', ');
+        return (`no connected session with id '${sessionId}'. Connected right now: ${named}. ` +
+            'Retry with one of those, or omit sessionId entirely and let Reticle scope to your project.');
+    }
     resolve(sessionId, scope) {
         if (sessionId !== undefined) {
             const found = this.#sessions.get(sessionId);
             if (found === undefined) {
-                throw new Error(`no connected session with id '${sessionId}'`);
+                throw new Error(this.#unknownSessionError(sessionId));
             }
             found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
             return found;
         }
-        if (this.#sessions.size === 0) {
+        if (0 === this.#sessions.size) {
             const closure = this.lastClosure();
+            // A diagnosis beats a checklist: it names which of the three causes this actually is.
+            const hint = this.#noSessionHint?.();
+            if (hint !== undefined && closure === undefined)
+                throw new Error(hint);
             throw new Error(closure === undefined
                 ? NO_SESSION_CONNECTED_ERROR
-                : `${NO_SESSION_CONNECTED_ERROR} NOTE: the bridge closed a session recently — "${closure.reason}". The app is probably still running; it was disconnected, and the SDK does not retry after a policy close. Reload the page to reconnect.`);
+                : `${NO_SESSION_CONNECTED_ERROR} NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`);
         }
         // Scope to the agent's active project FIRST, so a stray tab from another app/origin (e.g. a
         // leftover dashboard on a different port) is structurally unselectable — it never enters the
         // candidate set, no matter how recently it was heard from. This is the anti-cross-talk guard.
         // An explicit per-call scope wins; otherwise the daemon's active-project default applies.
         const effectiveScope = scope ?? this.#defaultScope;
-        const all = scopeSessions([...this.#sessions.values()], effectiveScope);
-        if (all.length === 0) {
+        const connected = [...this.#sessions.values()];
+        const all = scopeSessions(connected, effectiveScope);
+        if (0 === all.length) {
             // Sessions exist, but none belong to the scoped project — never fall back to a foreign tab.
-            throw new Error(scopeMissError(effectiveScope));
+            // ponytail: still a refusal, deliberately. Auto-targeting the only connected tab would be the
+            // friendlier 90% case and would also silently defeat the anti-cross-talk guard this scope
+            // exists to be. Naming the tab and its sessionId costs the agent one extra argument.
+            throw new Error(scopeMissError(connected, effectiveScope));
         }
-        if (all.length === 1) {
+        if (1 === all.length) {
             const [only] = all;
             if (only === undefined)
                 throw new Error('session lookup failed');
             only.markAgentActivity();
             return only;
         }
+        // Two projects and nothing to choose between them: refuse, BEFORE any scoring.
+        //
+        // Reported from the field: a call from `apps/next-app-router` was answered by a `rowy-*`
+        // session, and `act_and_wait` spent 16.9s returning `verified:'no'` about an app never under
+        // test — a confident false verdict, with a source pointer, about code the agent never touched.
+        //
+        // The recency rule below cannot prevent it. It asks "is one of these clearly fresher", which is
+        // the right question for two tabs of ONE app and the wrong question for two apps: the fresher
+        // tab of the wrong project is still the wrong project. The reported case had a clear winner,
+        // so the ambiguity check passed and the wrong app was selected.
+        //
+        // This sits ahead of scoring so freshness cannot rescue it. It only fires when nothing scoped
+        // the call — an explicit `sessionId` returns far above, and an explicit or default scope has
+        // already narrowed `all` to one project by here.
+        const projects = new Set(all.map((s) => s.projectId).filter((p) => p !== undefined));
+        if (projects.size > 1) {
+            const listed = all
+                .filter((s) => s.projectId !== undefined)
+                .map((s) => `'${String(s.projectId)}' (${s.url}, sessionId '${s.id}')`)
+                .join(', ');
+            throw new Error(`${String(projects.size)} different projects are connected and nothing says which one this ` +
+                `call is about: ${listed}. Pass sessionId to target one. Reticle refuses rather than ` +
+                'guessing here because picking the wrong app produces a confident verdict about code you ' +
+                'never touched — the daemon scopes to the directory it was started in, so running it above ' +
+                'several apps leaves it unable to tell them apart.');
+        }
         // Multiple sessions: score each (lower = better candidate for auto-selection).
         // 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat).
         const scored = all.map((s) => ({ s, score: s.throttled() ? 1 : 0, ms: s.lastSeenMs() }));
@@ -173,7 +285,7 @@ export class SessionManager {
         // desktop), the gap requirement is dropped: every session is already in "background" mode
         // so we just pick the one with the freshest heartbeat and let the agent proceed. Requiring
         // a gap here only produces spurious "ambiguous" errors while the user works elsewhere.
-        const allThrottled = bestScore === 1;
+        const allThrottled = 1 === bestScore;
         const RECENCY_GAP_MS = allThrottled ? 0 : 1_000;
         const clearWinner = runnerUp === undefined || best.ms + RECENCY_GAP_MS < runnerUp.ms;
         if (!clearWinner) {

package/dist/session/session-readiness.d.ts

@@ -16,7 +16,7 @@ interface WaitForReadyOptions {
     now: () => number;
     /** Injected delay between polls. */
     sleep: (ms: number) => Promise<void>;
-    /** Poll interval (ms). Default 100. */
+    /** Poll interval (ms). Default 25 — see DEFAULT_POLL_MS. */
     pollMs?: number;
 }
 /**

package/dist/session/session-readiness.js

@@ -1,4 +1,9 @@
-const DEFAULT_POLL_MS = 100;
+/**
+ * Same reasoning as session-reconnect: the check is an in-memory lookup and the thing awaited is an
+ * event (a session registering), so a coarse grid only adds latency to the first call an agent
+ * makes. Four times the checks of something with no I/O costs nothing measurable.
+ */
+const DEFAULT_POLL_MS = 25;
 /**
  * One-line orientation for a FRESH agent — the Reticle loop, returned by reticle_wait_ready (the first call)
  * so an agent learns how to drive Reticle without reading docs. Named so it is not a free string; kept

package/dist/session/session-reaper.js

@@ -20,7 +20,7 @@ const IDLE_WAITING_SUMMARY = 'Agent idle — your turn. Continue in your termina
  * it rides the end banner so the human can copy it into their terminal. No notes → the base unchanged.
  */
 export function composeEndedNotice(base, undelivered) {
-    if (undelivered.length === 0)
+    if (0 === undelivered.length)
         return base;
     const notes = undelivered.map((text) => `"${text}"`).join(', ');
     return `${base} · ${UNDELIVERED_NOTES_LABEL} ${notes}`;

package/dist/session/session-reconnect.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Block until a reloaded page has re-announced itself under the same session id.
+ *
+ * A reload tears the SDK down. The id survives (see session-continuity), and the daemon replaces the
+ * old Session with a new one when the page says HELLO again — so "is it back?" is exactly "does a
+ * DIFFERENT object hold this id now?". Identity, not a flag: the returning page always constructs a
+ * new Session, and nothing else can claim an id it already owns.
+ *
+ * Polls a live getter rather than subscribing, because there is no reconnect event to subscribe to
+ * and inventing one for this would be a wire change for a two-second wait.
+ */
+interface WaitForReconnectOptions {
+    /** The session registered under this id right now, or undefined if none is. */
+    current: () => object | undefined;
+    /** The session object that was live when the reload was dispatched. */
+    previous: object;
+    /** Give up after this much elapsed time and let the caller report it honestly. */
+    timeoutMs: number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    pollMs?: number;
+}
+/**
+ * How long a reload is worth waiting for before answering "not confirmed".
+ *
+ * A production build is back in well under a second; a cold dev-server route rebuild is the slow
+ * case this budget is sized for. It is a CEILING, not a delay — the common path returns on the first
+ * or second poll.
+ */
+export declare const RELOAD_RECONNECT_TIMEOUT_MS = 5000;
+export declare function waitForReconnect(opts: WaitForReconnectOptions): Promise<boolean>;
+export {};

package/dist/session/session-reconnect.js

@@ -0,0 +1,42 @@
+/**
+ * Block until a reloaded page has re-announced itself under the same session id.
+ *
+ * A reload tears the SDK down. The id survives (see session-continuity), and the daemon replaces the
+ * old Session with a new one when the page says HELLO again — so "is it back?" is exactly "does a
+ * DIFFERENT object hold this id now?". Identity, not a flag: the returning page always constructs a
+ * new Session, and nothing else can claim an id it already owns.
+ *
+ * Polls a live getter rather than subscribing, because there is no reconnect event to subscribe to
+ * and inventing one for this would be a wire change for a two-second wait.
+ */
+/**
+ * How often to look for the reconnected session.
+ *
+ * 25ms, not 100. What is being polled is an in-memory map lookup — no I/O, no browser round-trip —
+ * while the thing being waited for is an EVENT (the reloaded page's HELLO). At 100ms the agent paid
+ * up to a full interval of dead time after the page was already back, on every navigate-with-reload.
+ * Measured across the fixture fleet, `reticle_navigate` clustered at 105 / 202-206 / 308 / 407ms —
+ * the poll grid, visible in the data. Four times the checks of something this cheap costs nothing
+ * anyone can measure.
+ */
+const DEFAULT_POLL_MS = 25;
+/**
+ * How long a reload is worth waiting for before answering "not confirmed".
+ *
+ * A production build is back in well under a second; a cold dev-server route rebuild is the slow
+ * case this budget is sized for. It is a CEILING, not a delay — the common path returns on the first
+ * or second poll.
+ */
+export const RELOAD_RECONNECT_TIMEOUT_MS = 5000;
+export async function waitForReconnect(opts) {
+    const poll = opts.pollMs ?? DEFAULT_POLL_MS;
+    const start = opts.now();
+    for (;;) {
+        const live = opts.current();
+        if (live !== undefined && live !== opts.previous)
+            return true;
+        if (opts.now() - start >= opts.timeoutMs)
+            return false;
+        await opts.sleep(poll);
+    }
+}

package/dist/session/session.d.ts

@@ -3,7 +3,7 @@ import { LastAct } from './last-act.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../journal/journal-recorder.js';
 import { type EventQueryOptions } from '../journal/journal-query.js';
 import { type AmbientCounts } from '../journal/ambient.js';
@@ -27,6 +27,8 @@ export declare class Session {
     title: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
+    versionSkew?: string;
     /**
      * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
      * DRIVEN path can redact them too — a request body the daemon captures from the network stack
@@ -46,10 +48,12 @@ export declare class Session {
      * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
      * the desktop-specific timeout diagnosis rather than breaking.
      */
-    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string): void;
+    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string, brand?: BrowserBrand): void;
     /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
     get runtime(): PageRuntime | undefined;
     get engine(): string | undefined;
+    /** The browser brand the SDK reported. Absent (never guessed) when the page did not say. */
+    get brand(): BrowserBrand | undefined;
     /** Throttled if the tab is hidden OR we have not heard from it recently. */
     throttled(): boolean;
     /** The attachable health block — single source of truth for the tools. */
@@ -60,6 +64,14 @@ export declare class Session {
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
+    actedLabels(): ReadonlySet<string>;
+    /**
+     * Derive the snapshot-shaped label (`button "Deploy"`) from an act reply and remember it.
+     *
+     * Same shape the interactive snapshot emits, so coverage can match a control the agent drove
+     * against the same control after a re-render gave it a different ref.
+     */
+    private recordActedLabelFrom;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;
@@ -124,6 +136,7 @@ export declare class Session {
         dropped: number;
     };
     onEvent(listener: (event: ReticleEvent) => void): () => void;
+    onDisconnect(listener: () => void): () => void;
     /** Send a command to the browser and await its reply (or time out). */
     command(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<CommandResult>;
     handleResult(result: CommandResult): void;