@reticlehq/server 2.10.0 → 2.12.0

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

@@ -18,6 +18,14 @@ interface NoSessionWatchOptions {
     /** Where that was decided — this daemon's working directory unless a caller says otherwise. */
     directory?: string;
     probe?: () => Promise<number[]>;
+    /**
+     * Well-known Reticle ports other than ours that currently accept a connection.
+     *
+     * Remaining half of #261. Injected so tests can pin the observation without opening a socket.
+     * Production (no `probe` override) probes those ports itself. A test that injects `probe` and
+     * omits this is opting out: it owns the scan.
+     */
+    occupiedSiblings?: () => Promise<readonly number[]>;
     /**
      * How many pooled leases have aged out, if a pool exists. Injected as a reader rather than the
      * pool itself: the diagnosis needs one number, and taking the whole pool would tie the session

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

@@ -17,7 +17,9 @@ import { readProjectFramework, readProjectId, readProjectPort } from '../cli/cli
 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';
+import { stallUptime } from './stall-clock.js';
+import { probeDaemon } from '../mcp/mcp-proxy.js';
+import { findOccupiedSiblings } from '../cli/sibling-ports.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. */
@@ -56,6 +58,7 @@ export function startNoSessionWatch(options) {
      * `options.probe` returns only the serving set, so this stays empty for injected probes.
      */
     let slowListeners = [];
+    let siblingListeners = [];
     let running = false;
     /** Ports auto-attach has already spent its one attempt on. Bounded: never a loop, never a retry. */
     const attempted = new Set();
@@ -66,6 +69,27 @@ export function startNoSessionWatch(options) {
     // 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;
+    /**
+     * Resolve the daemon's current project scope once for both halves of a sessions response.
+     *
+     * This remains a live read because `init` commonly writes the config after the daemon starts.
+     */
+    const projectScopeFacts = () => {
+        const initialized = isWired();
+        if (initialized)
+            return { initialized };
+        const discovery = discoverProjectConfigs(directory);
+        const elsewhere = discovery.found.filter((config) => config.directory !== directory);
+        return 0 === elsewhere.length
+            ? { initialized, searchedDirectories: discovery.searched }
+            : {
+                initialized,
+                configsElsewhere: elsewhere.map((config) => ({
+                    directory: config.directory,
+                    ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+                })),
+            };
+    };
     // 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();
@@ -129,6 +153,12 @@ export function startNoSessionWatch(options) {
             : probe())
             .then(async (ports) => {
             listening = ports;
+            siblingListeners =
+                options.occupiedSiblings !== undefined
+                    ? await options.occupiedSiblings()
+                    : options.probe === undefined
+                        ? await findOccupiedSiblings(options.port, probeDaemon)
+                        : [];
             await autoAttach(ports);
         })
             .catch(() => {
@@ -141,77 +171,65 @@ export function startNoSessionWatch(options) {
     refresh();
     const timer = setInterval(refresh, REFRESH_MS);
     timer.unref();
-    const nextAction = () => nextActionFor({
+    const nextAction = (scope) => nextActionFor({
         everConnected: options.sessions.everConnected(),
-        initialized: isWired(),
+        initialized: scope.initialized,
+        ...(scope.configsElsewhere === undefined ? {} : { configsElsewhere: scope.configsElsewhere }),
         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(),
-        // 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,
-        // 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(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 ?? ''));
+    options.sessions.setNoSessionNextAction(() => nextAction(projectScopeFacts()));
+    options.sessions.setNoSessionHint(() => {
+        const scope = projectScopeFacts();
+        return (diagnoseNoSession({
+            everConnected: options.sessions.everConnected(),
+            // 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.
+            ...scope,
+            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,
+            // 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(directory);
+                return configured === undefined ? {} : { projectPort: configured };
+            })(),
+            ...(0 === siblingListeners.length ? {} : { siblingListeners }),
+        }) +
+            // 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 ?? ''));
+    });
     return () => {
         clearInterval(timer);
         options.sessions.setConnectionRecorder(undefined);

package/dist/session/output-budget.js

@@ -50,7 +50,10 @@ export function estimateTokens(text) {
 }
 export function sizeCost(payload) {
     const json = JSON.stringify(payload) ?? '';
-    return { bytes: json.length, tokens: estimateTokens(json) };
+    // Actual UTF-8 wire bytes, not json.length (UTF-16 code units) — the field is labeled `bytes`
+    // and drives the large-snapshot recommendation, so a multibyte-heavy payload was under-counted.
+    const bytes = Buffer.byteLength(json, 'utf8');
+    return { bytes, tokens: estimateTokens(json) };
 }
 /**
  * Attach a `cost` size preview to a read result. Pure: the cost is computed over the result BEFORE

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

@@ -45,6 +45,15 @@ export declare function healthEnvelope(session: Session): HealthEnvelope;
  * warn-only so background testing never breaks.
  */
 export declare function refuseIfThrottled(session: Session, refuse: unknown): void;
+/**
+ * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
+ * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
+ * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ */
+export declare function annotateStarvedFailure<V extends {
+    pass?: boolean;
+    failureReason?: string;
+}>(session: Session, verdict: V): V;
 /** The page's own visibility/runtime report, narrowed out of an untrusted PAGE_HEALTH payload. */
 interface HealthReport {
     hidden: boolean | undefined;

package/dist/session/session-health.js

@@ -35,6 +35,29 @@ export function refuseIfThrottled(session, refuse) {
         throw new Error(`refusing to act: ${THROTTLED_WARNING}`);
     }
 }
+/**
+ * The sentence appended to a FAILED predicate verdict waited out on a throttled tab.
+ *
+ * A starved tab and a missing element read identically as a bare near-miss: after a hard reload a
+ * backgrounded tab can sit on its loading state forever (hydration starved, nothing painted), and
+ * `wait_for { text }` timing out there looks exactly like "the code did not render" (#521). The
+ * health envelope already rode alongside saying `throttled:true`, but nothing connected it to the
+ * verdict an agent actually gates on. Appended, not replacing: the original diagnosis still leads,
+ * and on a healthy tab the failure says exactly what it always said.
+ */
+const STARVED_WAIT_NOTE = ' (the tab was throttled during this wait, so starvation can look exactly like absence: bring it to the front and re-check before concluding this is genuinely missing)';
+/**
+ * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
+ * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
+ * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ */
+export function annotateStarvedFailure(session, verdict) {
+    if (true === verdict.pass || verdict.failureReason === undefined)
+        return verdict;
+    if (true !== session.throttled())
+        return verdict;
+    return { ...verdict, failureReason: `${verdict.failureReason}${STARVED_WAIT_NOTE}` };
+}
 /**
  * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report
  * `runtime` at all — so each is returned as undefined rather than defaulted here, letting the caller

package/dist/session/session-manager.js

@@ -2,6 +2,7 @@ import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './attachment-history.js';
+import { pickDocumentSuccessor } from './session-successor.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)
@@ -61,6 +62,14 @@ function scopeMissError(connected, scope) {
  */
 /** How many bridge-initiated closes to remember for diagnosis. */
 const MAX_REMEMBERED_CLOSURES = 5;
+/**
+ * How many recently-departed session ids to remember for successor rebind.
+ *
+ * A full-document navigation HELLO's back under a new id while the agent still holds the old one.
+ * The tombstone is how `resolve(oldId)` finds the unique same-origin successor instead of refusing.
+ * Bounded so a long-lived daemon cannot accumulate one record per tab forever.
+ */
+const MAX_TOMBSTONES = 32;
 export class SessionManager {
     #sessions = new Map();
     /**
@@ -69,6 +78,13 @@ export class SessionManager {
      * Owned here because this is the one place that sees both halves — every add and every remove.
      */
     #attachment = new AttachmentHistory();
+    /**
+     * Recently departed sessions, keyed by the id the agent still holds.
+     *
+     * Insertion order is LRU: the oldest is dropped when the cap is hit. A reconnect under the same
+     * id forgets its tombstone — the live session is the answer then.
+     */
+    #tombstones = 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
@@ -100,6 +116,7 @@ export class SessionManager {
         // that silently fails to register is a leak nothing would report.
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
+        this.#tombstones.delete(session.id);
         return previous;
     }
     remove(session) {
@@ -110,8 +127,40 @@ export class SessionManager {
         // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
         // the reconnect is exactly where that matters.
         this.#attachment.detached(session.id);
+        this.#rememberTombstone(session);
         return this.#sessions.delete(session.id);
     }
+    #rememberTombstone(session) {
+        const origin = originOf(session.url);
+        if (origin === undefined)
+            return;
+        if (this.#tombstones.has(session.id))
+            this.#tombstones.delete(session.id);
+        this.#tombstones.set(session.id, {
+            id: session.id,
+            url: session.url,
+            ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+        });
+        while (this.#tombstones.size > MAX_TOMBSTONES) {
+            const oldest = this.#tombstones.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#tombstones.delete(oldest);
+        }
+    }
+    #successorOf(sessionId) {
+        const departed = this.#tombstones.get(sessionId);
+        if (departed === undefined)
+            return undefined;
+        const picked = pickDocumentSuccessor(this.all().map((s) => ({
+            id: s.id,
+            url: s.url,
+            ...(s.projectId === undefined ? {} : { projectId: s.projectId }),
+        })), departed);
+        if (picked === undefined)
+            return undefined;
+        return this.#sessions.get(picked.id);
+    }
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
@@ -239,7 +288,7 @@ export class SessionManager {
     }
     resolve(sessionId, scope) {
         if (sessionId !== undefined) {
-            const found = this.#sessions.get(sessionId);
+            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
             if (found === undefined) {
                 throw new Error(this.#unknownSessionError(sessionId));
             }

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

@@ -0,0 +1,37 @@
+/**
+ * The session that took over after a full-document navigation.
+ *
+ * Reload keeps the id (sessionStorage). A click that loads a new document often does not: the SDK
+ * is torn down with the page and HELLO's back under a new id, while the agent still holds the old
+ * one. `navigate` already waits for that HELLO (`awaitArrival`) and returns the new id.
+ * `act_and_wait` and `assert` did not, so an MPA drive ended at the first link.
+ *
+ * Unique at the departed origin (and project, when known). Two live tabs at that origin is still a
+ * guess, and a guess here would drive the wrong app.
+ */
+import type { Session } from './session.js';
+export interface SessionIdentity {
+    id: string;
+    url: string;
+    projectId?: string;
+}
+export interface SuccessorClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * The one live session that can honestly take over from `departed`, or undefined when none or more
+ * than one could.
+ *
+ * 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;
+export interface SuccessorRegistry {
+    get(id: string): Session | undefined;
+    all(): readonly Session[];
+}
+/**
+ * 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.
+ */
+export declare function awaitDocumentSuccessor(sessions: SuccessorRegistry, departed: Session, timeoutMs: number, clock?: SuccessorClock): Promise<Session | null>;

package/dist/session/session-successor.js

@@ -0,0 +1,78 @@
+/**
+ * The session that took over after a full-document navigation.
+ *
+ * Reload keeps the id (sessionStorage). A click that loads a new document often does not: the SDK
+ * is torn down with the page and HELLO's back under a new id, while the agent still holds the old
+ * one. `navigate` already waits for that HELLO (`awaitArrival`) and returns the new id.
+ * `act_and_wait` and `assert` did not, so an MPA drive ended at the first link.
+ *
+ * Unique at the departed origin (and project, when known). Two live tabs at that origin is still a
+ * guess, and a guess here would drive the wrong app.
+ */
+const POLL_MS = 25;
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function identityOf(session) {
+    return {
+        id: session.id,
+        url: session.url,
+        ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+    };
+}
+/**
+ * The one live session that can honestly take over from `departed`, or undefined when none or more
+ * than one could.
+ *
+ * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
+ */
+export function pickDocumentSuccessor(live, departed) {
+    const origin = originOf(departed.url);
+    if (origin === undefined)
+        return undefined;
+    const atOrigin = live.filter((s) => originOf(s.url) === origin);
+    const sameId = atOrigin.find((s) => s.id === departed.id);
+    if (sameId !== undefined)
+        return sameId;
+    const others = atOrigin.filter((s) => s.id !== departed.id &&
+        (departed.projectId === undefined || s.projectId === departed.projectId));
+    if (1 !== others.length)
+        return undefined;
+    return others[0];
+}
+/**
+ * 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.
+ */
+export async function awaitDocumentSuccessor(sessions, departed, timeoutMs, clock = REAL_CLOCK) {
+    const deadline = clock.now() + timeoutMs;
+    const departedIdentity = identityOf(departed);
+    for (;;) {
+        const sameId = sessions.get(departed.id);
+        if (sameId !== undefined && sameId !== departed)
+            return sameId;
+        // The departed session often still sits in the registry until the socket close lands. Leave it
+        // 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)
+            .map(identityOf), departedIdentity);
+        if (picked !== undefined) {
+            const live = sessions.get(picked.id);
+            if (live !== undefined && live !== departed)
+                return live;
+        }
+        if (clock.now() >= deadline)
+            return null;
+        await clock.sleep(POLL_MS);
+    }
+}

package/dist/session/session.d.ts

@@ -1,10 +1,12 @@
 import type { WebSocket } from 'ws';
 import type { ImpactSnapshot } from '@reticlehq/core';
 import { LastAct } from './last-act.js';
+import { GapLedger } from '../honesty/gap-ledger.js';
+import { CaptureLedger } from '../honesty/feature-capture.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../journal/journal-recorder.js';
 import { type EventQueryOptions } from '../journal/journal-query.js';
 import { type AmbientCounts } from '../journal/ambient.js';
@@ -62,6 +64,10 @@ export declare class Session {
     info(): SessionInfo;
     /** Wall-clock age of the session in milliseconds. */
     staleMs(): number;
+    /** The document the most recent stamped event was observed under. See `#documentId`. */
+    get currentDocumentId(): string | undefined;
+    /** The edit epoch the most recent stamped event was observed under. See `#editEpoch`. */
+    get currentEditEpoch(): number | undefined;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
@@ -99,8 +105,28 @@ export declare class Session {
      * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
      */
     beginAction(tool: string, args: Record<string, unknown>): string;
+    /**
+     * Record one action WITHOUT opening an attribution window — for a tool that returns a verdict but
+     * drives nothing, so no event it observes was caused by it. See `JournalRecorder.recordAction`.
+     */
+    recordAction(tool: string, args: Record<string, unknown>, effect?: unknown): string;
+    /**
+     * How many actions this session has dispatched.
+     *
+     * The counter that mints journal action ids, not a second one — so it equals the journal's own
+     * length, and `reticle_context`'s `step`, whenever this session journals at all.
+     */
+    get actionCount(): number;
     /** Close the active action window, persisting its action record with the settle outcome. */
     finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * The durable action ledger for this session — the ledger the run context is folded out of.
+     *
+     * `[]` when nothing journals this session (journaling disabled, or an id that is not a safe path
+     * segment). An absent ledger reads as an empty run, never as a missing one: the fold simply has
+     * nothing to say, which is the honest answer.
+     */
+    readJournalActions(): Promise<JournalAction[]>;
     /** Flush any buffered journal events to disk (call on session end). */
     flushJournal(): Promise<void>;
     eventsSince(cursor: number): ReticleEvent[];
@@ -111,6 +137,19 @@ export declare class Session {
      * from it, and the split between those two tool calls is the whole reason it exists.
      */
     readonly lastAct: LastAct;
+    /**
+     * What this app still cannot tell Reticle, as of the most recent verdict.
+     *
+     * Lives on the session because that is the scope the question belongs to: "am I done with this
+     * app" is a session question, and a gap closed halfway through must not follow the agent to the
+     * end of it.
+     */
+    readonly gaps: GapLedger;
+    /**
+     * The read-only calls the journal does not keep, so "was `reticle_context` ever called" has
+     * something to fold. See honesty/feature-capture.ts — it is the only state that instrument adds.
+     */
+    readonly capture: CaptureLedger;
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
      * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the