@reticlehq/server 2.8.0 → 2.10.0

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

@@ -9,24 +9,127 @@
  * 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 { probeDevServers, probeDevServerStates } from './dev-server-probe.js';
 import { diagnoseNoSession } from './no-session-diagnosis.js';
-import { readProjectPort } from '../cli/cli-port.js';
+import { detectDevCommand } from './dev-command.js';
+import { nextActionFor, renderNextAction } from './no-session-next-action.js';
+import { readProjectFramework, readProjectId, readProjectPort } from '../cli/cli-port.js';
+import { discoverProjectConfigs } from '../cli/config-discovery.js';
+import { hasProjectConnectedBefore, rememberConnected } from './connection-memory.js';
+import { reticleStateHome } from '../daemon/daemon.js';
+import { stallUptime } from '../telemetry/instrumentation-stall.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) {
+/** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
+const LOCALHOST = 'http://localhost';
+/**
+ * What the failure path says, always naming the reason rather than swallowing it.
+ *
+ * An auto-attach that fails silently is the same class of defect as the message it replaces: the
+ * agent is told absence and never learns that Reticle tried and could not.
+ */
+function attachFailureClause(port, reason) {
+    const collision = /EADDRINUSE|address already in use/i.test(reason);
+    return (` Reticle also tried to open ${LOCALHOST}:${String(port)} in a browser it owns and could not: ` +
+        `${reason}.` +
+        (collision
+            ? ' That is a port collision — something already holds the port this daemon needs, so the ' +
+                'browser Reticle drives could not be started. Stop the other Reticle process and retry, ' +
+                'rather than treating this as a problem with the app.'
+            : ''));
+}
+/**
+ * Start the watch. Returns a stop function; the timer is unref'd so it never holds the daemon up.
+ *
+ * Exported for the test that pins the after-boot config read below — the daemon itself starts this
+ * through `wireSessionScope`.
+ */
+export function startNoSessionWatch(options) {
     const probe = options.probe ?? (() => probeDevServers());
     let listening = [];
+    /**
+     * Ports that accepted a connection and then answered nothing in time.
+     *
+     * Tracked beside `listening` rather than folded into it: they are not dev servers as far as the
+     * probe knows, so they must not be spent as proof the app is up, and they are not absent either,
+     * so the diagnosis must stop telling people to start a server that is already running. A custom
+     * `options.probe` returns only the serving set, so this stays empty for injected probes.
+     */
+    let slowListeners = [];
     let running = false;
+    /** Ports auto-attach has already spent its one attempt on. Bounded: never a loop, never a retry. */
+    const attempted = new Set();
+    /** Set only when an attempt actually failed, so the diagnosis can say so instead of hiding it. */
+    let attachFailure;
+    const directory = options.directory ?? process.cwd();
+    // The boot answer still counts (it is what the daemon scoped its sessions with), but `.reticle.json`
+    // is routinely written by `init` AFTER this daemon started, so re-read rather than cache. See the
+    // `initialized` comment below, which this shares.
+    const isWired = () => options.initialized || readProjectId(directory) !== undefined;
+    // Read at boot: the daemon's own identity does not change under it, and this is the key the
+    // durable bit is stored under.
+    const stateDir = options.stateDir ?? reticleStateHome();
+    /**
+     * Only ever asked ABOUT A NAMED PROJECT.
+     *
+     * With no projectId the memory can still answer the weaker "has anything connected on this port",
+     * and that answer must not be spent here: a shared 4400 on a machine with several repos would
+     * then soften a genuinely-unwired directory's diagnosis on the strength of an unrelated app. That
+     * is the same over-confident claim this whole file exists to remove, pointing the other way.
+     */
+    const connectedBefore = () => hasProjectConnectedBefore(stateDir, options.port, readProjectId(directory));
+    // Every path that registers a session goes through SessionManager.add, so this is the one hook
+    // that makes the bit durable. Recorded per port + projectId so a shared 4400 cannot make one
+    // project's success into evidence about another's.
+    options.sessions.setConnectionRecorder((projectId) => {
+        rememberConnected(stateDir, options.port, projectId);
+    });
+    /**
+     * Open the app ourselves when there is exactly one unambiguous candidate.
+     *
+     * AUTOMATIC, not offered — the deliberate call. Offering means a round trip and a decision by an
+     * agent that has strictly less evidence than this daemon does, on the one case where there is
+     * nothing left to decide: the project is wired, so a page WILL connect, and exactly one dev server
+     * is listening, so there is no ambiguity about which. That case is the bulk of the loss. Every
+     * other shape (several listeners, an unwired project, no listener) still returns prose, because
+     * there the daemon would be guessing and a guess that opens a browser is worse than a sentence.
+     *
+     * Bounded by construction: one attempt per port per daemon. A failure is recorded, never retried —
+     * a retry loop against a broken Chromium install would spin for the daemon's whole life.
+     */
+    const autoAttach = async (ports) => {
+        const attach = options.attach;
+        if (attach === undefined)
+            return;
+        if (1 !== ports.length)
+            return;
+        const [only] = ports;
+        if (only === undefined || attempted.has(only))
+            return;
+        if (!isWired())
+            return;
+        attempted.add(only);
+        try {
+            await attach(`${LOCALHOST}:${String(only)}`);
+        }
+        catch (error) {
+            attachFailure = attachFailureClause(only, error instanceof Error ? error.message : String(error));
+        }
+    };
     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) => {
+        void (options.probe === undefined
+            ? probeDevServerStates().then((states) => {
+                slowListeners = states.slow;
+                return states.serving;
+            })
+            : probe())
+            .then(async (ports) => {
             listening = ports;
+            await autoAttach(ports);
         })
             .catch(() => {
             /* a diagnostic hint must never take the daemon down */
@@ -38,27 +141,82 @@ function startNoSessionWatch(options) {
     refresh();
     const timer = setInterval(refresh, REFRESH_MS);
     timer.unref();
+    const nextAction = () => nextActionFor({
+        everConnected: options.sessions.everConnected(),
+        initialized: isWired(),
+        previouslyConnected: connectedBefore(),
+        listening,
+        // Read when asked, like everything else here: a `package.json` can gain a dev script, and a
+        // daemon that cached "there is none" at boot would keep saying so for the rest of the day.
+        dev: detectDevCommand(directory),
+    });
+    options.sessions.setNoSessionNextAction(nextAction);
     options.sessions.setNoSessionHint(() => diagnoseNoSession({
         everConnected: options.sessions.everConnected(),
-        initialized: options.initialized,
+        // Read WHEN ASKED, for the same reason `projectPort` below is: `.reticle.json` is routinely
+        // written by `init` after this daemon started — that is the ordinary first-install order — and
+        // the boot-time answer is then permanently stale. Reported from the field as `reticle status`
+        // saying the project had never been through `init` about a project whose config named its
+        // framework and its projectId, and whose real problem was a dev server older than the plugin.
+        // The boot value still counts: it is the one the daemon scoped its sessions with.
+        initialized: isWired(),
         listening,
+        slowListeners,
         port: options.port,
         // The directory `initialized` was decided in. Named in the message because "there is no
         // `.reticle.json`" is a claim about ONE directory, and a reader standing somewhere else
         // cannot tell whether it is a claim about their app at all.
-        directory: options.directory ?? process.cwd(),
+        directory,
+        // Where the config actually is, when it is not here — and where we looked, when it is
+        // nowhere. Computed only on the branch that needs it: a wired daemon has its answer already,
+        // and a workspace scan on every hint would be a directory walk per tool refusal.
+        ...(isWired()
+            ? {}
+            : (() => {
+                const discovery = discoverProjectConfigs(directory);
+                const elsewhere = discovery.found.filter((c) => c.directory !== directory);
+                return 0 === elsewhere.length
+                    ? { searchedDirectories: discovery.searched }
+                    : {
+                        configsElsewhere: elsewhere.map((c) => ({
+                            directory: c.directory,
+                            ...(c.projectId === undefined ? {} : { projectId: c.projectId }),
+                        })),
+                    };
+            })()),
+        // The one fact that outranks every absence below it, and the reason a fresh daemon stopped
+        // claiming that an install which has demonstrably worked has never worked.
+        previouslyConnected: connectedBefore(),
+        // Ranks the causes. Read when asked, like the rest: `init` writes this file after the daemon
+        // starts on an ordinary first install.
+        ...(() => {
+            const framework = readProjectFramework(directory);
+            return framework === undefined ? {} : { framework };
+        })(),
         leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+        // How long this daemon has been waiting with no app. The diagnosis uses it to surface
+        // "install never finished" — the same condition telemetry already knows about.
+        ...(() => {
+            const upMs = stallUptime(Date.now());
+            return upMs === undefined ? {} : { daemonUpMs: upMs };
+        })(),
         // Read here rather than at boot: `.reticle.json` can be written by `init` after this daemon
         // started, which is the ordinary first-install order, and a port cached from before it existed
         // would make the daemon confidently report no mismatch on the one run where there is one.
         ...(() => {
-            const configured = readProjectPort(options.directory ?? process.cwd());
+            const configured = readProjectPort(directory);
             return configured === undefined ? {} : { projectPort: configured };
         })(),
-    }));
+    }) +
+        // Prose for the human, then the literal command for the agent. Appended rather than folded
+        // into the diagnosis so that file stays pure and its cases stay independently pinned.
+        ` ${renderNextAction(nextAction())}` +
+        (attachFailure ?? ''));
     return () => {
         clearInterval(timer);
+        options.sessions.setConnectionRecorder(undefined);
         options.sessions.setNoSessionHint(undefined);
+        options.sessions.setNoSessionNextAction(undefined);
     };
 }
 /**
@@ -69,7 +227,9 @@ function startNoSessionWatch(options) {
  */
 export function wireSessionScope(sessions, activeProjectId, port, 
 /** Reader for the pool's aged-out-lease count; omitted when this daemon runs no pool. */
-reapedLeases) {
+reapedLeases, 
+/** Opens a URL in a Reticle-owned browser (the pool). Omitted ⇒ auto-attach is off. */
+attach) {
     if (activeProjectId !== undefined)
         sessions.setDefaultScope({ projectId: activeProjectId });
     return startNoSessionWatch({
@@ -77,5 +237,6 @@ reapedLeases) {
         port,
         initialized: activeProjectId !== undefined,
         ...(reapedLeases === undefined ? {} : { reapedLeases }),
+        ...(attach === undefined ? {} : { attach }),
     });
 }

package/dist/session/pending-commands.d.ts

@@ -1,4 +1,16 @@
 import type { CommandResult } from '@reticlehq/core';
+/**
+ * The page was asked and did not answer inside the caller's budget.
+ *
+ * A distinct type because the two ways a command can fail mean opposite things, and a caller that
+ * cannot tell them apart will do the wrong thing with one of them. A rejection from a replaced
+ * transport says the question never reached the page and is worth asking again; a timeout says it
+ * did reach the page, which did not answer in the time granted — and asking again spends a budget
+ * that is already gone. Retrying a timeout as though it were a disconnect turned one read into
+ * hundreds of commands on the wire against a page that was reconnecting in a loop.
+ */
+export declare class CommandTimeoutError extends Error {
+}
 export declare class PendingCommands {
     #private;
     /** Next correlation id. Monotonic per session, so a reply can never match an earlier command. */

package/dist/session/pending-commands.js

@@ -1,3 +1,15 @@
+/**
+ * The page was asked and did not answer inside the caller's budget.
+ *
+ * A distinct type because the two ways a command can fail mean opposite things, and a caller that
+ * cannot tell them apart will do the wrong thing with one of them. A rejection from a replaced
+ * transport says the question never reached the page and is worth asking again; a timeout says it
+ * did reach the page, which did not answer in the time granted — and asking again spends a budget
+ * that is already gone. Retrying a timeout as though it were a disconnect turned one read into
+ * hundreds of commands on the wire against a page that was reconnecting in a loop.
+ */
+export class CommandTimeoutError extends Error {
+}
 export class PendingCommands {
     #pending = new Map();
     #seq = 0;
@@ -11,7 +23,7 @@ export class PendingCommands {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.#pending.delete(id);
-                reject(new Error(describeTimeout()));
+                reject(new CommandTimeoutError(describeTimeout()));
             }, timeoutMs);
             timer.unref();
             this.#pending.set(id, { resolve, reject, timer });

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

@@ -1,5 +1,6 @@
 import { Session, type SessionInfo } from './session.js';
 import { AttachmentHistory } from './attachment-history.js';
+import type { NoSessionNextAction } from './no-session-next-action.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
@@ -15,6 +16,7 @@ export declare class SessionManager {
     #private;
     /** Set the active project's default resolve scope (called once at daemon wiring). */
     setDefaultScope(scope: ResolveScope | undefined): void;
+    setConnectionRecorder(record: ((projectId: string | undefined) => void) | undefined): void;
     add(session: Session): Session | undefined;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
@@ -35,6 +37,8 @@ export declare class SessionManager {
      * already computed for the error path; this exposes it to the read path too.
      */
     noSessionHint(): string | undefined;
+    setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
+    noSessionNextAction(): NoSessionNextAction | undefined;
     everConnected(): boolean;
     /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
     noteClosure(reason: string, at: number): void;

package/dist/session/session-manager.js

@@ -79,8 +79,20 @@ export class SessionManager {
     setDefaultScope(scope) {
         this.#defaultScope = scope;
     }
+    /**
+     * Told about every session that registers, so the fact outlives this process.
+     *
+     * Injected rather than done here: this class owns a registry, not the filesystem. Wired here
+     * because `add` is the ONE method every path that registers a session goes through — the same
+     * reasoning that put the redaction declaration below it.
+     */
+    #recordConnection;
+    setConnectionRecorder(record) {
+        this.#recordConnection = record;
+    }
     add(session) {
         this.#everConnected = true;
+        this.#recordConnection?.(session.projectId);
         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
@@ -172,6 +184,20 @@ export class SessionManager {
     noSessionHint() {
         return this.#noSessionHint?.();
     }
+    /**
+     * The same diagnosis with the prose taken out — one action kind and one literal command.
+     *
+     * Separate from the hint rather than folded into it because the two have different consumers and
+     * different lifetimes: `resolve` throws an Error, which can only ever carry a string, while
+     * `reticle_sessions` returns a structured payload an agent can branch on without parsing English.
+     */
+    #noSessionNextAction;
+    setNoSessionNextAction(next) {
+        this.#noSessionNextAction = next;
+    }
+    noSessionNextAction() {
+        return this.#noSessionNextAction?.();
+    }
     /** Whether any session has connected since this daemon booted — half the diagnosis. */
     #everConnected = false;
     everConnected() {
@@ -224,11 +250,15 @@ export class SessionManager {
             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 REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`);
+            // BOTH, when there are both — the two answer different questions and the pair is strictly
+            // more than either. This used to be an either/or, and a recorded refusal DISCARDED the whole
+            // diagnosis: the one case where the daemon has hard evidence about why nothing is connected
+            // was also the one case where it threw away everything else it had learned, including the
+            // port scan and the next action. The refusal leads, because it is the fact.
+            const refusal = closure === undefined
+                ? ''
+                : ` NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`;
+            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}`);
         }
         // 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

package/dist/session/session-readiness.js

@@ -11,7 +11,7 @@ const DEFAULT_POLL_MS = 25;
  */
 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{action:"start"} → reticle_replay, or reticle_flow_verify for the whole ' +
+    'truth, not just the DOM · REGRESS: reticle_record{action:"start"} → reticle_replay, or reticle_verify{action:"flows"} for the whole ' +
     'suite. The human can flag bugs from the panel — drain them with reticle_session{action:"review"} and resolve each once fixed. ' +
     'MANDATORY: the moment you stop driving — finishing your reply or waiting on the human — call reticle_session {action:"yield"} ' +
     '(mode:"waiting", or mode:"ask" with the question) so the panel shows your real state; reticle_session{action:"end"} ' +

package/dist/session/session.d.ts

@@ -1,4 +1,5 @@
 import type { WebSocket } from 'ws';
+import type { ImpactSnapshot } from '@reticlehq/core';
 import { LastAct } from './last-act.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
@@ -148,6 +149,7 @@ export declare class Session {
     handleResult(result: CommandResult): void;
     /** Reject everything still in flight — used on disconnect. */
     rejectAll(reason: string): void;
+    succeededBy(next: Session): void;
     /** End this transport without letting a stale socket remove its replacement session. */
     disconnect(reason: string): void;
     getState(): SessionState;
@@ -184,8 +186,15 @@ export declare class Session {
      * Push a lifecycle state to the panel with optional human-facing `text`. State changes still flow
      * through `setState`; an auto-ended session rides a `warn` tone so the panel can shout "agent stopped".
      */
+    /**
+     * Push the impact record to this tab's HUD.
+     *
+     * Debounced: the record changes on every tool call, and the panel does not need 200 frames to
+     * show a counter going up. The LAST state always lands, because the timer re-reads the store
+     * when it fires rather than capturing a snapshot when it was scheduled.
+     */
+    pushImpact(read: () => ImpactSnapshot | undefined, immediate?: boolean): void;
     pushPresenter(state: SessionState, text?: string, tone?: PresenterTone): void;
-    /** Fire-and-forget a narration row to the live panel (so a resolved mark shows "✓ fixed"). */
     pushNarration(text: string): void;
     /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease(): SessionLease | undefined;

package/dist/session/session.js

@@ -1,7 +1,10 @@
+import { recordImpact } from '../impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
-import { PendingCommands } from './pending-commands.js';
+/** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
+const IMPACT_PUSH_DEBOUNCE_MS = 700;
+import { PendingCommands, CommandTimeoutError } from './pending-commands.js';
 import { span } from '../trace.js';
 import { AppRuntime, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '../events/ring-buffer.js';
@@ -18,6 +21,33 @@ import { buildSessionInfo } from './session-info.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
+/**
+ * Commands that may be re-issued against the connection that replaced this session.
+ *
+ * Reads only, and the boundary is the point. Re-reading a page costs nothing and answers the same
+ * question the caller asked. An act cannot be replayed: it may already have been dispatched in the
+ * page that went away, and performing it a second time behind the caller's back is a double submit
+ * nobody asked for. A replaced act still errors, and the caller's own retry — with the same id,
+ * which is still the right one — is the safe path.
+ */
+/**
+ * How far to walk a chain of replacements before giving up.
+ *
+ * Generous for the real case (a page reloading a handful of times while a call is in flight) and
+ * small enough that a cycle costs nothing. The number is a backstop, not a policy: a chain longer
+ * than this means something is re-dialling in a loop, and that is a different problem.
+ */
+const MAX_SUCCESSOR_HOPS = 32;
+const REBINDABLE_COMMANDS = new Set([
+    ReticleCommand.SNAPSHOT,
+    ReticleCommand.QUERY,
+    ReticleCommand.MATCH,
+    ReticleCommand.INSPECT,
+    ReticleCommand.STATE_READ,
+    ReticleCommand.STORAGE_READ,
+    ReticleCommand.CAPABILITIES,
+    ReticleCommand.ANIMATIONS,
+]);
 /** Prefix on minted action ids (a1, a2, …) — the journal's action identity, independent of commands. */
 const ACTION_ID_PREFIX = 'a';
 /** ws readyState for an OPEN socket — guard fire-and-forget pushes against a closing tab. */
@@ -192,8 +222,12 @@ export class Session {
         if (event.type === EventType.HUMAN_MARK) {
             // A human pinned a mistake to an element. Narrow at the boundary; an invalid mark is ignored.
             const parsed = HumanMarkDataSchema.safeParse(event.data);
-            if (parsed.success)
+            if (parsed.success) {
                 this.#review.add(parsed.data, this.elapsed());
+                // The impact record's `marks` field existed and nothing ever wrote it: the report would
+                // have shown a permanent zero next to a page covered in pins.
+                recordImpact({ marks: 1 });
+            }
         }
         if (event.type === EventType.ROUTE_CHANGE) {
             // Keep the reported URL live across SPA navigation. The SDK already emits route.change on
@@ -215,8 +249,18 @@ export class Session {
             : seen;
         this.#observed.observe(attributed);
         this.#buffer.push(attributed, t, byteSize);
-        for (const listener of this.#listeners)
-            listener(attributed);
+        // Each subscriber is independent, and this runs inside the websocket's `message` handler — a
+        // NON-async callback, so a sync throw here escapes every try/catch the tool call is wrapped in
+        // and becomes an uncaughtException, which the daemon answers by exiting. One observer's bug must
+        // not cost the fleet its daemon. Same rule the session-ready fan-out already follows.
+        for (const listener of this.#listeners) {
+            try {
+                listener(attributed);
+            }
+            catch {
+                /* an event observer must never break the session it observes */
+            }
+        }
     }
     // Passthroughs to ObservedState, which owns the per-session facts that must SURVIVE buffer
     // eviction: refs the agent drove, and what the layer could not see. See observed-state.ts.
@@ -397,6 +441,12 @@ export class Session {
             if ('string' === typeof ref)
                 this.recordActedRef(ref);
         }
+        // The page already re-dialled under this same id. Nothing has been sent yet, so handing the
+        // command to the live connection cannot perform anything twice — it is the call the agent would
+        // have made itself after a `reticle_sessions` round trip, minus the round trip.
+        const successor = this.#liveSuccessor();
+        if (successor !== undefined)
+            return successor.command(name, args, timeoutMs);
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = JSON.stringify({
             kind: MessageKind.COMMAND,
@@ -425,7 +475,27 @@ export class Session {
                 this.recordActedLabelFrom(result);
             return result;
         })
-            .finally(() => recordBrowserLatency(Date.now() - sentAt));
+            .finally(() => recordBrowserLatency(Date.now() - sentAt))
+            .catch((error) => {
+            // The replacement landed while this command was on the wire, which is the reported case:
+            // `reticle_navigate` reloads the page, the reload sends a fresh HELLO carrying the same id,
+            // and the `reticle_snapshot` already in flight is rejected by the displaced session.
+            // A TIMEOUT is not a replacement. The catch fired on any rejection, so a command that had
+            // simply not been answered in budget was read as "you were replaced, ask again" — and
+            // against a page re-dialling in a loop that turned one read into hundreds of commands on the
+            // wire, minutes of wall clock, and an answer still quoting the budget it had blown.
+            const next = error instanceof CommandTimeoutError ? undefined : this.#liveSuccessor();
+            if (next === undefined || !REBINDABLE_COMMANDS.has(name))
+                throw error;
+            // What is LEFT of the caller's budget, not a fresh copy of it. Re-issuing with the original
+            // timeout means a caller who granted 8s can wait 16, and across a chain of replacements the
+            // total is unbounded — a wait nobody asked for, on the path that exists to save a round trip.
+            // A budget already spent means there is nothing left to retry into, so the error stands.
+            const remaining = timeoutMs - (Date.now() - sentAt);
+            if (remaining <= 0)
+                throw error;
+            return next.command(name, args, remaining);
+        });
     }
     handleResult(result) {
         this.#pending.settle(result);
@@ -437,8 +507,52 @@ export class Session {
             listener();
         this.#disconnectListeners.clear();
     }
+    /**
+     * The connection that took this session's id over, once one has.
+     *
+     * Set by the bridge at the moment it displaces this session, so the two facts a replaced handle
+     * needs — that it was replaced, and by whom — arrive together. Without it, every tool call holding
+     * this handle could only report "session replaced by a newer connection claiming the same id", and
+     * the caller's only recovery was `reticle_sessions` plus a retry: two round trips to rediscover an
+     * id the daemon was already holding, and which had not even changed.
+     */
+    #successor;
+    succeededBy(next) {
+        // A session is never its own replacement; guarding here keeps `command` from recursing forever
+        // if a registry ever re-adds the same object.
+        if (next !== this)
+            this.#successor = next;
+    }
+    /**
+     * The replacement, but only while it can actually answer.
+     *
+     * A successor is recorded once and never cleared, so without this a session that was replaced an
+     * hour ago keeps handing commands to a socket that has since closed — and the caller pays the full
+     * timeout to learn it, turning an instant "session replaced" into a wait. The point of delegating
+     * was to save the caller a round trip; delegating to a dead socket costs them more than the error
+     * did.
+     */
+    #liveSuccessor() {
+        // Walked, not just read one hop. Two replacements in quick succession — a page that reloads
+        // twice — leave a CHAIN, and the handle the caller holds points at a session that is itself
+        // already displaced. Stopping at the first dead link fails safe and also fails: the open page is
+        // one hop further on, and the caller gets back exactly the error this exists to remove.
+        //
+        // Bounded, because `succeededBy` refuses self-succession but nothing prevents a cycle, and an
+        // unbounded walk over one is a hang — which is worse than the error it was trying to avoid.
+        let next = this.#successor;
+        for (let hops = 0; next !== undefined && hops < MAX_SUCCESSOR_HOPS; hops += 1) {
+            if (next.#socket.readyState === WS_OPEN)
+                return next;
+            next = next.#successor;
+        }
+        return undefined;
+    }
     /** End this transport without letting a stale socket remove its replacement session. */
     disconnect(reason) {
+        // "Longest run" means the longest SESSION, and it used to be fed a single tool call's duration
+        // - so the report's superlative was a number in milliseconds that never grew past a click.
+        recordImpact({}, { runMs: this.elapsed() });
         this.rejectAll(reason);
         try {
             this.#socket.close(1008, reason);
@@ -515,10 +629,37 @@ export class Session {
      * Push a lifecycle state to the panel with optional human-facing `text`. State changes still flow
      * through `setState`; an auto-ended session rides a `warn` tone so the panel can shout "agent stopped".
      */
+    /**
+     * Push the impact record to this tab's HUD.
+     *
+     * Debounced: the record changes on every tool call, and the panel does not need 200 frames to
+     * show a counter going up. The LAST state always lands, because the timer re-reads the store
+     * when it fires rather than capturing a snapshot when it was scheduled.
+     */
+    pushImpact(read, immediate = false) {
+        if (immediate) {
+            // A tab that just connected has nothing to show yet, so its first record goes out at once -
+            // waiting a debounce here is a report that reads "nothing recorded" over a month of history.
+            const first = read();
+            if (first !== undefined)
+                this.#post(ReticleCommand.IMPACT, { snapshot: first });
+            return;
+        }
+        if (this.#impactTimer !== undefined)
+            return;
+        this.#impactTimer = setTimeout(() => {
+            this.#impactTimer = undefined;
+            const snapshot = read();
+            if (snapshot !== undefined)
+                this.#post(ReticleCommand.IMPACT, { snapshot });
+        }, IMPACT_PUSH_DEBOUNCE_MS);
+        this.#impactTimer.unref?.();
+    }
     pushPresenter(state, text, tone) {
         this.#post(ReticleCommand.PRESENTER, buildPresenterArgs(state, text, tone));
     }
     /** Fire-and-forget a narration row to the live panel (so a resolved mark shows "✓ fixed"). */
+    #impactTimer;
     pushNarration(text) {
         this.#post(ReticleCommand.NARRATE, { text, level: 'info' });
     }

package/dist/telemetry/app-instrumented.d.ts

@@ -33,5 +33,13 @@ export interface InstrumentationFacts {
  * never be the reason a session fails to register.
  */
 export declare function reportAppInstrumented(facts: InstrumentationFacts, now?: () => number): void;
+/**
+ * Has an app connected to this daemon run at all?
+ *
+ * The same flag `reportAppInstrumented` uses for idempotency, read from outside. The stall check
+ * needs exactly this question and must not answer it from a window counter, which resets on every
+ * flush and would then report a long-instrumented daemon as freshly stalled.
+ */
+export declare function appEverConnected(): boolean;
 /** Tests only. */
 export declare function resetAppInstrumented(): void;

package/dist/telemetry/app-instrumented.js

@@ -47,6 +47,16 @@ export function reportAppInstrumented(facts, now = () => Date.now()) {
         /* never let a metric interfere with a page connecting */
     }
 }
+/**
+ * Has an app connected to this daemon run at all?
+ *
+ * The same flag `reportAppInstrumented` uses for idempotency, read from outside. The stall check
+ * needs exactly this question and must not answer it from a window counter, which resets on every
+ * flush and would then report a long-instrumented daemon as freshly stalled.
+ */
+export function appEverConnected() {
+    return reported;
+}
 /** Tests only. */
 export function resetAppInstrumented() {
     reported = false;