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

package/dist/session/codex-app-server.js

@@ -1,3 +1,4 @@
+import { ConversationObservation } from './conversation-observation.js';
 import { appendTaskCreated } from './task-notice.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
@@ -148,6 +149,7 @@ export class CodexAppServerSession {
     lastError;
     exit = null;
     queueDepth = 0;
+    observation = new ConversationObservation(() => this.captureObservation());
     promptTail = Promise.resolve();
     /** Admitted prompts not yet handed to the app-server, in admission order. */
     pendingPrompts = [];
@@ -170,6 +172,9 @@ export class CodexAppServerSession {
             roleId: options.name, log: line => options.log(`[${options.name}] ${line}`),
         });
         this.conversationStartCursor = this.conversation.lastCursor();
+        // A durable append can precede its inventory mutation. Capture only after
+        // the synchronous owner checkpoint, never the state at append notification.
+        this.conversation.subscribe(() => this.observation.scheduleCapture());
         // Use Fleet's provider-neutral resume marker so runner recovery rotates the
         // exact native thread id after a poisoned fast resume.
         this.threadFile = join(options.stateDir, '.session-id');
@@ -234,14 +239,18 @@ export class CodexAppServerSession {
         }
         const promptId = randomUUID();
         const queuedBehind = this.queueDepth;
-        this.admit(promptId, text, queuedBehind, options);
-        this.queueDepth++;
-        const run = this.enqueue(promptId, text, options.origin);
+        const run = this.observation.checkpoint(() => {
+            this.admit(promptId, text, queuedBehind, options);
+            this.queueDepth++;
+            return this.enqueue(promptId, text, options.origin);
+        });
         const completion = run.then(result => {
             this.queueDepth = Math.max(0, this.queueDepth - 1);
+            this.observation.publish();
             return result;
         }, error => {
             this.queueDepth = Math.max(0, this.queueDepth - 1);
+            this.observation.publish();
             return turnResult(false, 'failed', error instanceof Error ? error.message : String(error));
         });
         return {
@@ -413,6 +422,7 @@ export class CodexAppServerSession {
         });
         this.conversation.close();
         await this.transport.close();
+        this.observation.publish();
     }
     taskNoticeBinding() {
         return this.activeTurn && this.threadId ? { sessionGeneration: this.sessionGeneration, acpSessionId: this.threadId, promptId: this.activeTurn.promptId } : undefined;
@@ -432,6 +442,36 @@ export class CodexAppServerSession {
         }
         return { ...page, events: visible, snapshot: this.conversationSnapshot() };
     }
+    subscribeConversationFailure(listener) {
+        return this.conversation.subscribeFailure(listener);
+    }
+    conversationReplayAvailable(expectedGeneration) {
+        return expectedGeneration === this.sessionGeneration && this.conversation.generationDurable(expectedGeneration);
+    }
+    replayConversation(request) {
+        if (request.expectedGeneration !== this.sessionGeneration)
+            throw new Error('session generation changed');
+        return this.conversation.replay(request);
+    }
+    observeConversation(listener) {
+        return this.observation.observe(listener);
+    }
+    captureObservation() {
+        const snapshot = this.snapshot();
+        return {
+            ...this.conversationSnapshot(),
+            ...pendingInventory(this.pendingPrompts),
+            ledgerBarrier: Number(this.conversation.lastCursor() ?? 0),
+            alive: snapshot.alive,
+            readiness: snapshot.alive ? snapshot.readiness : 'offline',
+            activePromptIds: [...(this.activeTurn?.promptIds ?? [])],
+            pendingPermissions: [...this.pendingPermissions].flatMap(([permissionId, pending]) => pending.presented ? [{ permissionId, ...pending.presented }] : []),
+            commands: [{ name: 'compact', description: textBlock('Compact session context') }],
+            runtimeModel: snapshot.runtimeModel,
+            reasoningEffort: snapshot.reasoningEffort,
+            permissionMode: snapshot.permissionMode,
+        };
+    }
     conversationSnapshot() {
         return {
             sessionGeneration: this.sessionGeneration,
@@ -460,6 +500,7 @@ export class CodexAppServerSession {
             actor: { browserSession: command.actorBrowserSession },
         });
         const receipt = {
+            sessionGeneration: this.sessionGeneration,
             commandId: command.commandId, promptId: queued.promptId,
             state: queued.queuedBehind ? 'queued' : 'starting', queuedBehind: queued.queuedBehind,
             acceptedAt: new Date().toISOString(), eventCursor: this.conversation.lastCursor() ?? '0',
@@ -515,6 +556,7 @@ export class CodexAppServerSession {
             kind: 'session.state', sessionGeneration: this.sessionGeneration,
             payload: { status: 'idle' },
         });
+        this.observation.publish();
     }
     recoverOpenPrompts() {
         for (const open of this.conversation.openPrompts()) {
@@ -534,7 +576,8 @@ export class CodexAppServerSession {
                 ? { kind: 'owner-admin-console', commandId: open.commandId }
                 : undefined;
             const run = this.enqueue(open.promptId, open.text, origin);
-            void run.finally(() => { this.queueDepth = Math.max(0, this.queueDepth - 1); });
+            this.observation.publish();
+            void run.finally(() => { this.queueDepth = Math.max(0, this.queueDepth - 1); this.observation.publish(); });
         }
     }
     admit(promptId, text, queuedBehind, options) {
@@ -580,6 +623,7 @@ export class CodexAppServerSession {
         this.finalAnswerObserved = false;
         this.activeItems.clear();
         this.readiness = 'running';
+        this.observation.publish();
         this.events.emit('state', { turnId: promptId, status: 'running', origin });
         members.forEach((member, index) => this.conversation.appendSafe({
             kind: 'prompt.started', sessionGeneration: this.sessionGeneration,
@@ -890,6 +934,7 @@ export class CodexAppServerSession {
                     ...(active.cancellationSource ? { cancellationSource: active.cancellationSource } : {}),
                 },
             });
+        this.observation.publish();
         active.settle(result);
     }
     /**
@@ -1053,7 +1098,6 @@ export class CodexAppServerSession {
             this.resolvePermission(permissionId, pending, 'denied', 'automatic', 'deny_once', unattended ? 'permissions.unattended=deny' : 'permissions.approval=deny', unattended ? 'no controller is attached' : 'the role denies permission requests');
             return;
         }
-        this.pendingPermissions.set(permissionId, pending);
         this.readiness = 'awaiting_permission';
         const timeoutMs = this.options.permissionTimeoutMs ?? PERMISSION_TIMEOUT_MS;
         const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
@@ -1063,19 +1107,23 @@ export class CodexAppServerSession {
             ?? (method === 'item/fileChange/requestApproval' ? 'Apply file changes'
                 : method === 'item/permissions/requestApproval' ? 'Grant additional permissions'
                     : 'Run command');
+        const presented = { toolCallId, title, options, expiresAt };
+        pending.presented = presented;
+        this.pendingPermissions.set(permissionId, pending);
         this.events.emit('permission', {
             turnId: this.activeTurn?.promptId, origin: this.activeTurn?.origin,
-            permissionId, toolCallId, title, status: 'pending', options,
+            permissionId, ...presented, status: 'pending',
         });
         this.conversation.appendSafe({
             kind: 'permission.requested', sessionGeneration: this.sessionGeneration,
             permissionId, promptId: this.activeTurn?.promptId, turnId: this.activeTurn?.promptId,
-            toolCallId, payload: { toolCallId, title, options, expiresAt },
+            toolCallId, payload: presented,
         });
         pending.expiry = setTimeout(() => {
             this.autoResolvePermission(permissionId, pending, undefined, `no decision arrived within ${Math.round(timeoutMs / 1000)}s`);
         }, timeoutMs);
         pending.expiry.unref?.();
+        this.observation.publish();
     }
     serverRequestResolved(params) {
         const requestId = typeof params.requestId === 'string' || typeof params.requestId === 'number'
@@ -1101,6 +1149,8 @@ export class CodexAppServerSession {
         this.resolvePermission(permissionId, pending, 'denied', 'automatic', 'deny_once', policy, reason);
     }
     resolvePermission(permissionId, pending, decision, decisionSource, optionId, policy, reason) {
+        if (!this.pendingPermissions.size && this.readiness === 'awaiting_permission')
+            this.readiness = 'running';
         this.events.emit('permission', {
             turnId: this.activeTurn?.promptId, origin: this.activeTurn?.origin,
             permissionId, toolCallId: pending.toolCallId, status: 'completed', decision,
@@ -1113,8 +1163,7 @@ export class CodexAppServerSession {
             payload: { decision, decisionSource, ...(optionId ? { optionId } : {}),
                 ...(policy ? { policy } : {}), ...(reason ? { reason } : {}) },
         });
-        if (!this.pendingPermissions.size && this.readiness === 'awaiting_permission')
-            this.readiness = 'running';
+        this.observation.publish();
         this.scheduleTerminalReconciliation();
     }
     currentEvent(event) {
@@ -1162,10 +1211,12 @@ export class CodexAppServerSession {
             if (this.activeTurn)
                 this.finishTurn('failed', this.lastError);
         }
+        this.observation.publish();
     }
     fail(error) {
         this.lastError = error instanceof Error ? error.message : String(error);
         this.readiness = 'failed';
         this.events.emit('error', { text: this.lastError });
+        this.observation.publish();
     }
 }

package/dist/session/control.d.ts

@@ -1,6 +1,7 @@
 import type { LayoutControlRequest } from '../rooms-tasks/layout-control.js';
 import type { SupervisorCorrespondence, AgentHistoryQuery } from '../agent-ours/correspondence.js';
 import { type Socket } from 'node:net';
+import { type PassiveConversationFollowRequest } from './conversation-replay.js';
 import type { AgentSession, ControlFailureKind, SessionEvent, SessionSnapshot } from './types.js';
 import type { OwnerChannelHandle, OwnerChannelManagementRequest } from '../owner-channel/channel.js';
 import type { ScheduledLoopManagerHandle } from '../loops/manager.js';
@@ -26,7 +27,8 @@ export interface ControlRequest {
     ownerChannel?: OwnerChannelManagementRequest;
     loop?: string;
     /** Conversation cursor: replay strictly after this durable seq. */
-    after?: string;
+    after?: string | number;
+    expectedGeneration?: string;
     limit?: number;
     /** Idempotency key for v3 mutations. */
     commandId?: string;
@@ -141,6 +143,7 @@ export declare class RoleControlServer {
     private handle;
     /** Version and capability gate shared by every conversation v3 command. */
     private requireConversation;
+    private observationFeatures;
     private write;
 }
 /**
@@ -160,7 +163,7 @@ export declare function followControl(stateDir: string, onMessage: (message: Rec
  * `{ version, conversationEvent }`. Closing the socket detaches the
  * controller-presence this connection contributed.
  */
-export declare function followConversation(stateDir: string, after: string | undefined, onMessage: (message: Record<string, unknown>) => void): Promise<{
+export declare function followConversation(stateDir: string, after: string | undefined | PassiveConversationFollowRequest, onMessage: (message: Record<string, unknown>) => void): Promise<{
     socket: Socket;
     close(): void;
 }>;

package/dist/session/control.js

@@ -4,6 +4,7 @@ import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node
 import { createConnection, createServer } from 'node:net';
 import { join } from 'node:path';
 import { SessionControlError } from './types.js';
+import { MAX_CONVERSATION_RECORD_BYTES, startConversationReplay } from './conversation-replay.js';
 import { validateFleetAuditBegin, validateFleetAuditFinish, validateFleetAuditPresentations, } from '../fleet-command-audit.js';
 import { interruptSession, queueSessionPrompt, respondSessionPermission, respondSessionPermissionV2, } from '../application/session-mutations.js';
 const MAX_LINE_BYTES = 64 * 1024;
@@ -194,6 +195,12 @@ export class RoleControlServer {
                     continue;
                 void this.handle(line, socket).then(follow => {
                     if (follow) {
+                        if (socket.destroyed) {
+                            follow.stop();
+                            if (follow.controller)
+                                this.session.setControllerAttached(false);
+                            return;
+                        }
                         if (unsubscribe) {
                             unsubscribe();
                             if (controllerAttached)
@@ -242,6 +249,7 @@ export class RoleControlServer {
                                 'events_since', 'observer_follow', 'retained_range',
                                 ...(this.correspondence ? ['agent_correspondence'] : []),
                                 ...(this.session.conversationPage ? ['conversation_v3'] : []),
+                                ...this.observationFeatures(),
                                 ...(this.session.submitPromptBrowser ? ['generation_bound_prompts'] : []),
                                 ...(this.session.liveVoiceSupported ? ['idle_bound_prompts', 'targeted_voice_interrupt'] : []),
                                 ...(this.session.capabilities?.steering ? ['steering'] : []),
@@ -427,20 +435,98 @@ export class RoleControlServer {
                 }
                 case 'conversation_page': {
                     this.requireConversation(request);
-                    this.write(socket, {
-                        version: 1, id: request.id, ok: true,
-                        result: this.session.conversationPage({
-                            after: request.after, limit: request.limit,
-                        }),
+                    const page = this.session.conversationPage({
+                        after: request.after === undefined ? undefined : String(request.after), limit: request.limit,
                     });
+                    if (this.session.observeConversation) {
+                        try {
+                            const observation = this.session.observeConversation(() => { });
+                            try {
+                                if (observation.snapshot.observationFailure) {
+                                    page.snapshot = { ...page.snapshot, historyDegraded: true, observationFailure: 'capture_failed' };
+                                }
+                                else
+                                    page.snapshot = observation.snapshot;
+                            }
+                            finally {
+                                observation.unsubscribe();
+                            }
+                        }
+                        catch {
+                            // Canonical REST recovery remains usable without a live observation.
+                            // Never substitute a frozen capture/barrier for the current store page.
+                            page.snapshot = { ...page.snapshot, historyDegraded: true, observationFailure: 'capture_failed' };
+                        }
+                    }
+                    this.write(socket, { version: 1, id: request.id, ok: true, result: page });
                     return;
                 }
                 case 'conversation_follow': {
                     this.requireConversation(request);
+                    if (request.controller === false && request.expectedGeneration !== undefined) {
+                        let stopped = false;
+                        let heartbeat;
+                        let writing = Promise.resolve();
+                        const send = (message) => {
+                            const result = writing.then(() => writeMessage(message));
+                            writing = result.catch(() => { });
+                            return result;
+                        };
+                        const writeMessage = async (message) => {
+                            // Stream one replay record progressively; don't queue a valid 16 MiB record
+                            // into the 8 MiB pending-output budget. Framing is owned by the transport.
+                            const bytes = Buffer.from(JSON.stringify({ version: 1, ...message }) + '\n');
+                            for (let offset = 0; offset < bytes.length; offset += 64 * 1024) {
+                                if (stopped || socket.destroyed)
+                                    throw new Error('conversation socket closed');
+                                if (!socket.write(bytes.subarray(offset, offset + 64 * 1024))) {
+                                    await new Promise((resolve, reject) => {
+                                        const cleanup = () => { socket.off('drain', drained); socket.off('close', ended); socket.off('error', failed); };
+                                        const drained = () => { cleanup(); resolve(); };
+                                        const ended = () => { cleanup(); reject(new Error('conversation socket closed')); };
+                                        const failed = (error) => { cleanup(); reject(error); };
+                                        socket.once('drain', drained);
+                                        socket.once('close', ended);
+                                        socket.once('error', failed);
+                                    });
+                                }
+                            }
+                        };
+                        const follow = startConversationReplay(this.session, {
+                            expectedGeneration: request.expectedGeneration, after: request.after === undefined ? 0 : Number(request.after), controller: false,
+                        }, {
+                            replay: page => send({ conversationReplay: page }),
+                            ready: ready => send({ conversationReady: ready }),
+                            event: event => send({ conversationEvent: event }),
+                            state: state => send({ conversationState: state }),
+                            close: reason => {
+                                stopped = true;
+                                if (heartbeat)
+                                    clearInterval(heartbeat);
+                                if (reason && !socket.destroyed)
+                                    socket.end(JSON.stringify({ version: 1, id: request.id, ok: false, error: reason }) + '\n');
+                            },
+                        });
+                        const stop = () => { stopped = true; if (heartbeat)
+                            clearInterval(heartbeat); follow.close(); };
+                        let heartbeatPending = false;
+                        if (!stopped) {
+                            heartbeat = setInterval(() => {
+                                if (heartbeatPending || stopped)
+                                    return;
+                                heartbeatPending = true;
+                                void send({ controlHeartbeat: true }).catch(() => { stop(); socket.destroy(); })
+                                    .finally(() => { heartbeatPending = false; });
+                            }, 2_000);
+                            heartbeat.unref();
+                        }
+                        socket.once('close', stop);
+                        return { controller: false, stop: () => { socket.off('close', stop); stop(); } };
+                    }
                     this.write(socket, {
                         version: 1, id: request.id, ok: true,
                         result: this.session.conversationPage({
-                            after: request.after, limit: request.limit,
+                            after: request.after === undefined ? undefined : String(request.after), limit: request.limit,
                         }),
                     });
                     // A live conversation view is an attached controller: permission
@@ -560,6 +646,23 @@ export class RoleControlServer {
         if (!this.session.conversationPage || !this.session.subscribeConversation)
             throw new SessionControlError('rejected', 'this role has no conversation ledger');
     }
+    observationFeatures() {
+        if (!this.session.observeConversation || !this.session.replayConversation || !this.session.subscribeConversation || !this.session.subscribeConversationFailure)
+            return [];
+        try {
+            const observation = this.session.observeConversation(() => { });
+            try {
+                return observation.snapshot.observationFailure || !this.session.conversationReplayAvailable?.(observation.snapshot.sessionGeneration)
+                    ? [] : ['conversation_observation', 'control_heartbeat'];
+            }
+            finally {
+                observation.unsubscribe();
+            }
+        }
+        catch {
+            return [];
+        }
+    }
     write(socket, response) {
         if (!socket.destroyed)
             socket.write(JSON.stringify(response) + '\n');
@@ -652,32 +755,54 @@ export async function followControl(stateDir, onMessage) {
  * controller-presence this connection contributed.
  */
 export async function followConversation(stateDir, after, onMessage) {
+    const options = typeof after === 'object' ? after : undefined;
+    options?.signal?.throwIfAborted();
     const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
     const socket = createConnection(controlSocketPath(stateDir));
     socket.setEncoding('utf8');
-    let buffer = '';
+    // Admit one maximum-size logical record plus its actual private wrapper.
+    // coveredThrough is a safe integer. JSON brackets/envelope are outside the record budget.
+    const privateEnvelopeBytes = Math.max(Buffer.byteLength(JSON.stringify({ version: 1, conversationReplay: { events: [], coveredThrough: Number.MAX_SAFE_INTEGER } })), Buffer.byteLength(JSON.stringify({ version: 1, conversationReady: { snapshot: null, coveredThrough: Number.MAX_SAFE_INTEGER } })) - 4, Buffer.byteLength(JSON.stringify({ version: 1, conversationState: null })) - 4, Buffer.byteLength(JSON.stringify({ version: 1, conversationEvent: null })) - 4);
+    const limit = MAX_CONVERSATION_RECORD_BYTES + privateEnvelopeBytes;
+    let parts = [], bytes = 0;
     socket.on('data', chunk => {
-        buffer += chunk;
-        for (;;) {
-            const newline = buffer.indexOf('\n');
-            if (newline < 0)
-                break;
-            const line = buffer.slice(0, newline);
-            buffer = buffer.slice(newline + 1);
-            if (!line.trim())
-                continue;
-            try {
-                onMessage(JSON.parse(line));
+        for (const [index, part] of String(chunk).split('\n').entries()) {
+            if (index) {
+                const line = parts.join('');
+                parts = [];
+                bytes = 0;
+                if (line.trim()) {
+                    try {
+                        onMessage(JSON.parse(line));
+                    }
+                    catch {
+                        if (options) {
+                            socket.destroy(new Error('invalid conversation private frame'));
+                            return;
+                        }
+                    }
+                }
+            }
+            bytes += Buffer.byteLength(part);
+            if (options && bytes > limit) {
+                socket.destroy(new Error('conversation private frame exceeds assembly limit'));
+                return;
             }
-            catch { /* a torn frame ends this stream; the client resyncs over HTTP */ }
+            parts.push(part);
         }
     });
     await new Promise((resolve, reject) => {
+        const onAbort = () => { socket.destroy(); reject(new Error('conversation follow aborted')); };
+        options?.signal?.addEventListener('abort', onAbort, { once: true });
+        socket.once('close', () => options?.signal?.removeEventListener('abort', onAbort));
         socket.once('connect', resolve);
         socket.once('error', reject);
+        if (options?.signal?.aborted)
+            onAbort();
     });
     socket.write(JSON.stringify({
-        version: 3, id: randomUUID(), token, command: 'conversation_follow', after,
+        version: 3, id: randomUUID(), token, command: 'conversation_follow',
+        ...(options ? { expectedGeneration: options.expectedGeneration, after: options.after ?? 0, controller: false } : { after }),
     }) + '\n');
     return { socket, close: () => socket.destroy() };
 }

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

@@ -0,0 +1,25 @@
+import type { ConversationObservation as Observation, ConversationObservationState } from './conversation-types.js';
+type Capture = () => Omit<ConversationObservationState, 'stateRevision'>;
+/** Revision/publication only: the backend remains the sole owner of snapshot construction. */
+export declare class ConversationObservation {
+    private readonly capture;
+    private revision;
+    private fingerprint?;
+    private current?;
+    private scheduled;
+    private checkpointDepth;
+    private failed;
+    private readonly listeners;
+    constructor(capture: Capture);
+    observe(listener: (state: ConversationObservationState) => void): Observation;
+    /** Keep reentrant registration on the preceding coherent snapshot until the
+     * owner's synchronous durable append and inventory mutation finish together.
+     */
+    checkpoint<T>(mutation: () => T): T;
+    publish(): void;
+    private failCapture;
+    private deliver;
+    /** Fresh capture after a durable append's synchronous owner mutation completes. */
+    scheduleCapture(): void;
+}
+export {};

package/dist/session/conversation-observation.js

@@ -0,0 +1,100 @@
+/** Revision/publication only: the backend remains the sole owner of snapshot construction. */
+export class ConversationObservation {
+    capture;
+    revision = 0;
+    fingerprint;
+    current;
+    scheduled = false;
+    checkpointDepth = 0;
+    failed = false;
+    listeners = new Set();
+    constructor(capture) {
+        this.capture = capture;
+    }
+    observe(listener) {
+        // Registration and synchronous stable capture have no await gap. Inside an
+        // owner checkpoint, publish retains the preceding snapshot and its barrier.
+        // A reconnect never resets this generation's revision or implies control.
+        this.publish();
+        if (!this.current)
+            throw new Error('conversation observation unavailable: capture_failed');
+        this.listeners.add(listener);
+        return {
+            snapshot: structuredClone(this.current),
+            unsubscribe: () => { this.listeners.delete(listener); },
+        };
+    }
+    /** Keep reentrant registration on the preceding coherent snapshot until the
+     * owner's synchronous durable append and inventory mutation finish together.
+     */
+    checkpoint(mutation) {
+        if (this.checkpointDepth === 0)
+            this.publish();
+        this.checkpointDepth++;
+        try {
+            return mutation();
+        }
+        finally {
+            this.checkpointDepth--;
+            if (this.checkpointDepth === 0)
+                this.publish();
+        }
+    }
+    publish() {
+        if (this.checkpointDepth > 0 || this.failed)
+            return;
+        try {
+            const captured = this.capture();
+            const fingerprint = JSON.stringify(captured);
+            if (fingerprint === this.fingerprint)
+                return;
+            const current = structuredClone({ ...captured, stateRevision: this.revision + 1 });
+            this.fingerprint = fingerprint;
+            this.current = current;
+            this.revision++;
+        }
+        catch {
+            this.failCapture();
+            return;
+        }
+        this.deliver();
+    }
+    failCapture() {
+        if (this.failed)
+            return;
+        this.failed = true;
+        // Retain the entire preceding coherent state and its barrier. Consumers
+        // must stop healthy coverage; owner admission/receipt processing continues.
+        if (this.current) {
+            this.current = { ...this.current, stateRevision: ++this.revision, observationFailure: 'capture_failed' };
+            this.deliver();
+        }
+    }
+    deliver() {
+        for (const listener of this.listeners) {
+            let state;
+            try {
+                state = structuredClone(this.current);
+            }
+            catch {
+                this.failCapture();
+                return;
+            }
+            // An observer callback cannot break the owning backend's transition.
+            try {
+                listener(state);
+            }
+            catch { /* passive observer */ }
+        }
+    }
+    /** Fresh capture after a durable append's synchronous owner mutation completes. */
+    scheduleCapture() {
+        if (this.scheduled)
+            return;
+        this.scheduled = true;
+        queueMicrotask(() => {
+            this.scheduled = false;
+            this.publish();
+        });
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { ConversationEventV1 } from './conversation-types.js';
+export declare const MAX_REPLAY_BUFFER_BYTES: number;
+export declare const MAX_CONVERSATION_RECORD_BYTES: number;
+export interface ConversationReplayRequest {
+    expectedGeneration: string;
+    after: number;
+    through: number;
+    pageSize?: number;
+    signal?: AbortSignal;
+}
+export interface ConversationReplayPage {
+    events: ConversationEventV1[];
+    /** Storage coverage, including invisible events; never a visible-event cursor. */
+    coveredThrough: number;
+}
+export declare class ReplayCoverageError extends Error {
+    constructor(detail: string);
+}
+/** Bounded reads and explicit scheduling even when a whole segment is cached by the OS. */
+export declare function replayLines(path: string, signal?: AbortSignal): AsyncGenerator<string>;
+import type { ConversationObservation, ConversationObservationState } from './conversation-types.js';
+export interface PassiveConversationFollowRequest {
+    expectedGeneration: string;
+    after?: number;
+    controller: false;
+    signal?: AbortSignal;
+}
+export interface ConversationReplayReady {
+    snapshot: ConversationObservationState;
+    coveredThrough: number;
+}
+interface ReplayOwner {
+    observeConversation?(listener: (state: ConversationObservationState) => void): ConversationObservation;
+    subscribeConversationFailure?(listener: (generation: string) => void): () => void;
+    subscribeConversation?(listener: (event: ConversationEventV1) => void): () => void;
+    replayConversation?(request: ConversationReplayRequest): AsyncIterable<ConversationReplayPage>;
+}
+export interface ConversationReplaySink {
+    replay(page: ConversationReplayPage): void | Promise<void>;
+    ready(ready: ConversationReplayReady): void | Promise<void>;
+    event(event: ConversationEventV1): void | Promise<void>;
+    state(state: ConversationObservationState): void | Promise<void>;
+    close(reason?: string): void;
+}
+/** Passive owner-turn registration, complete replay, ready, then buffered post-barrier delivery. */
+export declare function startConversationReplay(owner: ReplayOwner, request: PassiveConversationFollowRequest, sink: ConversationReplaySink): {
+    ready: Promise<void>;
+    close: () => void;
+};
+export {};