@reticlehq/server 2.2.0 → 2.3.0

package/dist/session/live-control.js

@@ -61,4 +61,3 @@ export class LiveControl {
         }
     }
 }
-//# sourceMappingURL=live-control.js.map

package/dist/session/observed-state.d.ts

@@ -40,7 +40,17 @@ export declare class ObservedState {
      * In-session counts win: they describe this page as it is now.
      */
     seedAmbient(counts: AmbientCounts): void;
-    /** Latest reported count per blind-spot kind, for the whole session. */
+    /** Record a driven ref. Idempotent. */
+    recordActedRef(ref: string): void;
+    /** Every ref driven so far this session. */
+    actedRefs(): ReadonlySet<string>;
+    /**
+     * Record bridge-side sampling as a blind spot.
+     *
+     * Every other blind spot is reported BY the SDK, which cannot report this one: the events were
+     * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
+     * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
+     */
+    noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;
 }
-//# sourceMappingURL=observed-state.d.ts.map

package/dist/session/observed-state.js

@@ -1,4 +1,4 @@
-import { EventType } from '@reticlehq/core';
+import { BlindSpotKind, EventType } from '@reticlehq/core';
 import { ambientKeyOf } from '../journal/ambient.js';
 /**
  * The two things a session learns by watching its own event stream, as opposed to storing.
@@ -69,8 +69,35 @@ export class ObservedState {
         this.#seededAmbient = { ...counts };
     }
     /** Latest reported count per blind-spot kind, for the whole session. */
+    /**
+     * Refs the agent has driven, for the exercised/untouched split `reticle_coverage` reports.
+     *
+     * Kept here beside the blind-spot counts because both are per-session observed facts that must
+     * SURVIVE buffer eviction. Deriving "what did I touch" from the event buffer instead would mean an
+     * action fifty steps ago silently stops counting, so "untouched" would quietly come to mean
+     * "recently untouched" — a number that reads as thorough while drifting toward the opposite.
+     */
+    #actedRefs = new Set();
+    /** Record a driven ref. Idempotent. */
+    recordActedRef(ref) {
+        if (ref.length > 0)
+            this.#actedRefs.add(ref);
+    }
+    /** Every ref driven so far this session. */
+    actedRefs() {
+        return this.#actedRefs;
+    }
+    /**
+     * Record bridge-side sampling as a blind spot.
+     *
+     * Every other blind spot is reported BY the SDK, which cannot report this one: the events were
+     * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
+     * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
+     */
+    noteRateLimited(dropped) {
+        this.#blindSpots[BlindSpotKind.RATE_LIMITED] = dropped;
+    }
     blindSpots() {
         return this.#blindSpots;
     }
 }
-//# sourceMappingURL=observed-state.js.map

package/dist/session/output-budget.d.ts

@@ -47,4 +47,3 @@ export declare function sizeCost(payload: unknown): SizeCost;
  */
 export declare function withSizeCost<T>(result: T): T;
 export {};
-//# sourceMappingURL=output-budget.d.ts.map

package/dist/session/output-budget.js

@@ -62,4 +62,3 @@ export function withSizeCost(result) {
         return result;
     return { ...result, cost: sizeCost(result) };
 }
-//# sourceMappingURL=output-budget.js.map

package/dist/session/pending-commands.d.ts

@@ -0,0 +1,12 @@
+import type { CommandResult } from '@reticlehq/core';
+export declare class PendingCommands {
+    #private;
+    /** Next correlation id. Monotonic per session, so a reply can never match an earlier command. */
+    nextId(prefix: string): string;
+    /** Register a command and arm its timeout. `describeTimeout` runs only if the reply never lands. */
+    track(id: string, timeoutMs: number, describeTimeout: () => string): Promise<CommandResult>;
+    /** Resolve the command this reply belongs to. Unknown ids are ignored, never thrown on. */
+    settle(result: CommandResult): void;
+    /** Reject everything still in flight — used on disconnect, so no caller waits on a dead socket. */
+    rejectAll(reason: string): void;
+}

package/dist/session/pending-commands.js

@@ -0,0 +1,36 @@
+export class PendingCommands {
+    #pending = new Map();
+    #seq = 0;
+    /** Next correlation id. Monotonic per session, so a reply can never match an earlier command. */
+    nextId(prefix) {
+        this.#seq += 1;
+        return `${prefix}${String(this.#seq)}`;
+    }
+    /** Register a command and arm its timeout. `describeTimeout` runs only if the reply never lands. */
+    track(id, timeoutMs, describeTimeout) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(describeTimeout()));
+            }, timeoutMs);
+            this.#pending.set(id, { resolve, reject, timer });
+        });
+    }
+    /** Resolve the command this reply belongs to. Unknown ids are ignored, never thrown on. */
+    settle(result) {
+        const pending = this.#pending.get(result.id);
+        if (pending === undefined)
+            return;
+        clearTimeout(pending.timer);
+        this.#pending.delete(result.id);
+        pending.resolve(result);
+    }
+    /** Reject everything still in flight — used on disconnect, so no caller waits on a dead socket. */
+    rejectAll(reason) {
+        for (const [id, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(reason));
+            this.#pending.delete(id);
+        }
+    }
+}

package/dist/session/presenter-args.d.ts

@@ -5,4 +5,3 @@ import { PresenterTone, SessionState } from '@reticlehq/core';
  * Tone only rides an ended push; live transitions (active/paused) never carry one. Pure.
  */
 export declare function buildPresenterArgs(state: SessionState, text: string | undefined, tone: PresenterTone | undefined): Record<string, unknown>;
-//# sourceMappingURL=presenter-args.d.ts.map

package/dist/session/presenter-args.js

@@ -12,4 +12,3 @@ export function buildPresenterArgs(state, text, tone) {
         ...(carriesTone ? { tone } : {}),
     };
 }
-//# sourceMappingURL=presenter-args.js.map

package/dist/session/review-store.d.ts

@@ -37,4 +37,3 @@ export declare class ReviewStore {
      */
     resolve(id: string): boolean;
 }
-//# sourceMappingURL=review-store.d.ts.map

package/dist/session/review-store.js

@@ -58,4 +58,3 @@ export class ReviewStore {
         return true;
     }
 }
-//# sourceMappingURL=review-store.js.map

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

@@ -1,4 +1,15 @@
-import type { Session, SessionHealth } from './session.js';
+import type { Session } from './session.js';
+/**
+ * The health block spliced onto act/assert results. Defined here rather than in session.ts: this is
+ * the module that builds it, and session.ts was over the file-size cap.
+ */
+export interface SessionHealth {
+    lastSeenMs: number;
+    throttled: boolean;
+    focused: boolean;
+    /** present only when hidden/throttled — points at the `reticle drive` escape hatch. */
+    recommendation?: string;
+}
 /** The evidence-completeness block spliced onto observe/network/console results. */
 interface BufferEnvelope {
     buffer?: {
@@ -33,5 +44,18 @@ export declare function healthEnvelope(session: Session): HealthEnvelope;
  * warn-only so background testing never breaks.
  */
 export declare function refuseIfThrottled(session: Session, refuse: unknown): void;
+/** The page's own visibility/runtime report, narrowed out of an untrusted PAGE_HEALTH payload. */
+export interface HealthReport {
+    hidden: boolean | undefined;
+    focused: boolean | undefined;
+    runtime: string | undefined;
+    /** Coarse rendering engine (blink/gecko/webkit) — context for a feedback report, not a health input. */
+    engine: string | undefined;
+}
+/**
+ * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report
+ * `runtime` at all — so each is returned as undefined rather than defaulted here, letting the caller
+ * keep its previous value instead of silently flipping a session to "visible" on a partial report.
+ */
+export declare function readHealthEvent(data: Record<string, unknown>): HealthReport;
 export {};
-//# sourceMappingURL=session-health.d.ts.map

package/dist/session/session-health.js

@@ -35,4 +35,16 @@ export function refuseIfThrottled(session, refuse) {
         throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
     }
 }
-//# sourceMappingURL=session-health.js.map
+/**
+ * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report
+ * `runtime` at all — so each is returned as undefined rather than defaulted here, letting the caller
+ * keep its previous value instead of silently flipping a session to "visible" on a partial report.
+ */
+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,
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+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;
+    adapters: string[];
+    hasCapabilities: boolean;
+    /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
+    lastSeenMs: number;
+    hidden: boolean;
+    focused: boolean;
+    throttled: boolean;
+    /** present only when hidden/throttled — points at the `reticle drive` escape hatch. */
+    recommendation?: string;
+    stale?: boolean;
+    cleanup_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. */
+    review_suggestion?: string;
+}

package/dist/session/session-info.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * The one-time session lease block, returned on the very first agent command of a session.
+ *
+ * It has to be carried in a RESULT rather than in `reticle_session`'s tool description: that tool is
+ * not advertised under the default `hybrid` profile, so its description is never in the agent's
+ * context, and the lease is the only place these two calls are ever named. Coding agents read tool
+ * results, so this is where the reminder actually lands.
+ */
+export interface SessionLease {
+    sessionId: string;
+    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

@@ -0,0 +1,14 @@
+/**
+ * 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 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

@@ -10,11 +10,6 @@ interface ResolveScope {
 }
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export declare function originOf(url: string | undefined): string | undefined;
-/**
- * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
- * tool targets when the agent omits an explicit sessionId. Extracted from session.ts so each file
- * stays one cohesive unit (Session = one tab; SessionManager = the registry over all tabs).
- */
 export declare class SessionManager {
     #private;
     /** Set the active project's default resolve scope (called once at daemon wiring). */
@@ -26,20 +21,13 @@ export declare class SessionManager {
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
     count(): number;
-    /**
-     * Resolve the target session. With an explicit id, returns it. With none and exactly
-     * one connected, returns that.
-     *
-     * With none and multiple connected, applies smart auto-selection:
-     * 1. Prefer non-throttled sessions (not hidden + recently heard from).
-     * 2. Within each tier, prefer lowest lastSeenMs (most recently active SDK heartbeat).
-     * 3. If two or more non-throttled sessions are within 1 s of each other, throw —
-     * genuinely ambiguous, agent must specify sessionId.
-     * 4. If ALL sessions are throttled (e.g. user is working in their editor on another
-     * desktop), skip the gap check and pick the freshest heartbeat. This lets the agent
-     * keep working in the background without requiring sessionId every time.
-     */
+    /** 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. */
+    lastClosure(): {
+        at: number;
+        reason: string;
+    } | undefined;
     resolve(sessionId?: string, scope?: ResolveScope): Session;
 }
 export {};
-//# sourceMappingURL=session-manager.d.ts.map

package/dist/session/session-manager.js

@@ -42,6 +42,8 @@ function scopeMissError(scope) {
  * tool targets when the agent omits an explicit sessionId. Extracted from session.ts so each file
  * stays one cohesive unit (Session = one tab; SessionManager = the registry over all tabs).
  */
+/** How many bridge-initiated closes to remember for diagnosis. */
+const MAX_REMEMBERED_CLOSURES = 5;
 export class SessionManager {
     #sessions = new Map();
     /**
@@ -91,6 +93,29 @@ export class SessionManager {
      * desktop), skip the gap check and pick the freshest heartbeat. This lets the agent
      * keep working in the background without requiring sessionId every time.
      */
+    /**
+     * Why a session recently went away, when the bridge closed it rather than the tab.
+     *
+     * The bridge enforces a message-rate cap and closes the socket on breach with `1008 message rate
+     * exceeded` — a policy violation, so the SDK does not retry. The app keeps running and Reticle is
+     * blind from that moment. Measured on the bench app: 2600 requests fired in one tick disconnected
+     * the session permanently, and the only trace was a line in the PAGE console, which no agent reads.
+     *
+     * Without this the agent is told "no browser session connected — check your app is running with
+     * @reticlehq/browser enabled", which is precisely wrong: the app IS running and instrumented. It
+     * was hung up on. Keeping the last few reasons turns an unexplained disappearance into a fact.
+     */
+    #recentClosures = [];
+    /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
+    noteClosure(reason, at) {
+        this.#recentClosures.push({ at, reason });
+        if (this.#recentClosures.length > MAX_REMEMBERED_CLOSURES)
+            this.#recentClosures.shift();
+    }
+    /** The most recent bridge-initiated close, if any. */
+    lastClosure() {
+        return this.#recentClosures[this.#recentClosures.length - 1];
+    }
     resolve(sessionId, scope) {
         if (sessionId !== undefined) {
             const found = this.#sessions.get(sessionId);
@@ -101,7 +126,10 @@ export class SessionManager {
             return found;
         }
         if (this.#sessions.size === 0) {
-            throw new Error(NO_SESSION_CONNECTED_ERROR);
+            const closure = this.lastClosure();
+            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.`);
         }
         // 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
@@ -153,4 +181,3 @@ export class SessionManager {
         return best.s;
     }
 }
-//# sourceMappingURL=session-manager.js.map

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

@@ -32,4 +32,3 @@ export declare const RETICLE_LOOP_GUIDE: string;
  */
 export declare function waitForReady(opts: WaitForReadyOptions): Promise<boolean>;
 export {};
-//# sourceMappingURL=session-readiness.d.ts.map

package/dist/session/session-readiness.js

@@ -6,10 +6,10 @@ const DEFAULT_POLL_MS = 100;
  */
 export const RETICLE_LOOP_GUIDE = 'Reticle loop — LOOK: reticle_snapshot / reticle_query / reticle_inspect · ACT: reticle_act (or reticle_act_and_wait) · ' +
     'OBSERVE: reticle_observe / reticle_wait_for / reticle_network / reticle_console · ASSERT: reticle_assert over program ' +
-    'truth, not just the DOM · REGRESS: reticle_record_start → reticle_replay, or reticle_flow_verify for the whole ' +
-    'suite. The human can flag bugs from the panel — drain them with reticle_review and resolve each once fixed. ' +
+    'truth, not just the DOM · REGRESS: reticle_record{action:"start"} → reticle_replay, or reticle_flow_verify for the whole ' +
+    'suite. The human can flag bugs from the panel — drain them with reticle_session{action:"review"} and resolve each once fixed. ' +
     'MANDATORY: the moment you stop driving — finishing your reply or waiting on the human — call reticle_session {action:"yield"} ' +
-    '(mode:"waiting", or mode:"ask" with the question) so the panel shows your real state; reticle_end_session ' +
+    '(mode:"waiting", or mode:"ask" with the question) so the panel shows your real state; reticle_session{action:"end"} ' +
     'only when the whole task is done. Never leave the panel reading "live" when you have actually stopped.';
 /**
  * Resolve `true` as soon as at least one session is connected, or `false` if the timeout elapses
@@ -29,4 +29,3 @@ export async function waitForReady(opts) {
             return true;
     }
 }
-//# sourceMappingURL=session-readiness.js.map

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

@@ -34,4 +34,3 @@ export declare class SessionReaper {
     start(): void;
     stop(): void;
 }
-//# sourceMappingURL=session-reaper.d.ts.map

package/dist/session/session-reaper.js

@@ -91,4 +91,3 @@ export class SessionReaper {
         this.#timer = undefined;
     }
 }
-//# sourceMappingURL=session-reaper.js.map

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

@@ -15,4 +15,3 @@ export interface RecommendationInputs {
  * live tab is still scriptable, so blur alone does not trigger it. Pure.
  */
 export declare function buildSessionRecommendation(inputs: RecommendationInputs): string | undefined;
-//# sourceMappingURL=session-recommendation.d.ts.map

package/dist/session/session-recommendation.js

@@ -11,4 +11,3 @@ export function buildSessionRecommendation(inputs) {
         return UNSCRIPTABLE_TAB_RECOMMENDATION;
     return undefined;
 }
-//# sourceMappingURL=session-recommendation.js.map

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

@@ -6,4 +6,3 @@ import type { ToolDef } from '../tools/tools.js';
  * for the app: raise it for a slow app, lower it for a quick check.
  */
 export declare const SESSION_TOOLS: ToolDef[];
-//# sourceMappingURL=session-tools.d.ts.map

package/dist/session/session-tools.js

@@ -11,12 +11,12 @@ import { asNumber, asString } from '../tools/tools-helpers.js';
 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_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 }.',
+        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()
                 .optional()
-                .describe('Idle window in milliseconds after which the panel shows WAITING (your turn). Default: 300000 (5 min) — the slow backstop; prefer reticle_yield. Raise for slow apps.'),
+                .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
                 .string()
                 .optional()
@@ -40,4 +40,3 @@ export const SESSION_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=session-tools.js.map

package/dist/session/session.d.ts

@@ -1,4 +1,8 @@
 import type { WebSocket } from 'ws';
+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 type { JournalReader, JournalRecorder } from '../journal/journal-recorder.js';
 import { type EventQueryOptions } from '../journal/journal-query.js';
@@ -6,36 +10,9 @@ import { type AmbientCounts } from '../journal/ambient.js';
 import { type InboxMessage } from './live-control.js';
 export type { InboxMessage } from './live-control.js';
 import { type ReviewMark } from './review-store.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;
-    adapters: string[];
-    hasCapabilities: boolean;
-    /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
-    lastSeenMs: number;
-    hidden: boolean;
-    focused: boolean;
-    throttled: boolean;
-    /** present only when hidden/throttled — points at the `reticle drive` escape hatch. */
-    recommendation?: string;
-    stale?: boolean;
-    cleanup_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. */
-    review_suggestion?: string;
-}
-/** The health block spliced onto act/assert results. */
-export interface SessionHealth {
-    lastSeenMs: number;
-    throttled: boolean;
-    focused: boolean;
-    /** present only when hidden/throttled — points at the `reticle drive` escape hatch. */
-    recommendation?: string;
-}
+import { type SessionLease } from './session-lease.js';
+import type { SessionInfo } from './session-info.js';
+export type { SessionInfo } from './session-info.js';
 type Clock = () => number;
 /**
  * One connected browser tab. Owns its socket, a ring buffer of observations, and the
@@ -57,8 +34,16 @@ export declare class Session {
     touch(): void;
     /** ms since the SDK last reported anything (distinct from elapsed-since-connect). */
     lastSeenMs(): number;
-    /** Record the latest page visibility/focus state from a PAGE_HEALTH event. */
-    applyHealth(hidden: boolean, focused: boolean): void;
+    /**
+     * Record the latest page visibility/focus state from a PAGE_HEALTH event.
+     *
+     * `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;
+    /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
+    get runtime(): PageRuntime | undefined;
+    get engine(): string | 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. */
@@ -68,7 +53,9 @@ export declare class Session {
     staleMs(): number;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
-    /** Latest count per blind-spot kind; survives buffer eviction. See ObservedState for why. */
+    recordActedRef(ref: string): void;
+    actedRefs(): ReadonlySet<string>;
+    noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;
     /** Learned ambient-churn counts (PredicateSession hook the settle oracle reads). */
     ambientCounts(): AmbientCounts;
@@ -99,16 +86,12 @@ export declare class Session {
     flushJournal(): Promise<void>;
     eventsSince(cursor: number): ReticleEvent[];
     /**
-     * Honesty: remember the event cursor of the most recent act so wait_for/assert can default their
-     * evaluation floor to it — a signal buffered before this act can never fake a later pass.
+     * What the most recent act was: its cursor, its source, and what it changed inside its target.
+     *
+     * Exposed as the object rather than six pass-through methods — act writes to it and observe reads
+     * from it, and the split between those two tool calls is the whole reason it exists.
      */
-    markActCursor(cursor: number): void;
-    /** The cursor of the last act, or undefined if nothing has acted yet. */
-    lastActCursor(): number | undefined;
-    /** Remember where the last acted control is written (`file:line`), for failures with no element. */
-    markActSource(source: string | undefined): void;
-    /** Where the last acted control is written, or undefined if nothing has acted yet. */
-    lastActSource(): string | undefined;
+    readonly lastAct: LastAct;
     /**
      * 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
@@ -177,16 +160,8 @@ export declare class Session {
     pushPresenter(state: SessionState, text?: string, tone?: PresenterTone): void;
     /** Fire-and-forget a narration row to the live panel (so a resolved mark shows "✓ fixed"). */
     pushNarration(text: string): void;
-    /**
-     * Returns the one-time session lease block on the very first agent command, then undefined
-     * forever after. The lease carries an IMPORTANT reminder to call reticle_end_session. Coding agents
-     * (Claude Code, Codex) read tool results — they will see this and remember to clean up.
-     */
-    takeSessionLease(): {
-        sessionId: string;
-        opened_at: number;
-        IMPORTANT: string;
-    } | undefined;
+    /** The one-time lease block on the first agent command, then undefined forever after. */
+    takeSessionLease(): SessionLease | undefined;
     /**
      * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
      * Spliced onto every session-bound tool result so the agent is passively reminded to clean up
@@ -200,4 +175,3 @@ export declare class Session {
  * units under the file-size cap.
  */
 export { SessionManager } from './session-manager.js';
-//# sourceMappingURL=session.d.ts.map