@ours.network/fleet 1.2.0-nightly.62 → 1.2.0-nightly.64

package/dist/session/conversation-replay.js

@@ -0,0 +1,203 @@
+import { open } from 'node:fs/promises';
+import { setImmediate as yieldTurn } from 'node:timers/promises';
+export const MAX_REPLAY_BUFFER_BYTES = 8 * 1024 * 1024;
+export const MAX_CONVERSATION_RECORD_BYTES = 16 * 1024 * 1024;
+export class ReplayCoverageError extends Error {
+    constructor(detail) { super(`replay coverage unavailable: ${detail}`); }
+}
+/** Bounded reads and explicit scheduling even when a whole segment is cached by the OS. */
+export async function* replayLines(path, signal) {
+    const file = await open(path, 'r');
+    try {
+        const chunk = Buffer.alloc(64 * 1024);
+        let pending = Buffer.alloc(0);
+        for (;;) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await file.read(chunk, 0, chunk.length, null);
+            if (!bytesRead)
+                break;
+            const data = Buffer.concat([pending, chunk.subarray(0, bytesRead)]);
+            let start = 0;
+            for (let i = 0; i < data.length; i++) {
+                if (data[i] !== 10)
+                    continue;
+                if (i - start > MAX_CONVERSATION_RECORD_BYTES)
+                    throw new ReplayCoverageError('record exceeds assembly limit');
+                yield data.toString('utf8', start, i);
+                start = i + 1;
+            }
+            pending = Buffer.from(data.subarray(start));
+            if (pending.length > MAX_CONVERSATION_RECORD_BYTES)
+                throw new ReplayCoverageError('record exceeds assembly limit');
+            await yieldTurn();
+        }
+        if (pending.length)
+            throw new ReplayCoverageError('unterminated record');
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Passive owner-turn registration, complete replay, ready, then buffered post-barrier delivery. */
+export function startConversationReplay(owner, request, sink) {
+    if (request.controller !== false || !owner.observeConversation || !owner.subscribeConversation || !owner.subscribeConversationFailure || !owner.replayConversation)
+        throw new ReplayCoverageError('passive observation is unavailable');
+    const after = request.after ?? 0;
+    if (!request.expectedGeneration || !Number.isSafeInteger(after) || after < 0)
+        throw new ReplayCoverageError('invalid cursor or generation');
+    const abort = new AbortController();
+    const disposers = [];
+    const pending = [];
+    let pendingBytes = 0;
+    let closed = false;
+    let committed = false;
+    let draining = false;
+    let snapshot;
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    // Consumers can attach later without an unhandled rejection during synchronous registration.
+    void ready.catch(() => { });
+    const close = (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        abort.abort(new Error(reason ?? 'conversation follow closed'));
+        for (const dispose of disposers.splice(0))
+            dispose();
+        pending.length = 0;
+        pendingBytes = 0;
+        rejectReady(new Error(reason ?? 'conversation follow closed'));
+        sink.close(reason);
+    };
+    const own = (dispose) => { if (closed)
+        dispose();
+    else
+        disposers.push(dispose); };
+    const drain = async () => {
+        if (!committed || draining || closed)
+            return;
+        draining = true;
+        try {
+            while (pending.length && !closed) {
+                const next = pending[0];
+                if (next.value.event) {
+                    if (next.value.event.seq > snapshot.ledgerBarrier)
+                        await sink.event(next.value.event);
+                }
+                else if (next.value.state.stateRevision > snapshot.stateRevision)
+                    await sink.state(next.value.state);
+                if (!closed) {
+                    pending.shift();
+                    pendingBytes -= next.bytes;
+                }
+            }
+        }
+        catch (error) {
+            close(error.message);
+        }
+        finally {
+            draining = false;
+        }
+    };
+    const enqueue = (value) => {
+        if (closed)
+            return;
+        if (value.state?.observationFailure) {
+            close('conversation observation failed');
+            return;
+        }
+        if ((value.event ?? value.state).sessionGeneration !== request.expectedGeneration) {
+            close('session generation changed');
+            return;
+        }
+        const recordBytes = Buffer.byteLength(JSON.stringify(value.event ?? value.state));
+        const bytes = recordBytes + 10; // {"event":...} or {"state":...} queued envelope
+        if (recordBytes > MAX_CONVERSATION_RECORD_BYTES) {
+            close('conversation record exceeds assembly limit');
+            return;
+        }
+        // One active record goes straight to the progressive writer. Only waiting
+        // records count against the 8 MiB queue; the active assembly is bounded separately.
+        if (committed && !draining && pending.length === 0) {
+            draining = true;
+            void (async () => {
+                try {
+                    if (value.event) {
+                        if (value.event.seq > snapshot.ledgerBarrier)
+                            await sink.event(value.event);
+                    }
+                    else if (value.state.stateRevision > snapshot.stateRevision)
+                        await sink.state(value.state);
+                }
+                catch (error) {
+                    close(error.message);
+                }
+                finally {
+                    draining = false;
+                    void drain();
+                }
+            })();
+            return;
+        }
+        if (pendingBytes + bytes > MAX_REPLAY_BUFFER_BYTES) {
+            close('conversation live replay buffer exceeded');
+            return;
+        }
+        pending.push({ value, bytes });
+        pendingBytes += bytes;
+        void drain();
+    };
+    try {
+        // No await between registration and the owner's coherent snapshot/barrier capture.
+        own(owner.subscribeConversation(event => enqueue({ event })));
+        own(owner.subscribeConversationFailure(generation => {
+            if (generation === request.expectedGeneration)
+                close('conversation generation has non-durable events');
+        }));
+        const observation = owner.observeConversation(state => enqueue({ state }));
+        own(observation.unsubscribe);
+        snapshot = observation.snapshot;
+        if (snapshot.observationFailure)
+            throw new ReplayCoverageError('conversation observation failed');
+        if (snapshot.sessionGeneration !== request.expectedGeneration)
+            throw new ReplayCoverageError('session generation changed');
+        if (after > snapshot.ledgerBarrier)
+            throw new ReplayCoverageError('cursor exceeds barrier');
+        if (request.signal) {
+            const onAbort = () => close('conversation follow aborted');
+            request.signal.addEventListener('abort', onAbort, { once: true });
+            own(() => request.signal.removeEventListener('abort', onAbort));
+            if (request.signal.aborted)
+                onAbort();
+        }
+    }
+    catch (error) {
+        close(error.message);
+    }
+    if (!closed)
+        void (async () => {
+            try {
+                let coveredThrough = after;
+                for await (const page of owner.replayConversation({ expectedGeneration: request.expectedGeneration, after, through: snapshot.ledgerBarrier, signal: abort.signal })) {
+                    abort.signal.throwIfAborted();
+                    if (page.coveredThrough <= coveredThrough || page.coveredThrough > snapshot.ledgerBarrier)
+                        throw new ReplayCoverageError('non-progressing page');
+                    await sink.replay(page);
+                    coveredThrough = page.coveredThrough;
+                }
+                abort.signal.throwIfAborted();
+                if (coveredThrough !== snapshot.ledgerBarrier)
+                    throw new ReplayCoverageError('incomplete replay');
+                await sink.ready({ snapshot, coveredThrough });
+                abort.signal.throwIfAborted();
+                committed = true;
+                resolveReady();
+                await drain();
+            }
+            catch (error) {
+                close(error.message);
+            }
+        })();
+    return { ready, close: () => close() };
+}

package/dist/session/conversation-store.d.ts

@@ -1,3 +1,4 @@
+import { type ConversationReplayRequest, type ConversationReplayPage } from './conversation-replay.js';
 import type { ConversationEventV1, PromptReceipt } from './conversation-types.js';
 export interface ConversationStoreOptions {
     roleId: string;
@@ -29,6 +30,13 @@ type EventDraft = Omit<ConversationEventV1, 'schemaVersion' | 'roleId' | 'eventI
 export declare class ConversationEventStore {
     private readonly dir;
     private nextSeq;
+    private lastDurableSeq;
+    private readonly segmentRanges;
+    private readonly generationFloors;
+    private readonly failedGenerations;
+    private readonly failureListeners;
+    private unavailable;
+    private rotateBeforeAppend;
     private firstAvailableSeq?;
     private segments;
     private tail;
@@ -45,6 +53,8 @@ export declare class ConversationEventStore {
     constructor(dir: string, options: ConversationStoreOptions);
     /** First 24 hex chars of sha-256; the idempotency body-digest convention. */
     static bodyDigest(body: string): string;
+    /** Current delivery eligibility only; requested historical ranges still need replay verification. */
+    generationDurable(generation: string): boolean;
     get degraded(): boolean;
     get degradedDetail(): string | undefined;
     /**
@@ -59,6 +69,8 @@ export declare class ConversationEventStore {
     appendSafe(draft: EventDraft): ConversationEventV1 | undefined;
     page(request?: ConversationPageRequest): ConversationStorePage;
     subscribe(listener: (event: ConversationEventV1) => void): () => void;
+    /** A current-generation failed append invalidates even a follow already past ready. */
+    subscribeFailure(listener: (generation: string) => void): () => void;
     /** Store the receipt a repeated command must get back. */
     recordReceipt(commandId: string, receipt: PromptReceipt, bodyDigest: string): void;
     /**
@@ -82,6 +94,8 @@ export declare class ConversationEventStore {
     private trackPromptState;
     private segmentFd;
     private writeManifest;
+    /** One forward iterator owns the scan; each segment is opened at most once. */
+    replay(request: ConversationReplayRequest): AsyncGenerator<ConversationReplayPage>;
     private eventsAfter;
     private markDegraded;
 }

package/dist/session/conversation-store.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync, writeSync, } from 'node:fs';
 import { join } from 'node:path';
+import { setImmediate as yieldTurn } from 'node:timers/promises';
+import { replayLines, ReplayCoverageError } from './conversation-replay.js';
 /**
  * Durable, append-only, single-writer conversation ledger for one role
  * The per-role runner is the only writer; readers page by seq.
@@ -24,6 +26,13 @@ export class IdempotencyConflictError extends Error {
 export class ConversationEventStore {
     dir;
     nextSeq = 1;
+    lastDurableSeq = 0;
+    segmentRanges = new Map();
+    generationFloors = new Map();
+    failedGenerations = new Set();
+    failureListeners = new Set();
+    unavailable = false;
+    rotateBeforeAppend = false;
     firstAvailableSeq;
     segments = [];
     tail = [];
@@ -47,6 +56,7 @@ export class ConversationEventStore {
             this.recover();
         }
         catch (error) {
+            this.unavailable = true;
             this.markDegraded(`store unavailable: ${error.message}`);
         }
     }
@@ -54,6 +64,10 @@ export class ConversationEventStore {
     static bodyDigest(body) {
         return createHash('sha256').update(body).digest('hex').slice(0, 24);
     }
+    /** Current delivery eligibility only; requested historical ranges still need replay verification. */
+    generationDurable(generation) {
+        return Boolean(generation) && !this.unavailable && !this.failedGenerations.has(generation);
+    }
     get degraded() { return this._degraded; }
     get degradedDetail() { return this.degradedReason; }
     /**
@@ -69,12 +83,47 @@ export class ConversationEventStore {
             at: new Date().toISOString(),
             ...draft,
         };
-        const line = JSON.stringify(event) + '\n';
-        const fd = this.segmentFd(Buffer.byteLength(line));
-        writeSync(fd, line);
-        fsyncSync(fd);
+        let line;
+        try {
+            line = JSON.stringify(event) + '\n';
+            const fd = this.segmentFd(Buffer.byteLength(line));
+            // From this point writes may have reached disk even if write/fsync throws.
+            // Never let a later generation reuse that identity; gaps are safer than collisions.
+            this.nextSeq++;
+            const bytes = Buffer.from(line);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const written = writeSync(fd, bytes, offset, bytes.length - offset);
+                if (!written)
+                    throw new Error('short ledger write');
+                offset += written;
+            }
+            fsyncSync(fd);
+        }
+        catch (error) {
+            const firstFailure = !this.failedGenerations.has(draft.sessionGeneration);
+            this.failedGenerations.add(draft.sessionGeneration);
+            this.rotateBeforeAppend = true;
+            this.writeManifest();
+            this.markDegraded(`event append failed: ${error.message}`);
+            if (firstFailure)
+                for (const listener of this.failureListeners) {
+                    try {
+                        listener(draft.sessionGeneration);
+                    }
+                    catch { /* observers cannot interrupt owner failure handling */ }
+                }
+            throw error;
+        }
+        if (!this.generationFloors.has(event.sessionGeneration))
+            this.generationFloors.set(event.sessionGeneration, event.seq - 1);
+        const segment = this.segments.at(-1);
+        const range = this.segmentRanges.get(segment) ?? { damaged: false };
+        range.first ??= event.seq;
+        range.last = event.seq;
+        this.segmentRanges.set(segment, range);
         this.firstAvailableSeq ??= event.seq;
-        this.nextSeq++;
+        this.lastDurableSeq = event.seq;
         this.activeBytes += Buffer.byteLength(line);
         this.tail.push(event);
         if (this.tail.length > TAIL_EVENTS)
@@ -118,6 +167,11 @@ export class ConversationEventStore {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
+    /** A current-generation failed append invalidates even a follow already past ready. */
+    subscribeFailure(listener) {
+        this.failureListeners.add(listener);
+        return () => this.failureListeners.delete(listener);
+    }
     /** Store the receipt a repeated command must get back. */
     recordReceipt(commandId, receipt, bodyDigest) {
         this.commands.set(commandId, { receipt, bodyDigest });
@@ -143,7 +197,7 @@ export class ConversationEventStore {
         return [...this.promptStates.values()];
     }
     lastCursor() {
-        return this.nextSeq > 1 ? String(this.nextSeq - 1) : undefined;
+        return this.lastDurableSeq > 0 ? String(this.lastDurableSeq) : undefined;
     }
     close() {
         if (this.activeFd !== undefined) {
@@ -154,17 +208,27 @@ export class ConversationEventStore {
             this.activeFd = undefined;
         }
         this.listeners.clear();
+        this.failureListeners.clear();
     }
     // ── recovery ───────────────────────────────────────────────────────────────
     recover() {
         const manifest = this.readManifest();
-        this.segments = manifest?.segments.filter(name => existsSync(join(this.dir, name))) ?? this.discoverSegments();
-        if (!this.segments.length)
-            this.segments = this.discoverSegments();
+        for (const generation of manifest?.failedGenerations ?? [])
+            this.failedGenerations.add(generation);
+        // Preserve missing manifest entries: filtering them would erase proof of a gap on reopen.
+        this.segments = [...new Set([...(manifest?.segments ?? []), ...this.discoverSegments()])].sort();
         let maxSeq = 0;
         for (const segment of this.segments) {
             for (const event of this.readSegment(segment)) {
                 this.firstAvailableSeq ??= event.seq;
+                if (event.seq <= maxSeq) {
+                    // Pre-fix or corrupt ledgers may already contain colliding identities.
+                    // A cached generation floor must never certify the later duplicate.
+                    this.failedGenerations.add(event.sessionGeneration);
+                    this.markDegraded(`segment ${segment} has non-monotonic sequence ${event.seq}`);
+                }
+                if (!this.generationFloors.has(event.sessionGeneration))
+                    this.generationFloors.set(event.sessionGeneration, maxSeq);
                 maxSeq = Math.max(maxSeq, event.seq);
                 this.tail.push(event);
                 if (this.tail.length > TAIL_EVENTS)
@@ -173,10 +237,12 @@ export class ConversationEventStore {
                 this.rebuildCommandIndex(event);
             }
         }
-        this.nextSeq = maxSeq + 1;
+        this.nextSeq = Math.max(maxSeq + 1, manifest?.nextSeq ?? 1);
+        this.lastDurableSeq = maxSeq;
         if (this.segments.length) {
             const active = join(this.dir, this.segments.at(-1));
             this.activeBytes = existsSync(active) ? statSync(active).size : 0;
+            this.rotateBeforeAppend = this.segmentRanges.get(this.segments.at(-1))?.damaged ?? true;
         }
         this.writeManifest();
     }
@@ -201,25 +267,36 @@ export class ConversationEventStore {
     }
     readSegment(name) {
         const events = [];
+        const range = { damaged: false };
+        this.segmentRanges.set(name, range);
         let raw;
         try {
             raw = readFileSync(join(this.dir, name), 'utf8');
         }
         catch (error) {
+            range.damaged = true;
             this.markDegraded(`segment ${name} unreadable: ${error.message}`);
             return events;
         }
+        if (raw.length && !raw.endsWith('\n'))
+            range.damaged = true;
         for (const line of raw.split('\n')) {
             if (!line.trim())
                 continue;
             try {
                 const event = JSON.parse(line);
-                if (event.schemaVersion === 1 && typeof event.seq === 'number')
+                if (event.schemaVersion === 1 && Number.isSafeInteger(event.seq) && event.seq > 0) {
                     events.push(event);
-                else
+                    range.first ??= event.seq;
+                    range.last = event.seq;
+                }
+                else {
+                    range.damaged = true;
                     this.markDegraded(`segment ${name} holds a record of an unknown schema`);
+                }
             }
             catch {
+                range.damaged = true;
                 // A torn final line after a crash: everything before it stays readable.
                 this.markDegraded(`segment ${name} ends in a torn or corrupt line`);
             }
@@ -237,6 +314,8 @@ export class ConversationEventStore {
             bodyDigest,
             receipt: {
                 commandId: event.commandId,
+                ...(typeof event.sessionGeneration === 'string' && event.sessionGeneration
+                    ? { sessionGeneration: event.sessionGeneration } : {}),
                 promptId: event.promptId,
                 state: 'queued',
                 queuedBehind: payload.queuedBehind ?? 0,
@@ -275,7 +354,7 @@ export class ConversationEventStore {
     // ── segment management ─────────────────────────────────────────────────────
     segmentFd(incomingBytes) {
         if (this.activeFd !== undefined
-            && this.activeBytes + incomingBytes > this.segmentBytes) {
+            && (this.rotateBeforeAppend || this.activeBytes + incomingBytes > this.segmentBytes)) {
             try {
                 closeSync(this.activeFd);
             }
@@ -283,11 +362,12 @@ export class ConversationEventStore {
             this.activeFd = undefined;
         }
         if (this.activeFd === undefined) {
-            const needsNew = !this.segments.length
+            const needsNew = this.rotateBeforeAppend || !this.segments.length
                 || this.activeBytes + incomingBytes > this.segmentBytes;
             if (needsNew) {
-                const name = `events-${String(this.segments.length + 1).padStart(6, '0')}.jsonl`;
+                const name = `events-${String(Number(this.segments.at(-1)?.match(/\d+/)?.[0] ?? 0) + 1).padStart(6, '0')}.jsonl`;
                 this.segments.push(name);
+                this.rotateBeforeAppend = false;
                 this.activeBytes = 0;
                 this.writeManifest();
             }
@@ -301,6 +381,7 @@ export class ConversationEventStore {
     writeManifest() {
         const manifest = {
             schemaVersion: 1, nextSeq: this.nextSeq, segments: this.segments,
+            ...(this.failedGenerations.size ? { failedGenerations: [...this.failedGenerations] } : {}),
         };
         const tmp = join(this.dir, MANIFEST + '.tmp');
         try {
@@ -308,12 +389,115 @@ export class ConversationEventStore {
             renameSync(tmp, join(this.dir, MANIFEST));
         }
         catch (error) {
-            // The manifest is a recovery accelerator, not the source of truth;
-            // segments alone can always rebuild it.
+            // Segments reconstruct durable records, but cannot reconstruct reserved
+            // identities or failed-generation latches retained only in the manifest.
             this.log(`conversation manifest write failed: ${error.message}`);
         }
     }
     // ── reads ──────────────────────────────────────────────────────────────────
+    /** One forward iterator owns the scan; each segment is opened at most once. */
+    async *replay(request) {
+        const { expectedGeneration, after, through, signal } = request;
+        const available = Number(this.lastCursor() ?? 0);
+        if (!expectedGeneration || !Number.isSafeInteger(after) || after < 0 ||
+            !Number.isSafeInteger(through) || through < after || through > available)
+            throw new ReplayCoverageError('invalid cursor or barrier');
+        const check = () => {
+            signal?.throwIfAborted();
+            if (this.unavailable || this.failedGenerations.has(expectedGeneration))
+                throw new ReplayCoverageError('generation has non-durable events');
+        };
+        check();
+        const floor = this.generationFloors.get(expectedGeneration);
+        if (floor === undefined && through > after)
+            throw new ReplayCoverageError('generation is not retained');
+        let coveredThrough = Math.max(after, Math.min(floor ?? after, through));
+        let events = [];
+        let count = 0;
+        let bytes = 0;
+        const pageSize = Math.min(1000, Math.max(1, request.pageSize ?? 128));
+        const segments = this.segments.map(name => ({ name, ...this.segmentRanges.get(name) }));
+        const nextFirst = new Array(segments.length);
+        let following;
+        for (let i = segments.length - 1; i >= 0; i--) {
+            nextFirst[i] = following;
+            following = segments[i].first ?? following;
+        }
+        let corruptPrefix = false;
+        for (let index = 0; index < segments.length && coveredThrough < through; index++) {
+            check();
+            const segment = segments[index];
+            const followingFirst = nextFirst[index];
+            // A verified later old record localizes earlier damage outside the requested range.
+            if ((segment.last !== undefined && segment.last <= coveredThrough && !segment.damaged) ||
+                (followingFirst !== undefined && followingFirst <= coveredThrough))
+                continue;
+            try {
+                for await (const line of replayLines(join(this.dir, segment.name), signal)) {
+                    check();
+                    if (!line.trim())
+                        continue;
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch {
+                        corruptPrefix = true;
+                        continue;
+                    }
+                    if (event.schemaVersion !== 1 || !Number.isSafeInteger(event.seq) || event.seq < 1) {
+                        corruptPrefix = true;
+                        continue;
+                    }
+                    if (event.seq <= Math.max(after, floor ?? after)) {
+                        corruptPrefix = false;
+                        continue;
+                    }
+                    if (corruptPrefix)
+                        throw new ReplayCoverageError('corrupt record in requested range');
+                    if (event.seq <= coveredThrough)
+                        throw new ReplayCoverageError('non-monotonic sequence');
+                    if (event.seq !== coveredThrough + 1)
+                        throw new ReplayCoverageError('missing sequence');
+                    const visible = event.sessionGeneration === expectedGeneration && event.source !== 'agent_replay';
+                    const eventBytes = visible ? Buffer.byteLength(line) : 0;
+                    if (count && bytes + eventBytes > 256 * 1024) {
+                        yield { events, coveredThrough };
+                        events = [];
+                        count = 0;
+                        bytes = 0;
+                        await yieldTurn();
+                        check();
+                    }
+                    coveredThrough = event.seq;
+                    count++;
+                    if (visible) {
+                        events.push(event);
+                        bytes += eventBytes;
+                    }
+                    if (count >= pageSize || bytes >= 256 * 1024 || coveredThrough === through) {
+                        yield { events, coveredThrough };
+                        events = [];
+                        count = 0;
+                        bytes = 0;
+                        await yieldTurn();
+                    }
+                    if (coveredThrough === through)
+                        break;
+                }
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                throw new ReplayCoverageError(error.message);
+            }
+        }
+        check();
+        if (coveredThrough !== through)
+            throw new ReplayCoverageError('barrier is not retained');
+        if (count || (through > after && floor !== undefined && floor >= through))
+            yield { events, coveredThrough };
+    }
     eventsAfter(after, limit) {
         // Serve from the in-memory tail whenever the range allows it.
         if (this.tail.length && after >= this.tail[0].seq - 1)

package/dist/session/conversation-types.d.ts

@@ -1,5 +1,5 @@
 import type { TaskCreatedNotice } from './task-notice.js';
-import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.js';
+import type { PromptOrigin, SessionSnapshot, TurnCancellationSource, TurnOutcome } from './types.js';
 /**
  * Durable conversation domain schema for managed-session consoles.
  *
@@ -282,6 +282,8 @@ export interface SubmitPromptCommand {
 }
 export interface PromptReceipt {
     commandId: string;
+    /** Original durable admission generation; absent when historical provenance is unknown. */
+    sessionGeneration?: string;
     promptId: string;
     state: 'queued' | 'starting';
     queuedBehind: number;
@@ -311,10 +313,36 @@ export interface ConversationSnapshot {
     queueDepth: number;
     pendingPermissionIds: string[];
     historyDegraded?: boolean;
+    /** Live observation is unavailable; REST may still serve canonical durable data. */
+    observationFailure?: 'capture_failed';
     /** Every waiting prompt, in delivery order; `pendingPromptCount` equals its length. */
     pendingPrompts?: PendingPromptSummary[];
     pendingPromptCount?: number;
 }
+/** Position captured synchronously with the owning backend's complete live state. */
+export interface ObservationPosition {
+    sessionGeneration: string;
+    stateRevision: number;
+    ledgerBarrier: number;
+}
+export interface ConversationObservationState extends ConversationSnapshot, ObservationPosition {
+    alive: boolean;
+    activePromptIds: string[];
+    pendingPrompts: PendingPromptSummary[];
+    pendingPromptCount: number;
+    /** Already presented and sanitized by the backend; never reconstructed from raw options. */
+    pendingPermissions: Array<PermissionRequestedPayload & {
+        permissionId: string;
+    }>;
+    commands: NonNullable<CapabilitiesUpdatedPayload['commands']>;
+    runtimeModel?: SessionSnapshot['runtimeModel'];
+    reasoningEffort?: SessionSnapshot['reasoningEffort'];
+    permissionMode?: SessionSnapshot['permissionMode'];
+}
+export interface ConversationObservation {
+    snapshot: ConversationObservationState;
+    unsubscribe(): void;
+}
 export interface ConversationPage {
     events: ConversationEventV1[];
     firstAvailableCursor?: string;

package/dist/session/types.d.ts

@@ -300,6 +300,12 @@ export interface AgentSession {
         limit?: number;
     }): ConversationHandlePage;
     conversationSnapshot?(): ConversationSnapshot;
+    /** Side-effect-free current-generation durability eligibility; does not certify a historical range. */
+    conversationReplayAvailable?(expectedGeneration: string): boolean;
+    replayConversation?(request: import('./conversation-replay.js').ConversationReplayRequest): AsyncIterable<import('./conversation-replay.js').ConversationReplayPage>;
+    /** Passive: registering never attaches a controller or acknowledges activity. */
+    observeConversation?(listener: (state: import('./conversation-types.js').ConversationObservationState) => void): import('./conversation-types.js').ConversationObservation;
+    subscribeConversationFailure?(listener: (generation: string) => void): () => void;
     subscribeConversation?(listener: (event: ConversationEventV1) => void): () => void;
     /** Durably admit an idempotent browser prompt; resolves on admission. */
     submitPromptBrowser?(command: SubmitPromptCommand): Promise<PromptReceipt>;

package/dist/subscriptions/login.d.ts

@@ -56,6 +56,7 @@ export declare class ClaudeLogin extends BaseLogin {
     private child?;
     private output;
     private submitted;
+    private continued;
     /** Resolves with the CLI exit status once it exits. */
     exited: Promise<number | null>;
     constructor(owner: string, bins: SubscriptionBinaries, home: string, profileId: string);