@reticlehq/server 2.4.0 → 2.6.0

package/dist/session/command-timeout.js

@@ -1,4 +1,4 @@
-import { isOpaqueOrigin } from '@reticlehq/core';
+import { AppRuntime, isOpaqueOrigin } from '@reticlehq/core';
 /**
  * Inbound silence beyond this means the page may genuinely be wedged; inside it, the SDK has spoken
  * recently enough that "the page is hung" is provably the wrong story. A page that is streaming
@@ -18,7 +18,7 @@ const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWeb
     'loaded. If neither fits, the page is reachable but not executing, which is worth reporting.';
 /** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
 function isWebKitDesktop(context) {
-    if (context.runtime === 'tauri')
+    if (AppRuntime.TAURI === context.runtime)
         return true;
     // A `tauri://` origin is unambiguous even before the first health report lands.
     if (context.runtime !== undefined)

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

@@ -12,6 +12,12 @@ interface ControlEnvelope {
  * recovery path (address the guidance, then reticle_session{action:"resume"}) lives here in exactly one place.
  */
 export declare const PAUSE_HINT = "Paused by the human. Address the guidance, then call reticle_session{action:\"resume\"} (or wait for the human to resume).";
+/**
+ * `because` for the verdict a paused verification returns. Nothing was driven and nothing was
+ * asserted, which is the definition of unknown — never `no`, which would report the human's own
+ * pause as the app failing.
+ */
+export declare const PAUSED_NO_VERDICT = "the human paused this session, so nothing was driven and nothing was asserted";
 /** Shape returned by the short-circuit when an action tool refuses while paused. */
 interface PausedResult {
     paused: true;

package/dist/session/control-envelope.js

@@ -5,6 +5,12 @@ import { z } from 'zod';
  * recovery path (address the guidance, then reticle_session{action:"resume"}) lives here in exactly one place.
  */
 export const PAUSE_HINT = 'Paused by the human. Address the guidance, then call reticle_session{action:"resume"} (or wait for the human to resume).';
+/**
+ * `because` for the verdict a paused verification returns. Nothing was driven and nothing was
+ * asserted, which is the definition of unknown — never `no`, which would report the human's own
+ * pause as the app failing.
+ */
+export const PAUSED_NO_VERDICT = 'the human paused this session, so nothing was driven and nothing was asserted';
 /**
  * outputSchema fields every action tool that can short-circuit on pause MUST declare, or a validating
  * profile strips the WHOLE pause payload — and because `guidance` is drained-once, that loses the
@@ -28,7 +34,7 @@ export const pausedOutputShape = {
 export function buildControlEnvelope(session) {
     const state = session.getState();
     const guidance = session.drainInbox().map((m) => m.text);
-    if (state === SessionState.ACTIVE && guidance.length === 0)
+    if (state === SessionState.ACTIVE && 0 === guidance.length)
         return undefined;
     return { state, guidance };
 }

package/dist/session/dev-server-probe.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Which of the usual dev-server ports have something listening on them.
+ *
+ * The one fact that separates "the app is not running" from "the app is running and never dialled
+ * us" — the difference between two completely different next actions for the agent, which the
+ * no-session message could not tell apart before. See no-session-diagnosis.ts.
+ *
+ * Kept out of the hot path: `SessionManager.resolve` is synchronous and runs on every tool call, so
+ * the probe refreshes in the background and the resolve path reads a cached answer. A stale answer
+ * is fine here — it is a hint in an error message, not a decision.
+ */
+/** Every candidate port serving a document, in ascending order. Never rejects. */
+export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -0,0 +1,52 @@
+/**
+ * Which of the usual dev-server ports have something listening on them.
+ *
+ * The one fact that separates "the app is not running" from "the app is running and never dialled
+ * us" — the difference between two completely different next actions for the agent, which the
+ * no-session message could not tell apart before. See no-session-diagnosis.ts.
+ *
+ * Kept out of the hot path: `SessionManager.resolve` is synchronous and runs on every tool call, so
+ * the probe refreshes in the background and the resolve path reads a cached answer. A stale answer
+ * is fine here — it is a hint in an error message, not a decision.
+ */
+import { request } from 'node:http';
+import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { looksLikeDevServer } from './looks-like-dev-server.js';
+/** Give up fast: an HTTP answer from localhost either lands quickly or nothing is there. */
+const HTTP_PROBE_TIMEOUT_MS = 400;
+/**
+ * `localhost`, not `127.0.0.1` — so BOTH address families are tried.
+ *
+ * Measured: a plain `vite --port 4311` on this machine listens on `[::1]` only, and a probe pinned to
+ * the IPv4 loopback cannot see it. The old TCP probe had the same blind spot, which meant the
+ * diagnostic could miss the very dev server it exists to find while still reporting an unrelated
+ * service that happens to bind both stacks (macOS AirPlay does).
+ */
+const PROBE_HOST = 'localhost';
+/**
+ * Does this port serve a DOCUMENT — i.e. is it a dev server rather than merely something listening?
+ *
+ * A bare TCP connect reported macOS ControlCenter (AirPlay Receiver, on by default on every Mac,
+ * port 5000) as the user's dev server. See looks-like-dev-server for what it actually answers and
+ * why "a socket accepted" is the wrong question.
+ */
+function servesDocument(port, host = PROBE_HOST) {
+    return new Promise((resolve) => {
+        const req = request({ host, port, path: '/', method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS }, (res) => {
+            const answer = looksLikeDevServer(res.statusCode ?? 0, res.headers['content-type']);
+            res.resume(); // drain, so the socket closes rather than lingering
+            resolve(answer);
+        });
+        req.once('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.once('error', () => resolve(false));
+        req.end();
+    });
+}
+/** Every candidate port serving a document, in ascending order. Never rejects. */
+export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => servesDocument(p)) {
+    const results = await Promise.all(ports.map((p) => probe(p).then((up) => (up ? p : null))));
+    return results.filter((p) => p !== null).sort((a, b) => a - b);
+}

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

@@ -14,18 +14,32 @@
  *    the "this click did nothing" check is unreachable on the ordinary act-then-observe flow: an
  *    empty-window test is a statement about the PAGE, and no real app has a quiet page.
  */
-export interface ActEffect {
+interface ActEffect {
     action?: string | undefined;
     /** DOM mutations inside the acted element's own subtree. Undefined means nobody measured. */
     mutatedWithin?: number | undefined;
 }
 export declare class LastAct {
     #private;
-    markCursor(cursor: number): void;
+    /**
+     * Record an action that ACTUALLY DISPATCHED — cursor and effect together, never one without the
+     * other.
+     *
+     * It used to be two setters called BEFORE the ref was resolved, so a refused act (stale ref, a
+     * disabled control, a paused page) left a cursor and an empty effect standing. The next observe
+     * saw a cursor inside its window, asked for the effect, found `mutatedWithin: undefined` over a
+     * quiet window and reported "the click was dispatched and the page settled … the target does not
+     * react" — about a click nobody dispatched, blaming a control that was fine, on exactly the
+     * re-query-and-retry path the stale-ref message sends the agent down.
+     *
+     * Marking only on the success path is what makes that unrepeatable: a failure mode added later
+     * cannot forget to clean up state that was never written.
+     */
+    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined): void;
     cursor(): number | undefined;
     markSource(source: string | undefined): void;
     source(): string | undefined;
-    markEffect(action: string | undefined, mutatedWithin: number | undefined): void;
     /** Empty when nothing has acted — callers then fall back to checks that need no action context. */
     effect(): ActEffect;
 }
+export {};

package/dist/session/last-act.js

@@ -2,8 +2,23 @@ export class LastAct {
     #cursor;
     #source;
     #effect;
-    markCursor(cursor) {
+    /**
+     * Record an action that ACTUALLY DISPATCHED — cursor and effect together, never one without the
+     * other.
+     *
+     * It used to be two setters called BEFORE the ref was resolved, so a refused act (stale ref, a
+     * disabled control, a paused page) left a cursor and an empty effect standing. The next observe
+     * saw a cursor inside its window, asked for the effect, found `mutatedWithin: undefined` over a
+     * quiet window and reported "the click was dispatched and the page settled … the target does not
+     * react" — about a click nobody dispatched, blaming a control that was fine, on exactly the
+     * re-query-and-retry path the stale-ref message sends the agent down.
+     *
+     * Marking only on the success path is what makes that unrepeatable: a failure mode added later
+     * cannot forget to clean up state that was never written.
+     */
+    markActed(cursor, action, mutatedWithin) {
         this.#cursor = cursor;
+        this.#effect = { action, mutatedWithin };
     }
     cursor() {
         return this.#cursor;
@@ -14,9 +29,6 @@ export class LastAct {
     source() {
         return this.#source;
     }
-    markEffect(action, mutatedWithin) {
-        this.#effect = { action, mutatedWithin };
-    }
     /** Empty when nothing has acted — callers then fall back to checks that need no action context. */
     effect() {
         return this.#effect ?? {};

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { noteEmptyRead } from '../tools/observed-nothing.js';
 import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
@@ -95,7 +96,11 @@ export const LIVE_CONTROL_TOOLS = [
         outputSchema: { messages: z.array(z.unknown()) },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            return Promise.resolve({ messages: session.drainInbox() });
+            // An empty inbox and a panel that is not wired both return `[]`. The first means the human has
+            // said nothing; the second means an agent is waiting on a channel that does not exist.
+            return Promise.resolve(noteEmptyRead({ messages: session.drainInbox() }, 'messages', {
+                noun: 'messages from the human since the last poll',
+            }));
         },
     },
     {
@@ -135,7 +140,7 @@ export const LIVE_CONTROL_TOOLS = [
                     session.pushNarration(`✓ fixed: ${mark.note}`);
                 }
             }
-            const source = args['all'] === true ? session.allMarks() : session.pendingMarks();
+            const source = true === args['all'] ? session.allMarks() : session.pendingMarks();
             const marks = source.map((m) => ({ ...m, fix: buildFixHint(m) }));
             const out = {
                 marks,

package/dist/session/live-control.js

@@ -27,7 +27,7 @@ export class LiveControl {
     /** Queue a human note. Empty/whitespace-only text is ignored so a stray enter cannot spam the agent. */
     push(text, t) {
         const trimmed = text.trim();
-        if (trimmed.length === 0)
+        if (0 === trimmed.length)
             return;
         this.#inbox.push({ text: trimmed, t });
     }

package/dist/session/looks-like-dev-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Is the thing on this port a DEV SERVER serving the app, or just something on a port?
+ *
+ * The probe used to answer "something accepted a TCP connection", which on macOS means every Mac
+ * reports Apple's AirPlay Receiver on port 5000 as the user's dev server. Reproduced here: it
+ * answers `HTTP/1.1 403 Forbidden`, `Server: AirTunes/950.7.1`, no body. The agent was then told
+ * "something IS listening on port 5000 and this project is wired for Reticle" while the app was on
+ * 3100 — a diagnostic confidently naming a service with nothing to do with the project.
+ *
+ * A dev server serving an app answers `GET /` with a document. That is the whole test. A false
+ * negative costs a less specific message; a false positive costs trust in every diagnostic Reticle
+ * prints, which is far more expensive.
+ */
+export declare function looksLikeDevServer(status: number, contentType: string | undefined): boolean;

package/dist/session/looks-like-dev-server.js

@@ -0,0 +1,25 @@
+/**
+ * Is the thing on this port a DEV SERVER serving the app, or just something on a port?
+ *
+ * The probe used to answer "something accepted a TCP connection", which on macOS means every Mac
+ * reports Apple's AirPlay Receiver on port 5000 as the user's dev server. Reproduced here: it
+ * answers `HTTP/1.1 403 Forbidden`, `Server: AirTunes/950.7.1`, no body. The agent was then told
+ * "something IS listening on port 5000 and this project is wired for Reticle" while the app was on
+ * 3100 — a diagnostic confidently naming a service with nothing to do with the project.
+ *
+ * A dev server serving an app answers `GET /` with a document. That is the whole test. A false
+ * negative costs a less specific message; a false positive costs trust in every diagnostic Reticle
+ * prints, which is far more expensive.
+ */
+/** Statuses that mean "I will not serve you", which no local dev server does for its own app root. */
+const REFUSES = new Set([401, 403, 407]);
+export function looksLikeDevServer(status, contentType) {
+    if (REFUSES.has(status))
+        return false;
+    // A redirect IS a server routing: a dev server on a base path answers `/` with one.
+    if (status >= 300 && status < 400)
+        return true;
+    // Otherwise it has to be serving a document. A 404 that renders HTML is still a dev server — the
+    // server is there, only the route is missing.
+    return contentType !== undefined && contentType.toLowerCase().includes('text/html');
+}

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

@@ -0,0 +1,45 @@
+/**
+ * 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;
+    /**
+     * This daemon has reaped at least one EXPIRED pooled lease.
+     *
+     * Deliberately not "the session that just vanished was that lease" — nothing knows that. It is
+     * evidence, not proof, and the message below is worded accordingly.
+     */
+    leaseExpired?: boolean;
+}
+/**
+ * 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,120 @@
+/**
+ * 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.
+ */
+import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+/**
+ * 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).';
+/**
+ * The ports the scan actually covers, rendered for the message.
+ *
+ * Derived from DEV_SERVER_PORTS rather than re-typed: a message that lists ports the scan does not
+ * check, or omits ones it does, is a new version of the same defect — a confident claim about
+ * evidence that was never gathered.
+ */
+/**
+ * The second half of the answer for a project that never went through `init`.
+ *
+ * Held separately because it must appear ONLY when the project is uninstrumented — telling a wired
+ * project to re-run `init` sends the reader back to a step that already succeeded, which is its own
+ * kind of wrong answer.
+ */
+const UNINSTRUMENTED = 'Separately: this project has not been through `reticle init`, which is what installs the SDK ' +
+    'and wires it into the build — so even once the dev server is up, the app will carry no SDK and ' +
+    "no session will appear. Run `reticle init` in the app's directory too.";
+const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
+export function diagnoseNoSession(facts) {
+    const { everConnected, initialized, listening, port } = facts;
+    const ports = listening.join(', ');
+    if (everConnected) {
+        // A reaped lease first, because it is the one cause we have POSITIVE evidence for. Reported
+        // from the field (#157): an aged-out lease produced "the tab was closed … ask the human to
+        // reopen the app", which is wrong on every clause — there is no human tab, and the recovery it
+        // names is unavailable to the caller while the one that works goes unmentioned. The reporter
+        // went looking for a port mismatch. Hedged rather than swapped: a human tab may ALSO have
+        // closed, and this does not know which session went.
+        if (true === facts.leaseExpired) {
+            return ('no browser session connected — but one WAS connected to this daemon earlier, so the wiring ' +
+                'is correct. This daemon has expired at least one pooled lease, so the likeliest cause is ' +
+                'that a lease you were using aged out; a lease is a headless context, not a human tab, and ' +
+                'it takes its cookies with it (so an authenticated app needs signing in again). Re-acquire ' +
+                'with reticle_lease {action:"acquire", url} and carry on. If you were driving a human tab ' +
+                `instead, it went away — reopen it or run \`reticle open\`. ${RETRY}`);
+        }
+        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 the ports Reticle scans ' +
+            `(${SCANNED_PORTS}). The likeliest cause by far is that the dev server is not running: ask ` +
+            'the human to start it (`npm run dev`), then open the app in a browser. ' +
+            // The caveat is here rather than omitted because the scan is NARROW, and the old sentence
+            // spent its confidence as though an empty result from eleven ports were proof of absence.
+            // Reported from a scripted drive of 2.5.0: this branch asserted the app was not running while
+            // it served 200 on :7699. A dev server on any other port — 4173 from `vite preview`, 1420
+            // from Tauri, 5175 from a second Vite, anything passed to --port — is invisible to it.
+            'That scan is narrow, so it is not proof: a server on any other port is invisible to it. If ' +
+            // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
+            // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
+            // only move that can recover the :7699 case.
+            'the app IS running, ask the human for its URL rather than assuming it is down. ' +
+            // BOTH facts at once when the project was never wired. This branch fires before the
+            // `!initialized` one, so an uninstrumented project used to be told only "start your dev
+            // server" — the reader starts it, calls again, and is told ONLY THEN that no app carries the
+            // SDK. Two round trips to learn two things the daemon knew on the first call, and this is the
+            // largest cohort in the funnel (#171): 77 users attached an agent and never instrumented an
+            // app. They have a daemon (they registered the MCP server) and no SDK anywhere.
+            `${initialized ? '' : UNINSTRUMENTED} ${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,21 @@
+/**
+ * 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, 
+/** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
+reapedLeases?: () => number): () => void;

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

@@ -0,0 +1,69 @@
+/**
+ * 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,
+        leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+    }));
+    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, 
+/** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
+reapedLeases) {
+    if (activeProjectId !== undefined)
+        sessions.setDefaultScope({ projectId: activeProjectId });
+    return startNoSessionWatch({
+        sessions,
+        port,
+        initialized: activeProjectId !== undefined,
+        ...(reapedLeases === undefined ? {} : { reapedLeases }),
+    });
+}

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/pending-commands.js

@@ -13,6 +13,7 @@ export class PendingCommands {
                 this.#pending.delete(id);
                 reject(new Error(describeTimeout()));
             }, timeoutMs);
+            timer.unref();
             this.#pending.set(id, { resolve, reject, timer });
         });
     }

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