@reticlehq/server 2.2.1 → 2.3.0

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

package/dist/session/session.js

@@ -1,12 +1,18 @@
-import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { LastAct } from './last-act.js';
+import { commandTimeoutMessage } from './command-timeout.js';
+import { readHealthEvent } from './session-health.js';
+import { PendingCommands } from './pending-commands.js';
+import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '../events/ring-buffer.js';
 import { filterEvents, mergeEventsBySeq, } from '../journal/journal-query.js';
 import {} from '../journal/ambient.js';
 import { ObservedState } from './observed-state.js';
+import { recordBrowserLatency, recordSdkFailure } from '../telemetry/session-metrics.js';
 import { LiveControl } from './live-control.js';
 import { ReviewStore } from './review-store.js';
 import { buildSessionRecommendation } from './session-recommendation.js';
 import { buildPresenterArgs } from './presenter-args.js';
+import { buildSessionLease } from './session-lease.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
@@ -30,15 +36,15 @@ export class Session {
     #clock;
     #startedAt;
     #buffer = new RingBuffer();
-    #pending = new Map();
+    #pending = new PendingCommands();
     #listeners = new Set();
-    #seq = 0;
     #actionSeq = 0;
     #lastSeenAt;
     #hidden = false;
+    /** Which shell the page reported (PAGE_HEALTH). Undefined until the first report lands. */
+    #runtime;
+    #engine;
     #focused = true;
-    #lastActCursor;
-    #lastActSource;
     /** Liveness: wall-clock of the last AGENT command (distinct from browser chatter / lastSeen). */
     #lastAgentActivityAt;
     /** Server-side mirror of the agent-tuned idle window, so the reaper honors reticle_session. */
@@ -82,10 +88,27 @@ export class Session {
     lastSeenMs() {
         return this.#clock() - this.#lastSeenAt;
     }
-    /** Record the latest page visibility/focus state from a PAGE_HEALTH event. */
-    applyHealth(hidden, focused) {
+    /**
+     * 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, focused, runtime, engine) {
         this.#hidden = hidden;
         this.#focused = focused;
+        if (runtime === 'electron' || runtime === 'tauri' || runtime === 'web') {
+            this.#runtime = runtime;
+        }
+        if (engine !== undefined)
+            this.#engine = engine;
+    }
+    /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
+    get runtime() {
+        return this.#runtime;
+    }
+    get engine() {
+        return this.#engine;
     }
     /** Throttled if the tab is hidden OR we have not heard from it recently. */
     throttled() {
@@ -120,14 +143,14 @@ export class Session {
         if (this.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
             base.stale = true;
             base.cleanup_suggestion =
-                'Call reticle_end_session to free this session before starting new work.';
+                'Call reticle_session{action:"end"} to free this session before starting new work.';
         }
         // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).
         const marks = this.#review.pendingCount();
         if (marks > 0) {
             base.pendingMarks = marks;
             const s = marks === 1 ? '' : 's';
-            base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_review to see and fix ${marks === 1 ? 'it' : 'them'}.`;
+            base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_session{action:"review"} to see and fix ${marks === 1 ? 'it' : 'them'}.`;
         }
         return base;
     }
@@ -138,10 +161,15 @@ export class Session {
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event, byteSize) {
         if (event.type === EventType.PAGE_HEALTH) {
-            const data = event.data;
-            const hidden = typeof data['hidden'] === 'boolean' ? data['hidden'] : this.#hidden;
-            const focused = typeof data['focused'] === 'boolean' ? data['focused'] : this.#focused;
-            this.applyHealth(hidden, focused);
+            const r = readHealthEvent(event.data);
+            this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine);
+        }
+        // The in-page half of Reticle reporting its own failure — recorded like a tool error
+        // (fingerprinted, variables stripped) so a broken observer is as visible as a broken tool.
+        if (event.type === EventType.SDK_FAILED) {
+            const sdk = parseEventPayload(EventType.SDK_FAILED, event.data);
+            if (sdk.success)
+                recordSdkFailure(sdk.data);
         }
         if (event.type === EventType.HUMAN_CONTROL) {
             // Narrow unknown at the boundary; an invalid/unknown control is ignored (never thrown).
@@ -178,7 +206,17 @@ export class Session {
         for (const listener of this.#listeners)
             listener(attributed);
     }
-    /** Latest count per blind-spot kind; survives buffer eviction. See ObservedState for why. */
+    // Passthroughs to ObservedState, which owns the per-session facts that must SURVIVE buffer
+    // eviction: refs the agent drove, and what the layer could not see. See observed-state.ts.
+    recordActedRef(ref) {
+        this.#observed.recordActedRef(ref);
+    }
+    actedRefs() {
+        return this.#observed.actedRefs();
+    }
+    noteRateLimited(dropped) {
+        this.#observed.noteRateLimited(dropped);
+    }
     blindSpots() {
         return this.#observed.blindSpots();
     }
@@ -241,24 +279,12 @@ export class Session {
         return this.#buffer.since(cursor);
     }
     /**
-     * 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) {
-        this.#lastActCursor = cursor;
-    }
-    /** The cursor of the last act, or undefined if nothing has acted yet. */
-    lastActCursor() {
-        return this.#lastActCursor;
-    }
-    /** Remember where the last acted control is written (`file:line`), for failures with no element. */
-    markActSource(source) {
-        this.#lastActSource = source;
-    }
-    /** Where the last acted control is written, or undefined if nothing has acted yet. */
-    lastActSource() {
-        return this.#lastActSource;
-    }
+    lastAct = new LastAct();
     // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
@@ -309,8 +335,16 @@ export class Session {
     }
     /** Send a command to the browser and await its reply (or time out). */
     command(name, args = {}, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
-        this.#seq += 1;
-        const id = `${COMMAND_ID_PREFIX}${String(this.#seq)}`;
+        // Recorded HERE rather than at the tool call sites: this is the one place every driven action
+        // passes through, so act_sequence and flow replay count too. Doing it per-tool missed both, and
+        // an under-counted "exercised" reports worse coverage than reality — the safe direction, but
+        // still wrong, and it made the number depend on which tool the agent happened to use.
+        if (name === ReticleCommand.ACT) {
+            const ref = args['ref'];
+            if (typeof ref === 'string')
+                this.recordActedRef(ref);
+        }
+        const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = JSON.stringify({
             kind: MessageKind.COMMAND,
             id,
@@ -318,30 +352,24 @@ export class Session {
             name,
             args,
         });
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.#pending.delete(id);
-                reject(new Error(`command '${name}' timed out after ${String(timeoutMs)}ms`));
-            }, timeoutMs);
-            this.#pending.set(id, { resolve, reject, timer });
-            this.#socket.send(payload);
-        });
+        // The timeout message is built LAZILY: health can change while a command is in flight, and the
+        // diagnosis should describe the page as it was when the command actually gave up.
+        const awaited = this.#pending.track(id, timeoutMs, () => commandTimeoutMessage(name, timeoutMs, {
+            url: this.url,
+            hidden: this.#hidden,
+            lastSeenMs: this.lastSeenMs(),
+            ...(this.#runtime === undefined ? {} : { runtime: this.#runtime }),
+        }));
+        this.#socket.send(payload);
+        const sentAt = Date.now(); // browser-leg timing; see recordBrowserLatency for why it is split out
+        return awaited.finally(() => recordBrowserLatency(Date.now() - sentAt));
     }
     handleResult(result) {
-        const pending = this.#pending.get(result.id);
-        if (pending === undefined)
-            return;
-        clearTimeout(pending.timer);
-        this.#pending.delete(result.id);
-        pending.resolve(result);
+        this.#pending.settle(result);
     }
     /** Reject everything still in flight — used on disconnect. */
     rejectAll(reason) {
-        for (const [id, pending] of this.#pending) {
-            clearTimeout(pending.timer);
-            pending.reject(new Error(reason));
-            this.#pending.delete(id);
-        }
+        this.#pending.rejectAll(reason);
     }
     /** End this transport without letting a stale socket remove its replacement session. */
     disconnect(reason) {
@@ -424,20 +452,12 @@ export class Session {
     pushNarration(text) {
         this.#post(ReticleCommand.NARRATE, { text, level: 'info' });
     }
-    /**
-     * 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.
-     */
+    /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease() {
         if (this.#firstCommandDone)
             return undefined;
         this.#firstCommandDone = true;
-        return {
-            sessionId: this.id,
-            opened_at: this.#startedAt,
-            IMPORTANT: 'MANDATORY: the moment you stop driving — finishing a reply or waiting on the human — call reticle_session {action:"yield", mode:"waiting"} (or mode:"ask" with your question) so the panel never falsely reads "live". Call reticle_session {action:"end"} only when the whole task is done. The session revives on your next action.',
-        };
+        return buildSessionLease(this.id, this.#startedAt);
     }
     /**
      * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
@@ -449,14 +469,24 @@ export class Session {
         if (ageMs < SESSION_LEASE.WARN_AFTER_MS)
             return undefined;
         const minutes = Math.floor(ageMs / 60_000);
-        return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_end_session now.`;
+        return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_session{action:"end"} now.`;
     }
     /** Fire-and-forget command send — NOT registered in #pending (no correlated result expected). */
     #post(name, args) {
         if (this.#socket.readyState !== WS_OPEN)
             return;
-        this.#seq += 1;
-        const id = `${COMMAND_ID_PREFIX}${String(this.#seq)}`;
+        // Shares the same counter as tracked commands, so a fire-and-forget id can never collide with
+        // one that IS awaiting a reply.
+        // Recorded HERE rather than at the tool call sites: this is the one place every driven action
+        // passes through, so act_sequence and flow replay count too. Doing it per-tool missed both, and
+        // an under-counted "exercised" reports worse coverage than reality — the safe direction, but
+        // still wrong, and it made the number depend on which tool the agent happened to use.
+        if (name === ReticleCommand.ACT) {
+            const ref = args['ref'];
+            if (typeof ref === 'string')
+                this.recordActedRef(ref);
+        }
+        const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = JSON.stringify({
             kind: MessageKind.COMMAND,
             id,
@@ -478,4 +508,3 @@ export class Session {
  * units under the file-size cap.
  */
 export { SessionManager } from './session-manager.js';
-//# sourceMappingURL=session.js.map

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

@@ -5,4 +5,3 @@
  * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
  */
 export { selectPath, capDepth, type PathSelection } from '@reticlehq/core';
-//# sourceMappingURL=state-select.d.ts.map

package/dist/session/state-select.js

@@ -5,4 +5,3 @@
  * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
  */
 export { selectPath, capDepth } from '@reticlehq/core';
-//# sourceMappingURL=state-select.js.map

package/dist/telemetry/argument-shape.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which flags and parameters people actually use — WITHOUT ever sending what they set them to.
+ *
+ * This is the most dangerous data in the product to collect, and the split that makes it safe is
+ * NAMES versus VALUES:
+ *
+ *   - A flag or parameter NAME comes from a closed vocabulary we wrote ourselves. `--headed`,
+ *     `--port`, `ref`, `timeout_ms` — there are a few dozen, none of them describe the user, and
+ *     knowing which ones get used is the whole product question ("is anyone passing `fullPage`?
+ *     does anybody use `--storage-state`?").
+ *   - A VALUE is the user's. `--http-token` holds a secret. `--drive` holds a URL. `reticle_act`'s
+ *     `args` holds the text being typed into the app, which on a login form is a password. A rule
+ *     like "send short values, they're probably enums" would leak all three.
+ *
+ * So values are never sent, with one narrow exception: a handful of parameters whose values ARE our
+ * own enums, listed explicitly below. `action: "click"` is our vocabulary, not the user's, and it
+ * answers a real question. Membership in that list is opt-in per parameter and each entry names the
+ * exact values allowed — anything outside the list is reported as `other`, so a schema change can
+ * never quietly start forwarding free text.
+ */
+export declare const OTHER_VALUE = "other";
+/** True for anything we are willing to report a value for. */
+export declare function isSafeEnumParam(name: string): boolean;
+/**
+ * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
+ * known enum. Never the raw value of anything else.
+ */
+export declare function describeParam(name: string, value: unknown): string;
+/** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */
+export declare function describeToolParams(args: Record<string, unknown>): string[];
+/**
+ * The flags PRESENT on a CLI invocation, by name only.
+ *
+ * Values are dropped without exception here — no enum allowlist — because the CLI's flag values are
+ * uniformly the user's: a port, a URL, a file path, a pairing token. `--http-token` alone is reason
+ * enough to make this rule absolute rather than case-by-case.
+ *
+ * Anything not starting with `--` is an argument, not a flag, and is dropped entirely: that is where
+ * the URL, the file list, and the feedback message live.
+ */
+export declare function describeCliFlags(argv: readonly string[]): string[];