@floegence/floeterm-terminal-web 0.5.18 → 0.5.20

package/dist/core/PagedTerminalOutputCoordinator.js

@@ -1,9 +1,11 @@
+import { scheduleUiTurn } from '../internal/scheduleUiTurn';
 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;
@@ -51,6 +260,7 @@ class PagedTerminalOutputCoordinator {
         this.lastError = null;
         this.failure = null;
         this.recoveryStartSequence = 1;
+        this.explicitAttachFence = false;
         this.recoveryKind = 'initial';
         this.recoveryRunning = false;
         this.needsRebase = false;
@@ -62,6 +272,8 @@ class PagedTerminalOutputCoordinator {
         this.activeWriters = 0;
         this.writerQuiescenceWaiters = [];
         this.pausedRecoveryPending = false;
+        this.droppedLiveThroughSequence = 0;
+        this.preparedHistory = null;
         this.options = options;
         this.policy = {
             maxRetainedLiveChunks: normalizePositiveInteger(options.policy?.maxRetainedLiveChunks, DEFAULT_POLICY.maxRetainedLiveChunks),
@@ -72,9 +284,13 @@ class PagedTerminalOutputCoordinator {
             maxWriteBatchBytes: normalizePositiveInteger(options.policy?.maxWriteBatchBytes, DEFAULT_POLICY.maxWriteBatchBytes),
         };
     }
-    async attach(startSequence = 1) {
+    async attach(startSequence = 1, snapshotEndSequence, options) {
+        const attachGeneration = this.beginAttach(startSequence);
+        await this.completeAttach(attachGeneration, snapshotEndSequence, options);
+    }
+    beginAttach(startSequence = 1) {
         if (this.disposed)
-            return;
+            return this.generation;
         this.cancelRecovery();
         this.resolveBaselineWaiters();
         this.retainedLive = [];
@@ -88,10 +304,37 @@ class PagedTerminalOutputCoordinator {
         this.scheduledThroughSequence = this.coveredThroughSequence;
         this.recoveryKind = 'initial';
         this.recoveryStartSequence = Math.max(0, Math.floor(startSequence));
+        this.recoveryEndSequence = undefined;
+        this.explicitAttachFence = false;
+        this.droppedLiveThroughSequence = 0;
+        this.needsRebase = false;
         this.retryAttempt = 0;
         this.failure = null;
         this.lastError = null;
         this.historyRebasePrepared = false;
+        this.preparedHistory = null;
+        this.setState('idle');
+        return this.generation;
+    }
+    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();
+                await this.runRecovery();
+                return;
+            }
+            this.baselineReady = true;
+            this.resolveBaselineWaiters();
+            this.emitState();
+            this.setState('live');
+            this.drainRetainedLive();
+            return;
+        }
         await this.runRecovery();
     }
     waitForBaseline() {
@@ -163,10 +406,14 @@ class PagedTerminalOutputCoordinator {
         this.baselineReady = false;
         this.coveredThroughSequence = Math.max(0, Math.floor(startSequence) - 1);
         this.scheduledThroughSequence = this.coveredThroughSequence;
+        this.recoveryEndSequence = undefined;
+        this.explicitAttachFence = false;
+        this.droppedLiveThroughSequence = 0;
         this.retryAttempt = 0;
         this.failure = null;
         this.lastError = null;
         this.historyRebasePrepared = false;
+        this.preparedHistory = null;
         this.setState('idle');
         this.resolveBaselineWaiters();
     }
@@ -203,6 +450,7 @@ class PagedTerminalOutputCoordinator {
         this.pendingLiveWrites = [];
         this.liveWriteScheduled = false;
         this.pausedRecoveryPending = false;
+        this.preparedHistory = null;
         this.setState('disposed');
         this.resolveBaselineWaiters();
     }
@@ -211,9 +459,69 @@ class PagedTerminalOutputCoordinator {
             return;
         this.recoveryKind = 'catch-up';
         this.recoveryStartSequence = Math.max(0, Math.floor(startSequence));
+        const firstRetainedSequence = this.firstRetainedLiveSequence();
+        this.recoveryEndSequence = firstRetainedSequence === undefined
+            ? undefined
+            : Math.max(0, firstRetainedSequence - 1);
         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;
@@ -230,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 snapshotEnd;
-            let historyGeneration;
-            let coveredEnd = this.coveredThroughSequence;
-            let firstPage = true;
+            let startSequence = preparedHistory
+                ? Math.max(1, preparedHistory.coveredThroughSequence
+                    + (preparedHistory.coveredThroughSequence < (this.recoveryEndSequence ?? 0) ? 1 : 0))
+                : this.recoveryStartSequence;
+            let snapshotEnd = this.recoveryEndSequence;
+            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,
@@ -250,29 +571,78 @@ 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;
+                            await this.runRecovery();
+                            return;
+                        }
+                    }
+                    else {
+                        this.prepareHistoryGenerationRebase(firstRetained);
+                        this.recoveryRunning = false;
+                        await this.runRecovery();
+                        return;
+                    }
+                }
+                if (this.historyRebasePrepared && generationNeedsRebase) {
+                    throw new HistoryContractError('history_contract_invalid', 'history generation reset persisted after rebase');
+                }
+                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 (this.historyRebasePrepared && generationNeedsRebase) {
-                    throw new HistoryContractError('history_contract_invalid', 'history generation reset persisted after rebase');
+                if (snapshotEnd !== undefined && coverage > snapshotEnd) {
+                    throw new HistoryContractError('history_contract_invalid', 'coveredThroughSequence exceeded the recovery fence');
                 }
-                const coverage = this.validatePage(page, coveredEnd);
                 if (firstPage) {
-                    snapshotEnd = pageSnapshotEnd;
+                    if (this.recoveryEndSequence !== undefined) {
+                        if (pageSnapshotEnd !== undefined && pageSnapshotEnd !== this.recoveryEndSequence) {
+                            throw new HistoryContractError('history_contract_invalid', 'snapshotEndSequence does not match the requested recovery fence');
+                        }
+                        snapshotEnd = this.recoveryEndSequence;
+                    }
+                    else {
+                        snapshotEnd = pageSnapshotEnd;
+                    }
                     historyGeneration = pageGeneration;
                     const effectiveStart = Math.max(1, startSequence);
-                    if (firstRetained !== undefined && firstRetained > effectiveStart) {
+                    if (!fencedRangeFullyEvicted && firstRetained !== undefined && firstRetained > effectiveStart) {
                         if (!this.historyRebasePrepared) {
                             this.options.clear?.();
                             this.options.onHistoryTruncated?.('history-evicted');
@@ -284,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');
                     }
                 }
@@ -300,6 +677,9 @@ class PagedTerminalOutputCoordinator {
             } while (!controller.signal.aborted);
             if (!this.isRecoveryCurrent(generation, recoverySerial, controller))
                 return;
+            if (this.recoveryEndSequence !== undefined && coveredEnd < this.recoveryEndSequence) {
+                throw new HistoryContractError('history_coverage_incomplete', 'terminal history coverage did not reach the recovery fence');
+            }
             if (this.needsRebase) {
                 this.prepareRetainedLiveRebase();
                 this.recoveryRunning = false;
@@ -332,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();
@@ -380,8 +761,8 @@ class PagedTerminalOutputCoordinator {
         for (const item of this.retainedLive) {
             const sequence = this.chunkSequence(item);
             if (sequence !== undefined && sequence <= coveredEnd) {
-                if (!selected.has(sequence))
-                    selected.set(sequence, item);
+                // A live copy preserves terminal query/response semantics that history replay suppresses.
+                selected.set(sequence, item);
             }
             else {
                 remaining.push(item);
@@ -467,6 +848,10 @@ class PagedTerminalOutputCoordinator {
             if (!removed)
                 break;
             this.retainedLiveBytes -= removed.data.byteLength;
+            const removedSequence = this.chunkSequence(removed);
+            if (removedSequence !== undefined) {
+                this.droppedLiveThroughSequence = Math.max(this.droppedLiveThroughSequence, removedSequence);
+            }
             this.needsRebase = true;
         }
         this.emitState();
@@ -476,6 +861,9 @@ class PagedTerminalOutputCoordinator {
         this.historyRebasePrepared = false;
         this.recoveryKind = this.baselineReady ? 'catch-up' : 'initial';
         this.recoveryStartSequence = 0;
+        const firstRetainedSequence = this.firstRetainedLiveSequence();
+        this.recoveryEndSequence = Math.max(this.droppedLiveThroughSequence, firstRetainedSequence === undefined ? 0 : firstRetainedSequence - 1) || undefined;
+        this.droppedLiveThroughSequence = 0;
         this.coveredThroughSequence = 0;
         this.scheduledThroughSequence = 0;
         this.options.clear?.();
@@ -502,6 +890,14 @@ class PagedTerminalOutputCoordinator {
         const sequence = this.chunkSequence(chunk);
         if (sequence !== undefined && sequence <= this.scheduledThroughSequence)
             return;
+        if (sequence !== undefined
+            && this.explicitAttachFence
+            && this.scheduledThroughSequence === 0
+            && sequence > 1) {
+            this.retainLive(chunk);
+            this.beginCatchUp(1);
+            return;
+        }
         if (sequence !== undefined
             && this.scheduledThroughSequence > 0
             && sequence > this.scheduledThroughSequence + 1) {