@reticlehq/server 2.12.0 → 2.13.0

package/dist/session/resolve-within.js

@@ -0,0 +1,53 @@
+/**
+ * Resolve a session, or spend the caller's stated budget waiting for one to arrive.
+ *
+ * Every tool that takes a `timeout_ms` used to resolve the session as its FIRST statement, so an
+ * empty session map threw before the budget was ever consulted. A caller that said "wait up to
+ * thirty seconds for the app" was refused in under a millisecond, and the only way to actually wait
+ * was to poll `reticle_sessions` blind.
+ *
+ * That is the wrong answer to the commonest situation in the product. The moment an agent has run
+ * `init` and restarted the dev server is exactly the moment there is no session yet and one is about
+ * to appear — and `no_session` is the refusal agents hit most. An agent that gets refused rarely
+ * retries; it concludes and moves on. Spending the budget it already asked for turns the most common
+ * dead end into a wait that ends in a verdict.
+ *
+ * Deliberately narrow in two ways.
+ *
+ * Only the EMPTY case waits. A `sessionId` that names a session which is not connected while others
+ * are is a different error with a different fix, and waiting on it would hide a typo behind a
+ * timeout.
+ *
+ * The original error is what gets thrown on expiry, never a generic timeout message. That error
+ * carries the daemon's whole diagnosis — the port scan, the next action, the literal command — and
+ * it is the single most valuable string this product emits to an agent that has nothing connected.
+ * Replacing it with "timed out" would trade the answer for a stopwatch reading.
+ */
+/** How often to re-ask. A session appearing is an out-of-band event; this is a plain poll. */
+const POLL_MS = 250;
+export async function resolveSessionWithin(sessions, sessionId, timeoutMs, deps) {
+    try {
+        return sessions.resolve(sessionId);
+    }
+    catch (first) {
+        // Nothing to wait FOR unless the map is empty, and nothing to wait WITH unless a budget was
+        // given. Either way the caller gets the same error it would have got before.
+        if (timeoutMs <= 0 || sessions.count() > 0)
+            throw first;
+        const deadline = deps.now() + timeoutMs;
+        for (;;) {
+            const remaining = deadline - deps.now();
+            if (remaining <= 0)
+                throw first;
+            await deps.sleep(Math.min(POLL_MS, remaining));
+            try {
+                return sessions.resolve(sessionId);
+            }
+            catch {
+                // Still nothing. Keep the FIRST error: it was raised when the daemon had most recently
+                // computed its diagnosis, and re-throwing the newest one would report the same fact with a
+                // staler explanation.
+            }
+        }
+    }
+}

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

@@ -8,6 +8,15 @@ export interface SessionInfo {
     title?: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /**
+     * Which shell answered: `web`, `electron` or `tauri`.
+     *
+     * Absent — never defaulted to `web` — on an SDK too old to report one, because the guess is wrong
+     * on exactly the machines this exists to tell apart. Two windows on the same url are otherwise
+     * indistinguishable, and a browser tab is not a desktop app: it has none of its IPC, and it does
+     * not render like it.
+     */
+    runtime?: string;
     /** 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). */
@@ -19,6 +28,13 @@ export interface SessionInfo {
     recommendation?: string;
     stale?: boolean;
     cleanup_suggestion?: string;
+    /**
+     * present ONLY when this tab has stopped answering commands — attached, streaming events, and
+     * missing every command budget. Never `false`: absence means "answering, or not asked yet".
+     */
+    unresponsive?: true;
+    /** present with `unresponsive` — the in-protocol way out of a wedged tab. */
+    unresponsive_suggestion?: string;
     /** present only when the human has flagged bugs on this tab — count of pending review marks. */
     pendingMarks?: number;
     /** present with pendingMarks — nudges the agent to drain them with reticle_review. */
@@ -47,11 +63,13 @@ interface SessionView {
     title: string;
     adapters: string[];
     hasCapabilities: boolean;
+    runtime: string | undefined;
     versionSkew: string | undefined;
     hidden: boolean;
     health: () => SessionHealth;
     staleMs: () => number;
     pendingMarkCount: () => number;
+    unresponsive: () => boolean;
 }
 /**
  * Project a live Session into the shape the tools return.

package/dist/session/session-info.js

@@ -25,6 +25,8 @@ export function buildSessionInfo(session) {
         ...('' === session.title.trim() ? {} : { title: session.title }),
         adapters: session.adapters,
         hasCapabilities: session.hasCapabilities,
+        // Omitted when the page never said, so absence stays readable as "unknown" rather than "web".
+        ...(session.runtime === undefined ? {} : { runtime: session.runtime }),
         // 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,
@@ -35,6 +37,15 @@ export function buildSessionInfo(session) {
         base.cleanup_suggestion =
             'Call reticle_session{action:"end"} to free this session before starting new work.';
     }
+    // A tab that is attached and answering nothing. Said out loud because every health field beside it
+    // reads fine — that combination is exactly what made the wedge invisible.
+    if (session.unresponsive()) {
+        base.unresponsive = true;
+        base.unresponsive_suggestion =
+            'This tab is connected but has stopped answering commands, so every call against it will time ' +
+                'out. Ending the session does not revive the page. Reload the tab, or run `reticle open <url>` ' +
+                'to get a fresh one — it will no longer hand this tab back.';
+    }
     // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).
     const marks = session.pendingMarkCount();
     if (marks > 0) {

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

@@ -1,3 +1,4 @@
+import type { NoSessionReason } from '@reticlehq/core';
 import { Session, type SessionInfo } from './session.js';
 import { AttachmentHistory } from './attachment-history.js';
 import type { NoSessionNextAction } from './no-session-next-action.js';
@@ -37,6 +38,8 @@ export declare class SessionManager {
      * already computed for the error path; this exposes it to the read path too.
      */
     noSessionHint(): string | undefined;
+    setNoSessionReason(reason: (() => NoSessionReason | undefined) | undefined): void;
+    noSessionReason(): NoSessionReason | undefined;
     setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
     noSessionNextAction(): NoSessionNextAction | undefined;
     everConnected(): boolean;
@@ -47,6 +50,17 @@ export declare class SessionManager {
         at: number;
         reason: string;
     } | undefined;
+    /**
+     * The id of the session that most recently went away, if any.
+     *
+     * Distinct from {@link lastClosure}, which only records closes the bridge itself initiated
+     * (handshake refusals, auth failures) — an ordinary disconnect never reaches it. This reads the
+     * tombstone ring `remove()` maintains, so it covers every departure.
+     *
+     * Read by the no-session diagnosis, which needs to say something about the session that actually
+     * vanished rather than about the daemon's lifetime history (#611).
+     */
+    lastDeparted(): string | undefined;
     resolve(sessionId?: string, scope?: ResolveScope): Session;
 }
 export {};

package/dist/session/session-manager.js

@@ -1,4 +1,5 @@
 import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
+import { notePendingNoSessionReason } from '../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './attachment-history.js';
@@ -111,6 +112,11 @@ export class SessionManager {
         this.#recordConnection?.(session.projectId);
         const previous = this.#sessions.get(session.id);
         this.#sessions.set(session.id, session);
+        // Who can SEE this session's HUD feed. Wired here because `add` is the one method every path
+        // that registers a session goes through, and read lazily so a tab that opens later still counts.
+        // Optional-call for the same reason `pushImpact` is one at the dispatch chokepoint: a test
+        // double is a partial Session, and wiring a courtesy channel must never break registration.
+        session.setViewers?.(() => this.#viewersFor(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.
@@ -119,6 +125,17 @@ export class SessionManager {
         this.#tombstones.delete(session.id);
         return previous;
     }
+    /**
+     * The other tabs of the same app as `driven`.
+     *
+     * Scoped the same way auto-selection is: by the stable projectId when the driven tab stamped one,
+     * else by origin. A drive session is frequently a headless pooled context (see Session.#viewers),
+     * so without this the human's own tab is the one place the report never reaches.
+     */
+    #viewersFor(driven) {
+        const scope = driven.projectId === undefined ? { url: driven.url } : { projectId: driven.projectId };
+        return scopeSessions([...this.#sessions.values()], scope).filter((s) => s !== driven);
+    }
     remove(session) {
         if (this.#sessions.get(session.id) !== session)
             return false;
@@ -218,6 +235,13 @@ export class SessionManager {
      * bridge constructed without a daemon (every unit test) keeps the plain message.
      */
     #noSessionHint;
+    /**
+     * The CODE for the same diagnosis `#noSessionHint` renders as prose.
+     *
+     * Registered from the same `explainNoSession` call as the hint, so the two cannot describe
+     * different branches. See no-session-watch.ts.
+     */
+    #noSessionReason;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint) {
         this.#noSessionHint = hint;
@@ -233,6 +257,12 @@ export class SessionManager {
     noSessionHint() {
         return this.#noSessionHint?.();
     }
+    setNoSessionReason(reason) {
+        this.#noSessionReason = reason;
+    }
+    noSessionReason() {
+        return this.#noSessionReason?.();
+    }
     /**
      * The same diagnosis with the prose taken out — one action kind and one literal command.
      *
@@ -262,6 +292,22 @@ export class SessionManager {
     lastClosure() {
         return this.#recentClosures[this.#recentClosures.length - 1];
     }
+    /**
+     * The id of the session that most recently went away, if any.
+     *
+     * Distinct from {@link lastClosure}, which only records closes the bridge itself initiated
+     * (handshake refusals, auth failures) — an ordinary disconnect never reaches it. This reads the
+     * tombstone ring `remove()` maintains, so it covers every departure.
+     *
+     * Read by the no-session diagnosis, which needs to say something about the session that actually
+     * vanished rather than about the daemon's lifetime history (#611).
+     */
+    lastDeparted() {
+        let last;
+        for (const id of this.#tombstones.keys())
+            last = id;
+        return last;
+    }
     /**
      * A dead `sessionId`, answered with what the caller needs to recover — not with an errand.
      *
@@ -307,6 +353,10 @@ export class SessionManager {
             const refusal = closure === undefined
                 ? ''
                 : ` 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.`;
+            // Hand the branch code to the refusal that is about to be reported for this throw. The
+            // diagnosis is computed HERE and the refusal is classified from the message downstream, so
+            // without this the largest refusal cohort stays one undifferentiated bucket (#615).
+            notePendingNoSessionReason(this.#noSessionReason?.());
             throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}`);
         }
         // Scope to the agent's active project FIRST, so a stray tab from another app/origin (e.g. a
@@ -357,8 +407,15 @@ export class SessionManager {
                 '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() }));
+        // 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat),
+        // 2 = attached but not answering commands. A wedged tab keeps streaming events, so recency
+        // RATES IT HIGHEST — it was beating a healthy sibling on the one signal scoring looked at, and
+        // every call auto-targeted the one tab guaranteed to time out.
+        const scored = all.map((s) => ({
+            s,
+            score: s.unresponsive() ? 2 : s.throttled() ? 1 : 0,
+            ms: s.lastSeenMs(),
+        }));
         const bestScore = Math.min(...scored.map((x) => x.score));
         const candidates = scored.filter((x) => x.score === bestScore);
         // Sort candidates by recency (ascending lastSeenMs = most recently active first).
@@ -375,7 +432,8 @@ 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 = 1 === bestScore;
+        // Nothing healthy left to choose between (all throttled, or all wedged): drop the gap check.
+        const allThrottled = bestScore >= 1;
         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-mirror.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a tab that is only WATCHING gets to see of a drive happening somewhere else.
+ *
+ * Its own module because it is its own question — the rest of session.ts is about a session Reticle
+ * is DRIVING, and this is about the one it is not. Split out when session.ts crossed the 1000-line
+ * cap; the cap did its job, because these two had no reason to share a file beyond history.
+ */
+/**
+ * How a mirrored row is introduced on a tab that is only WATCHING.
+ *
+ * The row happened somewhere else, and a HUD that prints it unlabelled tells the reader their own
+ * tab was driven. Naming the session is also the handle they need to address it.
+ */
+export declare function mirroredNarration(sessionId: string, text: string): string;
+/** The pushes that are a REPORT of what happened, and so are worth showing to a watching tab. */
+export declare const MIRRORED_COMMANDS: ReadonlySet<string>;

package/dist/session/session-mirror.js

@@ -0,0 +1,22 @@
+/**
+ * What a tab that is only WATCHING gets to see of a drive happening somewhere else.
+ *
+ * Its own module because it is its own question — the rest of session.ts is about a session Reticle
+ * is DRIVING, and this is about the one it is not. Split out when session.ts crossed the 1000-line
+ * cap; the cap did its job, because these two had no reason to share a file beyond history.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+/**
+ * How a mirrored row is introduced on a tab that is only WATCHING.
+ *
+ * The row happened somewhere else, and a HUD that prints it unlabelled tells the reader their own
+ * tab was driven. Naming the session is also the handle they need to address it.
+ */
+export function mirroredNarration(sessionId, text) {
+    return `${sessionId} \u2192 ${text}`;
+}
+/** The pushes that are a REPORT of what happened, and so are worth showing to a watching tab. */
+export const MIRRORED_COMMANDS = new Set([
+    ReticleCommand.NARRATE,
+    ReticleCommand.IMPACT,
+]);

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

@@ -6,12 +6,26 @@ export interface RecommendationInputs {
     hidden: boolean;
     throttled: boolean;
     focused: boolean;
+    /**
+     * The shell this session runs in, as the SDK reported it at handshake. Undefined for an older SDK
+     * that does not report one — and an unknown runtime keeps the WEB advice, because a browser tab is
+     * what most sessions are and withholding a usable escape hatch is the worse error.
+     */
+    runtime?: string | undefined;
 }
 /**
- * A human-readable escape-hatch hint when a tab is hidden/throttled and may be
- * un-scriptable/un-focusable from here. Returns undefined for a healthy tab so the field stays
- * ABSENT (not empty). Keys on `hidden || throttled` — the same disjunction as Session.throttled —
- * so it never disagrees with the `throttled` flag the agent already sees. A merely-unfocused but
- * live tab is still scriptable, so blur alone does not trigger it. Pure.
+ * A human-readable hint when a tab is hidden or throttled. Returns undefined for a healthy tab so
+ * the field stays ABSENT (not empty). A merely-unfocused but live tab is still scriptable, so blur
+ * alone does not trigger it. Pure.
+ *
+ * HIDDEN and THROTTLED get DIFFERENT answers, which is the fix. They used to share one message that
+ * said "may be un-focusable; acquire a guaranteed scriptable context" — correct for a background
+ * tab, and actively harmful for a visible one. A visible throttled tab is driveable; measured in the
+ * field, one took a sign-in and two clean net-grade verdicts with no retries, while that message had
+ * already sent the agent into a lease the watching human could not see. One flag, advice that cost
+ * the product's main trust surface, and nothing bought.
+ *
+ * Hidden outranks throttled when both are set: a background tab is the stronger fact, and its
+ * failure mode (events landing on a page that never advances) is the one worth warning about.
  */
 export declare function buildSessionRecommendation(inputs: RecommendationInputs): string | undefined;

package/dist/session/session-recommendation.js

@@ -1,13 +1,29 @@
-import { UNSCRIPTABLE_TAB_RECOMMENDATION } from '@reticlehq/core';
+import { AppRuntime, DESKTOP_WINDOW_BACKGROUNDED, HIDDEN_TAB_RECOMMENDATION, THROTTLED_TAB_RECOMMENDATION, } from '@reticlehq/core';
 /**
- * A human-readable escape-hatch hint when a tab is hidden/throttled and may be
- * un-scriptable/un-focusable from here. Returns undefined for a healthy tab so the field stays
- * ABSENT (not empty). Keys on `hidden || throttled` — the same disjunction as Session.throttled —
- * so it never disagrees with the `throttled` flag the agent already sees. A merely-unfocused but
- * live tab is still scriptable, so blur alone does not trigger it. Pure.
+ * A human-readable hint when a tab is hidden or throttled. Returns undefined for a healthy tab so
+ * the field stays ABSENT (not empty). A merely-unfocused but live tab is still scriptable, so blur
+ * alone does not trigger it. Pure.
+ *
+ * HIDDEN and THROTTLED get DIFFERENT answers, which is the fix. They used to share one message that
+ * said "may be un-focusable; acquire a guaranteed scriptable context" — correct for a background
+ * tab, and actively harmful for a visible one. A visible throttled tab is driveable; measured in the
+ * field, one took a sign-in and two clean net-grade verdicts with no retries, while that message had
+ * already sent the agent into a lease the watching human could not see. One flag, advice that cost
+ * the product's main trust surface, and nothing bought.
+ *
+ * Hidden outranks throttled when both are set: a background tab is the stronger fact, and its
+ * failure mode (events landing on a page that never advances) is the one worth warning about.
  */
 export function buildSessionRecommendation(inputs) {
-    if (inputs.hidden || inputs.throttled)
-        return UNSCRIPTABLE_TAB_RECOMMENDATION;
-    return undefined;
+    if (!inputs.hidden && !inputs.throttled)
+        return undefined;
+    // A desktop window gets the one answer it can act on. Checked BEFORE hidden/throttled are told
+    // apart, because the distinction between them is about browser tab lifecycle and neither of its
+    // two answers exists for an app whose window is the client. See DESKTOP_WINDOW_BACKGROUNDED.
+    if (AppRuntime.ELECTRON === inputs.runtime || AppRuntime.TAURI === inputs.runtime) {
+        return DESKTOP_WINDOW_BACKGROUNDED;
+    }
+    if (inputs.hidden)
+        return HIDDEN_TAB_RECOMMENDATION;
+    return THROTTLED_TAB_RECOMMENDATION;
 }

package/dist/session/session-successor.js

@@ -9,6 +9,7 @@
  * Unique at the departed origin (and project, when known). Two live tabs at that origin is still a
  * guess, and a guess here would drive the wrong app.
  */
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
 const POLL_MS = 25;
 const REAL_CLOCK = {
     now: () => Date.now(),
@@ -22,6 +23,39 @@ function originOf(url) {
         return undefined;
     }
 }
+/**
+ * The session a URL explicitly CLAIMS to be, via `__reticle_session`.
+ *
+ * A leased tab carries this marker so the pool can find the context it opened, and an app can set it
+ * deliberately so a battery addresses a known id. Either way it is a claim of identity, not a
+ * coincidence of origin — which is what makes it the right thing to gate succession on.
+ */
+function claimedSessionOf(url) {
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether one session may inherit another's identity.
+ *
+ * Origin alone is not enough. A leased tab is an isolated context that an AGENT owns and no human
+ * can see; the developer's own tab at the same origin is a different trust and visibility domain
+ * entirely. Letting one succeed the other meant an expired lease silently redirected the next call
+ * into somebody's real browser tab — observed, twice, and reported as success.
+ *
+ * So a session that claims an explicit identity only ever succeeds to one claiming the SAME
+ * identity. A session that claims none is unaffected, which is the ordinary reload case this whole
+ * mechanism exists for.
+ */
+function mayInherit(departed, candidate) {
+    const claimed = claimedSessionOf(departed.url);
+    if (claimed === undefined)
+        return true;
+    return claimedSessionOf(candidate.url) === claimed;
+}
 function identityOf(session) {
     return {
         id: session.id,
@@ -44,7 +78,8 @@ export function pickDocumentSuccessor(live, departed) {
     if (sameId !== undefined)
         return sameId;
     const others = atOrigin.filter((s) => s.id !== departed.id &&
-        (departed.projectId === undefined || s.projectId === departed.projectId));
+        (departed.projectId === undefined || s.projectId === departed.projectId) &&
+        mayInherit(departed, s));
     if (1 !== others.length)
         return undefined;
     return others[0];

package/dist/session/session-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ReticleCommand } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { idleMsSchema } from '../tools/numeric-bounds.js';
 /**
  * Session lifecycle controls. The presenter session begins on the agent's first action and ends
  * either when the agent ends it (reticle_end_session) or after an idle window — and the human keeps the
@@ -13,8 +14,7 @@ export const SESSION_TOOLS = [
         name: ReticleTool.SESSION_TUNE,
         description: 'Tune the presenter session for this app. { idleEndMs } sets how long the session stays open after you go quiet before the panel shows the human you are WAITING (your turn). Default 5min — the SLOW backstop; signal handback IMMEDIATELY with reticle_session{action:"yield"} instead of waiting for this. Lower it for snappier auto-handback, raise it for a slow app where long gaps between your tool calls are normal. Enforced SERVER-SIDE (immune to background-tab throttling); it also fires if you (the MCP client) disconnect — so a forgotten or crashed session never leaves the HUD reading "live". Going quiet then acting again revives the session automatically. Returns { applied, idleEndMs }.',
         inputSchema: {
-            idleEndMs: z
-                .number()
+            idleEndMs: idleMsSchema
                 .optional()
                 .describe('Idle window in milliseconds after which the panel shows WAITING (your turn). Default: 300000 (5 min) — the slow backstop; prefer reticle_session{action:"yield"}. Raise for slow apps.'),
             sessionId: z

package/dist/session/session.d.ts

@@ -26,6 +26,17 @@ export declare class Session {
     readonly id: string;
     /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
     readonly projectId: string | undefined;
+    /**
+     * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
+     *
+     * Stamped once when the session is created, from the project it declared in HELLO, rather than
+     * resolved per call: the answer cannot change while the tab is connected, and resolving it once
+     * means every counter that fires for this session agrees about where it goes.
+     *
+     * Undefined when nothing could name a project — the caller then falls back to the daemon's own
+     * root, which is what every counter did unconditionally before this existed.
+     */
+    artifactRoot: string | undefined;
     url: string;
     title: string;
     adapters: string[];
@@ -62,6 +73,13 @@ export declare class Session {
     /** The attachable health block — single source of truth for the tools. */
     health(): SessionHealth;
     info(): SessionInfo;
+    /**
+     * Attached but not answering. A tab can be `connected` with a fresh `lastSeenMs` and still answer
+     * nothing: `lastSeenMs` measures the events the SDK streams, not the commands it replies to. Reuse
+     * and auto-selection read that as health, so `reticle open` handed a wedged tab back forever and
+     * `reticle_session{action:"end"}` — a flag on the record, not on the page — could not help.
+     */
+    unresponsive(): boolean;
     /** Wall-clock age of the session in milliseconds. */
     staleMs(): number;
     /** The document the most recent stamped event was observed under. See `#documentId`. */
@@ -187,10 +205,10 @@ export declare class Session {
     command(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<CommandResult>;
     handleResult(result: CommandResult): void;
     /** Reject everything still in flight — used on disconnect. */
-    rejectAll(reason: string): void;
+    rejectAll(reason: string, replaced?: boolean): void;
     succeededBy(next: Session): void;
     /** End this transport without letting a stale socket remove its replacement session. */
-    disconnect(reason: string): void;
+    disconnect(reason: string, replaced?: boolean): void;
     getState(): SessionState;
     isPaused(): boolean;
     isEnded(): boolean;
@@ -243,6 +261,8 @@ export declare class Session {
      * without needing an explicit polling loop.
      */
     ageWarning(): string | undefined;
+    /** Wired by SessionManager.add, the one place every session registers. */
+    setViewers(read: () => Session[]): void;
 }
 /**
  * Re-exported from session-manager.ts so the public import path (`./session.js`) is unchanged for