@reticlehq/server 2.0.0

package/dist/session/presenter-args.js

@@ -0,0 +1,15 @@
+import { PresenterTone, SessionState } from '@reticlehq/core';
+/**
+ * Build the args for a PRESENTER push. An ended session can carry a `tone` so the panel tells apart
+ * how the agent stopped — waiting (turn done), ask (needs you), warn (crashed) — from a calm "done".
+ * Tone only rides an ended push; live transitions (active/paused) never carry one. Pure.
+ */
+export function buildPresenterArgs(state, text, tone) {
+    const carriesTone = state === SessionState.ENDED && tone !== undefined && tone !== PresenterTone.CALM;
+    return {
+        state,
+        ...(text !== undefined ? { text } : {}),
+        ...(carriesTone ? { tone } : {}),
+    };
+}
+//# sourceMappingURL=presenter-args.js.map

package/dist/session/presenter-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter-args.js","sourceRoot":"","sources":["../../src/session/presenter-args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAmB,EACnB,IAAwB,EACxB,IAA+B;IAE/B,MAAM,WAAW,GACf,KAAK,KAAK,YAAY,CAAC,KAAK,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,aAAa,CAAC,IAAI,CAAC;IACpF,OAAO;QACL,KAAK;QACL,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,40 @@
+import { MarkStatus, type HumanMarkData, type MarkAnchorStrategy } from '@reticlehq/core';
+/**
+ * One human review mark: a mistake a human flagged on the running page, pinned to an element, ready
+ * for the agent to drain and fix. The wire payload (HumanMarkData) plus a server-assigned id, the
+ * session-relative time it landed, and its lifecycle status.
+ */
+export interface ReviewMark {
+    id: string;
+    note: string;
+    /** Re-resolvable element anchor (auto-anchor string). */
+    anchor: string;
+    strategy: MarkAnchorStrategy;
+    label?: string;
+    /** Source file:line the agent should open to fix it, when the framework stamped one. */
+    source?: {
+        file: string;
+        line: number;
+    };
+    route?: string;
+    /** Session-relative ms the mark was made (injected clock at the call site — never read here). */
+    at: number;
+    status: MarkStatus;
+}
+export declare class ReviewStore {
+    #private;
+    /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
+    add(data: HumanMarkData, at: number): ReviewMark;
+    /** All marks still awaiting a fix, oldest first. Reading never consumes — resolve() retires a mark. */
+    pending(): ReviewMark[];
+    /** Count of pending marks, for the panel badge / diagnostics. */
+    pendingCount(): number;
+    /** Full history (pending + resolved), oldest first. */
+    all(): ReviewMark[];
+    /**
+     * Retire a mark the agent has fixed. Returns true on a genuine pending → resolved transition,
+     * false for an unknown id or an already-resolved mark (so resolve is idempotent).
+     */
+    resolve(id: string): boolean;
+}
+//# sourceMappingURL=review-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"review-store.d.ts","sourceRoot":"","sources":["../../src/session/review-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1F;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAeD,qBAAa,WAAW;;IAItB,gGAAgG;IAChG,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAiBhD,uGAAuG;IACvG,OAAO,IAAI,UAAU,EAAE;IAIvB,iEAAiE;IACjE,YAAY,IAAI,MAAM;IAItB,uDAAuD;IACvD,GAAG,IAAI,UAAU,EAAE;IAInB;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAM7B"}

package/dist/session/review-store.js

@@ -0,0 +1,61 @@
+import { MarkStatus } from '@reticlehq/core';
+/**
+ * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
+ * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
+ * resolve() when the agent claims the fix — distinct from the live-control inbox, which is drained
+ * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
+ * THEN resolve, and a fix can be verified against the same mark.
+ *
+ * Pure in-memory state: no IO, no clock. The id is a monotonic counter (m1, m2, …) so it is
+ * deterministic and never depends on Math.random/Date.now; the timestamp is passed in by the caller.
+ */
+/** Prefix on review-mark ids (m1, m2, …) — distinguishes them from command ids. */
+const MARK_ID_PREFIX = 'm';
+export class ReviewStore {
+    #marks = [];
+    #seq = 0;
+    /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
+    add(data, at) {
+        this.#seq += 1;
+        const mark = {
+            id: `${MARK_ID_PREFIX}${String(this.#seq)}`,
+            note: data.note,
+            anchor: data.anchor,
+            strategy: data.strategy,
+            at,
+            status: MarkStatus.PENDING,
+        };
+        if (data.label !== undefined)
+            mark.label = data.label;
+        if (data.source !== undefined)
+            mark.source = data.source;
+        if (data.route !== undefined)
+            mark.route = data.route;
+        this.#marks.push(mark);
+        return mark;
+    }
+    /** All marks still awaiting a fix, oldest first. Reading never consumes — resolve() retires a mark. */
+    pending() {
+        return this.#marks.filter((m) => m.status === MarkStatus.PENDING).map((m) => ({ ...m }));
+    }
+    /** Count of pending marks, for the panel badge / diagnostics. */
+    pendingCount() {
+        return this.#marks.reduce((n, m) => (m.status === MarkStatus.PENDING ? n + 1 : n), 0);
+    }
+    /** Full history (pending + resolved), oldest first. */
+    all() {
+        return this.#marks.map((m) => ({ ...m }));
+    }
+    /**
+     * Retire a mark the agent has fixed. Returns true on a genuine pending → resolved transition,
+     * false for an unknown id or an already-resolved mark (so resolve is idempotent).
+     */
+    resolve(id) {
+        const mark = this.#marks.find((m) => m.id === id);
+        if (mark === undefined || mark.status === MarkStatus.RESOLVED)
+            return false;
+        mark.status = MarkStatus.RESOLVED;
+        return true;
+    }
+}
+//# sourceMappingURL=review-store.js.map

package/dist/session/review-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-store.js","sourceRoot":"","sources":["../../src/session/review-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA+C,MAAM,iBAAiB,CAAC;AAsB1F;;;;;;;;;GASG;AACH,mFAAmF;AACnF,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,MAAM,OAAO,WAAW;IACb,MAAM,GAAiB,EAAE,CAAC;IACnC,IAAI,GAAG,CAAC,CAAC;IAET,gGAAgG;IAChG,GAAG,CAAC,IAAmB,EAAE,EAAU;QACjC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QACf,MAAM,IAAI,GAAe;YACvB,EAAE,EAAE,GAAG,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAC3C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,EAAE;YACF,MAAM,EAAE,UAAU,CAAC,OAAO;SAC3B,CAAC;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACtD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uGAAuG;IACvG,OAAO;QACL,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,iEAAiE;IACjE,YAAY;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,uDAAuD;IACvD,GAAG;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,EAAU;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5E,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

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

@@ -0,0 +1,22 @@
+import type { Session, SessionHealth } from './session.js';
+/** The `session` (and optional throttled `warning`) block spliced onto act/assert results. */
+interface HealthEnvelope {
+    session?: SessionHealth;
+    warning?: string;
+}
+/**
+ * Build the health envelope for a tool result. When the session is **nominal** (focused, not
+ * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
+ * conveys nothing actionable, and emitting it on every act/observe/assert call is pure token
+ * overhead. The block (and a throttled `warning`) appears only when something is actually wrong,
+ * so no health signal is lost — absence means healthy.
+ */
+export declare function healthEnvelope(session: Session): HealthEnvelope;
+/**
+ * Opt-in hard stop. When `refuseWhenThrottled` is true and the tab is throttled, throw so the
+ * agent does not drive a tab where timers/rAF/pointer gestures may silently no-op. Default is
+ * warn-only so background testing never breaks.
+ */
+export declare function refuseIfThrottled(session: Session, refuse: unknown): void;
+export {};
+//# sourceMappingURL=session-health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-health.d.ts","sourceRoot":"","sources":["../../src/session/session-health.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE3D,8FAA8F;AAC9F,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAK/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAIzE"}

package/dist/session/session-health.js

@@ -0,0 +1,26 @@
+import { THROTTLED_WARNING } from '@reticlehq/core';
+/**
+ * Build the health envelope for a tool result. When the session is **nominal** (focused, not
+ * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
+ * conveys nothing actionable, and emitting it on every act/observe/assert call is pure token
+ * overhead. The block (and a throttled `warning`) appears only when something is actually wrong,
+ * so no health signal is lost — absence means healthy.
+ */
+export function healthEnvelope(session) {
+    const health = session.health();
+    const nominal = !health.throttled && health.focused && health.recommendation === undefined;
+    if (nominal)
+        return {};
+    return health.throttled ? { session: health, warning: THROTTLED_WARNING } : { session: health };
+}
+/**
+ * Opt-in hard stop. When `refuseWhenThrottled` is true and the tab is throttled, throw so the
+ * agent does not drive a tab where timers/rAF/pointer gestures may silently no-op. Default is
+ * warn-only so background testing never breaks.
+ */
+export function refuseIfThrottled(session, refuse) {
+    if (refuse === true && session.throttled()) {
+        throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
+    }
+}
+//# sourceMappingURL=session-health.js.map

package/dist/session/session-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-health.js","sourceRoot":"","sources":["../../src/session/session-health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AASpD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC;IAC3F,IAAI,OAAO;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAClG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,MAAe;IACjE,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,oBAAoB,iBAAiB,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,43 @@
+import { Session, type SessionInfo } from './session.js';
+/**
+ * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
+ * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
+ * don't stamp a projectId. Both optional — an empty scope means "no project filter" (legacy behavior).
+ */
+interface ResolveScope {
+    projectId?: string;
+    url?: string;
+}
+/**
+ * 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). */
+    setDefaultScope(scope: ResolveScope | undefined): void;
+    add(session: Session): Session | undefined;
+    remove(session: Session): boolean;
+    get(sessionId: string): Session | undefined;
+    list(): SessionInfo[];
+    /** 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.
+     */
+    resolve(sessionId?: string, scope?: ResolveScope): Session;
+}
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/session/session-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;GAIG;AACH,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAwCD;;;;GAIG;AACH,qBAAa,cAAc;;IASzB,qFAAqF;IACrF,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAItD,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAM1C,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAMjC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI3C,IAAI,IAAI,WAAW,EAAE;IAIrB,iGAAiG;IACjG,GAAG,IAAI,OAAO,EAAE;IAIhB,KAAK,IAAI,MAAM;IAIf;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO;CAsE3D"}

package/dist/session/session-manager.js

@@ -0,0 +1,155 @@
+import { Session } from './session.js';
+/** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
+function originOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Narrow a session list to those belonging to the scoped project. With a `projectId` the match is by
+ * that stable id (origin ignored — it survives port swaps). With only a `url`, match by origin. With
+ * no scope, return the list unchanged (legacy single-/multi-session behavior).
+ */
+function scopeSessions(sessions, scope) {
+    if (scope === undefined)
+        return sessions;
+    if (scope.projectId !== undefined) {
+        return sessions.filter((s) => s.projectId === scope.projectId);
+    }
+    const wantOrigin = originOf(scope.url);
+    if (wantOrigin !== undefined) {
+        return sessions.filter((s) => originOf(s.url) === wantOrigin);
+    }
+    return sessions;
+}
+/** Honest, scoped error when sessions exist but none match the agent's project. */
+function scopeMissError(scope) {
+    const who = scope?.projectId !== undefined
+        ? `project '${scope.projectId}'`
+        : scope?.url !== undefined
+            ? `your app at ${scope.url}`
+            : 'the active project';
+    return `no browser session for ${who} — is that app running with @reticlehq/core enabled? (other apps may be connected, but they won't be driven by mistake)`;
+}
+/**
+ * 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 class SessionManager {
+    #sessions = new Map();
+    /**
+     * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
+     * without passing its own scope, this is applied — so auto-selection is project-scoped by default
+     * and a stray tab from another app is never picked, even on the no-sessionId path.
+     */
+    #defaultScope;
+    /** Set the active project's default resolve scope (called once at daemon wiring). */
+    setDefaultScope(scope) {
+        this.#defaultScope = scope;
+    }
+    add(session) {
+        const previous = this.#sessions.get(session.id);
+        this.#sessions.set(session.id, session);
+        return previous;
+    }
+    remove(session) {
+        if (this.#sessions.get(session.id) !== session)
+            return false;
+        session.rejectAll('session disconnected');
+        return this.#sessions.delete(session.id);
+    }
+    get(sessionId) {
+        return this.#sessions.get(sessionId);
+    }
+    list() {
+        return [...this.#sessions.values()].map((s) => s.info());
+    }
+    /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
+    all() {
+        return [...this.#sessions.values()];
+    }
+    count() {
+        return this.#sessions.size;
+    }
+    /**
+     * 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.
+     */
+    resolve(sessionId, scope) {
+        if (sessionId !== undefined) {
+            const found = this.#sessions.get(sessionId);
+            if (found === undefined) {
+                throw new Error(`no connected session with id '${sessionId}'`);
+            }
+            found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
+            return found;
+        }
+        if (this.#sessions.size === 0) {
+            throw new Error('no browser session connected — is your app running with @reticlehq/browser enabled?');
+        }
+        // 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
+        // candidate set, no matter how recently it was heard from. This is the anti-cross-talk guard.
+        // An explicit per-call scope wins; otherwise the daemon's active-project default applies.
+        const effectiveScope = scope ?? this.#defaultScope;
+        const all = scopeSessions([...this.#sessions.values()], effectiveScope);
+        if (all.length === 0) {
+            // Sessions exist, but none belong to the scoped project — never fall back to a foreign tab.
+            throw new Error(scopeMissError(effectiveScope));
+        }
+        if (all.length === 1) {
+            const [only] = all;
+            if (only === undefined)
+                throw new Error('session lookup failed');
+            only.markAgentActivity();
+            return only;
+        }
+        // Multiple sessions: score each (lower = better candidate for auto-selection).
+        // 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat).
+        const scored = all.map((s) => ({ s, score: s.throttled() ? 1 : 0, ms: s.lastSeenMs() }));
+        const bestScore = Math.min(...scored.map((x) => x.score));
+        const candidates = scored.filter((x) => x.score === bestScore);
+        // Sort candidates by recency (ascending lastSeenMs = most recently active first).
+        candidates.sort((a, b) => a.ms - b.ms);
+        const [best, runnerUp] = candidates;
+        if (best === undefined)
+            throw new Error('session lookup failed');
+        // Only auto-select if there is a clear winner.
+        //
+        // When at least one non-throttled (focused/visible) session exists, require a >1 s recency
+        // gap before committing — two tabs that both had recent heartbeats are genuinely ambiguous.
+        //
+        // When ALL candidates are throttled (e.g. the user switched to their editor on another
+        // desktop), the gap requirement is dropped: every session is already in "background" mode
+        // so we just pick the one with the freshest heartbeat and let the agent proceed. Requiring
+        // a gap here only produces spurious "ambiguous" errors while the user works elsewhere.
+        const allThrottled = bestScore === 1;
+        const RECENCY_GAP_MS = allThrottled ? 0 : 1_000;
+        const clearWinner = runnerUp === undefined || best.ms + RECENCY_GAP_MS < runnerUp.ms;
+        if (!clearWinner) {
+            // Ambiguous: list sessions with their health so the agent can choose.
+            const detail = all
+                .map((s) => `${s.id} (${s.throttled() ? 'throttled' : 'active'}, lastSeenMs=${s.lastSeenMs()})`)
+                .join(', ');
+            throw new Error(`multiple sessions connected — pass sessionId to target one: ${detail}`);
+        }
+        best.s.markAgentActivity();
+        return best.s;
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/session/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../../src/session/session-manager.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+/**
+ * First-run readiness: the agent often issues its first tool call in the window between `reticle init`
+ * and the app's SDK actually connecting its WebSocket — so a naive resolve throws "no session". This
+ * lets the agent (via reticle_wait_ready) BLOCK briefly until a session appears instead of failing the
+ * race, smoothing the most common first-5-minutes footgun.
+ *
+ * Pure control loop: the session count, clock, and sleep are all injected, so it is unit-tested with
+ * no real timers — and in production it polls a real `setTimeout` sleep.
+ */
+interface WaitForReadyOptions {
+    /** Live count of connected sessions (SessionManager.count). */
+    count: () => number;
+    /** Give up after this much elapsed time. */
+    timeoutMs: number;
+    /** Injected monotonic clock (ms). */
+    now: () => number;
+    /** Injected delay between polls. */
+    sleep: (ms: number) => Promise<void>;
+    /** Poll interval (ms). Default 100. */
+    pollMs?: number;
+}
+/**
+ * One-line orientation for a FRESH agent — the Reticle loop, returned by reticle_wait_ready (the first call)
+ * so an agent learns how to drive Reticle without reading docs. Named so it is not a free string; kept
+ * terse on purpose (it rides the first response, where token budget is tightest).
+ */
+export declare const RETICLE_LOOP_GUIDE: string;
+/**
+ * Resolve `true` as soon as at least one session is connected, or `false` if the timeout elapses
+ * first. Returns immediately when a session is already connected (the common, already-ready case —
+ * so this never adds latency on the happy path, including the benchmark which always has a session).
+ */
+export declare function waitForReady(opts: WaitForReadyOptions): Promise<boolean>;
+export {};
+//# sourceMappingURL=session-readiness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-readiness.d.ts","sourceRoot":"","sources":["../../src/session/session-readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,UAAU,mBAAmB;IAC3B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,oCAAoC;IACpC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAO2E,CAAC;AAE3G;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAS9E"}

package/dist/session/session-readiness.js

@@ -0,0 +1,32 @@
+const DEFAULT_POLL_MS = 100;
+/**
+ * One-line orientation for a FRESH agent — the Reticle loop, returned by reticle_wait_ready (the first call)
+ * so an agent learns how to drive Reticle without reading docs. Named so it is not a free string; kept
+ * terse on purpose (it rides the first response, where token budget is tightest).
+ */
+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. ' +
+    'MANDATORY: the moment you stop driving — finishing your reply or waiting on the human — call reticle_yield ' +
+    '(mode:"waiting", or mode:"ask" with the question) so the panel shows your real state; reticle_end_session ' +
+    '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
+ * first. Returns immediately when a session is already connected (the common, already-ready case —
+ * so this never adds latency on the happy path, including the benchmark which always has a session).
+ */
+export async function waitForReady(opts) {
+    if (opts.count() > 0)
+        return true;
+    const start = opts.now();
+    const poll = opts.pollMs ?? DEFAULT_POLL_MS;
+    for (;;) {
+        if (opts.now() - start >= opts.timeoutMs)
+            return opts.count() > 0;
+        await opts.sleep(poll);
+        if (opts.count() > 0)
+            return true;
+    }
+}
+//# sourceMappingURL=session-readiness.js.map

package/dist/session/session-readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-readiness.js","sourceRoot":"","sources":["../../src/session/session-readiness.ts"],"names":[],"mappings":"AAsBA,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,yHAAyH;IACzH,wHAAwH;IACxH,iHAAiH;IACjH,8GAA8G;IAC9G,6GAA6G;IAC7G,4GAA4G;IAC5G,wGAAwG,CAAC;AAE3G;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAyB;IAC1D,IAAI,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;IAC5C,SAAS,CAAC;QACR,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAClE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACpC,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,37 @@
+import type { SessionManager } from './session.js';
+/**
+ * Server-authoritative session liveness. The browser idle timer is throttled in a backgrounded tab
+ * and dies with the bridge if the agent (MCP client) is killed — so the Node server, which is immune
+ * to throttling, owns the decision. The reaper ends a session whose AGENT has gone quiet past its
+ * idle window; the end is pushed to the browser as a PRESENTER command, which a throttled tab still
+ * receives. A returning agent revives an auto-ended session (see Session.markAgentActivity).
+ */
+/**
+ * Human-facing summary shown in the HUD when the MCP client (the agent) disconnects. Agent-neutral:
+ * Reticle runs under any agent (Codex/OpenCode/Claude/Hermes), so the copy never names one.
+ */
+export declare const MCP_DISCONNECT_SUMMARY = "Session ended \u2014 the agent disconnected.";
+/**
+ * Fold any unread human notes into the end-of-session notice. Pure. A prompt typed into the panel in
+ * the death-race — the agent stops before draining its inbox — would otherwise vanish silently; here
+ * it rides the end banner so the human can copy it into their terminal. No notes → the base unchanged.
+ */
+export declare function composeEndedNotice(base: string, undelivered: string[]): string;
+/**
+ * Hand back every session whose agent has gone quiet past its window — shown as WAITING (your turn),
+ * not a crash, since the agent is still connected and revives on its next action. Returns the ids.
+ */
+export declare function reapIdleSessions(sessions: SessionManager): string[];
+/** End every active session immediately (the agent / MCP client disconnected → WARN). Returns ended ids. */
+export declare function endAllSessions(sessions: SessionManager, reason: string): string[];
+/**
+ * Runs {@link reapIdleSessions} on a Node interval. The timer is `unref`'d so it never keeps the
+ * process alive on its own, and `start()` is idempotent.
+ */
+export declare class SessionReaper {
+    #private;
+    constructor(sessions: SessionManager, intervalMs?: number);
+    start(): void;
+    stop(): void;
+}
+//# sourceMappingURL=session-reaper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-reaper.d.ts","sourceRoot":"","sources":["../../src/session/session-reaper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,cAAc,CAAC;AAG5D;;;;;;GAMG;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,iDAA4C,CAAC;AAKhF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAI9E;AAWD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,EAAE,CAWnE;AAED,4GAA4G;AAC5G,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CASjF;AAED;;;GAGG;AACH,qBAAa,aAAa;;gBAKZ,QAAQ,EAAE,cAAc,EAAE,UAAU,GAAE,MAA2C;IAK7F,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;CAKb"}

package/dist/session/session-reaper.js

@@ -0,0 +1,94 @@
+import { PresenterTone, SESSION_LIFECYCLE, UNDELIVERED_NOTES_LABEL } from '@reticlehq/core';
+import { log } from '../log.js';
+/**
+ * Server-authoritative session liveness. The browser idle timer is throttled in a backgrounded tab
+ * and dies with the bridge if the agent (MCP client) is killed — so the Node server, which is immune
+ * to throttling, owns the decision. The reaper ends a session whose AGENT has gone quiet past its
+ * idle window; the end is pushed to the browser as a PRESENTER command, which a throttled tab still
+ * receives. A returning agent revives an auto-ended session (see Session.markAgentActivity).
+ */
+/**
+ * Human-facing summary shown in the HUD when the MCP client (the agent) disconnects. Agent-neutral:
+ * Reticle runs under any agent (Codex/OpenCode/Claude/Hermes), so the copy never names one.
+ */
+export const MCP_DISCONNECT_SUMMARY = 'Session ended — the agent disconnected.';
+/** Shown when the agent goes quiet between turns and the session is handed back to the human (WAITING). */
+const IDLE_WAITING_SUMMARY = 'Agent idle — your turn. Continue in your terminal.';
+/**
+ * Fold any unread human notes into the end-of-session notice. Pure. A prompt typed into the panel in
+ * the death-race — the agent stops before draining its inbox — would otherwise vanish silently; here
+ * it rides the end banner so the human can copy it into their terminal. No notes → the base unchanged.
+ */
+export function composeEndedNotice(base, undelivered) {
+    if (undelivered.length === 0)
+        return base;
+    const notes = undelivered.map((text) => `"${text}"`).join(', ');
+    return `${base} · ${UNDELIVERED_NOTES_LABEL} ${notes}`;
+}
+/**
+ * End a session, surfacing any unread human notes in its end notice instead of dropping them. `tone`
+ * tells the panel how to present it: WAITING (agent went quiet) vs WARN (agent crashed/disconnected).
+ */
+function endWithUndelivered(session, base, tone) {
+    const undelivered = session.drainInbox().map((m) => m.text);
+    session.autoEnd(composeEndedNotice(base, undelivered), tone);
+}
+/**
+ * Hand back every session whose agent has gone quiet past its window — shown as WAITING (your turn),
+ * not a crash, since the agent is still connected and revives on its next action. Returns the ids.
+ */
+export function reapIdleSessions(sessions) {
+    const ended = [];
+    for (const session of sessions.all()) {
+        if (session.isEnded())
+            continue;
+        if (session.agentIdleMs() >= session.idleEndMs()) {
+            endWithUndelivered(session, IDLE_WAITING_SUMMARY, PresenterTone.WAITING);
+            ended.push(session.id);
+        }
+    }
+    if (ended.length > 0)
+        log('session_reaped_idle', { sessions: ended });
+    return ended;
+}
+/** End every active session immediately (the agent / MCP client disconnected → WARN). Returns ended ids. */
+export function endAllSessions(sessions, reason) {
+    const ended = [];
+    for (const session of sessions.all()) {
+        if (session.isEnded())
+            continue;
+        endWithUndelivered(session, reason, PresenterTone.WARN);
+        ended.push(session.id);
+    }
+    if (ended.length > 0)
+        log('sessions_ended', { reason, sessions: ended });
+    return ended;
+}
+/**
+ * Runs {@link reapIdleSessions} on a Node interval. The timer is `unref`'d so it never keeps the
+ * process alive on its own, and `start()` is idempotent.
+ */
+export class SessionReaper {
+    #timer;
+    #sessions;
+    #intervalMs;
+    constructor(sessions, intervalMs = SESSION_LIFECYCLE.REAP_INTERVAL_MS) {
+        this.#sessions = sessions;
+        this.#intervalMs = intervalMs;
+    }
+    start() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => {
+            reapIdleSessions(this.#sessions);
+        }, this.#intervalMs);
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+//# sourceMappingURL=session-reaper.js.map

package/dist/session/session-reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reaper.js","sourceRoot":"","sources":["../../src/session/session-reaper.ts"],"names":[],"mappings":"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"}