@reticlehq/server 2.2.1 → 2.3.0

package/dist/runs/run-diff.js

@@ -68,4 +68,3 @@ export function diffRuns(before, after, noiseFloorPct = DEFAULT_NOISE_FLOOR_PCT)
     };
     return { ...base, headline: headlineFor(base) };
 }
-//# sourceMappingURL=run-diff.js.map

package/dist/runs/run-store.d.ts

@@ -42,4 +42,3 @@ export declare class RunStore {
     latestTwo(): Promise<[ReticleVerificationRun, ReticleVerificationRun] | undefined>;
 }
 export {};
-//# sourceMappingURL=run-store.d.ts.map

package/dist/runs/run-store.js

@@ -135,4 +135,3 @@ export class RunStore {
         return [previous, current];
     }
 }
-//# sourceMappingURL=run-store.js.map

package/dist/runs/run-tools.d.ts

@@ -7,4 +7,3 @@ import type { ToolDef } from '../tools/tools.js';
  * reticleRoot (it is stateless), so this needs no new ToolDeps wiring.
  */
 export declare const RUN_TOOLS: ToolDef[];
-//# sourceMappingURL=run-tools.d.ts.map

package/dist/runs/run-tools.js

@@ -79,4 +79,3 @@ export const RUN_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=run-tools.js.map

package/dist/runs/runner-port.d.ts

@@ -11,4 +11,3 @@ import type { RunnerPort } from './reticle-runner.js';
 export declare function defaultRunId(): RunId;
 /** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
 export declare function createRunnerPort(deps: ToolDeps, sessionId?: string): RunnerPort;
-//# sourceMappingURL=runner-port.d.ts.map

package/dist/runs/runner-port.js

@@ -20,4 +20,3 @@ export function createRunnerPort(deps, sessionId) {
         newRunId: defaultRunId,
     };
 }
-//# sourceMappingURL=runner-port.js.map

package/dist/runs/verification-sync.d.ts

@@ -21,4 +21,3 @@ export interface TimedReplay {
  * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
  */
 export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], projectId: string | undefined): Promise<string | undefined>;
-//# sourceMappingURL=verification-sync.d.ts.map

package/dist/runs/verification-sync.js

@@ -64,4 +64,3 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     }
     return run.runId;
 }
-//# sourceMappingURL=verification-sync.js.map

package/dist/runs/verify-http.d.ts

@@ -31,4 +31,3 @@ export interface VerifyHttpResponse {
  * and returns a status + body. No sockets, no globals — a test calls it directly.
  */
 export declare function handleVerifyRequest(req: VerifyHttpRequest, runner: ReticleRunner, expectedToken: string, persist?: (run: ReticleVerificationRun) => Promise<void>): Promise<VerifyHttpResponse>;
-//# sourceMappingURL=verify-http.d.ts.map

package/dist/runs/verify-http.js

@@ -99,4 +99,3 @@ export async function handleVerifyRequest(req, runner, expectedToken, persist) {
         return { status: 500, body: { error: 'verify failed' } };
     }
 }
-//# sourceMappingURL=verify-http.js.map

package/dist/runs/verify-server.d.ts

@@ -23,4 +23,3 @@ export declare function startVerifyServer(opts: VerifyServerOptions, port: numbe
     server: http.Server;
     port: number;
 }>;
-//# sourceMappingURL=verify-server.d.ts.map

package/dist/runs/verify-server.js

@@ -96,4 +96,3 @@ export function startVerifyServer(opts, port) {
         });
     });
 }
-//# sourceMappingURL=verify-server.js.map

package/dist/server-version.d.ts

@@ -5,4 +5,3 @@ export declare const SERVER_VERSION: string;
  * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
  */
 export declare const RETICLE_NPM_PACKAGE: string;
-//# sourceMappingURL=server-version.d.ts.map

package/dist/server-version.js

@@ -7,4 +7,3 @@ export const SERVER_VERSION = _pkg.version;
  * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
  */
 export const RETICLE_NPM_PACKAGE = _pkg.name;
-//# sourceMappingURL=server-version.js.map

package/dist/session/command-timeout.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turn a bare command timeout into something the reader can act on.
+ *
+ * The default message — `command 'snapshot' timed out after 8000ms` — is eight seconds of silence
+ * followed by a fact with no cause. For a Tauri app the cause is usually not a bug in the app: its
+ * window was hidden before the webview had ever been PRESENTED, and a webview that has never been
+ * presented never loads its page. The session stays connected, so nothing looks wrong, and the
+ * developer goes hunting through their own code for a fault that is not there.
+ *
+ * This advice previously blamed occlusion — "macOS suspends an occluded or off-Space WKWebView" —
+ * which is false, and was the kind of wrong steer this function exists to prevent. A LOADED Tauri
+ * webview keeps answering while minimized, app-hidden, occluded, and on another Space.
+ *
+ * It then over-corrected: it asserted the hidden-before-load ordering as FACT. But the only evidence
+ * here is `hidden === true` — the ordering is never observed. Measured on a Tauri shell pointed at an
+ * external http origin, whose window nothing ever hid: the message confidently prescribed a fix for a
+ * mistake that had not been made, and two rounds of debugging went into the wrong place. A diagnostic
+ * that names the wrong cause is worse than a bare timeout, because the bare timeout at least sends
+ * the reader looking. So this now reports what is KNOWN and ranks the causes rather than picking one.
+ *
+ * The advice is ADDED, never substituted — the original fact still leads — and only for a runtime
+ * that can actually suffer it, since misdirecting an Electron user costs them the same hour.
+ */
+/** What the page told us about its shell, via PAGE_HEALTH. Undefined before the first report. */
+export type PageRuntime = 'electron' | 'tauri' | 'web';
+export interface TimeoutContext {
+    url: string;
+    /** The page's own last visibility report. */
+    hidden: boolean;
+    /** Reported by the SDK. A URL cannot distinguish a Tauri dev server from a plain localhost app. */
+    runtime?: PageRuntime;
+    /** ms since ANY inbound message from the SDK. Small = the page is demonstrably still running. */
+    lastSeenMs?: number;
+}
+export declare function commandTimeoutMessage(name: string, timeoutMs: number, context: TimeoutContext): string;

package/dist/session/command-timeout.js

@@ -0,0 +1,41 @@
+import { isOpaqueOrigin } from '@reticlehq/core';
+/**
+ * Inbound silence beyond this means the page may genuinely be wedged; inside it, the SDK has spoken
+ * recently enough that "the page is hung" is provably the wrong story. A page that is streaming
+ * events is executing JavaScript by definition.
+ */
+const RECENTLY_HEARD_MS = 2000;
+const ONE_WAY_ADVICE = 'The page is ALIVE — the SDK last reported to the bridge %MS%ms ago — but it is not answering ' +
+    'commands. A page that is still sending is executing JavaScript, so it is not hung, hidden or ' +
+    'suspended: messages are getting OUT and not back IN. Look at the bridge→page direction (a socket ' +
+    'replaced mid-session, a proxy buffering one way) rather than at your app.';
+const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWebView (Tauri) window, so the webview is ' +
+    'most likely not running the page at all. Two known causes, commonest first: (1) the window was ' +
+    'hidden BEFORE its first page load — a webview that has never been presented never loads, so hide ' +
+    'it from `on_page_load` instead of `setup` (see `reticle_tauri::on_page_load`, which does this for ' +
+    'RETICLE_HEADLESS=1); once the page HAS loaded, hiding it is safe. (2) the window never presented ' +
+    'for another reason — check that it is declared with a visible size and that the page URL actually ' +
+    'loaded. If neither fits, the page is reachable but not executing, which is worth reporting.';
+/** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
+function isWebKitDesktop(context) {
+    if (context.runtime === 'tauri')
+        return true;
+    // A `tauri://` origin is unambiguous even before the first health report lands.
+    if (context.runtime !== undefined)
+        return false;
+    return isOpaqueOrigin(context.url) && context.url.startsWith('tauri:');
+}
+export function commandTimeoutMessage(name, timeoutMs, context) {
+    const base = `command '${name}' timed out after ${String(timeoutMs)}ms`;
+    // Checked FIRST, and it overrides the visibility story: a page that was heard from moments ago is
+    // executing JavaScript, so "hidden, hung or never presented" cannot be the explanation whatever
+    // `hidden` says. Deduced from the invariant, not from a measured incident — the Tauri case that
+    // prompted it turned out to go fully silent instead, which this branch correctly does not claim.
+    const heard = context.lastSeenMs;
+    if (heard !== undefined && heard <= RECENTLY_HEARD_MS) {
+        return `${base}. ${ONE_WAY_ADVICE.replace('%MS%', String(heard))}`;
+    }
+    if (!context.hidden || !isWebKitDesktop(context))
+        return base;
+    return `${base}. ${HIDDEN_ADVICE}`;
+}

package/dist/session/control-envelope.d.ts

@@ -9,9 +9,9 @@ interface ControlEnvelope {
 }
 /**
  * Agent-readable hint returned when an action is refused mid-pause. Named, not free — the agent's
- * recovery path (address the guidance, then reticle_resume) lives here in exactly one place.
+ * recovery path (address the guidance, then reticle_session{action:"resume"}) lives here in exactly one place.
  */
-export declare const PAUSE_HINT = "Paused by the human. Address the guidance, then call reticle_resume (or wait for the human to resume).";
+export declare const PAUSE_HINT = "Paused by the human. Address the guidance, then call reticle_session{action:\"resume\"} (or wait for the human to resume).";
 /** Shape returned by the short-circuit when an action tool refuses while paused. */
 interface PausedResult {
     paused: true;
@@ -54,4 +54,3 @@ export declare function pausedShortCircuit(session: Session): PausedResult | und
  */
 export declare function withControl<T extends object>(session: Session, result: T): T & ControlSpread;
 export {};
-//# sourceMappingURL=control-envelope.d.ts.map

package/dist/session/control-envelope.js

@@ -2,9 +2,9 @@ import { SessionState } from '@reticlehq/core';
 import { z } from 'zod';
 /**
  * Agent-readable hint returned when an action is refused mid-pause. Named, not free — the agent's
- * recovery path (address the guidance, then reticle_resume) lives here in exactly one place.
+ * recovery path (address the guidance, then reticle_session{action:"resume"}) lives here in exactly one place.
  */
-export const PAUSE_HINT = 'Paused by the human. Address the guidance, then call reticle_resume (or wait for the human to resume).';
+export const PAUSE_HINT = 'Paused by the human. Address the guidance, then call reticle_session{action:"resume"} (or wait for the human to resume).';
 /**
  * outputSchema fields every action tool that can short-circuit on pause MUST declare, or a validating
  * profile strips the WHOLE pause payload — and because `guidance` is drained-once, that loses the
@@ -53,4 +53,3 @@ export function withControl(session, result) {
     const control = buildControlEnvelope(session);
     return control === undefined ? result : { ...result, control };
 }
-//# sourceMappingURL=control-envelope.js.map

package/dist/session/last-act.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What the most recent action was, kept so a LATER tool call can judge the window it opened.
+ *
+ * Reticle's act and observe tools are separate calls by design — act returns a cursor immediately and
+ * the agent decides when to look. That split means the tool doing the judging holds none of the facts
+ * the tool doing the acting measured, and every honesty check that needs both has to bridge the gap
+ * somewhere. This is that somewhere.
+ *
+ *  - **cursor** — the evaluation floor for wait_for/assert, so a signal buffered BEFORE the act can
+ *    never fake a later pass.
+ *  - **source** — where the acted control is written, for failures that have no element left to point
+ *    at because the action unmounted it.
+ *  - **action + mutatedWithin** — what was done and how much changed inside the target. Without these
+ *    the "this click did nothing" check is unreachable on the ordinary act-then-observe flow: an
+ *    empty-window test is a statement about the PAGE, and no real app has a quiet page.
+ */
+export interface ActEffect {
+    action?: string | undefined;
+    /** DOM mutations inside the acted element's own subtree. Undefined means nobody measured. */
+    mutatedWithin?: number | undefined;
+}
+export declare class LastAct {
+    #private;
+    markCursor(cursor: number): void;
+    cursor(): number | undefined;
+    markSource(source: string | undefined): void;
+    source(): string | undefined;
+    markEffect(action: string | undefined, mutatedWithin: number | undefined): void;
+    /** Empty when nothing has acted — callers then fall back to checks that need no action context. */
+    effect(): ActEffect;
+}

package/dist/session/last-act.js

@@ -0,0 +1,24 @@
+export class LastAct {
+    #cursor;
+    #source;
+    #effect;
+    markCursor(cursor) {
+        this.#cursor = cursor;
+    }
+    cursor() {
+        return this.#cursor;
+    }
+    markSource(source) {
+        this.#source = source;
+    }
+    source() {
+        return this.#source;
+    }
+    markEffect(action, mutatedWithin) {
+        this.#effect = { action, mutatedWithin };
+    }
+    /** Empty when nothing has acted — callers then fall back to checks that need no action context. */
+    effect() {
+        return this.#effect ?? {};
+    }
+}

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

@@ -13,4 +13,3 @@ import type { ToolDef } from '../tools/tools.js';
  * elapsed clock at enqueue time.
  */
 export declare const LIVE_CONTROL_TOOLS: ToolDef[];
-//# sourceMappingURL=live-control-tools.d.ts.map

package/dist/session/live-control-tools.js

@@ -26,7 +26,7 @@ export const LIVE_CONTROL_TOOLS = [
         name: ReticleTool.END_SESSION,
         description: 'End this session for good — use ONLY when the whole task is complete. Sets state "ended" ' +
             '(calm, terminal) and shows the optional `summary` on the panel. If you are just finishing a ' +
-            'turn or waiting on the human, call reticle_yield instead (revivable). Idempotent.',
+            'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent.',
         inputSchema: { summary: z.string().optional(), ...sessionIdShape },
         outputSchema: { ended: z.boolean(), sessionId: z.string() },
         handler: (deps, args) => {
@@ -43,7 +43,7 @@ export const LIVE_CONTROL_TOOLS = [
             'mode:"waiting" = you are done responding and will continue on their next message. ' +
             'mode:"ask" = you are blocked and need an answer first; put the question in `note` so it shows ' +
             'on the panel. The session is REVIVED automatically on your next tool call, so you never need to ' +
-            'reopen it. Use reticle_end_session instead only when the whole task is truly complete.',
+            'reopen it. Use reticle_session{action:"end"} instead only when the whole task is truly complete.',
         inputSchema: {
             mode: z
                 .enum([PresenterTone.WAITING, PresenterTone.ASK])
@@ -194,6 +194,5 @@ function buildFixHint(m) {
         : m.label !== undefined
             ? `Find the "${m.label}" element`
             : 'Find the flagged element';
-    return `${where} and fix: ${m.note}. Then call reticle_review { resolve: "${m.id}" }.`;
+    return `${where} and fix: ${m.note}. Then call reticle_session { action: "review", resolve: "${m.id}" }.`;
 }
-//# sourceMappingURL=live-control-tools.js.map

package/dist/session/live-control.d.ts

@@ -35,4 +35,3 @@ export declare class LiveControl {
      */
     nextStateFor(data: HumanControlData): SessionState | undefined;
 }
-//# sourceMappingURL=live-control.d.ts.map

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