@reticlehq/server 3.1.0 → 3.3.0

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

@@ -23,7 +23,7 @@ import { daemonsServingProjectElsewhere, splitBrainNote } from '../../command/da
 import { stallUptime } from './stall-clock.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
-import { WS_CLOSE_REASON } from '../bridge/bridge.js';
+import { isAuthRefusalReason } from '../bridge/auth-failure-reason.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
@@ -208,7 +208,7 @@ export function startNoSessionWatch(options) {
     /**
      * Is a refusal on the pairing token the CURRENT state of the bridge?
      *
-     * The bridge records the refusal (`noteClosure(WS_CLOSE_REASON.AUTH_FAILED)`) and nothing read it
+     * The bridge records the refusal (the sentence it closed the socket with) and nothing read it
      * as a DIAGNOSIS. It is the one fact that proves an app is running and instrumented: only an SDK
      * dials the bridge, so a refused hello means the wiring works and this daemon would not serve it.
      *
@@ -223,7 +223,7 @@ export function startNoSessionWatch(options) {
      * recorded no refusal, which falls through to the behaviour that was there before -- the safe
      * direction for a fact whose job is to SUPPRESS advice rather than to add any.
      */
-    const lastCloseWasAuthFailure = () => options.sessions.lastClosure?.()?.reason === WS_CLOSE_REASON.AUTH_FAILED &&
+    const lastCloseWasAuthFailure = () => isAuthRefusalReason(options.sessions.lastClosure?.()?.reason) &&
         true !== options.sessions.connectedSinceLastClosure?.();
     const nextAction = (scope) => {
         const split = splitBrain();
@@ -307,19 +307,23 @@ export function startNoSessionWatch(options) {
             ...(0 === siblingListeners.length ? {} : { siblingListeners }),
         });
     };
-    options.sessions.setNoSessionHint(() => {
+    // The lead, then the literal command, then the differential. Both renderings consume the same
+    // scope facts so a discovered workspace config cannot become an `init` recommendation below it,
+    // and both come from ONE `explain()` call so they cannot describe different branches.
+    const rendered = () => {
         const scope = projectScopeFacts();
-        return (explain().message +
-            // Prose for the human, then the literal command for the agent. Both consume the same scope
-            // facts so a discovered workspace config cannot become an `init` recommendation below it.
-            ` ${renderNextAction(nextAction(scope))}` +
-            (attachFailure ?? ''));
-    });
+        const { message, detail } = explain();
+        const lead = `${message} ${renderNextAction(nextAction(scope))}${attachFailure ?? ''}`;
+        return { lead, full: undefined === detail ? lead : `${lead} ${detail}` };
+    };
+    options.sessions.setNoSessionHint(() => rendered().full);
+    options.sessions.setNoSessionLead(() => rendered().lead);
     options.sessions.setNoSessionReason(() => explain().reason);
     return () => {
         clearInterval(timer);
         options.sessions.setConnectionRecorder(undefined);
         options.sessions.setNoSessionHint(undefined);
+        options.sessions.setNoSessionLead(undefined);
         options.sessions.setNoSessionReason(undefined);
         options.sessions.setNoSessionNextAction(undefined);
     };

package/dist/portal/session/presence/attachment-history.d.ts

@@ -15,11 +15,22 @@
  * The clock is injected, per the repo rule: this is arithmetic over timestamps, and a test that
  * needs to wait four seconds to check a four-second gap is a test nobody runs.
  */
-/** What an agent needs to know about the continuity of one session. */
+/**
+ * What an agent needs to know about the continuity of one session.
+ *
+ * Every field here measures the SDK-to-daemon LINK. None of them measures the app: the origin the
+ * page was served from can stop answering entirely without any of these moving, because the socket
+ * that reports them is between the daemon and a document the browser is already holding. Reported
+ * as a false read of app health in #938, where a tab whose dev server was dead carried `outages: 0`
+ * and `connectedSinceMs: 11min` and was taken for a healthy app.
+ */
 interface Attachment {
     /** How long THIS attachment has lasted. Resets on reconnect — it is not the session's lifetime. */
     connectedSinceMs: number;
-    /** How many times this session dropped and came back. Zero means it never left. */
+    /**
+     * How many times this session dropped and came back. Zero means the LINK never dropped; it does
+     * not mean the app behind it is alive.
+     */
     outages: number;
     /** The most recent gap, when there has been one. */
     lastOutage?: {

package/dist/portal/session/rebind.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export declare const REBINDABLE_COMMANDS: ReadonlySet<string>;
+/**
+ * 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.
+ */
+export declare const MAX_SUCCESSOR_HOPS = 32;

package/dist/portal/session/rebind.js

@@ -0,0 +1,38 @@
+/**
+ * Whether a command in flight may be re-issued against the connection that REPLACED this session,
+ * and how far a chain of replacements is worth walking.
+ *
+ * One question, so one file. It left `session.ts` when that file crossed the thousand-line cap on a
+ * merge: two branches had each grown it by a few lines and the sum went over, which is the moment
+ * the rule says to split rather than to raise the number. These two constants and the reasoning
+ * behind them are the most self-contained thing in there — `session.ts` reads them twice and owns
+ * nothing else about rebinding.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+/**
+ * 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.
+ */
+export const REBINDABLE_COMMANDS = new Set([
+    ReticleCommand.SNAPSHOT,
+    ReticleCommand.QUERY,
+    ReticleCommand.MATCH,
+    ReticleCommand.INSPECT,
+    ReticleCommand.STATE_READ,
+    ReticleCommand.STORAGE_READ,
+    ReticleCommand.CAPABILITIES,
+    ReticleCommand.ANIMATIONS,
+]);
+/**
+ * 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.
+ */
+export const MAX_SUCCESSOR_HOPS = 32;

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

@@ -38,6 +38,22 @@ export interface SessionHealth {
      * on `reticle_sessions` or `reticle_lease` is not on the surface it reads every call.
      */
     versionSkew?: string;
+    /**
+     * The session's event ledger, once it has grown enough to be worth a reader's attention.
+     *
+     * Present only past `LEDGER_NOTICE_FRACTION` of the cap, so a healthy session costs nothing --
+     * the same rule `pendingNavigationMs` follows. A ledger below that is doing its job quietly.
+     *
+     * It is here because nothing reported it. A repeating uncaught error wrote one session's ledger
+     * until the disk was full; neither the daemon nor `doctor` nor any
+     * health counter said a word, and the user found out when the disk was full (#986). A cap bounds
+     * the damage but does not make the writing visible, and this block is the surface an agent
+     * already reads on every act and assert.
+     */
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
 }
 /**
  * How long a request may be in flight before it is worth reporting on session health.
@@ -84,6 +100,18 @@ interface BufferEnvelope {
  * so a clean/empty result there is trustworthy and costs zero tokens.
  */
 export declare function bufferEnvelope(session: HealthSubject): BufferEnvelope;
+/**
+ * The session registered under `session.id` NOW, for describing a tab after a call that may have
+ * replaced its document. A reload or full navigation registers a new Session under the same id, and
+ * the object a handler resolved first is the page that unloaded; it reported itself hidden on the way
+ * out, so its health said "throttled" about a tab that was fine. Optional-called because test doubles
+ * are partial registries.
+ */
+export declare function currentOf<S extends {
+    id: string;
+}>(registry: {
+    get?: (id: string) => S | undefined;
+}, session: S): S;
 /** The `session` (and optional throttled `warning`) block spliced onto act/assert results. */
 interface HealthEnvelope {
     session?: SessionHealth;
@@ -142,4 +170,37 @@ interface HealthReport {
  * keep its previous value instead of silently flipping a session to "visible" on a partial report.
  */
 export declare function readHealthEvent(data: Record<string, unknown>): HealthReport;
+/**
+ * The ledger block for the health payload, or nothing when it is not worth saying.
+ *
+ * Absent below `LEDGER_NOTICE_FRACTION` of the cap, and absent when the size has not been measured
+ * yet -- a reader must be able to tell "not measured" from "empty", and a zero reported before the
+ * first append would be a claim rather than a reading.
+ */
+export declare function ledgerNotice(ledger: {
+    bytes: number;
+    capBytes: number;
+} | undefined): {
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
+};
+/**
+ * Every health field that is present only when it means something.
+ *
+ * One place answers "which optional facts belong on the health block", so a session does not have
+ * to know the rule for each. A healthy session gets an empty object back and its health block
+ * carries only the fields that are always true.
+ */
+export declare function healthNotices(events: readonly ReticleEvent[], elapsed: number, ledger: {
+    bytes: number;
+    capBytes: number;
+} | undefined): {
+    pendingNavigationMs?: number;
+    ledger?: {
+        bytes: number;
+        capBytes: number;
+    };
+};
 export {};

package/dist/portal/session/session-health.js

@@ -1,4 +1,4 @@
-import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, THROTTLED_WARNING, } from '@reticlehq/core';
+import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, SESSION_HEALTH, THROTTLED_WARNING, } from '@reticlehq/core';
 /**
  * How long a request may be in flight before it is worth reporting on session health.
  *
@@ -68,6 +68,16 @@ export function bufferEnvelope(session) {
         return {};
     return { buffer: { held: total, dropped, note: BUFFER_EVICTION_WARNING } };
 }
+/**
+ * The session registered under `session.id` NOW, for describing a tab after a call that may have
+ * replaced its document. A reload or full navigation registers a new Session under the same id, and
+ * the object a handler resolved first is the page that unloaded; it reported itself hidden on the way
+ * out, so its health said "throttled" about a tab that was fine. Optional-called because test doubles
+ * are partial registries.
+ */
+export function currentOf(registry, session) {
+    return registry.get?.(session.id) ?? session;
+}
 /**
  * Build the health envelope for a tool result. When the session is **nominal** (focused, not
  * throttled, no escape-hatch recommendation) the block is OMITTED entirely — a healthy session
@@ -152,3 +162,32 @@ export function readHealthEvent(data) {
         brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
     };
 }
+/**
+ * The ledger block for the health payload, or nothing when it is not worth saying.
+ *
+ * Absent below `LEDGER_NOTICE_FRACTION` of the cap, and absent when the size has not been measured
+ * yet -- a reader must be able to tell "not measured" from "empty", and a zero reported before the
+ * first append would be a claim rather than a reading.
+ */
+export function ledgerNotice(ledger) {
+    if (ledger === undefined || 0 >= ledger.capBytes)
+        return {};
+    const fraction = ledger.bytes / ledger.capBytes;
+    return fraction < SESSION_HEALTH.LEDGER_NOTICE_FRACTION ? {} : { ledger };
+}
+/**
+ * Every health field that is present only when it means something.
+ *
+ * One place answers "which optional facts belong on the health block", so a session does not have
+ * to know the rule for each. A healthy session gets an empty object back and its health block
+ * carries only the fields that are always true.
+ */
+export function healthNotices(events, elapsed, ledger) {
+    // From event t=0, not a cursor: a wedge that began before the current action is exactly the case
+    // a per-window reading cannot see, and is the one both reporters hit.
+    const stuck = pendingNavigationMs(events, elapsed);
+    return {
+        ...(stuck === undefined ? {} : { pendingNavigationMs: stuck }),
+        ...ledgerNotice(ledger),
+    };
+}

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

@@ -45,6 +45,12 @@ export interface SessionInfo {
      * A tab that dropped for four seconds and came back is indistinguishable from one that never left
      * (#117), and that difference decides whether a verdict over the window can be trusted. Attached
      * by `SessionManager.list()`, which is the layer that sees every connect and disconnect.
+     *
+     * Scoped to the SDK-to-daemon LINK, and the names do not say so on their own. A zombie tab whose
+     * dev server had died reported `outages: 0` and `connectedSinceMs: 11min`, and both were correct:
+     * the page's socket was still attached to the daemon. Read as app health, they said the app was
+     * up while nothing was listening on the port (#938). The describe() on the `reticle_sessions`
+     * output schema carries that caveat, because that is where an agent reads it.
      */
     attachment?: {
         connectedSinceMs: number;

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

@@ -22,6 +22,15 @@ export declare class SessionManager {
     add(session: Session): Session | undefined;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
+    /**
+     * Did this id belong to a session that has since disconnected?
+     *
+     * `resolve` answers a departed id with its live SUCCESSOR, which is what keeps a reload working
+     * for everything that observes. A caller that is about to do something DESTRUCTIVE needs the
+     * other answer: whether the thing it named is still there. Ending a session it did not name is
+     * not a recoverable mistake (#983).
+     */
+    departed(sessionId: string): SessionIdentity | undefined;
     list(): SessionInfo[];
     /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
     attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
@@ -30,6 +39,10 @@ export declare class SessionManager {
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    /** Wire the short rendering. Registered from the same `explainNoSession` call as the hint. */
+    setNoSessionLead(lead: (() => string | undefined) | undefined): void;
+    /** The lead and the next action, for a surface a person reads. */
+    noSessionLead(): string | undefined;
     /**
      * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
      *

package/dist/portal/session/session-manager.js

@@ -3,7 +3,8 @@ import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
-import { pickDocumentSuccessor } from './session-successor.js';
+import { openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
+import { SESSION_DISCONNECTED_REASON } from './facts/session-replaced.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
     if (url === undefined)
@@ -86,6 +87,8 @@ export class SessionManager {
      * id forgets its tombstone — the live session is the answer then.
      */
     #tombstones = new Map();
+    /** The tabs already open when each tombstoned session departed: siblings, never its successor. */
+    #siblingsAtDeparture = new Map();
     /**
      * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
      * without passing its own scope, this is applied — so auto-selection is project-scoped by default
@@ -127,6 +130,7 @@ export class SessionManager {
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
         this.#tombstones.delete(session.id);
+        this.#siblingsAtDeparture.delete(session.id);
         return previous;
     }
     /**
@@ -143,7 +147,7 @@ export class SessionManager {
     remove(session) {
         if (this.#sessions.get(session.id) !== session)
             return false;
-        session.rejectAll('session disconnected');
+        session.rejectAll(SESSION_DISCONNECTED_REASON);
         forgetDrivenRedactionKeys(session.id);
         // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
         // the reconnect is exactly where that matters.
@@ -157,6 +161,9 @@ export class SessionManager {
             return;
         if (this.#tombstones.has(session.id))
             this.#tombstones.delete(session.id);
+        this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
+            .filter((s) => s !== session && openedBeforeDeparture(s, session))
+            .map((s) => s.id)));
         this.#tombstones.set(session.id, {
             id: session.id,
             url: session.url,
@@ -167,13 +174,17 @@ export class SessionManager {
             if (oldest === undefined)
                 break;
             this.#tombstones.delete(oldest);
+            this.#siblingsAtDeparture.delete(oldest);
         }
     }
     #successorOf(sessionId) {
         const departed = this.#tombstones.get(sessionId);
         if (departed === undefined)
             return undefined;
-        const picked = pickDocumentSuccessor(this.all().map((s) => ({
+        const siblings = this.#siblingsAtDeparture.get(sessionId);
+        const picked = pickDocumentSuccessor(this.all()
+            .filter((s) => true !== siblings?.has(s.id))
+            .map((s) => ({
             id: s.id,
             url: s.url,
             ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
@@ -185,6 +196,17 @@ export class SessionManager {
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
+    /**
+     * Did this id belong to a session that has since disconnected?
+     *
+     * `resolve` answers a departed id with its live SUCCESSOR, which is what keeps a reload working
+     * for everything that observes. A caller that is about to do something DESTRUCTIVE needs the
+     * other answer: whether the thing it named is still there. Ending a session it did not name is
+     * not a recoverable mistake (#983).
+     */
+    departed(sessionId) {
+        return this.#tombstones.get(sessionId);
+    }
     list() {
         return [...this.#sessions.values()].map((s) => {
             const info = s.info();
@@ -246,10 +268,27 @@ export class SessionManager {
      * different branches. See no-session-watch.ts.
      */
     #noSessionReason;
+    /**
+     * The same diagnosis with the differential left off: the lead and the next action, nothing else.
+     *
+     * Two renderings because there are two readers, and only one of them can spend the words. An
+     * agent about to burn a drive on a guess wants the ranked causes, the port-scan caveat and the
+     * lease offer. The person watching `reticle init` fail wants to know what is wrong and what to
+     * type, and was instead handed roughly five hundred words in one paragraph.
+     */
+    #noSessionLead;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint) {
         this.#noSessionHint = hint;
     }
+    /** Wire the short rendering. Registered from the same `explainNoSession` call as the hint. */
+    setNoSessionLead(lead) {
+        this.#noSessionLead = lead;
+    }
+    /** The lead and the next action, for a surface a person reads. */
+    noSessionLead() {
+        return this.#noSessionLead?.();
+    }
     /**
      * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
      *

package/dist/portal/session/session-successor.d.ts

@@ -26,6 +26,17 @@ export interface SuccessorClock {
  * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
  */
 export declare function pickDocumentSuccessor(live: readonly SessionIdentity[], departed: SessionIdentity): SessionIdentity | undefined;
+/**
+ * Whether `candidate` was already connected before the agent last drove `departed`.
+ *
+ * Such a tab is a SIBLING, never the document the departed tab's navigation produced: that document
+ * can only have connected after the command that caused it. Without this, two tabs of one project
+ * were resolved as "unique at the origin" in the gap before the departed tab came back, and a verdict
+ * for tab A was graded on tab B (#983, reproduced by driving). Measured as ages rather than instants,
+ * so both sides read the same clock at the same moment and the comparison does not drift while a
+ * caller polls.
+ */
+export declare function openedBeforeDeparture(candidate: Pick<Session, 'staleMs'>, departed: Pick<Session, 'agentIdleMs'>): boolean;
 export interface SuccessorRegistry {
     get(id: string): Session | undefined;
     all(): readonly Session[];

package/dist/portal/session/session-successor.js

@@ -100,6 +100,19 @@ export function pickDocumentSuccessor(live, departed) {
         return undefined;
     return others[0];
 }
+/**
+ * Whether `candidate` was already connected before the agent last drove `departed`.
+ *
+ * Such a tab is a SIBLING, never the document the departed tab's navigation produced: that document
+ * can only have connected after the command that caused it. Without this, two tabs of one project
+ * were resolved as "unique at the origin" in the gap before the departed tab came back, and a verdict
+ * for tab A was graded on tab B (#983, reproduced by driving). Measured as ages rather than instants,
+ * so both sides read the same clock at the same moment and the comparison does not drift while a
+ * caller polls.
+ */
+export function openedBeforeDeparture(candidate, departed) {
+    return candidate.staleMs() > departed.agentIdleMs();
+}
 /**
  * Poll until a successor of `departed` is live, or the budget runs out. Null on timeout — never
  * throws, because failing to follow is a legitimate `observation_lost`, not an error.
@@ -115,7 +128,7 @@ export async function awaitDocumentSuccessor(sessions, departed, timeoutMs, cloc
         // out of the pick, or same-id-first would keep returning the page that just unloaded.
         const picked = pickDocumentSuccessor(sessions
             .all()
-            .filter((s) => s !== departed)
+            .filter((s) => s !== departed && !openedBeforeDeparture(s, departed))
             .map(identityOf), departedIdentity);
         if (picked !== undefined) {
             const live = sessions.get(picked.id);

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

@@ -0,0 +1,28 @@
+/**
+ * The facts a SESSION contributes to a verdict, in the shape `decideVerified` takes.
+ *
+ * `decideVerified` is pure and has no session, so anything it needs about the link has to be
+ * threaded in. Two tools produce verdicts — `reticle_assert` and `reticle_act_and_wait` — and both
+ * were threading the same fields with the same conditional-spread idiom and the same comment
+ * beside it. A third fact (`versionSkew`) would have been a third copy.
+ *
+ * One function instead, for the ordinary reason: when a fourth fact arrives, a verdict surface that
+ * learns it in one place cannot half-learn it. That failure mode is not hypothetical here — the
+ * repo already records `net` assertions being discarded on one half of a surface because a filter
+ * was updated on the other.
+ *
+ * Every field is omitted rather than defaulted when absent. An SDK too old to declare sends
+ * nothing, and an empty value is a claim nobody made.
+ */
+/** What a session can tell a verdict. Optional throughout: absent means nobody said. */
+export interface SessionVerdictFacts {
+    readonly sdkVersion?: string;
+    readonly versionSkew?: string;
+}
+/** The shape read here — structural, so a test double needs no session. */
+export interface VerdictRelevantSession {
+    readonly sdkVersion?: string | undefined;
+    readonly versionSkew?: string | undefined;
+    readonly channels?: readonly string[] | undefined;
+}
+export declare function sessionVerdictFacts(session: VerdictRelevantSession): SessionVerdictFacts;

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

@@ -0,0 +1,15 @@
+export function sessionVerdictFacts(session) {
+    const facts = {};
+    // So the unread-body remedy can check it applies to THIS page.
+    if (session.sdkVersion !== undefined)
+        facts.sdkVersion = session.sdkVersion;
+    /*
+     * An empty string is NOT a skew. The bridge sets this only on a real mismatch, but a defaulted
+     * or cleared field reaching the verdict would cost every call a `yes` it had earned — which is a
+     * worse failure than the one this exists to fix.
+     */
+    if (session.versionSkew !== undefined && session.versionSkew.length > 0) {
+        facts.versionSkew = session.versionSkew;
+    }
+    return facts;
+}

package/dist/portal/session/session.d.ts

@@ -1,5 +1,5 @@
 import type { WebSocket } from 'ws';
-import type { ChannelId, ImpactSnapshot } from '@reticlehq/core';
+import { type ChannelId, type ImpactSnapshot, type ProjectId } from '@reticlehq/core';
 import type { HandshakeFacts } from './facts/handshake-facts.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
@@ -7,7 +7,7 @@ import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { type PageRuntime } from './timing/command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type JournalWriteLoss, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../../memory/journal/journal-recorder.js';
 import { type EventQueryOptions } from '../../memory/journal/journal-query.js';
 import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
@@ -25,8 +25,14 @@ type Clock = () => number;
 export declare class Session implements HandshakeFacts {
     #private;
     readonly id: string;
-    /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
-    readonly projectId: string | undefined;
+    /**
+     * Stable build-stamped project identity; undefined for SDKs old enough to omit it.
+     *
+     * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
+     * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
+     * downstream reader takes the brand from this property rather than re-blessing a string.
+     */
+    readonly projectId: ProjectId | undefined;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
      *
@@ -38,6 +44,11 @@ export declare class Session implements HandshakeFacts {
      * root, which is what every counter did unconditionally before this existed.
      */
     artifactRoot: string | undefined;
+    /**
+     * Same-origin endpoints this session's project declared as background (`.reticle.json`
+     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
+     */
+    background: readonly string[];
     url: string;
     title: string;
     adapters: string[];
@@ -118,12 +129,13 @@ export declare class Session implements HandshakeFacts {
      */
     setJournal(recorder: JournalRecorder, reader?: JournalReader): void;
     /**
-     * Journal-backed event query: the ring buffer's events, merged with the durable journal **only when
-     * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by since/until/
-     * actionId. This is how "what did action N cause" is answered after the buffer has dropped the
-     * evidence — the substrate's whole point. The sync `eventsSince`/`window` stay for the hot path.
+     * Journal-backed event query — the rule itself lives in `readQueryEvents`, beside the merge and
+     * filter it is made of. This is how "what did action N cause" is answered after the buffer has
+     * dropped the evidence. The sync `eventsSince`/`window` stay for the hot path.
      */
     queryEvents(options: EventQueryOptions): Promise<ReticleEvent[]>;
+    /** What the durable ledger could not WRITE — see `readJournalWriteLoss` for the rule and why. */
+    journalWriteLoss(): Promise<JournalWriteLoss | undefined>;
     /**
      * Open an action-attribution window: events observed until finishAction attribute to the returned
      * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
@@ -200,9 +212,13 @@ export declare class Session implements HandshakeFacts {
         dropped: number;
     };
     /**
-     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
      * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
-     * moves for the age and churn evictions that every live page produces continuously.
+     * moves for the age and churn evictions that every live page produces continuously. The journal is
+     * the other half of that store, so a durable read that could not reach back to `cursor` lost
+     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+     * conservative direction, both times.
      */
     lostSince(cursor: number): boolean;
     onEvent(listener: (event: ReticleEvent) => void): () => void;