@reticlehq/server 2.11.0 → 2.13.0

package/dist/session/session-manager.js

@@ -1,7 +1,9 @@
 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';
+import { pickDocumentSuccessor } from './session-successor.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)
@@ -61,6 +63,14 @@ function scopeMissError(connected, scope) {
  */
 /** How many bridge-initiated closes to remember for diagnosis. */
 const MAX_REMEMBERED_CLOSURES = 5;
+/**
+ * How many recently-departed session ids to remember for successor rebind.
+ *
+ * A full-document navigation HELLO's back under a new id while the agent still holds the old one.
+ * The tombstone is how `resolve(oldId)` finds the unique same-origin successor instead of refusing.
+ * Bounded so a long-lived daemon cannot accumulate one record per tab forever.
+ */
+const MAX_TOMBSTONES = 32;
 export class SessionManager {
     #sessions = new Map();
     /**
@@ -69,6 +79,13 @@ export class SessionManager {
      * Owned here because this is the one place that sees both halves — every add and every remove.
      */
     #attachment = new AttachmentHistory();
+    /**
+     * Recently departed sessions, keyed by the id the agent still holds.
+     *
+     * Insertion order is LRU: the oldest is dropped when the cap is hit. A reconnect under the same
+     * id forgets its tombstone — the live session is the answer then.
+     */
+    #tombstones = 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
@@ -95,13 +112,30 @@ 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.
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
+        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;
@@ -110,8 +144,40 @@ export class SessionManager {
         // 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);
+        this.#rememberTombstone(session);
         return this.#sessions.delete(session.id);
     }
+    #rememberTombstone(session) {
+        const origin = originOf(session.url);
+        if (origin === undefined)
+            return;
+        if (this.#tombstones.has(session.id))
+            this.#tombstones.delete(session.id);
+        this.#tombstones.set(session.id, {
+            id: session.id,
+            url: session.url,
+            ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+        });
+        while (this.#tombstones.size > MAX_TOMBSTONES) {
+            const oldest = this.#tombstones.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#tombstones.delete(oldest);
+        }
+    }
+    #successorOf(sessionId) {
+        const departed = this.#tombstones.get(sessionId);
+        if (departed === undefined)
+            return undefined;
+        const picked = pickDocumentSuccessor(this.all().map((s) => ({
+            id: s.id,
+            url: s.url,
+            ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
+        })), departed);
+        if (picked === undefined)
+            return undefined;
+        return this.#sessions.get(picked.id);
+    }
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
@@ -169,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;
@@ -184,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.
      *
@@ -213,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.
      *
@@ -239,7 +334,7 @@ export class SessionManager {
     }
     resolve(sessionId, scope) {
         if (sessionId !== undefined) {
-            const found = this.#sessions.get(sessionId);
+            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
             if (found === undefined) {
                 throw new Error(this.#unknownSessionError(sessionId));
             }
@@ -258,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
@@ -308,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).
@@ -326,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.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The session that took over after a full-document navigation.
+ *
+ * Reload keeps the id (sessionStorage). A click that loads a new document often does not: the SDK
+ * is torn down with the page and HELLO's back under a new id, while the agent still holds the old
+ * one. `navigate` already waits for that HELLO (`awaitArrival`) and returns the new id.
+ * `act_and_wait` and `assert` did not, so an MPA drive ended at the first link.
+ *
+ * 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 type { Session } from './session.js';
+export interface SessionIdentity {
+    id: string;
+    url: string;
+    projectId?: string;
+}
+export interface SuccessorClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * The one live session that can honestly take over from `departed`, or undefined when none or more
+ * than one could.
+ *
+ * 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;
+export interface SuccessorRegistry {
+    get(id: string): Session | undefined;
+    all(): readonly Session[];
+}
+/**
+ * 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.
+ */
+export declare function awaitDocumentSuccessor(sessions: SuccessorRegistry, departed: Session, timeoutMs: number, clock?: SuccessorClock): Promise<Session | null>;

package/dist/session/session-successor.js

@@ -0,0 +1,113 @@
+/**
+ * The session that took over after a full-document navigation.
+ *
+ * Reload keeps the id (sessionStorage). A click that loads a new document often does not: the SDK
+ * is torn down with the page and HELLO's back under a new id, while the agent still holds the old
+ * one. `navigate` already waits for that HELLO (`awaitArrival`) and returns the new id.
+ * `act_and_wait` and `assert` did not, so an MPA drive ended at the first link.
+ *
+ * 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(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        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,
+        url: session.url,
+        ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+    };
+}
+/**
+ * The one live session that can honestly take over from `departed`, or undefined when none or more
+ * than one could.
+ *
+ * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
+ */
+export function pickDocumentSuccessor(live, departed) {
+    const origin = originOf(departed.url);
+    if (origin === undefined)
+        return undefined;
+    const atOrigin = live.filter((s) => originOf(s.url) === origin);
+    const sameId = atOrigin.find((s) => s.id === departed.id);
+    if (sameId !== undefined)
+        return sameId;
+    const others = atOrigin.filter((s) => s.id !== departed.id &&
+        (departed.projectId === undefined || s.projectId === departed.projectId) &&
+        mayInherit(departed, s));
+    if (1 !== others.length)
+        return undefined;
+    return others[0];
+}
+/**
+ * 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.
+ */
+export async function awaitDocumentSuccessor(sessions, departed, timeoutMs, clock = REAL_CLOCK) {
+    const deadline = clock.now() + timeoutMs;
+    const departedIdentity = identityOf(departed);
+    for (;;) {
+        const sameId = sessions.get(departed.id);
+        if (sameId !== undefined && sameId !== departed)
+            return sameId;
+        // The departed session often still sits in the registry until the socket close lands. Leave it
+        // 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)
+            .map(identityOf), departedIdentity);
+        if (picked !== undefined) {
+            const live = sessions.get(picked.id);
+            if (live !== undefined && live !== departed)
+                return live;
+        }
+        if (clock.now() >= deadline)
+            return null;
+        await clock.sleep(POLL_MS);
+    }
+}

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

@@ -2,10 +2,11 @@ import type { WebSocket } from 'ws';
 import type { ImpactSnapshot } from '@reticlehq/core';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '../honesty/gap-ledger.js';
+import { CaptureLedger } from '../honesty/feature-capture.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, 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';
@@ -25,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[];
@@ -61,8 +73,19 @@ 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`. */
+    get currentDocumentId(): string | undefined;
+    /** The edit epoch the most recent stamped event was observed under. See `#editEpoch`. */
+    get currentEditEpoch(): number | undefined;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
@@ -100,8 +123,28 @@ export declare class Session {
      * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
      */
     beginAction(tool: string, args: Record<string, unknown>): string;
+    /**
+     * Record one action WITHOUT opening an attribution window — for a tool that returns a verdict but
+     * drives nothing, so no event it observes was caused by it. See `JournalRecorder.recordAction`.
+     */
+    recordAction(tool: string, args: Record<string, unknown>, effect?: unknown): string;
+    /**
+     * How many actions this session has dispatched.
+     *
+     * The counter that mints journal action ids, not a second one — so it equals the journal's own
+     * length, and `reticle_context`'s `step`, whenever this session journals at all.
+     */
+    get actionCount(): number;
     /** Close the active action window, persisting its action record with the settle outcome. */
     finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * The durable action ledger for this session — the ledger the run context is folded out of.
+     *
+     * `[]` when nothing journals this session (journaling disabled, or an id that is not a safe path
+     * segment). An absent ledger reads as an empty run, never as a missing one: the fold simply has
+     * nothing to say, which is the honest answer.
+     */
+    readJournalActions(): Promise<JournalAction[]>;
     /** Flush any buffered journal events to disk (call on session end). */
     flushJournal(): Promise<void>;
     eventsSince(cursor: number): ReticleEvent[];
@@ -120,6 +163,11 @@ export declare class Session {
      * end of it.
      */
     readonly gaps: GapLedger;
+    /**
+     * The read-only calls the journal does not keep, so "was `reticle_context` ever called" has
+     * something to fold. See honesty/feature-capture.ts — it is the only state that instrument adds.
+     */
+    readonly capture: CaptureLedger;
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
      * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the
@@ -157,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;
@@ -213,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