@reticlehq/server 2.7.0 → 2.9.0

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

@@ -9,23 +9,126 @@
  * 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 { 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';
 /** 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 */
@@ -37,16 +140,76 @@ 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,
+        // 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,
-    }));
+        // 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(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);
     };
 }
 /**
@@ -57,7 +220,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({
@@ -65,5 +230,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/ref-provenance.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which tab a ref came out of, so the call that spends it cannot be routed to a different one.
+ *
+ * Reported from the field: three tabs of one project were connected, a snapshot was taken against a
+ * named session, and the act that followed omitted `sessionId`. Auto-selection picked a different
+ * tab, the ref legitimately did not exist there, and the refusal read "that ref is stale: refs are
+ * invalidated whenever the DOM re-renders" — a confident diagnosis of the wrong thing, and one that
+ * accuses the app under test. The recovery text then sends the agent to re-snapshot, which mints a
+ * fresh ref in whichever tab is chosen next, so the lesson it teaches is wrong either way.
+ *
+ * The quiet outcome is the worse one. Refs are minted from a per-document block, so the same number
+ * is a real, live, DIFFERENT element in the tab that was guessed: the identical call on a luckier day
+ * drives the wrong tab and returns a green about a page nobody asked about. That is a false green
+ * with extra steps, and it is the failure class this product exists to remove.
+ *
+ * Every `sessionId` description on the surface already promises that Reticle "refuses rather than
+ * guesses when ambiguous". This is the fact that makes the ambiguity visible: the tab a ref was
+ * handed out of is known at the moment it is handed out. Resolution is otherwise untouched — a call
+ * that names a session, carries no ref, or lands on the tab it looked at resolves silently, which is
+ * the cost the surface wording was rewritten to avoid.
+ *
+ * ponytail: one slot, not a per-ref map. It answers the reported shape — look at one tab, act on
+ * what you saw — for the cost of an assignment. A drive that interleaves refs from several tabs
+ * inside one turn needs per-ref provenance, and that is the upgrade if it ever shows up.
+ */
+/** Record that a tool handed out refs from this session. */
+export declare function noteRefsMinted(sessionId: string): void;
+export declare function refsLastMintedIn(): string | undefined;
+/** Test seam: the module holds one slot for the process, so a test has to be able to clear it. */
+export declare function forgetRefProvenance(): void;
+interface RefRouting {
+    /** The ref this call is about to spend, if it carries one. */
+    ref: string | undefined;
+    /** The `sessionId` the CALLER passed — when present, nothing was guessed. */
+    explicitSessionId: string | undefined;
+    /** The session resolution actually picked. */
+    chosenSessionId: string;
+    /**
+     * The connected sessions, read ONLY once a refusal is certain. A thunk because listing them walks
+     * every session and builds a health block each time, and the answer is wanted on the rare path.
+     */
+    connected: () => readonly {
+        sessionId: string;
+        url: string;
+    }[];
+}
+/**
+ * The refusal for a ref that belongs to another tab, or undefined when there is no ambiguity.
+ *
+ * Silent when the minting tab is no longer connected: that ref really is dead, and the stale-ref
+ * refusal that already exists is the honest answer for it.
+ */
+export declare function wrongTabRefusal(routing: RefRouting): string | undefined;
+export {};

package/dist/session/ref-provenance.js

@@ -0,0 +1,61 @@
+/**
+ * Which tab a ref came out of, so the call that spends it cannot be routed to a different one.
+ *
+ * Reported from the field: three tabs of one project were connected, a snapshot was taken against a
+ * named session, and the act that followed omitted `sessionId`. Auto-selection picked a different
+ * tab, the ref legitimately did not exist there, and the refusal read "that ref is stale: refs are
+ * invalidated whenever the DOM re-renders" — a confident diagnosis of the wrong thing, and one that
+ * accuses the app under test. The recovery text then sends the agent to re-snapshot, which mints a
+ * fresh ref in whichever tab is chosen next, so the lesson it teaches is wrong either way.
+ *
+ * The quiet outcome is the worse one. Refs are minted from a per-document block, so the same number
+ * is a real, live, DIFFERENT element in the tab that was guessed: the identical call on a luckier day
+ * drives the wrong tab and returns a green about a page nobody asked about. That is a false green
+ * with extra steps, and it is the failure class this product exists to remove.
+ *
+ * Every `sessionId` description on the surface already promises that Reticle "refuses rather than
+ * guesses when ambiguous". This is the fact that makes the ambiguity visible: the tab a ref was
+ * handed out of is known at the moment it is handed out. Resolution is otherwise untouched — a call
+ * that names a session, carries no ref, or lands on the tab it looked at resolves silently, which is
+ * the cost the surface wording was rewritten to avoid.
+ *
+ * ponytail: one slot, not a per-ref map. It answers the reported shape — look at one tab, act on
+ * what you saw — for the cost of an assignment. A drive that interleaves refs from several tabs
+ * inside one turn needs per-ref provenance, and that is the upgrade if it ever shows up.
+ */
+/** The session the last ref-bearing result was produced from. Undefined until something mints one. */
+let mintedIn;
+/** Record that a tool handed out refs from this session. */
+export function noteRefsMinted(sessionId) {
+    mintedIn = sessionId;
+}
+export function refsLastMintedIn() {
+    return mintedIn;
+}
+/** Test seam: the module holds one slot for the process, so a test has to be able to clear it. */
+export function forgetRefProvenance() {
+    mintedIn = undefined;
+}
+/**
+ * The refusal for a ref that belongs to another tab, or undefined when there is no ambiguity.
+ *
+ * Silent when the minting tab is no longer connected: that ref really is dead, and the stale-ref
+ * refusal that already exists is the honest answer for it.
+ */
+export function wrongTabRefusal(routing) {
+    if (routing.ref === undefined || routing.explicitSessionId !== undefined)
+        return undefined;
+    const source = mintedIn;
+    if (source === undefined || source === routing.chosenSessionId)
+        return undefined;
+    const connected = routing.connected();
+    if (!connected.some((s) => s.sessionId === source))
+        return undefined;
+    const listed = connected.map((s) => `'${s.sessionId}' (${s.url})`).join(', ');
+    return (`ref '${routing.ref}' was handed out by session '${source}', and this call named no sessionId so ` +
+        `it resolved to '${routing.chosenSessionId}'. A ref only means something in the tab it was taken ` +
+        'in — refs are minted per document, so the same one can point at a different element in another ' +
+        'tab — and Reticle refuses rather than guessing which tab you meant. Connected right now: ' +
+        `${listed}. Pass sessionId: '${source}' to act on the tab you looked at, or re-read the tab you ` +
+        'actually want first. Nothing was driven.');
+}

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.
  */
-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

@@ -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.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;