@floegence/floeterm-terminal-web 0.5.19 → 0.5.21

package/README.md

@@ -51,6 +51,17 @@ const core = new TerminalCore(
 await core.initialize();
 ```
 
+Hosts can preload the dynamic Ghostty module, WASM, and renderer resources before a terminal surface is visible without creating a `TerminalCore`:
+
+```ts
+import { preloadTerminalResources } from '@floegence/floeterm-terminal-web';
+
+await preloadTerminalResources({ signal });
+await core.initialize({ priority: 'interactive', signal });
+```
+
+Resource loading is single-flight and retryable after a real import or WASM initialization failure. Caller cancellation only stops that caller from waiting; it does not interrupt shared resource initialization. Core initialization is globally bounded, gives queued interactive work priority over background work, and shares the actual ready promise across duplicate calls.
+
 ## Notes
 
 - You must provide a `TerminalTransport` and `TerminalEventSource` for the managed controller.
@@ -96,6 +107,26 @@ If a page reports `historyReset` or changes `historyGeneration` while catch-up i
 
 Use `TerminalCore.writeHistory` for history batches. Its auto-response suppression is scoped to that parser write and ends at its completion callback, so later live output and user input use normal terminal behavior.
 
+Running sessions can prepare bounded history before a visible terminal exists. Preparation does not create a Core, attach a session, resize a PTY, or subscribe to live output:
+
+```ts
+const preparedHistory = await preparePagedTerminalHistory({
+  fetchPage: request => transport.historyPage(sessionId, request),
+  maxBytes: 4 * 1024 * 1024,
+  signal,
+});
+
+const attachGeneration = output.beginAttach(0);
+const attach = await transport.attachWithHistoryBoundary(sessionId, cols, rows);
+await output.completeAttach(attachGeneration, attach.historyBoundarySequence, {
+  preparedHistory,
+});
+```
+
+Prepared history is renderer-neutral and pins `historyGeneration`, `firstRetainedSequence`, and `snapshotEndSequence`. The visible attach validates those boundaries, replays the seed once, and fetches only the missing delta. A generation reset, retention advance, stale fence, or malformed seed discards it and falls back to the normal full recovery path.
+
+`preparePagedTerminalHistory` requires those three metadata fields on every prepared page and passes the remaining retained-byte budget as `request.maxBytes` so transports can bound each page as well. The helper always enforces its retained seed budget after a page returns; adapters should honor the request hint to keep peak response memory bounded too.
+
 ## Restorable In-Memory Snapshots
 
 Adaptive host worksets can release inactive renderers without closing their PTY sessions:

package/dist/core/PagedTerminalOutputCoordinator.d.ts

@@ -1,10 +1,11 @@
-import type { TerminalOutputPipelineChunk, TerminalOutputPipelineScheduler } from './TerminalOutputPipeline';
+import type { TerminalOutputPipelineChunk, TerminalOutputPipelineScheduler } from './TerminalOutputPipeline.js';
 export type PagedTerminalOutputState = 'idle' | 'initial-replay' | 'live' | 'catching-up' | 'retry-wait' | 'failed' | 'disposed';
 export interface PagedTerminalHistoryRequest {
     startSequence: number;
     endSequence?: number;
     historyGeneration?: number;
     cursor?: string | number;
+    maxBytes?: number;
     signal: AbortSignal;
 }
 export interface PagedTerminalHistoryPage {
@@ -21,6 +22,27 @@ export interface PagedTerminalHistoryPage {
     coveredBytes?: number;
     totalBytes?: number;
 }
+export interface PreparePagedTerminalHistoryOptions {
+    fetchPage(request: PagedTerminalHistoryRequest): Promise<PagedTerminalHistoryPage>;
+    startSequence?: number;
+    maxBytes?: number;
+    signal?: AbortSignal;
+    yieldControl?: () => void | Promise<void>;
+}
+export interface PreparedPagedTerminalHistory {
+    readonly chunks: readonly Readonly<TerminalOutputPipelineChunk>[];
+    readonly requestedStartSequence: number;
+    readonly firstRetainedSequence: number;
+    readonly coveredThroughSequence: number;
+    readonly snapshotEndSequence: number;
+    readonly historyGeneration: number;
+    readonly byteLength: number;
+    readonly pageCount: number;
+    readonly complete: boolean;
+}
+export interface PagedTerminalCompleteAttachOptions {
+    preparedHistory?: PreparedPagedTerminalHistory;
+}
 export type PagedTerminalHistoryTruncationReason = 'history-evicted' | 'retained-live-overflow';
 export type PagedTerminalOutputFailureCode = 'history_fetch_failed' | 'history_coverage_incomplete' | 'history_contract_missing' | 'history_contract_invalid' | 'retained_live_overflow' | 'history_evicted';
 export interface PagedTerminalOutputFailure {
@@ -84,9 +106,10 @@ export interface PagedTerminalOutputCoordinatorHandle {
 }
 export interface AtomicPagedTerminalOutputCoordinatorHandle extends PagedTerminalOutputCoordinatorHandle {
     beginAttach(startSequence?: number): number;
-    completeAttach(attachGeneration: number, snapshotEndSequence?: number): Promise<void>;
-    attach(startSequence?: number, snapshotEndSequence?: number): Promise<void>;
+    completeAttach(attachGeneration: number, snapshotEndSequence?: number, options?: PagedTerminalCompleteAttachOptions): Promise<void>;
+    attach(startSequence?: number, snapshotEndSequence?: number, options?: PagedTerminalCompleteAttachOptions): Promise<void>;
 }
+export declare const preparePagedTerminalHistory: (options: PreparePagedTerminalHistoryOptions) => Promise<PreparedPagedTerminalHistory>;
 export declare const createPagedTerminalOutputCoordinator: (options: PagedTerminalOutputCoordinatorOptions) => AtomicPagedTerminalOutputCoordinatorHandle;
 export {};
 //# sourceMappingURL=PagedTerminalOutputCoordinator.d.ts.map

package/dist/core/PagedTerminalOutputCoordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PagedTerminalOutputCoordinator.d.ts","sourceRoot":"","sources":["../../src/core/PagedTerminalOutputCoordinator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PagedTerminalOutputCoordinator.d.ts","sourceRoot":"","sources":["../../src/core/PagedTerminalOutputCoordinator.ts"],"names":[],"mappings":"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"}

package/dist/core/PagedTerminalOutputCoordinator.js

@@ -1,9 +1,11 @@
+import { scheduleUiTurn } from '../internal/scheduleUiTurn.js';
 const DEFAULT_POLICY = {
     maxRetainedLiveChunks: 2048,
     maxRetainedLiveBytes: 8 * 1024 * 1024,
     retryDelaysMs: [250, 1000, 4000],
     maxWriteBatchBytes: 256 * 1024,
 };
+const DEFAULT_PREPARED_HISTORY_MAX_BYTES = 32 * 1024 * 1024;
 const normalizePositiveInteger = (value, fallback) => (typeof value === 'number' && Number.isSafeInteger(value) && value > 0
     ? value
     : fallback);
@@ -33,6 +35,213 @@ class HistoryContractError extends Error {
         this.firstRetainedSequence = firstRetainedSequence;
     }
 }
+const createAbortError = () => {
+    if (typeof DOMException !== 'undefined')
+        return new DOMException('Operation aborted', 'AbortError');
+    const error = new Error('Operation aborted');
+    error.name = 'AbortError';
+    return error;
+};
+const throwIfAborted = (signal) => {
+    if (signal?.aborted)
+        throw createAbortError();
+};
+const waitForPreparedPage = (promise, signal) => {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(createAbortError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(createAbortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(value => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, error => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+};
+const yieldHistoryPreparation = async (signal, yieldControl) => {
+    throwIfAborted(signal);
+    if (yieldControl) {
+        await yieldControl();
+        throwIfAborted(signal);
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const cancelTurn = scheduleUiTurn(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        });
+        const onAbort = () => {
+            cancelTurn();
+            reject(createAbortError());
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+};
+const clonePreparedChunk = (chunk) => {
+    const immutableData = new Uint8Array(chunk.data);
+    return Object.freeze({
+        get data() {
+            return new Uint8Array(immutableData);
+        },
+        ...(chunk.sequence !== undefined ? { sequence: chunk.sequence } : {}),
+        ...(chunk.timestampMs !== undefined ? { timestampMs: chunk.timestampMs } : {}),
+    });
+};
+export const preparePagedTerminalHistory = async (options) => {
+    const requestedStartSequence = normalizeSequence(options.startSequence ?? 1, 'startSequence');
+    const maxBytes = normalizePositiveInteger(options.maxBytes, DEFAULT_PREPARED_HISTORY_MAX_BYTES);
+    let startSequence = Math.max(1, requestedStartSequence);
+    let cursor;
+    let historyGeneration;
+    let snapshotEndSequence;
+    let firstRetainedSequence;
+    let coveredThroughSequence = Math.max(0, startSequence - 1);
+    let byteLength = 0;
+    let pageCount = 0;
+    let chunks = [];
+    let rebaseAttempts = 0;
+    const requestSignal = options.signal ?? new AbortController().signal;
+    while (true) {
+        throwIfAborted(options.signal);
+        const page = await waitForPreparedPage(options.fetchPage({
+            startSequence,
+            endSequence: snapshotEndSequence,
+            historyGeneration,
+            cursor,
+            maxBytes: Math.max(1, maxBytes - byteLength),
+            signal: requestSignal,
+        }), options.signal);
+        throwIfAborted(options.signal);
+        pageCount += 1;
+        if (!Object.prototype.hasOwnProperty.call(page, 'coveredThroughSequence')) {
+            throw new HistoryContractError('history_contract_missing', 'coveredThroughSequence is required');
+        }
+        if (!Object.prototype.hasOwnProperty.call(page, 'snapshotEndSequence')) {
+            throw new HistoryContractError('history_contract_missing', 'snapshotEndSequence is required');
+        }
+        if (!Object.prototype.hasOwnProperty.call(page, 'historyGeneration')) {
+            throw new HistoryContractError('history_contract_missing', 'historyGeneration is required');
+        }
+        if (!Object.prototype.hasOwnProperty.call(page, 'firstRetainedSequence')
+            && !Object.prototype.hasOwnProperty.call(page, 'firstAvailableSequence')) {
+            throw new HistoryContractError('history_contract_missing', 'firstRetainedSequence is required');
+        }
+        const pageCoverage = normalizeSequence(page.coveredThroughSequence, 'coveredThroughSequence');
+        const pageSnapshotEnd = normalizeSequence(page.snapshotEndSequence, 'snapshotEndSequence');
+        const pageGeneration = normalizeSequence(page.historyGeneration, 'historyGeneration');
+        const pageFirstRetained = normalizeSequence(page.firstRetainedSequence ?? page.firstAvailableSequence, 'firstRetainedSequence');
+        const generationChanged = historyGeneration !== undefined && pageGeneration !== historyGeneration;
+        const snapshotChanged = snapshotEndSequence !== undefined && pageSnapshotEnd !== snapshotEndSequence;
+        const retentionAdvanced = firstRetainedSequence !== undefined
+            && pageFirstRetained > firstRetainedSequence;
+        if (historyGeneration !== undefined
+            && (page.historyReset || page.historyTruncated || generationChanged || snapshotChanged || retentionAdvanced)) {
+            if (rebaseAttempts >= 2) {
+                throw new HistoryContractError('history_contract_invalid', 'terminal history changed repeatedly while preparing a stable snapshot');
+            }
+            rebaseAttempts += 1;
+            startSequence = Math.max(1, pageFirstRetained);
+            cursor = undefined;
+            historyGeneration = undefined;
+            snapshotEndSequence = undefined;
+            firstRetainedSequence = undefined;
+            coveredThroughSequence = startSequence - 1;
+            byteLength = 0;
+            chunks = [];
+            await yieldHistoryPreparation(options.signal, options.yieldControl);
+            continue;
+        }
+        if (pageCoverage < coveredThroughSequence) {
+            throw new HistoryContractError('history_contract_invalid', 'coveredThroughSequence regressed');
+        }
+        if (pageCoverage > pageSnapshotEnd) {
+            throw new HistoryContractError('history_contract_invalid', 'coveredThroughSequence exceeded snapshotEndSequence');
+        }
+        let previousChunkSequence = coveredThroughSequence;
+        for (const chunk of page.chunks) {
+            const sequence = normalizeSequence(chunk.sequence, 'chunk.sequence');
+            if (sequence <= previousChunkSequence || sequence > pageCoverage) {
+                throw new HistoryContractError('history_contract_invalid', 'prepared history chunks must have strictly increasing sequences within page coverage');
+            }
+            previousChunkSequence = sequence;
+        }
+        if (pageCoverage > Math.max(0, pageFirstRetained - 1)
+            && previousChunkSequence !== pageCoverage) {
+            throw new HistoryContractError('history_contract_invalid', 'prepared history page did not include its covered terminal sequence');
+        }
+        historyGeneration = pageGeneration;
+        snapshotEndSequence = pageSnapshotEnd;
+        firstRetainedSequence = pageFirstRetained;
+        if (pageFirstRetained > startSequence) {
+            coveredThroughSequence = Math.max(coveredThroughSequence, pageFirstRetained - 1);
+        }
+        const pageBytes = page.chunks.reduce((sum, chunk) => sum + chunk.data.byteLength, 0);
+        const remainingBytes = maxBytes - byteLength;
+        if (pageBytes <= remainingBytes) {
+            chunks.push(...page.chunks.map(clonePreparedChunk));
+            byteLength += pageBytes;
+            coveredThroughSequence = Math.max(coveredThroughSequence, pageCoverage);
+        }
+        else {
+            for (const chunk of page.chunks) {
+                const sequence = normalizeSequence(chunk.sequence, 'chunk.sequence');
+                if (byteLength + chunk.data.byteLength > maxBytes)
+                    break;
+                chunks.push(clonePreparedChunk(chunk));
+                byteLength += chunk.data.byteLength;
+                coveredThroughSequence = Math.max(coveredThroughSequence, sequence);
+            }
+            return Object.freeze({
+                chunks: Object.freeze(chunks),
+                requestedStartSequence,
+                firstRetainedSequence,
+                coveredThroughSequence,
+                snapshotEndSequence,
+                historyGeneration,
+                byteLength,
+                pageCount,
+                complete: false,
+            });
+        }
+        if (!page.hasMore) {
+            return Object.freeze({
+                chunks: Object.freeze(chunks),
+                requestedStartSequence,
+                firstRetainedSequence,
+                coveredThroughSequence,
+                snapshotEndSequence,
+                historyGeneration,
+                byteLength,
+                pageCount,
+                complete: coveredThroughSequence >= snapshotEndSequence,
+            });
+        }
+        if (byteLength >= maxBytes) {
+            return Object.freeze({
+                chunks: Object.freeze(chunks),
+                requestedStartSequence,
+                firstRetainedSequence,
+                coveredThroughSequence,
+                snapshotEndSequence,
+                historyGeneration,
+                byteLength,
+                pageCount,
+                complete: false,
+            });
+        }
+        if (page.nextCursor === undefined) {
+            throw new HistoryContractError('history_contract_invalid', 'nextCursor is required when hasMore is true');
+        }
+        cursor = page.nextCursor;
+        startSequence = pageCoverage + 1;
+        await yieldHistoryPreparation(options.signal, options.yieldControl);
+    }
+};
 class PagedTerminalOutputCoordinator {
     constructor(options) {
         this.active = true;
@@ -64,6 +273,7 @@ class PagedTerminalOutputCoordinator {
         this.writerQuiescenceWaiters = [];
         this.pausedRecoveryPending = false;
         this.droppedLiveThroughSequence = 0;
+        this.preparedHistory = null;
         this.options = options;
         this.policy = {
             maxRetainedLiveChunks: normalizePositiveInteger(options.policy?.maxRetainedLiveChunks, DEFAULT_POLICY.maxRetainedLiveChunks),
@@ -74,9 +284,9 @@ class PagedTerminalOutputCoordinator {
             maxWriteBatchBytes: normalizePositiveInteger(options.policy?.maxWriteBatchBytes, DEFAULT_POLICY.maxWriteBatchBytes),
         };
     }
-    async attach(startSequence = 1, snapshotEndSequence) {
+    async attach(startSequence = 1, snapshotEndSequence, options) {
         const attachGeneration = this.beginAttach(startSequence);
-        await this.completeAttach(attachGeneration, snapshotEndSequence);
+        await this.completeAttach(attachGeneration, snapshotEndSequence, options);
     }
     beginAttach(startSequence = 1) {
         if (this.disposed)
@@ -102,14 +312,16 @@ class PagedTerminalOutputCoordinator {
         this.failure = null;
         this.lastError = null;
         this.historyRebasePrepared = false;
+        this.preparedHistory = null;
         this.setState('idle');
         return this.generation;
     }
-    async completeAttach(attachGeneration, snapshotEndSequence) {
+    async completeAttach(attachGeneration, snapshotEndSequence, options = {}) {
         if (this.disposed || !this.isCurrent(attachGeneration))
             return;
         this.explicitAttachFence = snapshotEndSequence !== undefined;
         this.recoveryEndSequence = normalizeSequence(snapshotEndSequence, 'snapshotEndSequence', true);
+        this.preparedHistory = this.acceptPreparedHistory(options.preparedHistory);
         if (this.explicitAttachFence && this.recoveryEndSequence === 0) {
             if (this.needsRebase) {
                 this.prepareRetainedLiveRebase();
@@ -201,6 +413,7 @@ class PagedTerminalOutputCoordinator {
         this.failure = null;
         this.lastError = null;
         this.historyRebasePrepared = false;
+        this.preparedHistory = null;
         this.setState('idle');
         this.resolveBaselineWaiters();
     }
@@ -237,6 +450,7 @@ class PagedTerminalOutputCoordinator {
         this.pendingLiveWrites = [];
         this.liveWriteScheduled = false;
         this.pausedRecoveryPending = false;
+        this.preparedHistory = null;
         this.setState('disposed');
         this.resolveBaselineWaiters();
     }
@@ -252,6 +466,62 @@ class PagedTerminalOutputCoordinator {
         this.retryAttempt = 0;
         void this.runRecovery();
     }
+    acceptPreparedHistory(preparedHistory) {
+        if (!preparedHistory || this.recoveryEndSequence === undefined)
+            return null;
+        try {
+            const requestedStart = normalizeSequence(preparedHistory.requestedStartSequence, 'preparedHistory.requestedStartSequence');
+            const firstRetained = normalizeSequence(preparedHistory.firstRetainedSequence, 'preparedHistory.firstRetainedSequence');
+            const coveredThrough = normalizeSequence(preparedHistory.coveredThroughSequence, 'preparedHistory.coveredThroughSequence');
+            const snapshotEnd = normalizeSequence(preparedHistory.snapshotEndSequence, 'preparedHistory.snapshotEndSequence');
+            normalizeSequence(preparedHistory.historyGeneration, 'preparedHistory.historyGeneration');
+            normalizeSequence(preparedHistory.byteLength, 'preparedHistory.byteLength');
+            normalizeSequence(preparedHistory.pageCount, 'preparedHistory.pageCount');
+            const expectedStart = Math.max(1, this.recoveryStartSequence);
+            if (requestedStart > expectedStart)
+                return null;
+            if (firstRetained > coveredThrough + 1)
+                return null;
+            if (coveredThrough < expectedStart - 1 || coveredThrough > snapshotEnd)
+                return null;
+            if (snapshotEnd > this.recoveryEndSequence || coveredThrough > this.recoveryEndSequence)
+                return null;
+            if (!Array.isArray(preparedHistory.chunks))
+                return null;
+            let previousChunkSequence = Math.max(0, firstRetained - 1);
+            let preparedBytes = 0;
+            for (const chunk of preparedHistory.chunks) {
+                if (!(chunk.data instanceof Uint8Array))
+                    return null;
+                const sequence = normalizeSequence(chunk.sequence, 'preparedHistory.chunk.sequence');
+                if (sequence <= previousChunkSequence || sequence > coveredThrough)
+                    return null;
+                previousChunkSequence = sequence;
+                preparedBytes += chunk.data.byteLength;
+            }
+            if (preparedBytes !== preparedHistory.byteLength)
+                return null;
+            if (coveredThrough >= Math.max(1, firstRetained)
+                && previousChunkSequence !== coveredThrough)
+                return null;
+            if (preparedHistory.complete !== (coveredThrough >= snapshotEnd))
+                return null;
+            if (firstRetained > expectedStart) {
+                this.options.clear?.();
+                this.options.onHistoryTruncated?.('history-evicted');
+            }
+            return preparedHistory;
+        }
+        catch {
+            return null;
+        }
+    }
+    discardPreparedHistoryForFullRecovery() {
+        this.preparedHistory = null;
+        this.coveredThroughSequence = Math.max(0, this.recoveryStartSequence - 1);
+        this.scheduledThroughSequence = this.coveredThroughSequence;
+        this.historyRebasePrepared = false;
+    }
     async runRecovery() {
         if (this.disposed || this.recoveryRunning)
             return;
@@ -268,13 +538,26 @@ class PagedTerminalOutputCoordinator {
             await this.writeChain;
             if (!this.isRecoveryCurrent(generation, recoverySerial, controller))
                 return;
-            const historyChunks = [];
+            const preparedHistory = this.preparedHistory;
+            const historyChunks = preparedHistory
+                ? preparedHistory.chunks.map(item => ({ ...item, data: new Uint8Array(item.data), source: 'history' }))
+                : [];
             let cursor;
-            let startSequence = this.recoveryStartSequence;
+            let startSequence = preparedHistory
+                ? Math.max(1, preparedHistory.coveredThroughSequence
+                    + (preparedHistory.coveredThroughSequence < (this.recoveryEndSequence ?? 0) ? 1 : 0))
+                : this.recoveryStartSequence;
             let snapshotEnd = this.recoveryEndSequence;
-            let historyGeneration;
-            let coveredEnd = this.coveredThroughSequence;
-            let firstPage = true;
+            let historyGeneration = preparedHistory?.historyGeneration;
+            let coveredEnd = preparedHistory?.coveredThroughSequence ?? this.coveredThroughSequence;
+            let firstPage = preparedHistory === null;
+            const preparedBaseline = preparedHistory === null
+                ? undefined
+                : Math.max(Math.max(1, this.recoveryStartSequence) - 1, preparedHistory.firstRetainedSequence - 1);
+            if (preparedBaseline !== undefined) {
+                this.coveredThroughSequence = preparedBaseline;
+                this.scheduledThroughSequence = preparedBaseline;
+            }
             do {
                 const page = await this.options.fetchPage({
                     startSequence,
@@ -288,21 +571,32 @@ class PagedTerminalOutputCoordinator {
                 const pageSnapshotEnd = normalizeSequence(page.snapshotEndSequence, 'snapshotEndSequence', true);
                 const pageGeneration = normalizeSequence(page.historyGeneration, 'historyGeneration', true);
                 const firstRetained = normalizeSequence(page.firstRetainedSequence ?? page.firstAvailableSequence, 'firstRetainedSequence', true);
+                if (preparedHistory !== null
+                    && (pageSnapshotEnd === undefined || pageGeneration === undefined || firstRetained === undefined)) {
+                    this.discardPreparedHistoryForFullRecovery();
+                    this.recoveryRunning = false;
+                    await this.runRecovery();
+                    return;
+                }
                 const generationChanged = historyGeneration !== undefined
                     && pageGeneration !== undefined
                     && pageGeneration !== historyGeneration;
                 const effectivePageStart = Math.max(1, startSequence);
                 const retentionAdvanced = firstRetained !== undefined
-                    && firstRetained > effectivePageStart;
+                    && (firstRetained > effectivePageStart
+                        || (preparedHistory !== null && firstRetained > preparedHistory.firstRetainedSequence));
                 const generationNeedsRebase = page.historyReset || generationChanged;
                 const retentionNeedsRebase = page.historyTruncated || retentionAdvanced;
                 const fencedRangeFullyEvicted = this.recoveryEndSequence !== undefined
                     && firstRetained !== undefined
                     && firstRetained > this.recoveryEndSequence;
                 if (!this.historyRebasePrepared && (generationNeedsRebase || retentionNeedsRebase)) {
+                    this.preparedHistory = null;
                     if (fencedRangeFullyEvicted) {
                         this.options.clear?.();
                         this.options.onHistoryTruncated?.('history-evicted');
+                        if (preparedHistory !== null)
+                            historyChunks.length = 0;
                         if (generationNeedsRebase) {
                             this.historyRebasePrepared = true;
                             this.recoveryRunning = false;
@@ -320,7 +614,19 @@ class PagedTerminalOutputCoordinator {
                 if (this.historyRebasePrepared && generationNeedsRebase) {
                     throw new HistoryContractError('history_contract_invalid', 'history generation reset persisted after rebase');
                 }
-                const coverage = this.validatePage(page, coveredEnd);
+                let coverage;
+                try {
+                    coverage = this.validatePage(page, coveredEnd);
+                }
+                catch (error) {
+                    if (preparedHistory === null)
+                        throw error;
+                    this.preparedHistory = null;
+                    this.prepareHistoryGenerationRebase(firstRetained);
+                    this.recoveryRunning = false;
+                    await this.runRecovery();
+                    return;
+                }
                 if (snapshotEnd !== undefined && coverage > snapshotEnd) {
                     throw new HistoryContractError('history_contract_invalid', 'coveredThroughSequence exceeded the recovery fence');
                 }
@@ -348,6 +654,13 @@ class PagedTerminalOutputCoordinator {
                 }
                 else {
                     if (snapshotEnd !== undefined && pageSnapshotEnd !== undefined && pageSnapshotEnd !== snapshotEnd) {
+                        if (preparedHistory !== null) {
+                            this.preparedHistory = null;
+                            this.prepareHistoryGenerationRebase(firstRetained);
+                            this.recoveryRunning = false;
+                            await this.runRecovery();
+                            return;
+                        }
                         throw new HistoryContractError('history_contract_invalid', 'snapshotEndSequence changed during pagination');
                     }
                 }
@@ -399,6 +712,7 @@ class PagedTerminalOutputCoordinator {
             this.retryAttempt = 0;
             this.lastError = null;
             this.failure = null;
+            this.preparedHistory = null;
             this.setState('live');
             this.recoveryRunning = false;
             this.drainRetainedLive();