@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/session/daemon-answers.d.ts

@@ -0,0 +1,20 @@
+import { log } from '../../log.js';
+import { bindSpanContext } from '../../trace.js';
+/**
+ * What the daemon answers when the rules that decide a verdict ask it for something.
+ *
+ * The rules are meant to be liftable out of the daemon on their own, so they never go looking for
+ * the log or the tracer -- both are handed to them, on the session object they are already given.
+ * See `events/engine-host.ts` for why, and for what happens when nobody answers.
+ *
+ * They live here rather than inside the session class because neither is anything to do with a
+ * particular browser tab. They are the daemon's own identity, and every session gives the same
+ * answer.
+ */
+/** Write something down where the daemon writes everything else. */
+export declare const noteToDaemonLog: typeof log;
+/**
+ * Keep a callback belonging to the call that created it, so a re-check scheduled for later still
+ * traces back to the wait that asked for it instead of looking like work starting from nowhere.
+ */
+export declare const keepCallerContextInDaemon: typeof bindSpanContext;

package/dist/portal/session/daemon-answers.js

@@ -0,0 +1,20 @@
+import { log } from '../../log.js';
+import { bindSpanContext } from '../../trace.js';
+/**
+ * What the daemon answers when the rules that decide a verdict ask it for something.
+ *
+ * The rules are meant to be liftable out of the daemon on their own, so they never go looking for
+ * the log or the tracer -- both are handed to them, on the session object they are already given.
+ * See `events/engine-host.ts` for why, and for what happens when nobody answers.
+ *
+ * They live here rather than inside the session class because neither is anything to do with a
+ * particular browser tab. They are the daemon's own identity, and every session gives the same
+ * answer.
+ */
+/** Write something down where the daemon writes everything else. */
+export const noteToDaemonLog = log;
+/**
+ * Keep a callback belonging to the call that created it, so a re-check scheduled for later still
+ * traces back to the wait that asked for it instead of looking like work starting from nowhere.
+ */
+export const keepCallerContextInDaemon = bindSpanContext;

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

@@ -0,0 +1,147 @@
+/**
+ * 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 '../../../command/cli/ports/resolve/cli-port.js';
+import { looksLikeDevServer } from '../../../memory/recall/looks-like-dev-server.js';
+/**
+ * Give up fast, but do not call giving up an absence.
+ *
+ * This budget suits Vite handing back a static index.html. It does NOT suit an SSR framework
+ * compiling a route on the first request: Nuxt and Next routinely take seconds cold, and treating
+ * that as "nothing is there" told a reporter to start a dev server that was already serving 57KB of
+ * HTML — advice that would have hit their dev lock with a second `nuxt dev`.
+ *
+ * So the budget stays short and the TIMEOUT changed meaning instead. See PortState.
+ */
+const HTTP_PROBE_TIMEOUT_MS = 400;
+/**
+ * What the probe actually learned about a port. Three states, because two cannot express this.
+ *
+ * A bare TCP connect is not enough (macOS AirPlay Receiver holds 5000 on every Mac and would read as
+ * the user's dev server), and a document check alone is not enough either (a compiling SSR server
+ * reads as absent). The thing in between — accepted the connection, said nothing in time — is a
+ * listener we cannot classify, and reporting that honestly is the point.
+ */
+export const PortState = {
+    /** Nothing accepted a connection on either loopback family. */
+    CLOSED: 'closed',
+    /** Accepted a connection, then answered nothing within the budget. Something IS there. */
+    CONNECTED_NO_ANSWER: 'connected-no-answer',
+    /** Answered with a document: a dev server serving an app. */
+    SERVES_DOCUMENT: 'serves-document',
+};
+/** The probe's answer for one port, however it was obtained. */
+export function classifyPort(port, probe) {
+    return probe(port).catch(() => PortState.CLOSED);
+}
+/**
+ * `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).
+ */
+/**
+ * Both loopback addresses, BY ADDRESS — never by the name `localhost`.
+ *
+ * A dev server started with `--host` binds the wildcards `0.0.0.0` and `[::]` rather than the
+ * loopbacks, and a wildcard bind serves only the family it belongs to. Asking for `localhost` hands
+ * the choice of family to the resolver: on Windows it prefers `::1`, so a `0.0.0.0` listener is
+ * invisible and the scan reports "nothing is listening" about a dev server that is plainly running.
+ * Reported from the field on exactly that setup.
+ *
+ * `[::1]` is also how a `[::]` bind is reached, and on most stacks a `[::]` bind additionally
+ * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
+ */
+export const PROBE_HOSTS = ['127.0.0.1', '::1'];
+/**
+ * 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 probeState(port, host) {
+    return new Promise((resolve) => {
+        // Whether the SOCKET came up is tracked separately from whether a response did, because that is
+        // the whole difference between "nothing is there" and "something is there and still compiling".
+        let connected = false;
+        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 ? PortState.SERVES_DOCUMENT : PortState.CLOSED);
+        });
+        req.once('socket', (socket) => {
+            socket.once('connect', () => {
+                connected = true;
+            });
+        });
+        req.once('timeout', () => {
+            req.destroy();
+            resolve(connected ? PortState.CONNECTED_NO_ANSWER : PortState.CLOSED);
+        });
+        req.once('error', () => resolve(PortState.CLOSED));
+        req.end();
+    });
+}
+/** Kept for callers that only need the yes/no. A slow listener is NOT a dev server, but it is not absent. */
+function servesDocument(port, host) {
+    return probeState(port, host).then((state) => state === PortState.SERVES_DOCUMENT);
+}
+/**
+ * Is anything serving a document on this port, on EITHER loopback family?
+ *
+ * "Either" and not "both": one answer is enough, and requiring both would make the wildcard binds
+ * this exists to see fail the check again. A family that errors (no IPv6 stack at all) is an
+ * absence, never a rejection — a diagnostic must not throw at the tool it is diagnosing.
+ */
+export async function anyFamilyServes(port, probe = servesDocument) {
+    const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => false)));
+    return answers.some((up) => up);
+}
+/**
+ * Every candidate port, split by what the probe could actually establish.
+ *
+ * `slow` is the set that accepted a connection and then said nothing inside the budget. Those ports
+ * are NOT dev servers as far as this check knows, and they are emphatically not absent — an SSR
+ * framework compiling its first route lands here every time. Reported separately so the diagnosis
+ * can stop telling people to start a server that is already running.
+ */
+export async function probeDevServerStates(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyState(p)) {
+    const states = await Promise.all(ports.map((p) => classifyPort(p, probe).then((state) => ({ port: p, state }))));
+    const pick = (want) => states
+        .filter((s) => s.state === want)
+        .map((s) => s.port)
+        .sort((a, b) => a - b);
+    return { serving: pick(PortState.SERVES_DOCUMENT), slow: pick(PortState.CONNECTED_NO_ANSWER) };
+}
+/**
+ * The strongest state either loopback family reports.
+ *
+ * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
+ * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
+ * three states.
+ */
+async function anyFamilyState(port, probe = probeState) {
+    const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => PortState.CLOSED)));
+    if (answers.includes(PortState.SERVES_DOCUMENT))
+        return PortState.SERVES_DOCUMENT;
+    if (answers.includes(PortState.CONNECTED_NO_ANSWER))
+        return PortState.CONNECTED_NO_ANSWER;
+    return PortState.CLOSED;
+}
+/** Every candidate port serving a document, in ascending order. Never rejects. */
+export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyServes(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/portal/session/facts/handshake-facts.d.ts

@@ -0,0 +1,56 @@
+import type { ChannelId } from '@reticlehq/core';
+/**
+ * What the page told us about itself when it connected.
+ *
+ * Six facts, all arriving in one HELLO, all read much later by code that has no idea a handshake
+ * happened. They lived as six loose fields on `Session` with a paragraph of documentation each,
+ * which is how a session class becomes a thousand lines of things that are not sessions.
+ *
+ * Gathering them is not filing. Every one of these answers the same question — *what is this
+ * implementation able to do, in its own words* — and the protocol treats that question as the
+ * first assertion an implementation makes. What follows from it is a rule: an assertion the page
+ * cannot answer must be refused BEFORE an action is spent on it, not answered with an empty
+ * result that reads exactly like the thing not being there.
+ *
+ * **`undefined` means "an SDK too old to say", and never "no".** That distinction is the whole
+ * reason these are optional rather than defaulted. A page that predates a field is a page we know
+ * nothing about on that axis, and treating silence as a negative would refuse every claim from
+ * every older page in the field — which is a worse failure than the one being prevented, because
+ * it looks like the tool being broken rather than the tool being careful.
+ */
+export interface HandshakeFacts {
+    /** Set when the page's SDK version differs from the daemon's. See version-skew.ts. */
+    versionSkew?: string;
+    /** SDK version from HELLO; kept so a remedy can check it applies. See body-capture-remedy.ts. */
+    sdkVersion?: string | undefined;
+    /** Whether the page records network bodies. */
+    captureBodies?: boolean | undefined;
+    /**
+     * The channels this build declared it can observe.
+     *
+     * The protocol's first assertion, and the input that decides whether a claim is answerable at
+     * all. See `declaredChannels()` in the browser SDK for what makes the list truthful.
+     */
+    channels?: readonly ChannelId[] | undefined;
+    /**
+     * The commands this build will answer.
+     *
+     * Read before a command is sent, so one the page does not serve is refused rather than waited
+     * out. See `Session.command`, and the same `undefined` rule as `channels`: silence is an SDK
+     * too old to say, never an empty list.
+     */
+    commands?: readonly string[] | undefined;
+    /**
+     * Whether this build stamps `data-reticle-source`, when the build plugin said.
+     *
+     * `false` separates "the project turned it off" from "nothing provides one".
+     */
+    sourceMapping?: boolean | undefined;
+    /**
+     * Extra key names this app declared sensitive via `connect({ redact: { keys } })`.
+     *
+     * Held so the DRIVEN path can redact them too — a request body the daemon captures from the
+     * network stack never passes through the SDK, so nothing else would.
+     */
+    readonly redactKeys: readonly string[];
+}

package/dist/portal/session/facts/handshake-facts.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,60 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
+/**
+ * The two things a session learns by watching its own event stream, as opposed to storing.
+ *
+ * Both are LEVELS derived from a stream, and both have to outlive the ring buffer — which is what
+ * separates them from the buffer's job and earns them their own unit:
+ *
+ *   ambient    — which regions of the page move on their own (chat, tickers, live counters). Used by
+ *                the settle oracle to ignore background motion, so an action isn't held open forever
+ *                by churn it did not cause.
+ *   blindSpots — how much of the page the SDK cannot observe (cross-origin frames, closed shadow
+ *                roots). The SDK reports these only when the count CHANGES, so a page that mounts
+ *                two frames at load announces them once and is silent forever after. Anything that
+ *                infers coverage from a window of events therefore sees nothing and concludes the
+ *                page was fully observed — a positive claim to have seen what we cannot see. Holding
+ *                the level here makes coverage something to ask rather than infer.
+ */
+export declare class ObservedState {
+    #private;
+    /** Fold one already-attributed event into the learned state. */
+    observe(event: ReticleEvent): void;
+    /**
+     * Learned ambient-churn counts — seeded history PLUS this session — for the settle oracle, which
+     * wants the sharpest available picture of what moves on its own.
+     */
+    ambientCounts(): AmbientCounts;
+    /**
+     * ONLY what this session observed — the correct input to persistence.
+     *
+     * Teardown accumulates by adding the session's counts onto the file it loaded. When the session's
+     * counts still contained the seeded ones, that addition wrote `2 x persisted + own` every run, so
+     * the map doubled per session: the file committed in this repo had reached ~9.1e23 (about 2^80,
+     * i.e. ~80 sessions of doubling). Keeping the seed separate makes the accumulation what it always
+     * claimed to be — history plus what is new.
+     */
+    ownAmbientCounts(): AmbientCounts;
+    /**
+     * Seed from the persisted per-app map so the picture sharpens across sessions.
+     * In-session counts win: they describe this page as it is now.
+     */
+    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.
+     *
+     * Every other blind spot is reported BY the SDK, which cannot report this one: the events were
+     * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
+     * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
+     */
+    noteRateLimited(dropped: number): void;
+    blindSpots(): Readonly<Record<string, number>>;
+}

package/dist/portal/session/facts/observed-state.js

@@ -0,0 +1,121 @@
+import { BlindSpotKind, EventType } from '@reticlehq/core';
+import { ambientKeyOf } from '@reticlehq/engine/window/ambient.js';
+/**
+ * The two things a session learns by watching its own event stream, as opposed to storing.
+ *
+ * Both are LEVELS derived from a stream, and both have to outlive the ring buffer — which is what
+ * separates them from the buffer's job and earns them their own unit:
+ *
+ *   ambient    — which regions of the page move on their own (chat, tickers, live counters). Used by
+ *                the settle oracle to ignore background motion, so an action isn't held open forever
+ *                by churn it did not cause.
+ *   blindSpots — how much of the page the SDK cannot observe (cross-origin frames, closed shadow
+ *                roots). The SDK reports these only when the count CHANGES, so a page that mounts
+ *                two frames at load announces them once and is silent forever after. Anything that
+ *                infers coverage from a window of events therefore sees nothing and concludes the
+ *                page was fully observed — a positive claim to have seen what we cannot see. Holding
+ *                the level here makes coverage something to ask rather than infer.
+ */
+export class ObservedState {
+    /** What THIS session observed. Never contains seeded history — see seedAmbient. */
+    #ownAmbient = {};
+    /** What previous sessions learned, kept separate so it is never re-persisted as if newly seen. */
+    #seededAmbient = {};
+    #blindSpots = {};
+    /** Fold one already-attributed event into the learned state. */
+    observe(event) {
+        // Only UNATTRIBUTED events count as ambient: an event caused by an action is the action's work,
+        // and learning it as background would teach the settle oracle to ignore real effects.
+        if (event.actionId === undefined) {
+            const key = ambientKeyOf(event);
+            if (key !== undefined)
+                this.#ownAmbient[key] = (this.#ownAmbient[key] ?? 0) + 1;
+        }
+        if (event.type === EventType.BLIND_SPOT) {
+            const kind = event.data['kind'];
+            const count = event.data['count'];
+            if ('string' === typeof kind && 'number' === typeof count)
+                this.#blindSpots[kind] = count;
+        }
+    }
+    /**
+     * Learned ambient-churn counts — seeded history PLUS this session — for the settle oracle, which
+     * wants the sharpest available picture of what moves on its own.
+     */
+    ambientCounts() {
+        const merged = { ...this.#seededAmbient };
+        for (const [key, count] of Object.entries(this.#ownAmbient)) {
+            merged[key] = (merged[key] ?? 0) + count;
+        }
+        return merged;
+    }
+    /**
+     * ONLY what this session observed — the correct input to persistence.
+     *
+     * Teardown accumulates by adding the session's counts onto the file it loaded. When the session's
+     * counts still contained the seeded ones, that addition wrote `2 x persisted + own` every run, so
+     * the map doubled per session: the file committed in this repo had reached ~9.1e23 (about 2^80,
+     * i.e. ~80 sessions of doubling). Keeping the seed separate makes the accumulation what it always
+     * claimed to be — history plus what is new.
+     */
+    ownAmbientCounts() {
+        return this.#ownAmbient;
+    }
+    /**
+     * Seed from the persisted per-app map so the picture sharpens across sessions.
+     * In-session counts win: they describe this page as it is now.
+     */
+    seedAmbient(counts) {
+        this.#seededAmbient = { ...counts };
+    }
+    /** Latest reported count per blind-spot kind, for the whole session. */
+    /**
+     * Refs the agent has driven, for the exercised/untouched split `reticle_coverage` reports.
+     *
+     * Kept here beside the blind-spot counts because both are per-session observed facts that must
+     * SURVIVE buffer eviction. Deriving "what did I touch" from the event buffer instead would mean an
+     * action fifty steps ago silently stops counting, so "untouched" would quietly come to mean
+     * "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.
+     *
+     * Every other blind spot is reported BY the SDK, which cannot report this one: the events were
+     * dropped before they reached the observer. Recording it here keeps the honesty contract intact —
+     * a verdict over a sampled window says `coverage: partial` rather than implying it saw everything.
+     */
+    noteRateLimited(dropped) {
+        this.#blindSpots[BlindSpotKind.RATE_LIMITED] = dropped;
+    }
+    blindSpots() {
+        return this.#blindSpots;
+    }
+}

package/dist/portal/session/facts/session-replaced.d.ts

@@ -0,0 +1,43 @@
+/**
+ * "The page reconnected under the same id" — one sentence, and one way to recognise it.
+ *
+ * A server-rendered app reconnects its SDK on EVERY full page load, so on an MPA this is the normal
+ * consequence of following a link, not a fault. The bridge rejects any command that was in flight
+ * when it happens, and a caller that reads that rejection as fatal cannot walk past the first link:
+ * reported against `reticle_verify action=crawl`, which died on link one of every Django, Rails and
+ * plain-HTML app.
+ *
+ * The prefix lives here so the producer and the predicate cannot drift apart. This repo has already
+ * shipped that exact bug twice — a remedy string restated in a second place, and a redaction name
+ * derived two different ways — and both times the halves disagreed silently.
+ */
+/** The start of the reason the bridge hands to commands displaced by a reconnect. */
+export declare const SESSION_REPLACED_PREFIX = "session replaced by a newer connection";
+/** Build the full reason. The only place this sentence is written. */
+export declare function sessionReplacedReason(id: string, url: string): string;
+/**
+ * Was this failure a reconnect rather than a fault?
+ *
+ * Accepts the thrown value rather than a string so every call site can hand over whatever it caught
+ * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
+ */
+export declare function isSessionReplacedError(error: unknown): boolean;
+/**
+ * The reason every command still in flight is rejected with when the socket under it closes.
+ *
+ * A full-document navigation closes that socket, so on an MPA — or on any click that loads a new
+ * page — this arrives for the exact command that CAUSED it, and the successor is still connecting.
+ * `SessionManager.remove` cannot tell those two apart at the moment it runs: it is called from the
+ * socket's own close handler, the tombstone it writes is what a successor is later matched against,
+ * and nothing has arrived yet. So the rejection stays a plain transport failure, as
+ * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
+ */
+export declare const SESSION_DISCONNECTED_REASON = "session disconnected";
+/**
+ * Is this failure the page's transport going away, rather than an answer from the page?
+ *
+ * True for both shapes the same event takes: the reconnect that claimed the id back, and the close
+ * that landed before any successor did. A caller holding a budget can follow either; a caller that
+ * cannot must say it stopped watching, never that the app failed.
+ */
+export declare function isDocumentGoneError(error: unknown): boolean;

package/dist/portal/session/facts/session-replaced.js

@@ -0,0 +1,51 @@
+/**
+ * "The page reconnected under the same id" — one sentence, and one way to recognise it.
+ *
+ * A server-rendered app reconnects its SDK on EVERY full page load, so on an MPA this is the normal
+ * consequence of following a link, not a fault. The bridge rejects any command that was in flight
+ * when it happens, and a caller that reads that rejection as fatal cannot walk past the first link:
+ * reported against `reticle_verify action=crawl`, which died on link one of every Django, Rails and
+ * plain-HTML app.
+ *
+ * The prefix lives here so the producer and the predicate cannot drift apart. This repo has already
+ * shipped that exact bug twice — a remedy string restated in a second place, and a redaction name
+ * derived two different ways — and both times the halves disagreed silently.
+ */
+/** The start of the reason the bridge hands to commands displaced by a reconnect. */
+export const SESSION_REPLACED_PREFIX = 'session replaced by a newer connection';
+/** Build the full reason. The only place this sentence is written. */
+export function sessionReplacedReason(id, url) {
+    return `${SESSION_REPLACED_PREFIX} claiming the same id (${id}) from ${url}`;
+}
+/**
+ * Was this failure a reconnect rather than a fault?
+ *
+ * Accepts the thrown value rather than a string so every call site can hand over whatever it caught
+ * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
+ */
+export function isSessionReplacedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes(SESSION_REPLACED_PREFIX);
+}
+/**
+ * The reason every command still in flight is rejected with when the socket under it closes.
+ *
+ * A full-document navigation closes that socket, so on an MPA — or on any click that loads a new
+ * page — this arrives for the exact command that CAUSED it, and the successor is still connecting.
+ * `SessionManager.remove` cannot tell those two apart at the moment it runs: it is called from the
+ * socket's own close handler, the tombstone it writes is what a successor is later matched against,
+ * and nothing has arrived yet. So the rejection stays a plain transport failure, as
+ * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
+ */
+export const SESSION_DISCONNECTED_REASON = 'session disconnected';
+/**
+ * Is this failure the page's transport going away, rather than an answer from the page?
+ *
+ * True for both shapes the same event takes: the reconnect that claimed the id back, and the close
+ * that landed before any successor did. A caller holding a budget can follow either; a caller that
+ * cannot must say it stopped watching, never that the app failed.
+ */
+export function isDocumentGoneError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return isSessionReplacedError(error) || message === SESSION_DISCONNECTED_REASON;
+}

package/dist/portal/session/live-control-tools.d.ts

@@ -0,0 +1,15 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * Live-control agent tools: the agent's side of the human-in-the-loop control surface.
+ *
+ * - reticle_end_session: terminal stop. Sets state `ended` and syncs the panel (PRESENTER) with an
+ * optional summary. Idempotent — ending an already-ended session is a safe no-op.
+ * - reticle_resume: clears a human pause. Sets state `active` and syncs the panel.
+ * - reticle_messages: explicit poll — drains and returns the queued human notes.
+ *
+ * State changes go through `setState`, which echoes the state to the panel in a SINGLE PRESENTER
+ * push (optionally carrying human-facing text, e.g. the end summary) — a transition never emits two
+ * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
+ * elapsed clock at enqueue time.
+ */
+export declare const LIVE_CONTROL_TOOLS: ToolDef[];