@reticlehq/server 2.4.0 → 2.5.0

package/dist/session/no-session-diagnosis.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turning "no browser session connected" from a dead end into a next action.
+ *
+ * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
+ * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
+ * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
+ * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ *
+ * The old message asked the agent to check two things it cannot see from where it stands ("is your
+ * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
+ * the three cases apart, and each has a different, concrete fix:
+ *
+ *   - a session was here and went away    -> the tab closed or reloaded; reopen it
+ *   - something is listening, never dialled, project not wired -> run `reticle init` in THAT app
+ *   - something is listening, project wired -> port mismatch or a stale build; restart the dev server
+ *   - nothing is listening anywhere       -> there is no app running; start it
+ *
+ * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
+ * the hot resolve() path and this stays unit-testable.
+ */
+interface NoSessionFacts {
+    /** Whether ANY session has connected to this daemon since it booted. */
+    everConnected: boolean;
+    /** Whether this project has been through `reticle init` (a .reticle.json / projectId is present). */
+    initialized: boolean;
+    /** Localhost ports with something listening that looks like a dev server. */
+    listening: readonly number[];
+    /** The port this daemon is on — half of the mismatch the old message asked about. */
+    port: number;
+}
+/**
+ * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
+ * recovery: a message that already carries its own next action must not be handed a second, more
+ * generic one that contradicts it.
+ */
+export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again \u2014 it will appear within a second of the page loading.";
+export declare function diagnoseNoSession(facts: NoSessionFacts): string;
+export {};

package/dist/session/no-session-diagnosis.js

@@ -0,0 +1,70 @@
+/**
+ * Turning "no browser session connected" from a dead end into a next action.
+ *
+ * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
+ * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
+ * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
+ * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ *
+ * The old message asked the agent to check two things it cannot see from where it stands ("is your
+ * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
+ * the three cases apart, and each has a different, concrete fix:
+ *
+ *   - a session was here and went away    -> the tab closed or reloaded; reopen it
+ *   - something is listening, never dialled, project not wired -> run `reticle init` in THAT app
+ *   - something is listening, project wired -> port mismatch or a stale build; restart the dev server
+ *   - nothing is listening anywhere       -> there is no app running; start it
+ *
+ * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
+ * the hot resolve() path and this stays unit-testable.
+ */
+/**
+ * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
+ * recovery: a message that already carries its own next action must not be handed a second, more
+ * generic one that contradicts it.
+ */
+export const SELF_RECOVERING_MARKER = 'Then call reticle_sessions again — it will appear within a second of the page loading.';
+const RETRY = SELF_RECOVERING_MARKER;
+/**
+ * The way out that needs no human at all.
+ *
+ * `reticle_lease` opens a browser Reticle drives itself, instead of waiting for somebody's tab to
+ * dial in. Measured over a day of telemetry it is the single strongest predictor of a session that
+ * works: the 5 sessions that used it had a MEDIAN of 30 tool calls and produced 46% of every bug
+ * found, against a median of 1 call for the 20 active sessions that did not — and not one
+ * single-call bounce used one. It is also advertised on no profile except `full`, so an agent only
+ * ever finds it if it already knew it existed. Naming it HERE puts it in front of the agent at the
+ * one moment it is the answer, and costs nothing on the turns when it is not.
+ *
+ * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
+ * browser and comes back `ready:false`.
+ */
+const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
+    'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
+    'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
+export function diagnoseNoSession(facts) {
+    const { everConnected, initialized, listening, port } = facts;
+    const ports = listening.join(', ');
+    if (everConnected) {
+        return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+            'is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
+            `the app (or run \`reticle open\`), or reload the tab. ${SELF_SERVE} ${RETRY}`);
+    }
+    if (0 === listening.length) {
+        return ('no browser session connected, and nothing is listening on any of the usual dev-server ports ' +
+            '— so the app is almost certainly not running. This is not a Reticle wiring problem: ask the ' +
+            `human to start their dev server (\`npm run dev\`), then open the app in a browser. ${RETRY}`);
+    }
+    if (!initialized) {
+        return (`no browser session connected, but something IS listening on port ${ports} — so a server is ` +
+            'up and has never dialled this daemon. This project has not been through `reticle init`, ' +
+            'which is what installs the SDK and wires it into the build, so the likeliest cause is that ' +
+            "the app carries no Reticle SDK. Ask the human to run `reticle init` in the app's directory " +
+            `and restart the dev server. ${RETRY}`);
+    }
+    return (`no browser session connected, but something IS listening on port ${ports} and this project is ` +
+        `wired for Reticle — so the app is either serving a build made before the wiring landed, or ` +
+        `dialling a different daemon than this one (this daemon is on ${String(port)}). Ask the human ` +
+        'to restart the dev server and hard-reload the page; if it still does not appear, check that ' +
+        `the app's reticle port matches ${String(port)}. ${SELF_SERVE} ${RETRY}`);
+}

package/dist/session/no-session-watch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Keeps the "why is nothing connected" diagnosis fresh, without putting a probe on the hot path.
+ *
+ * `SessionManager.resolve` is synchronous and runs on every tool call, so it cannot await a port
+ * scan. This refreshes the answer in the background and hands the manager a closure that reads the
+ * cached result — a hint in an error message is exactly the sort of thing that may be a few seconds
+ * stale.
+ *
+ * It only probes while NOTHING is connected. Once a session is live the question is moot, and a
+ * daemon that outlives the agent by hours has no business scanning ports it does not need.
+ */
+import type { SessionManager } from './session-manager.js';
+/**
+ * The daemon's whole session-scoping decision in one call: scope auto-selection to the active
+ * project, and keep the no-session diagnosis fresh. Both derive from the same one fact — whether
+ * this directory has been through `reticle init` — so they belong together rather than as two
+ * adjacent blocks in the bootstrap.
+ */
+export declare function wireSessionScope(sessions: SessionManager, activeProjectId: string | undefined, port: number): () => void;

package/dist/session/no-session-watch.js

@@ -0,0 +1,61 @@
+/**
+ * Keeps the "why is nothing connected" diagnosis fresh, without putting a probe on the hot path.
+ *
+ * `SessionManager.resolve` is synchronous and runs on every tool call, so it cannot await a port
+ * scan. This refreshes the answer in the background and hands the manager a closure that reads the
+ * cached result — a hint in an error message is exactly the sort of thing that may be a few seconds
+ * stale.
+ *
+ * It only probes while NOTHING is connected. Once a session is live the question is moot, and a
+ * daemon that outlives the agent by hours has no business scanning ports it does not need.
+ */
+import { probeDevServers } from './dev-server-probe.js';
+import { diagnoseNoSession } from './no-session-diagnosis.js';
+/** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
+const REFRESH_MS = 15_000;
+/** Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up. */
+function startNoSessionWatch(options) {
+    const probe = options.probe ?? (() => probeDevServers());
+    let listening = [];
+    let running = false;
+    const refresh = () => {
+        // Nothing to diagnose while a session is live, and no reason to scan.
+        if (running || options.sessions.count() > 0)
+            return;
+        running = true;
+        void probe()
+            .then((ports) => {
+            listening = ports;
+        })
+            .catch(() => {
+            /* a diagnostic hint must never take the daemon down */
+        })
+            .finally(() => {
+            running = false;
+        });
+    };
+    refresh();
+    const timer = setInterval(refresh, REFRESH_MS);
+    timer.unref();
+    options.sessions.setNoSessionHint(() => diagnoseNoSession({
+        everConnected: options.sessions.everConnected(),
+        initialized: options.initialized,
+        listening,
+        port: options.port,
+    }));
+    return () => {
+        clearInterval(timer);
+        options.sessions.setNoSessionHint(undefined);
+    };
+}
+/**
+ * The daemon's whole session-scoping decision in one call: scope auto-selection to the active
+ * project, and keep the no-session diagnosis fresh. Both derive from the same one fact — whether
+ * this directory has been through `reticle init` — so they belong together rather than as two
+ * adjacent blocks in the bootstrap.
+ */
+export function wireSessionScope(sessions, activeProjectId, port) {
+    if (activeProjectId !== undefined)
+        sessions.setDefaultScope({ projectId: activeProjectId });
+    return startNoSessionWatch({ sessions, port, initialized: activeProjectId !== undefined });
+}

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

@@ -42,8 +42,12 @@ export declare class ObservedState {
     seedAmbient(counts: AmbientCounts): void;
     /** Record a driven ref. Idempotent. */
     recordActedRef(ref: string): void;
+    /** Record a driven control's re-render-surviving label. Idempotent; empty labels are not identities. */
+    recordActedLabel(label: string): void;
     /** Every ref driven so far this session. */
     actedRefs(): ReadonlySet<string>;
+    /** Every driven control's label, for matching across re-renders. */
+    actedLabels(): ReadonlySet<string>;
     /**
      * Record bridge-side sampling as a blind spot.
      *

package/dist/session/observed-state.js

@@ -34,7 +34,7 @@ export class ObservedState {
         if (event.type === EventType.BLIND_SPOT) {
             const kind = event.data['kind'];
             const count = event.data['count'];
-            if (typeof kind === 'string' && typeof count === 'number')
+            if ('string' === typeof kind && 'number' === typeof count)
                 this.#blindSpots[kind] = count;
         }
     }
@@ -78,15 +78,33 @@ export class ObservedState {
      * "recently untouched" — a number that reads as thorough while drifting toward the opposite.
      */
     #actedRefs = new Set();
+    /**
+     * The same drives, keyed by something that SURVIVES a re-render.
+     *
+     * A ref is invalidated whenever the DOM changes, so on a framework that replaces nodes rather than
+     * reconciling in place (Next's app router, for one) every driven ref is stale by the time coverage
+     * is asked and the number reads 0 forever. The snapshot label — `button "Deploy"` — names the same
+     * control on both sides of a re-render.
+     */
+    #actedLabels = new Set();
     /** Record a driven ref. Idempotent. */
     recordActedRef(ref) {
         if (ref.length > 0)
             this.#actedRefs.add(ref);
     }
+    /** Record a driven control's re-render-surviving label. Idempotent; empty labels are not identities. */
+    recordActedLabel(label) {
+        if (label.length > 0)
+            this.#actedLabels.add(label);
+    }
     /** Every ref driven so far this session. */
     actedRefs() {
         return this.#actedRefs;
     }
+    /** Every driven control's label, for matching across re-renders. */
+    actedLabels() {
+        return this.#actedLabels;
+    }
     /**
      * Record bridge-side sampling as a blind spot.
      *

package/dist/session/output-budget.js

@@ -58,7 +58,7 @@ export function sizeCost(payload) {
  * Non-object results (e.g. a thrown-error envelope) pass through unchanged.
  */
 export function withSizeCost(result) {
-    if (typeof result !== 'object' || result === null)
+    if (typeof result !== 'object' || null === result)
         return result;
     return { ...result, cost: sizeCost(result) };
 }

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

@@ -1,3 +1,4 @@
+import { BrowserBrand } from '@reticlehq/core';
 import type { Session } from './session.js';
 /**
  * The health block spliced onto act/assert results. Defined here rather than in session.ts: this is
@@ -45,12 +46,18 @@ export declare function healthEnvelope(session: Session): HealthEnvelope;
  */
 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 {
+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;
+    /**
+     * Which browser the page is. Narrowed to `BrowserBrand` HERE rather than trusted: the SDK already
+     * normalises, so anything else is a stale or hand-forged payload and is dropped — the point of the
+     * closed list is that an unbounded string can never reach telemetry through it.
+     */
+    brand: BrowserBrand | undefined;
 }
 /**
  * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report

package/dist/session/session-health.js

@@ -1,4 +1,4 @@
-import { BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
+import { BrowserBrand, BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
 /**
  * Buffer-honesty envelope for observe/network/console. When the ring buffer has evicted anything
  * (age/size cap), a "no such event" answer may be a false negative — so we attach the drop count and
@@ -7,7 +7,7 @@ import { BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
  */
 export function bufferEnvelope(session) {
     const { total, dropped } = session.bufferHealth();
-    if (dropped === 0)
+    if (0 === dropped)
         return {};
     return { buffer: { held: total, dropped, note: BUFFER_EVICTION_WARNING } };
 }
@@ -31,7 +31,7 @@ export function healthEnvelope(session) {
  * warn-only so background testing never breaks.
  */
 export function refuseIfThrottled(session, refuse) {
-    if (refuse === true && session.throttled()) {
+    if (true === refuse && session.throttled()) {
         throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
     }
 }
@@ -42,9 +42,10 @@ export function refuseIfThrottled(session, refuse) {
  */
 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,
+        hidden: 'boolean' === typeof data['hidden'] ? data['hidden'] : undefined,
+        focused: 'boolean' === typeof data['focused'] ? data['focused'] : undefined,
+        runtime: 'string' === typeof data['runtime'] ? data['runtime'] : undefined,
+        engine: 'string' === typeof data['engine'] ? data['engine'] : undefined,
+        brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
     };
 }

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

@@ -1,10 +1,4 @@
-/**
- * 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.
- */
+import type { SessionHealth } from './session-health.js';
 export interface SessionInfo {
     sessionId: string;
     url: string;
@@ -13,6 +7,8 @@ export interface SessionInfo {
     title: string;
     adapters: string[];
     hasCapabilities: boolean;
+    /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
+    versionSkew?: string;
     /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
     lastSeenMs: number;
     hidden: boolean;
@@ -27,3 +23,26 @@ export interface SessionInfo {
     /** present with pendingMarks — nudges the agent to drain them with reticle_review. */
     review_suggestion?: string;
 }
+/** The read-only slice of a Session that the projection needs. Keeps this module class-free. */
+interface SessionView {
+    id: string;
+    url: string;
+    projectId: string | undefined;
+    title: string;
+    adapters: string[];
+    hasCapabilities: boolean;
+    versionSkew: string | undefined;
+    hidden: boolean;
+    health: () => SessionHealth;
+    staleMs: () => number;
+    pendingMarkCount: () => number;
+}
+/**
+ * Project a live Session into the shape the tools return.
+ *
+ * Lives beside the SessionInfo type rather than on the class: it is a pure read of already-computed
+ * state, it is where every "what does the agent see about this tab" decision belongs, and Session is
+ * a stateful class already at its size cap — every field added to a listing was costing a line there.
+ */
+export declare function buildSessionInfo(session: SessionView): SessionInfo;
+export {};

package/dist/session/session-info.js

@@ -1 +1,42 @@
-export {};
+/**
+ * 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.
+ */
+import { SESSION_LEASE } from '@reticlehq/core';
+/**
+ * Project a live Session into the shape the tools return.
+ *
+ * Lives beside the SessionInfo type rather than on the class: it is a pure read of already-computed
+ * state, it is where every "what does the agent see about this tab" decision belongs, and Session is
+ * a stateful class already at its size cap — every field added to a listing was costing a line there.
+ */
+export function buildSessionInfo(session) {
+    const base = {
+        sessionId: session.id,
+        url: session.url,
+        ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+        title: session.title,
+        adapters: session.adapters,
+        hasCapabilities: session.hasCapabilities,
+        // On every listing, not buried in a log — skew explains failures that read as app bugs.
+        ...(session.versionSkew === undefined ? {} : { versionSkew: session.versionSkew }),
+        hidden: session.hidden,
+        ...session.health(),
+    };
+    if (session.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
+        base.stale = true;
+        base.cleanup_suggestion =
+            '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 = session.pendingMarkCount();
+    if (marks > 0) {
+        base.pendingMarks = marks;
+        const s = 1 === marks ? '' : 's';
+        base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_session{action:"review"} to see and fix ${1 === marks ? 'it' : 'them'}.`;
+    }
+    return base;
+}

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

@@ -11,15 +11,4 @@ export interface SessionLease {
     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

@@ -8,7 +8,7 @@
  *
  * 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.';
+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

@@ -21,6 +21,9 @@ export declare class SessionManager {
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
     count(): number;
+    /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
+    setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    everConnected(): boolean;
     /** 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. */

package/dist/session/session-manager.js

@@ -29,14 +29,29 @@ function scopeSessions(sessions, scope) {
     }
     return sessions;
 }
-/** Honest, scoped error when sessions exist but none match the agent's project. */
-function scopeMissError(scope) {
+/**
+ * Honest, scoped error when sessions exist but none match the agent's project.
+ *
+ * The daemon takes its default scope from the `.reticle.json` of whichever directory started it, so
+ * attaching from a second project — or another worktree of the SAME project — makes every tool
+ * refuse while `reticle_sessions` shows the tab sitting right there. The old message asked "is that
+ * app running with @reticlehq/core enabled?", which is the one thing that is definitely true, so the
+ * reader goes looking at their app instead of at the scope. Name what IS connected and how to
+ * target it: both facts are already in hand here.
+ */
+function scopeMissError(connected, 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)`;
+    const listed = connected
+        .map((s) => `'${s.projectId ?? 'untagged'}' (${s.url}, sessionId '${s.id}')`)
+        .join(', ');
+    return (`no browser session for ${who}, but ${String(connected.length)} session(s) ARE connected under a ` +
+        `different project: ${listed}. The daemon scopes to the .reticle.json of the directory it was ` +
+        `started in, so this is a scope mismatch, not a dead app. Pass the sessionId above to target one, ` +
+        `or restart the daemon from that app's directory.`);
 }
 /**
  * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
@@ -58,6 +73,7 @@ export class SessionManager {
         this.#defaultScope = scope;
     }
     add(session) {
+        this.#everConnected = true;
         const previous = this.#sessions.get(session.id);
         this.#sessions.set(session.id, session);
         // Publish what this app declared sensitive to the driven-path rule. Here rather than in the
@@ -112,6 +128,25 @@ export class SessionManager {
      * was hung up on. Keeping the last few reasons turns an unexplained disappearance into a fact.
      */
     #recentClosures = [];
+    /**
+     * What the daemon knows about WHY nothing is connected, refreshed in the background.
+     *
+     * Measured: of the sessions that call any tool, half make exactly one call — usually
+     * reticle_sessions — and stop, because the answer they get names two things they cannot check and
+     * nothing they can do. The daemon can tell "no app is running" from "an app is running and never
+     * dialled us" from "one was connected and left", and each has a different fix. Optional so a
+     * bridge constructed without a daemon (every unit test) keeps the plain message.
+     */
+    #noSessionHint;
+    /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
+    setNoSessionHint(hint) {
+        this.#noSessionHint = hint;
+    }
+    /** Whether any session has connected since this daemon booted — half the diagnosis. */
+    #everConnected = false;
+    everConnected() {
+        return this.#everConnected;
+    }
     /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
     noteClosure(reason, at) {
         this.#recentClosures.push({ at, reason });
@@ -131,8 +166,12 @@ export class SessionManager {
             found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
             return found;
         }
-        if (this.#sessions.size === 0) {
+        if (0 === this.#sessions.size) {
             const closure = this.lastClosure();
+            // A diagnosis beats a checklist: it names which of the three causes this actually is.
+            const hint = this.#noSessionHint?.();
+            if (hint !== undefined && closure === undefined)
+                throw new Error(hint);
             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.`);
@@ -142,12 +181,16 @@ export class SessionManager {
         // 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) {
+        const connected = [...this.#sessions.values()];
+        const all = scopeSessions(connected, effectiveScope);
+        if (0 === all.length) {
             // Sessions exist, but none belong to the scoped project — never fall back to a foreign tab.
-            throw new Error(scopeMissError(effectiveScope));
+            // ponytail: still a refusal, deliberately. Auto-targeting the only connected tab would be the
+            // friendlier 90% case and would also silently defeat the anti-cross-talk guard this scope
+            // exists to be. Naming the tab and its sessionId costs the agent one extra argument.
+            throw new Error(scopeMissError(connected, effectiveScope));
         }
-        if (all.length === 1) {
+        if (1 === all.length) {
             const [only] = all;
             if (only === undefined)
                 throw new Error('session lookup failed');
@@ -173,7 +216,7 @@ export class SessionManager {
         // desktop), the gap requirement is dropped: every session is already in "background" mode
         // so we just pick the one with the freshest heartbeat and let the agent proceed. Requiring
         // a gap here only produces spurious "ambiguous" errors while the user works elsewhere.
-        const allThrottled = bestScore === 1;
+        const allThrottled = 1 === bestScore;
         const RECENCY_GAP_MS = allThrottled ? 0 : 1_000;
         const clearWinner = runnerUp === undefined || best.ms + RECENCY_GAP_MS < runnerUp.ms;
         if (!clearWinner) {

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

@@ -16,7 +16,7 @@ interface WaitForReadyOptions {
     now: () => number;
     /** Injected delay between polls. */
     sleep: (ms: number) => Promise<void>;
-    /** Poll interval (ms). Default 100. */
+    /** Poll interval (ms). Default 25 — see DEFAULT_POLL_MS. */
     pollMs?: number;
 }
 /**

package/dist/session/session-readiness.js

@@ -1,4 +1,9 @@
-const DEFAULT_POLL_MS = 100;
+/**
+ * Same reasoning as session-reconnect: the check is an in-memory lookup and the thing awaited is an
+ * event (a session registering), so a coarse grid only adds latency to the first call an agent
+ * makes. Four times the checks of something with no I/O costs nothing measurable.
+ */
+const DEFAULT_POLL_MS = 25;
 /**
  * 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

package/dist/session/session-reaper.js

@@ -20,7 +20,7 @@ const IDLE_WAITING_SUMMARY = 'Agent idle — your turn. Continue in your termina
  * 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)
+    if (0 === undelivered.length)
         return base;
     const notes = undelivered.map((text) => `"${text}"`).join(', ');
     return `${base} · ${UNDELIVERED_NOTES_LABEL} ${notes}`;

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

@@ -0,0 +1,32 @@
+/**
+ * Block until a reloaded page has re-announced itself under the same session id.
+ *
+ * A reload tears the SDK down. The id survives (see session-continuity), and the daemon replaces the
+ * old Session with a new one when the page says HELLO again — so "is it back?" is exactly "does a
+ * DIFFERENT object hold this id now?". Identity, not a flag: the returning page always constructs a
+ * new Session, and nothing else can claim an id it already owns.
+ *
+ * Polls a live getter rather than subscribing, because there is no reconnect event to subscribe to
+ * and inventing one for this would be a wire change for a two-second wait.
+ */
+interface WaitForReconnectOptions {
+    /** The session registered under this id right now, or undefined if none is. */
+    current: () => object | undefined;
+    /** The session object that was live when the reload was dispatched. */
+    previous: object;
+    /** Give up after this much elapsed time and let the caller report it honestly. */
+    timeoutMs: number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    pollMs?: number;
+}
+/**
+ * How long a reload is worth waiting for before answering "not confirmed".
+ *
+ * A production build is back in well under a second; a cold dev-server route rebuild is the slow
+ * case this budget is sized for. It is a CEILING, not a delay — the common path returns on the first
+ * or second poll.
+ */
+export declare const RELOAD_RECONNECT_TIMEOUT_MS = 5000;
+export declare function waitForReconnect(opts: WaitForReconnectOptions): Promise<boolean>;
+export {};