feat(terminal): share deep history reconstruction through one host flight

- Journal appliedRevision invalidates on every applied record and each affecting transition;
  committed log bytes advance with the queue commit so a cut never counts a batch twice.
- One latest derived image per journal within a 16 MiB host budget; eviction clears the
  payload and owner pointer before uncharging, and leases sever their own references.
- One cold lane guards one host flight that owns the cut, the revocable pending source, the
  replay lease and the result; up to 64 consumers join exact cuts with independent cancellation.
- Pending records live only behind a revocable handle; replay reads them per synchronous slice,
  and writer pressure severs the handle and parser before releasing the read's charge.
- Replay-derived title, cwd, link and escape-tail strings are detached from their input.
- Attach admission precedes the atomic cut with the old viewer intact; cached and joined images
  encode the full reply at a proved anchor before detach.
- Replies encoded once with the existing encoder reach the outer writer, which releases their
  consumer once on write settlement, close, an already closed socket, throw or notify.
- Deep getSnapshot carries the caller's remaining budget and aborts on disconnect.

Sleep final-flush and probed cwd remain open.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Brennan Benson
2026-11-12 08:49:06 -08:00
co-authored by Claude Opus 5.5
parent a3d038c17c
commit aec4d35a0b
29 changed files with 1642 additions and 226 deletions
@@ -24,7 +24,6 @@ import {
} from './terminal-view-attribute-responder'
import { installDeviceAttributesResponder } from './startup-device-attributes-responder'
import type { TerminalSnapshot } from '../protocol/terminal-snapshot'
import type { TerminalModes } from '../protocol/terminal-modes'
import type { TerminalOscLinkRange } from '../../../shared/terminal/links/terminal-osc-link-ranges'
import type { TerminalCursorContext } from '../../../shared/terminal/input/terminal-composer-draft'
import { readTerminalCursorLineContext } from '../../../shared/terminal/input/terminal-cursor-line-context'
@@ -242,7 +241,7 @@ export class HeadlessEmulator {
}
getSnapshot(opts: { scrollbackRows?: number } = {}): TerminalSnapshot {
const modes = this.getModes()
const modes = readTerminalModes(this.terminal)
// Absolute cursor restore avoids wrap-pending drift; carry the saved register for DECRC.
const serializedAnsi = serializeWithAbsoluteCursor(
this.serializer,
@@ -353,10 +352,9 @@ export class HeadlessEmulator {
dispose(): void {
this.disposed = true
// Parser-held text may slice its input; a disposed model keeps none of it.
this.partialEscapeTail = ''
this.oscText = new TerminalOscCwdTitleScanner()
this.terminal.dispose()
}
private getModes(): TerminalModes {
return readTerminalModes(this.terminal)
}
}
@@ -0,0 +1,95 @@
import type { TerminalHistoryImage } from './terminal-session-journal-contract'
/** Aggregate retained derived images host-wide, including invalidated ones still leased. */
export const DERIVED_IMAGE_BUDGET_BYTES = 16 * 1024 * 1024
/** A disposable projection of one journal's latest answer; never a history source. */
export type DerivedHistoryImage = {
readonly key: string
/** Cleared before its charge ends, so an uncharged entry keeps no payload reachable. */
image: TerminalHistoryImage | null
/** Conservative retained charge: UTF-16 string backing plus link and metadata overhead. */
readonly charge: number
leases: number
eligible: boolean
/** Clears the owner's pointer when the budget evicts this entry. */
readonly onEvict: () => void
}
/** A consumer's hold on one image; release drops this wrapper's own reference too. */
export type DerivedImageLease = { readonly image: TerminalHistoryImage | null; release(): void }
export class DerivedHistoryImageBudget {
private charged = 0
private readonly entries = new Set<DerivedHistoryImage>()
constructor(readonly capacity = DERIVED_IMAGE_BUDGET_BYTES) {}
/** Admits by evicting only unleased entries; false leaves the answer uncached, never trimmed. */
admit(entry: DerivedHistoryImage): boolean {
if (entry.charge > this.capacity) {
return false
}
for (const other of this.entries) {
if (this.charged + entry.charge <= this.capacity) {
break
}
if (other.leases === 0) {
other.eligible = false
other.onEvict()
this.settle(other)
}
}
if (this.charged + entry.charge > this.capacity) {
return false
}
this.entries.add(entry)
this.charged += entry.charge
return true
}
/** Invalidation removes eligibility at once; payload and charge end with the last lease. */
settle(entry: DerivedHistoryImage): void {
if (!entry.eligible && entry.leases === 0 && this.entries.delete(entry)) {
entry.image = null
this.charged -= entry.charge
}
}
lease(entry: DerivedHistoryImage): DerivedImageLease {
let image = entry.image
if (image) {
entry.leases += 1
}
return {
get image() {
return image
},
release: () => {
if (image) {
image = null
entry.leases -= 1
this.settle(entry)
}
}
}
}
}
export function derivedImageCharge(image: TerminalHistoryImage): number {
const { snapshot } = image
const strings = [
snapshot.snapshotAnsi,
snapshot.scrollbackAnsi,
snapshot.rehydrateSequences,
snapshot.pendingEscapeTailAnsi,
snapshot.frameRestoreAnsi,
snapshot.cwd,
snapshot.lastTitle
]
let units = strings.reduce((sum, text) => sum + (text?.length ?? 0), 0)
for (const link of snapshot.oscLinks ?? []) {
units += link.uri.length + 32
}
return units * 2 + 1024
}
@@ -0,0 +1,25 @@
import type { TerminalSnapshot } from '../../protocol/terminal-snapshot'
/** Copies every code unit, lone surrogates included, into backing shared with no other string. */
function detach(value: string): string {
return Buffer.from(value, 'utf16le').toString('utf16le')
}
/**
* A retained result must not keep a pending record alive through a small slice of it. Title,
* cwd, link targets and the parser tail come from replay input; the serialized cell output is
* built fresh by the serializer.
*/
export function detachTerminalSnapshotStrings(snapshot: TerminalSnapshot): TerminalSnapshot {
return {
...snapshot,
cwd: snapshot.cwd === null ? null : detach(snapshot.cwd),
...(snapshot.lastTitle !== undefined ? { lastTitle: detach(snapshot.lastTitle) } : {}),
...(snapshot.pendingEscapeTailAnsi !== undefined
? { pendingEscapeTailAnsi: detach(snapshot.pendingEscapeTailAnsi) }
: {}),
...(snapshot.oscLinks
? { oscLinks: snapshot.oscLinks.map((link) => ({ ...link, uri: detach(link.uri) })) }
: {})
}
}
@@ -13,7 +13,12 @@ import {
writeTerminalHistoryMeta,
type SessionMeta
} from '../storage/terminal-history-metadata'
import { TerminalSessionJournal } from './terminal-session-journal'
import {
JOURNAL_SESSION_BACKLOG_BYTES,
JOURNAL_SESSION_BACKLOG_RECORDS,
TerminalSessionJournal
} from './terminal-session-journal'
import { TerminalHistoryReads } from './terminal-history-read-admission'
import type { TerminalSessionJournalReads } from './terminal-session-journal-reads'
// Backing for queued, in-flight and frozen inputs across every journal on this host.
@@ -30,6 +35,12 @@ export type TerminalHistoryHold = {
/** The daemon's single owner of its host-local history root. */
export class TerminalHistoryJournals {
private readonly replay = new PrioritySemaphore(1)
readonly reads = new TerminalHistoryReads(
(journal, readBytes, records) =>
this.backlogBytes + readBytes <= JOURNAL_HOST_BACKLOG_BYTES &&
journal.backlog + journal.pendingSource.bytes <= JOURNAL_SESSION_BACKLOG_BYTES &&
records + journal.pendingSource.records <= JOURNAL_SESSION_BACKLOG_RECORDS
)
// Latest journal per ID until its actual I/O settles; a successor waits on it.
private readonly byId = new Map<string, TerminalSessionJournal>()
private readonly open = new Set<TerminalSessionJournalReads>()
@@ -128,7 +139,8 @@ export class TerminalHistoryJournals {
}
const journal = new TerminalSessionJournal(
{
acquireReplay: (priority) => this.replay.acquire(priority),
acquireReplay: (priority, signal) => this.replay.acquire(priority, signal),
images: this.reads.images,
charge: (owner, bytes) => this.charge(owner, bytes),
settled: (owner) => this.release(hold.sessionId, owner),
log: (event, details) => this.logger?.log(event, details)
@@ -163,7 +175,14 @@ export class TerminalHistoryJournals {
private charge(journal: TerminalSessionJournalReads, bytes: number): void {
this.backlogBytes += bytes
if (bytes <= 0 || this.backlogBytes <= JOURNAL_HOST_BACKLOG_BYTES) {
if (
bytes <= 0 ||
this.backlogBytes + this.reads.readSourceBytes <= JOURNAL_HOST_BACKLOG_BYTES
) {
return
}
this.reads.relievePressure()
if (this.backlogBytes <= JOURNAL_HOST_BACKLOG_BYTES) {
return
}
let largest = journal
@@ -0,0 +1,36 @@
import type { PendingOutputRecord } from '../../protocol/daemon-rpc-contract'
import type { ReplayRecordSource } from '../restoration/cold-restore-replay-writer'
/**
* The sole owner of a reader's frozen pending records. Cuts and continuations keep this handle,
* never the array or its strings, so revocation severs the backing before its charge ends.
*/
export class RevocablePendingSource {
private records: PendingOutputRecord[] | null
private disposeParser: (() => void) | null = null
constructor(records: PendingOutputRecord[]) {
this.records = records
}
readonly at: ReplayRecordSource = (index) => (this.records ? this.records[index] : null)
get revoked(): boolean {
return this.records === null
}
/** The replay parser reading this source; revocation disposes it at the yielded boundary. */
holdParser(dispose: (() => void) | null): void {
this.disposeParser = this.records ? dispose : null
if (!this.records) {
dispose?.()
}
}
revoke(): void {
this.records = null
const dispose = this.disposeParser
this.disposeParser = null
dispose?.()
}
}
@@ -0,0 +1,264 @@
import { PrioritySemaphore } from '../../../../shared/priority-semaphore'
import { DerivedHistoryImageBudget, type DerivedImageLease } from './terminal-history-derived-image'
import type { TerminalSessionJournal } from './terminal-session-journal'
import { HistoryReadConsumer } from './terminal-history-read-consumer'
import type {
TerminalHistoryImage,
TerminalHistoryReadCut
} from './terminal-session-journal-contract'
/** Admitted deep-history consumers host-wide, waiting, joined and writing alike. */
export const HISTORY_READ_CONSUMERS = 64
type FitsReadSource = (journal: TerminalSessionJournal, bytes: number, records: number) => boolean
/**
* Host owner of deep-history reads: bounded consumers, the derived-image budget, one cold lane
* and the single flight it guards, and the charge for that flight's frozen pending source.
*/
export class TerminalHistoryReads {
private consumers = 0
private readonly lane = new PrioritySemaphore(1)
private flight: HistoryFlight | null = null
private readonly wakers = new Set<() => void>()
private readonly severs = new Set<() => void>()
private sourceCharge = 0
constructor(
private readonly fits: FitsReadSource,
readonly images = new DerivedHistoryImageBudget()
) {}
get readSourceBytes(): number {
return this.sourceCharge
}
/** A consumer record held until its reply settles; null when all are taken. */
admit(signal: AbortSignal): HistoryReadConsumer | null {
if (this.consumers >= HISTORY_READ_CONSUMERS) {
return null
}
this.consumers += 1
return new HistoryReadConsumer(this, signal, () => {
this.consumers -= 1
})
}
/** Writer pressure severs every read source before any healthy writer is gapped. */
relievePressure(): void {
for (const sever of Array.from(this.severs)) {
sever()
}
}
/** Reserves before the copy; release follows the severing of every reference into it. */
reserveSource(journal: TerminalSessionJournal, sever: () => void): (() => void) | null {
const { bytes, records } = journal.pendingSource
if (!this.fits(journal, this.sourceCharge + bytes, records)) {
return null
}
this.sourceCharge += bytes
this.severs.add(sever)
return () => {
this.severs.delete(sever)
this.sourceCharge -= bytes
}
}
current(journal: TerminalSessionJournal, key: string): HistoryFlight | null {
const flight = this.flight
return flight?.joinable(journal, key) ? flight : null
}
publish(flight: HistoryFlight): void {
this.flight = flight
for (const wake of Array.from(this.wakers)) {
wake()
}
}
retire(flight: HistoryFlight): void {
if (this.flight === flight) {
this.flight = null
}
}
/** The cold lane, or 'published' when a flight appears that this waiter may join instead. */
async waitLane(signal: AbortSignal): Promise<(() => void) | 'published'> {
const wake = new AbortController()
const waker = (): void => wake.abort()
this.wakers.add(waker)
try {
return await this.lane.acquire(1, AbortSignal.any([signal, wake.signal]))
} catch (error) {
if (wake.signal.aborted && !signal.aborted) {
return 'published'
}
throw error
} finally {
this.wakers.delete(waker)
}
}
}
export type FlightInterest = {
readonly result: Promise<DerivedImageLease | null>
leave(): void
}
/**
* One cold reconstruction shared by every consumer of the same exact cut and shape. It owns the
* cut, the revocable pending source, the replay lease and the result; consumers own only their
* interests. Joining closes at reconstruction completion.
*/
export class HistoryFlight {
key: string | null = null
private cut: TerminalHistoryReadCut | null = null
private closed = false
private releaseSource: (() => void) | null = null
private readonly controller = new AbortController()
private readonly interests = new Set<(lease: DerivedImageLease | null) => void>()
constructor(
private readonly reads: TerminalHistoryReads,
private readonly journal: TerminalSessionJournal,
private readonly scrollbackRows: number | undefined,
private releaseLane: (() => void) | null,
private releaseReplay: (() => void) | null
) {}
joinable(journal: TerminalSessionJournal, key: string): boolean {
return !this.closed && this.cut !== null && this.journal === journal && this.key === key
}
/** A participant's interest; the last departure before completion cancels unused work. */
join(): FlightInterest {
let resolve!: (lease: DerivedImageLease | null) => void
let settled: DerivedImageLease | null | undefined
const result = new Promise<DerivedImageLease | null>((done) => {
resolve = done
})
const deliver = (lease: DerivedImageLease | null): void => {
settled = lease
resolve(lease)
}
this.interests.add(deliver)
return {
result,
leave: () => {
if (settled !== undefined) {
settled?.release()
return
}
this.interests.delete(deliver)
if (this.interests.size === 0 && !this.closed) {
this.closed = true
this.sever()
if (!this.cut) {
this.end(null)
}
}
}
}
}
/** Synchronous with the leader's capture: reserve source headroom, copy, then publish. */
capture(): boolean {
this.releaseSource = this.reads.reserveSource(this.journal, () => this.sever())
if (!this.releaseSource || this.closed) {
this.releaseSource?.()
this.releaseSource = null
this.end(null)
return false
}
this.cut = this.journal.captureReadCut()
this.key = this.journal.derivedKey(this.scrollbackRows)
this.reads.publish(this)
void this.run(this.cut)
return true
}
private async run(cut: TerminalHistoryReadCut): Promise<TerminalHistoryImage | null> {
let image: TerminalHistoryImage | null = null
try {
image = await this.journal.readImage(cut, {
scrollbackRows: this.scrollbackRows,
isCanceled: () => this.controller.signal.aborted
})
} finally {
// I/O and the parser have settled: drop the source, end its charge, then free the slot.
this.dropSource()
this.releaseReplay?.()
this.releaseReplay = null
}
this.end(this.controller.signal.aborted ? null : image)
return image
}
/** Pressure or the last departure: close joining, cancel, then drop the source. */
private sever(): void {
this.closed = true
this.controller.abort()
this.dropSource()
}
/** Revokes the pending handle and its parser before the charge for them ends. */
private dropSource(): void {
this.cut?.source.revoke()
this.releaseSource?.()
this.releaseSource = null
}
private end(image: TerminalHistoryImage | null): void {
this.closed = true
this.reads.retire(this)
this.releaseReplay?.()
this.releaseReplay = null
const interests = [...this.interests]
this.interests.clear()
const entry =
image && this.key ? this.journal.offerDerived(this.key, this.scrollbackRows, image) : null
if (entry || !image || interests.length === 0) {
this.freeLane()
}
const shared = entry
? null
: image && sharedUncached(image, interests.length, () => this.freeLane())
for (const deliver of interests) {
deliver(entry ? this.reads.images.lease(entry) : (shared?.() ?? null))
}
}
private freeLane(): void {
this.releaseLane?.()
this.releaseLane = null
}
}
/** One untrimmed result outside I: it keeps the cold lane until its last participant settles. */
function sharedUncached(
image: TerminalHistoryImage,
participants: number,
free: () => void
): () => DerivedImageLease {
let held: TerminalHistoryImage | null = image
let remaining = participants
return () => {
let leased = held
return {
get image() {
return leased
},
release: () => {
if (leased) {
leased = null
remaining -= 1
if (remaining === 0) {
held = null
free()
}
}
}
}
}
}
@@ -0,0 +1,139 @@
import type { DerivedImageLease } from './terminal-history-derived-image'
import type { TerminalSessionJournal } from './terminal-session-journal'
import type { TerminalHistoryImage } from './terminal-session-journal-contract'
import {
HistoryFlight,
type FlightInterest,
type TerminalHistoryReads
} from './terminal-history-read-admission'
/**
* One request's admitted record: its deadline signal, its interest in a flight and its image
* lease. Released once, when its reply settles or it is abandoned before writing.
*/
export class HistoryReadConsumer {
private lease: DerivedImageLease | null = null
private interest: FlightInterest | null = null
key: string | null = null
private released = false
constructor(
private readonly reads: TerminalHistoryReads,
readonly signal: AbortSignal,
private readonly onRelease: () => void
) {}
get image(): TerminalHistoryImage | null {
return this.lease?.image ?? null
}
/**
* An exact image for the journal's current cut and shape, or a flight this consumer leads and
* must capture. Every wait rechecks the latest result and flight; one deadline governs all.
*/
async acquire(
journal: TerminalSessionJournal,
scrollbackRows: number | undefined,
barrier: () => Promise<void>
): Promise<HistoryFlight | 'image' | null> {
for (;;) {
this.signal.throwIfAborted()
await barrier()
const found = this.findSync(journal, scrollbackRows)
if (found === 'joined') {
// A failed or revoked flight is this read's answer too; it does not reconstruct again.
return (await this.awaitInterest()) ? 'image' : null
}
if (found !== 'miss') {
return found
}
const lane = await this.reads.waitLane(this.signal)
if (lane === 'published') {
continue
}
const afterLane = this.findSync(journal, scrollbackRows)
if (afterLane !== 'miss') {
lane()
if (afterLane === 'joined') {
return (await this.awaitInterest()) ? 'image' : null
}
return afterLane
}
let releaseReplay: () => void
try {
releaseReplay = await journal.acquireRead(this.signal)
} catch (error) {
lane()
throw error
}
const flight = new HistoryFlight(this.reads, journal, scrollbackRows, lane, releaseReplay)
this.interest = flight.join()
return flight
}
}
/** The leader's result after its capture; false when reconstruction produced nothing. */
async awaitFlight(flight: HistoryFlight): Promise<boolean> {
this.key = flight.key
return this.awaitInterest()
}
/** Drops the image for a changed-cut retry while keeping this consumer's admission. */
dropImage(): void {
this.lease?.release()
this.lease = null
this.interest?.leave()
this.interest = null
}
release(): void {
if (!this.released) {
this.released = true
this.dropImage()
this.onRelease()
}
}
private findSync(
journal: TerminalSessionJournal,
scrollbackRows: number | undefined
): 'image' | 'joined' | 'miss' | null {
const key = journal.derivedKey(scrollbackRows)
if (!key) {
return null
}
this.key = key
this.lease = journal.leaseDerived(key)
if (this.lease) {
return 'image'
}
const flight = this.reads.current(journal, key)
if (!flight) {
return 'miss'
}
this.interest = flight.join()
return 'joined'
}
private async awaitInterest(): Promise<boolean> {
const interest = this.interest!
const abort = Promise.withResolvers<null>()
const onAbort = (): void => abort.resolve(null)
this.signal.addEventListener('abort', onAbort, { once: true })
try {
const lease = await Promise.race([interest.result, abort.promise])
if (!lease) {
// A cancelled or failed join leaves only this interest; others keep theirs.
interest.leave()
this.interest = null
this.signal.throwIfAborted()
return false
}
this.interest = null
this.lease = lease
return true
} finally {
this.signal.removeEventListener('abort', onAbort)
}
}
}
@@ -2,9 +2,12 @@ import type { PendingOutputRecord } from '../../protocol/daemon-rpc-contract'
import type { TerminalSnapshot } from '../../protocol/terminal-snapshot'
import type { TerminalOwner } from '../../../../shared/terminal/pty/lifecycle/terminal-owner'
import type { TerminalSessionJournalReads } from './terminal-session-journal-reads'
import type { DerivedHistoryImageBudget } from './terminal-history-derived-image'
import type { RevocablePendingSource } from './terminal-history-pending-source'
export type TerminalSessionJournalHost = {
acquireReplay(priority: number): Promise<() => void>
acquireReplay(priority: number, signal?: AbortSignal): Promise<() => void>
readonly images: DerivedHistoryImageBudget
charge(journal: TerminalSessionJournalReads, bytes: number): void
settled(journal: TerminalSessionJournalReads): void
log(event: string, details: Record<string, unknown>): void
@@ -20,11 +23,18 @@ export type TerminalHistoryCut = {
gapped: boolean
}
/** A reader's immutable cut: scalars plus the handle that alone owns its frozen records. */
export type TerminalHistoryReadCut = Omit<TerminalHistoryCut, 'records'> & {
source: RevocablePendingSource
}
export type TerminalJournalSession = {
readonly incarnationId: string
readonly historySeeded: boolean | undefined
readonly isAlive: boolean
settleShellOwnershipConfirmation(): Promise<void>
/** Releases held startup bytes into the stream, as a live snapshot would first. */
snapshotBarrier(): void
prepareForFinalSnapshot(): string
}
@@ -1,6 +1,5 @@
import { join } from 'node:path'
import type { TerminalHistoryOutcome } from '../../protocol/daemon-history-protocol'
import type { PendingOutputRecord } from '../../protocol/daemon-rpc-contract'
import type { TerminalSnapshot } from '../../protocol/terminal-snapshot'
import type { TerminalHistorySessionWriter } from '../storage/terminal-history-session-writer'
import { LOG_HEADER_BYTES } from '../storage/terminal-history-log'
@@ -8,11 +7,21 @@ import { TerminalJournalBacklog } from './terminal-session-journal-backlog'
import type {
TerminalHistoryCut,
TerminalHistoryImage,
TerminalHistoryReadCut,
TerminalJournalOutput,
TerminalJournalSession,
TerminalSessionJournalHost
} from './terminal-session-journal-contract'
import { replayTerminalJournalSource } from './terminal-session-journal-source'
import {
replayTerminalJournalSource,
type TerminalJournalSource
} from './terminal-session-journal-source'
import { RevocablePendingSource } from './terminal-history-pending-source'
import {
derivedImageCharge,
type DerivedHistoryImage,
type DerivedImageLease
} from './terminal-history-derived-image'
export const JOURNAL_READ_PRIORITY = 1
@@ -30,6 +39,11 @@ export class TerminalSessionJournalReads {
protected seq = 0
protected foldGeneration = 0
protected folded = false
/** Log bytes committed together with the queue head, so a cut never counts a batch twice. */
protected committedLogBytes = 0
/** Bumped by every applied record and every transition that can change a derived answer. */
protected appliedRevision = 0
private derived: DerivedHistoryImage | null = null
constructor(
protected readonly host: TerminalSessionJournalHost,
root: string,
@@ -64,6 +78,7 @@ export class TerminalSessionJournalReads {
}
bindSession(session: TerminalJournalSession): void {
this.markApplied()
this.incarnationId = session.incarnationId
this.boundSession = session
}
@@ -82,7 +97,7 @@ export class TerminalSessionJournalReads {
const records = this.queue.snapshot()
return {
generation: this.foldGeneration,
logBytes: this.writer?.committedLog?.bytes ?? 0,
logBytes: this.committedLogBytes,
records,
outputSequence: this.output?.outputSequence() ?? 0,
terminalOwner: this.output?.terminalOwner(),
@@ -90,30 +105,107 @@ export class TerminalSessionJournalReads {
}
}
/** Read-only: replays the cut through one parser without touching storage or the live model. */
async readImage(
cutOrCapture: TerminalHistoryCut | (() => TerminalHistoryCut | null),
opts: { scrollbackRows?: number; isCanceled?: () => boolean } = {}
): Promise<TerminalHistoryImage | null> {
if (this.state === 'gap') {
/** Backing a reader's cut must reserve before copying: queued bytes and records. */
get pendingSource(): { bytes: number; records: number } {
return { bytes: this.queue.bytes, records: this.queue.length }
}
/** A reader's cut; only the returned handle holds the copied pending records. */
captureReadCut(): TerminalHistoryReadCut {
const { records, ...cut } = this.captureCut()
return { ...cut, source: new RevocablePendingSource(records) }
}
/** The replay lease a reader holds from before its capture until its parser is disposed. */
acquireRead(signal?: AbortSignal): Promise<() => void> {
return this.host.acquireReplay(JOURNAL_READ_PRIORITY, signal)
}
/**
* Exact qualification of a derived answer for this request shape, read after the caller's
* barriers. Null while no answer can be derived. Incarnation, fold generation, every applied
* transition, the stream position and the owner all take part.
*/
derivedKey(scrollbackRows: number | undefined): string | null {
if (this.state === 'gap' || !this.session) {
return null
}
// Admission precedes any capture a reader makes, so waiting readers pin no copies.
const release = await this.host.acquireReplay(JOURNAL_READ_PRIORITY)
try {
const cut = typeof cutOrCapture === 'function' ? cutOrCapture() : cutOrCapture
// A cut that read nothing from files holds its whole source, whatever was published since.
const selfContained = cut?.generation === 0 && cut.logBytes <= LOG_HEADER_BYTES
if (
!cut ||
cut.gapped ||
this.gapped ||
(cut.generation !== this.foldGeneration && !selfContained) ||
opts.isCanceled?.()
) {
return null
return JSON.stringify([
this.incarnationId,
this.foldGeneration,
this.appliedRevision,
scrollbackRows ?? null,
this.output?.outputSequence() ?? 0,
this.output?.terminalOwner() ?? null
])
}
/** The latest derived answer for exactly this key, leased; null when absent or stale. */
leaseDerived(key: string): DerivedImageLease | null {
const derived = this.derived
return derived?.eligible && derived.key === key ? this.host.images.lease(derived) : null
}
/** Installs a fresh answer as the sole entry if its key is still current and it fits I. */
offerDerived(
key: string,
scrollbackRows: number | undefined,
image: TerminalHistoryImage
): DerivedHistoryImage | null {
if (this.derivedKey(scrollbackRows) !== key) {
return null
}
const entry: DerivedHistoryImage = {
key,
image,
charge: derivedImageCharge(image),
leases: 0,
eligible: true,
onEvict: () => {
if (this.derived === entry) {
this.derived = null
}
}
const snapshot = await this.replay(cut.logBytes, cut.records, { ...opts, selfContained })
}
this.invalidateDerived()
if (!this.host.images.admit(entry)) {
return null
}
this.derived = entry
return entry
}
protected markApplied(): void {
this.appliedRevision += 1
this.invalidateDerived()
}
protected invalidateDerived(): void {
const derived = this.derived
if (derived) {
this.derived = null
derived.eligible = false
this.host.images.settle(derived)
}
}
/** Replays the cut through one parser; the caller holds the replay lease from before capture. */
async readImage(
cut: TerminalHistoryReadCut,
opts: { scrollbackRows?: number; isCanceled?: () => boolean } = {}
): Promise<TerminalHistoryImage | null> {
// A cut that read nothing from files holds its whole source, whatever was published since.
const selfContained = cut.generation === 0 && cut.logBytes <= LOG_HEADER_BYTES
if (
this.state === 'gap' ||
cut.gapped ||
(cut.generation !== this.foldGeneration && !selfContained) ||
opts.isCanceled?.()
) {
return null
}
try {
const snapshot = await this.replay(cut.logBytes, cut.source, { ...opts, selfContained })
return snapshot
? {
snapshot: {
@@ -130,8 +222,6 @@ export class TerminalSessionJournalReads {
: null
} catch {
return null
} finally {
release()
}
}
@@ -148,13 +238,14 @@ export class TerminalSessionJournalReads {
return
}
this.state = 'gap'
this.markApplied()
this.host.log('terminal-history-gap', { reason, incarnationId: this.incarnationId })
this.host.charge(this, -this.queue.clear())
}
protected replay(
logBytes: number,
pending: readonly PendingOutputRecord[],
pending: TerminalJournalSource['pending'],
opts: { scrollbackRows?: number; isCanceled?: () => boolean; selfContained?: boolean } = {}
): Promise<TerminalSnapshot | null> {
return replayTerminalJournalSource(
@@ -13,6 +13,9 @@ import { readTerminalHistoryBufferAsync } from '../storage/terminal-history-file
import { TERMINAL_HISTORY_LOG_MAX_BYTES } from '../storage/terminal-history-file-limits'
import { readTerminalHistoryCheckpoint } from '../restoration/terminal-history-checkpoint-reader'
import { replayTerminalHistory } from '../restoration/terminal-history-replay'
import type { ReplayRecordSource } from '../restoration/cold-restore-replay-writer'
import type { RevocablePendingSource } from './terminal-history-pending-source'
import { detachTerminalSnapshotStrings } from './terminal-history-detached-snapshot'
import { TerminalHistorySessionWriter } from '../storage/terminal-history-session-writer'
import {
clearLegacyTerminalHistoryScrollback,
@@ -29,7 +32,8 @@ export type TerminalJournalSource = {
generation: number
folded: boolean
logBytes: number
pending: readonly PendingOutputRecord[]
/** Read per slice; a revocable source also owns the parser it feeds. */
pending: ReplayRecordSource | RevocablePendingSource
origin: { cols: number; rows: number; wslDistro: string | undefined }
}
@@ -69,6 +73,16 @@ export async function replayTerminalJournalSource(
wslDistro: source.origin.wslDistro,
windowsPty: historyReplayWindowsPty(DAEMON_HISTORY_RESIZE_MODEL)
})
const pending = typeof source.pending === 'function' ? source.pending : source.pending.at
const revocable = typeof source.pending === 'function' ? null : source.pending
let disposed = false
const dispose = (): void => {
if (!disposed) {
disposed = true
emulator.dispose()
}
}
revocable?.holdParser(dispose)
try {
// The checkpoint's cwd is the baseline; a later OSC 7 in the replayed records still wins.
if (checkpoint?.cwd) {
@@ -77,23 +91,18 @@ export async function replayTerminalJournalSource(
const replayed = await replayTerminalHistory(
emulator,
checkpoint,
concatRecords(logged, source.pending),
opts.isCanceled
(index) => (index < logged.length ? logged[index] : pending(index - logged.length)),
() => opts.isCanceled?.() === true || revocable?.revoked === true
)
return replayed ? emulator.getSnapshot({ scrollbackRows: opts.scrollbackRows }) : null
return replayed && !revocable?.revoked
? detachTerminalSnapshotStrings(emulator.getSnapshot({ scrollbackRows: opts.scrollbackRows }))
: null
} finally {
emulator.dispose()
revocable?.holdParser(null)
dispose()
}
}
function* concatRecords(
first: readonly PendingOutputRecord[],
second: readonly PendingOutputRecord[]
): Generator<PendingOutputRecord> {
yield* first
yield* second
}
/** An explicit new physical origin: predecessor replay files go, fresh metadata, generation 0. */
export function openTerminalJournalOrigin(
dir: string,
@@ -124,7 +133,7 @@ export async function publishTerminalJournalSeedOrigin(
generation: 0,
folded: false,
logBytes: 0,
pending: seed,
pending: (index) => seed[index],
origin
})
if (!snapshot) {
@@ -40,6 +40,8 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
/** Called in applied order; the seed origin is exempt from the backlog bound it predates. */
record(record: PendingOutputRecord, opts: { origin?: boolean } = {}): void {
// Coalescing can change content without new intake; every applied call invalidates.
this.markApplied()
if (this.state !== 'open' || this.ending) {
return
}
@@ -92,6 +94,7 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
}
this.ending = true
this.exitCode = exitCode
this.markApplied()
this.kick()
}
@@ -167,6 +170,7 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
}
if (appended === 'ok') {
this.seq += 1
this.committedLogBytes = this.writer.committedLog?.bytes ?? 0
this.host.charge(this, -this.queue.commit(batch.records, batch.headOffset))
continue
}
@@ -197,6 +201,7 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
!hasReplayableTerminalHistorySessionFiles(this.dir)
) {
this.writer = openTerminalJournalOrigin(this.dir, this.origin)
this.committedLogBytes = 0
return
}
// Predecessor files stay the sole recovery until the seed's checkpoint is durable.
@@ -211,6 +216,8 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
return
}
this.writer = writer
this.committedLogBytes = writer.committedLog?.bytes ?? 0
this.markApplied()
this.foldGeneration += 1
this.host.charge(this, -this.queue.commit(this.originRecords, 0))
} finally {
@@ -229,7 +236,8 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
}
const covered = this.queue.sealAll()
const cut = this.captureCut()
const snapshot = await this.replay(committed.bytes, cut.records)
const records = cut.records
const snapshot = await this.replay(committed.bytes, (index) => records[index])
if (!snapshot || this.state !== 'open') {
throw new Error('terminal_history_fold_replay_failed')
}
@@ -240,6 +248,8 @@ export class TerminalSessionJournal extends TerminalSessionJournalReads {
}
this.foldGeneration += 1
this.folded = true
this.committedLogBytes = writer.committedLog?.bytes ?? 0
this.markApplied()
this.host.charge(this, -this.queue.commit(covered, 0))
} finally {
release()
@@ -0,0 +1,227 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { PrioritySemaphore } from '../../../../../shared/priority-semaphore'
import { TerminalSessionJournal } from '../terminal-session-journal'
import { DerivedHistoryImageBudget } from '../terminal-history-derived-image'
import { TerminalHistoryReads } from '../terminal-history-read-admission'
import { getHistorySessionDirName } from '../../storage/history-paths'
const roots: string[] = []
afterEach(() => {
vi.restoreAllMocks()
for (const root of roots.splice(0)) {
rmSync(root, { recursive: true, force: true })
}
})
function openReads(imageBudget?: number) {
const replay = new PrioritySemaphore(1)
const images = new DerivedHistoryImageBudget(imageBudget)
const reads = new TerminalHistoryReads(() => true, images)
const root = mkdtempSync(join(tmpdir(), 'orca-read-flight-'))
roots.push(root)
let sequence = 0
const openJournal = (sessionId: string): TerminalSessionJournal => {
const dirName = getHistorySessionDirName(sessionId)
mkdirSync(join(root, dirName), { recursive: true })
const journal = new TerminalSessionJournal(
{
acquireReplay: (priority, signal) => replay.acquire(priority, signal),
images,
charge: () => {},
settled: () => {},
log: () => {}
},
root,
dirName,
{ cwd: '/tmp', cols: 80, rows: 24, wslDistro: undefined, preservesRecovery: false }
)
journal.bindSession({
incarnationId: `${sessionId}-incarnation`,
historySeeded: undefined,
isAlive: true,
settleShellOwnershipConfirmation: async () => {},
snapshotBarrier: () => {},
prepareForFinalSnapshot: () => ''
})
journal.bindOutput({
outputSequence: () => sequence,
terminalOwner: () => undefined,
hasAttachedClient: () => false
})
return journal
}
const record = (journal: TerminalSessionJournal, data: string): void => {
sequence += data.length
journal.record({ kind: 'output', data })
}
// An opened origin with an empty queue, so later output stays pending in its append window.
const prime = async (journal: TerminalSessionJournal): Promise<void> => {
record(journal, 'PRIME\r\n')
await journal.flush()
}
const rows = (marker: string, count: number): string =>
Array.from(
{ length: count },
(_, i) => `${marker}_${String(i).padStart(4, '0')}${'.'.repeat(60)}\r\n`
).join('')
return { reads, replay, images, openJournal, record, prime, rows }
}
/** One consumer's whole read, as a deep snapshot route performs it. */
async function readDeep(
reads: TerminalHistoryReads,
journal: TerminalSessionJournal,
signal = new AbortController().signal
): Promise<string | null> {
const consumer = reads.admit(signal)!
try {
const found = await consumer.acquire(journal, 5000, async () => {})
const ready =
found === 'image' ||
(found !== null && found.capture() && (await consumer.awaitFlight(found)))
const image = consumer.image
return ready && image ? image.snapshot.snapshotAnsi : null
} catch {
return null
} finally {
consumer.release()
}
}
describe('shared deep-history flight', () => {
it.each([
['cacheable', undefined],
['uncached', 1024]
] as const)(
'serves queued and arriving %s readers of one cut from one reconstruction',
async (_, budget) => {
const { reads, openJournal, record } = openReads(budget)
const journal = openJournal('flight-shared')
record(journal, 'SHARED_ROW_ONE\r\nSHARED_ROW_TWO\r\n')
const reconstructions = vi.spyOn(journal, 'readImage')
const answers = await Promise.all([readDeep(reads, journal), readDeep(reads, journal)])
expect(answers[0]).toContain('SHARED_ROW_TWO')
expect(answers[1]).toBe(answers[0])
expect(reconstructions).toHaveBeenCalledTimes(1)
}
)
it('keeps a joined reader when the leader leaves, and cancels work nobody wants', async () => {
const { reads, openJournal, record } = openReads()
const journal = openJournal('flight-cancel')
record(journal, 'JOINED_ROW\r\n')
// Hold the reconstruction open so the published flight can be joined and left.
let gate = Promise.withResolvers<void>()
const readImage = journal.readImage.bind(journal)
const reconstructions = vi.spyOn(journal, 'readImage').mockImplementation(async (...args) => {
await gate.promise
return readImage(...args)
})
const leaderAbort = new AbortController()
const leader = readDeep(reads, journal, leaderAbort.signal)
await vi.waitFor(() => expect(reconstructions).toHaveBeenCalledTimes(1))
const joiner = readDeep(reads, journal)
leaderAbort.abort()
gate.resolve()
expect(await leader).toBeNull()
expect(await joiner).toContain('JOINED_ROW')
expect(reconstructions).toHaveBeenCalledTimes(1)
// Once every reader has left, nobody's work continues.
const lone = new AbortController()
gate = Promise.withResolvers<void>()
record(journal, 'UNWANTED_ROW\r\n')
const unwanted = readDeep(reads, journal, lone.signal)
await vi.waitFor(() => expect(reconstructions).toHaveBeenCalledTimes(2))
lone.abort()
gate.resolve()
expect(await unwanted).toBeNull()
expect(await readDeep(reads, journal)).toContain('UNWANTED_ROW')
// The abandoned flight installed nothing: the later reader had to reconstruct.
expect(reconstructions).toHaveBeenCalledTimes(3)
})
// Coalesced output changes content without new intake; the old answer must not be reused.
it('never reuses an answer after output coalesces into the queued tail', async () => {
const { reads, openJournal, record } = openReads()
const journal = openJournal('flight-coalesce')
record(journal, 'BEFORE_')
expect(await readDeep(reads, journal)).toContain('BEFORE_')
record(journal, 'AFTER\r\n')
expect(await readDeep(reads, journal)).toContain('BEFORE_AFTER')
})
it('evicts a quiet journal for another, but keeps a leased answer charged until release', async () => {
// Room for one of these answers but not two.
const { reads, openJournal, record, rows } = openReads(150_000)
const first = openJournal('flight-quiet')
const second = openJournal('flight-busy')
record(first, rows('QUIET_ROW', 600))
record(second, rows('BUSY_ROW', 600))
const firstRead = vi.spyOn(first, 'readImage')
expect(await readDeep(reads, first)).toContain('QUIET_ROW')
const held = reads.admit(new AbortController().signal)!
expect(await held.acquire(first, 5000, async () => {})).toBe('image')
// The leased answer fills the budget: the other journal is still served, uncached.
const secondRead = vi.spyOn(second, 'readImage')
expect(await readDeep(reads, second)).toContain('BUSY_ROW')
expect(await readDeep(reads, second)).toContain('BUSY_ROW')
expect(secondRead).toHaveBeenCalledTimes(2)
held.release()
expect(await readDeep(reads, second)).toContain('BUSY_ROW')
expect(await readDeep(reads, second)).toContain('BUSY_ROW')
expect(secondRead).toHaveBeenCalledTimes(3)
// The quiet journal's answer was evicted, not kept uncharged.
expect(await readDeep(reads, first)).toContain('QUIET_ROW')
expect(firstRead).toHaveBeenCalledTimes(2)
})
// Writer pressure severs the frozen source and frees its charge without gapping the writer.
it('releases a severed source at once and answers correctly afterwards', async () => {
const { reads, openJournal, record, prime } = openReads()
const journal = openJournal('flight-pressure')
await prime(journal)
record(journal, 'PRESSURED_ROW\r\n')
const consumer = reads.admit(new AbortController().signal)!
const found = await consumer.acquire(journal, 5000, async () => {})
expect(found).not.toBe('image')
if (found === 'image' || found === null) {
return
}
expect(found.capture()).toBe(true)
expect(reads.readSourceBytes).toBeGreaterThan(0)
reads.relievePressure()
expect(reads.readSourceBytes).toBe(0)
expect(await consumer.awaitFlight(found)).toBe(false)
consumer.release()
expect(journal.gapped).toBe(false)
expect(await readDeep(reads, journal)).toContain('PRESSURED_ROW')
})
// F1: a title sliced from a large pending burst must survive exactly, lone surrogate included.
it('keeps every code unit of a long title read from a large pending burst', async () => {
const { reads, openJournal, record, prime } = openReads()
const journal = openJournal('flight-title')
await prime(journal)
const title = 'Agent working on a long task \ud800 done'
record(journal, `${'x'.repeat(60_000)}\x1b]2;${title}\x07TITLE_ROW\r\n`)
const consumer = reads.admit(new AbortController().signal)!
const found = await consumer.acquire(journal, 5000, async () => {})
if (found !== 'image' && found !== null) {
found.capture()
await consumer.awaitFlight(found)
}
expect(consumer.image?.snapshot.lastTitle).toBe(title)
consumer.release()
})
})
@@ -10,6 +10,7 @@ import {
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { TerminalSessionJournal } from '../terminal-session-journal'
import { DerivedHistoryImageBudget } from '../terminal-history-derived-image'
import { getHistorySessionDirName } from '../../storage/history-paths'
import { HistoryReader } from '../../restoration/history-reader'
import { TerminalHistorySessionWriter } from '../../storage/terminal-history-session-writer'
@@ -38,7 +39,13 @@ function openJournal(
const dir = join(root, dirName)
mkdirSync(dir, { recursive: true })
const journal = new TerminalSessionJournal(
{ acquireReplay: async () => () => {}, charge: () => {}, settled: () => {}, log: () => {} },
{
acquireReplay: async () => () => {},
images: new DerivedHistoryImageBudget(),
charge: () => {},
settled: () => {},
log: () => {}
},
root,
dirName,
{ cwd: '/tmp', cols: 80, rows: 24, wslDistro: undefined, preservesRecovery: false, ...opts }
@@ -52,6 +59,7 @@ function bind(journal: TerminalSessionJournal, historySeeded?: boolean): void {
historySeeded,
isAlive: true,
settleShellOwnershipConfirmation: async () => {},
snapshotBarrier: () => {},
prepareForFinalSnapshot: () => ''
})
journal.bindOutput({
@@ -71,13 +79,14 @@ describe('TerminalSessionJournal', () => {
journal.record(output('COMMITTED\r\n'))
expect(await journal.flush()).toBe(true)
journal.record(output('AT_CUT\r\n'))
const cut = journal.captureCut()
const cut = journal.captureReadCut()
journal.record(output('AFTER_CUT\r\n'))
const image = await journal.readImage(cut)
expect(image?.snapshot.snapshotAnsi).toContain('COMMITTED')
expect(image?.snapshot.snapshotAnsi).toContain('AT_CUT')
expect(image?.snapshot.snapshotAnsi).not.toContain('AFTER_CUT')
expect(await journal.flush()).toBe(true)
})
// CJ3: a seeded origin used to delete the predecessor before its own replacement was durable.
@@ -122,7 +131,7 @@ describe('TerminalSessionJournal', () => {
expect(readGeneration().cwd).toBe('/tmp/cwd-a')
journal.record(output('\x1b]7;file://host/tmp/cwd-c\x07CWD_C_ROW\r\n'))
const image = await journal.readImage(journal.captureCut(), { scrollbackRows: 5000 })
const image = await journal.readImage(journal.captureReadCut(), { scrollbackRows: 5000 })
expect(image?.snapshot.cwd).toBe('/tmp/cwd-c')
expect(await journal.flush()).toBe(true)
const restored = await new HistoryReader(root).detectColdRestore(sessionId)
@@ -1,4 +1,12 @@
import type { HeadlessEmulator } from '../../emulation/headless-emulator'
import type { PendingOutputRecord } from '../../protocol/daemon-rpc-contract'
import { isValidTerminalHistorySize } from './terminal-history-dimensions'
/**
* Records read by position at each synchronous slice. Undefined ends the source; null means it
* was revoked. Nothing a slice reads survives the next yield.
*/
export type ReplayRecordSource = (index: number) => PendingOutputRecord | undefined | null
const REPLAY_CHARS_PER_TURN = 64 * 1024
const REPLAY_OPERATIONS_PER_TURN = 1024
@@ -40,6 +48,80 @@ export class ColdRestoreReplayWriter {
return true
}
/** Replays the source with no record, string or slice held across a yield. */
async replayRecords(source: ReplayRecordSource, isCanceled: () => boolean): Promise<boolean> {
const position = { index: 0, offset: 0 }
for (;;) {
const pendingYield = this.takeBudgetYield()
if (pendingYield) {
await pendingYield
}
if (isCanceled()) {
return false
}
const step = this.replayStep(source, position)
if (step !== 'more') {
return step === 'done'
}
}
}
// One synchronous slice: its record and string locals end when it returns.
private replayStep(
source: ReplayRecordSource,
position: { index: number; offset: number }
): 'more' | 'done' | 'failed' {
const record = source(position.index)
if (record === undefined) {
return 'done'
}
if (record === null) {
return 'failed'
}
this.operations += 1
if (record.kind === 'resize') {
if (!isValidTerminalHistorySize(record.cols, record.rows)) {
return 'failed'
}
this.emulator.resize(record.cols, record.rows)
} else if (record.kind === 'clear') {
this.emulator.clearScrollback()
} else {
const end = this.sliceEnd(record.data, position.offset)
if (
end > position.offset &&
!this.emulator.writeSync(record.data.slice(position.offset, end))
) {
return 'failed'
}
this.chars += end - position.offset
position.offset = end
if (end < record.data.length) {
return 'more'
}
}
position.index += 1
position.offset = 0
return 'more'
}
private sliceEnd(data: string, offset: number): number {
let end = Math.min(data.length, offset + Math.max(1, REPLAY_CHARS_PER_TURN - this.chars))
// Keep UTF-16 surrogate pairs together across xterm replay slices.
const left = data.charCodeAt(end - 1)
const right = data.charCodeAt(end)
if (
end < data.length &&
left >= 0xd800 &&
left <= 0xdbff &&
right >= 0xdc00 &&
right <= 0xdfff
) {
end += end === offset + 1 ? 1 : -1
}
return end
}
async resize(cols: number, rows: number): Promise<void> {
const pendingYield = this.takeBudgetYield()
if (pendingYield) {
@@ -259,7 +259,7 @@ export class HistoryReader {
})
try {
const records = log.batches.flatMap((batch) => batch.records)
if (!(await replayTerminalHistory(emulator, checkpoint, records))) {
if (!(await replayTerminalHistory(emulator, checkpoint, (index) => records[index]))) {
return { restoreInfo: null, readFailed: true }
}
const snapshot = emulator.getSnapshot()
@@ -1,14 +1,12 @@
import type { HeadlessEmulator } from '../../emulation/headless-emulator'
import type { TerminalCheckpointFile } from '../../protocol/daemon-checkpoint-file'
import type { PendingOutputRecord } from '../../protocol/daemon-rpc-contract'
import { ColdRestoreReplayWriter } from './cold-restore-replay-writer'
import { isValidTerminalHistorySize } from './terminal-history-dimensions'
import { ColdRestoreReplayWriter, type ReplayRecordSource } from './cold-restore-replay-writer'
/** Raw checkpoint segments, then applied records, through one parser so modes carry across. */
export async function replayTerminalHistory(
emulator: HeadlessEmulator,
checkpoint: TerminalCheckpointFile | null,
records: Iterable<PendingOutputRecord>,
records: ReplayRecordSource,
isCanceled: () => boolean = () => false
): Promise<boolean> {
const replay = new ColdRestoreReplayWriter(emulator)
@@ -26,22 +24,5 @@ export async function replayTerminalHistory(
emulator.setLastTitle(checkpoint.lastTitle)
}
}
for (const record of records) {
if (isCanceled()) {
return false
}
if (record.kind === 'output') {
if (!(await replay.write(record.data))) {
return false
}
} else if (record.kind === 'resize') {
if (!isValidTerminalHistorySize(record.cols, record.rows)) {
return false
}
await replay.resize(record.cols, record.rows)
} else {
await replay.clearScrollback()
}
}
return !isCanceled()
return (await replay.replayRecords(records, isCanceled)) && !isCanceled()
}
@@ -201,6 +201,8 @@ export type GetSnapshotRequest = {
scrollbackRows?: number
/** Host-owned history answers only for this incarnation. */
expectedIncarnationId?: string
/** The caller's remaining wait; deep reads stop by it, capped by the daemon's own budget. */
remainingBudgetMs?: number
}
}
@@ -267,6 +267,40 @@ describe('daemon-owned terminal history', () => {
expect(screen?.data).not.toContain('OLD_INCARNATION')
}, 30_000)
// R2-A: a known answer whose full reply cannot fit must fail before it detaches the viewer.
it('refuses an over-long attach reply while the existing viewer keeps streaming', async () => {
const { child, options } = await startHostHistory()
const { id } = await adapter!.spawn({
sessionId: 'host-history-oversize-attach',
cols: 80,
rows: 24,
cwd: '/tmp'
})
child._simulateData('ATTACHED_ROW\r\n')
const request = { sessionId: id, cols: 80, rows: 24, cwd: '/tmp' }
// This attach leaves its answer as the latest result, then streams to its own viewer.
const viewer = new DaemonPtyAdapter(options)
const late = new DaemonPtyAdapter(options)
try {
expect((await viewer.spawn(request)).snapshot).toContain('ATTACHED_ROW')
const received: string[] = []
viewer.onData(({ data }) => received.push(data))
harness!.server.host.setLaunchNote(id, {
arm: {
launchToken: 'oversize',
launchConfig: { agentArgs: '', agentEnv: { BIG: 'x'.repeat(17 * 1024 * 1024) } }
}
})
await expect(late.spawn(request)).rejects.toThrow()
child._simulateData('AFTER_REFUSAL\r\n')
await waitFor(() => received.join('').includes('AFTER_REFUSAL'))
} finally {
await viewer.disconnectOnly()
viewer.dispose()
late.dispose()
}
}, 30_000)
// Ruling 23:29: after a storage gap the live terminal continues, deep history stays unavailable.
it('keeps the live window after a storage gap and never ends the gapped history cleanly', async () => {
const { child } = await startHostHistory()
@@ -0,0 +1,160 @@
import type { TerminalHost } from '../terminal-host/terminal-host'
import type {
AttachHistoryAdmission,
CreateOrAttachResult
} from '../terminal-host/terminal-host-create-contract'
import type { HistoryFlight } from '../history/journal/terminal-history-read-admission'
import type { HistoryReadConsumer } from '../history/journal/terminal-history-read-consumer'
import { TerminalAttachCanceledError } from '../protocol/daemon-errors'
import { TerminalHistoryUnavailableError } from '../protocol/daemon-history-protocol'
import { withPreparedReply, type PreparedDaemonReply } from './daemon-reply-obligation'
// Bounded like the former adapter overlay; the live terminal keeps running meanwhile.
const ATTACH_HISTORY_IMAGE_DEADLINE_MS = 5_000
/** The complete reply line for an attach result, from the existing encoder and projection. */
export type EncodeAttachReply = (result: Omit<CreateOrAttachResult, 'attachToken'>) => string
/**
* An attach's deep-history read. A cached or joined image is awaited with the old viewer still
* attached and its full reply is encoded in the same turn as the token install, at a proved
* anchor. A cold leader installs its token at C, reconstructs, then encodes before the final
* membership check. Every exit releases the consumer once, through the reply that carries it.
*/
export function openAttachHistory(
host: TerminalHost,
request: { cancelSignal: AbortSignal; isCanceled: () => boolean },
encodeReply: EncodeAttachReply
): {
admission: AttachHistoryAdmission
finish(
sessionId: string,
result: CreateOrAttachResult
): Promise<{ result: CreateOrAttachResult; prepared?: PreparedDaemonReply }>
fail(error: unknown): unknown
} {
const journals = host.historyJournals!
let consumer: HistoryReadConsumer | null = null
let leading: HistoryFlight | null = null
let line: string | undefined
// One absolute deadline for every admission, join, retry and settlement of this attach.
let signal: AbortSignal | null = null
const owned = (): PreparedDaemonReply | null => {
const held = consumer
return held ? { ...(line ? { line } : {}), release: () => held.release() } : null
}
const admission: AttachHistoryAdmission = {
admit: async (sessionId, incarnationId) => {
const journal = journals.live(sessionId, incarnationId)
const session = journal?.session
if (!journal || !session || journal.gapped) {
return null
}
signal ??= AbortSignal.any([
request.cancelSignal,
AbortSignal.timeout(ATTACH_HISTORY_IMAGE_DEADLINE_MS)
])
consumer ??= journals.reads.admit(signal)
const reader = consumer
if (!reader) {
throw new TerminalHistoryUnavailableError()
}
reader.dropImage()
line = undefined
const found = await reader.acquire(journal, undefined, () =>
session.settleShellOwnershipConfirmation()
)
if (!found) {
throw new TerminalHistoryUnavailableError()
}
leading = found === 'image' ? null : found
return {
capture: (result) => {
if (leading) {
// The cold leader's provisional token goes in at C; refusal leaves the old viewer.
if (!leading.capture()) {
throw new TerminalHistoryUnavailableError()
}
return 'captured'
}
// The live snapshot already ran its barrier; the image must match this exact anchor.
const image = reader.image
if (!image || journal.derivedKey(undefined) !== reader.key) {
return 'retry'
}
result.snapshot = image.snapshot
result.history = image.outcome
// Owned once: a later launch-note change cannot alter the encoded reply.
result.launchNote = structuredClone(result.launchNote)
line = encodeOrUnavailable(encodeReply, result)
return 'captured'
},
release: () => {
leading = null
reader.dropImage()
}
}
}
}
const fail = (error: unknown): unknown => {
const reply = owned()
consumer = null
const failure = error instanceof Error ? error : new TerminalHistoryUnavailableError()
return reply ? withPreparedReply(failure, { release: reply.release }) : failure
}
const finish = async (
sessionId: string,
result: CreateOrAttachResult
): Promise<{ result: CreateOrAttachResult; prepared?: PreparedDaemonReply }> => {
const journal = journals.live(sessionId, result.incarnationId)
if (result.isNew || !consumer) {
consumer?.release()
consumer = null
// A permanent gap still attaches the same live window, explicitly labelled.
const unavailable = { kind: 'unavailable' as const, incarnationId: result.incarnationId }
const outputSequence = result.isNew ? 0 : (result.snapshot?.outputSequence ?? 0)
return { result: { ...result, history: journal?.outcome(outputSequence) ?? unavailable } }
}
const reader = consumer
try {
let final = result
if (leading) {
const built = await reader.awaitFlight(leading)
if (request.isCanceled()) {
throw new TerminalAttachCanceledError(sessionId)
}
const image = reader.image
if (!built || !image || !journal) {
// Transient: the live owner is known, so the same ID retries; never presumed gone.
throw new TerminalHistoryUnavailableError()
}
final = { ...result, snapshot: image.snapshot, history: image.outcome }
line = encodeOrUnavailable(encodeReply, final)
}
// Final membership check, with no await before the caller commits the attachment.
if (
journals.live(sessionId, result.incarnationId) !== journal ||
!journal?.hasAttachedClient(result.attachToken)
) {
throw new TerminalAttachCanceledError(sessionId)
}
return { result: final, prepared: owned()! }
} catch (error) {
host.detach(sessionId, result.attachToken)
throw fail(error)
}
}
return { admission, finish, fail }
}
/** An over-long reply is honestly unavailable, never a smaller image; the existing encoder decides. */
function encodeOrUnavailable(
encodeReply: EncodeAttachReply,
result: Omit<CreateOrAttachResult, 'attachToken'>
): string {
try {
return encodeReply(result)
} catch {
throw new TerminalHistoryUnavailableError()
}
}
@@ -2,6 +2,7 @@ import { readTerminalStartFailure } from '../../../shared/terminal/pty/lifecycle
import type { Socket } from 'node:net'
import { NOTIFY_PREFIX, type DaemonRequest } from '../protocol/daemon-rpc-contract'
import { encodeNdjson } from '../../../shared/main-process-ndjson-framer'
import { takePreparedReply, type PreparedDaemonReply } from './daemon-reply-obligation'
export async function answerDaemonControlRequest(
socket: Socket,
@@ -10,23 +11,67 @@ export async function answerDaemonControlRequest(
onReply: () => void
): Promise<void> {
const isNotify = request.id.startsWith(NOTIFY_PREFIX)
let owned: PreparedDaemonReply | undefined
let line: string
let replied: (() => void) | undefined
try {
const result = await route()
if (!isNotify) {
socket.write(encodeNdjson({ id: request.id, ok: true, payload: result }), onReply)
owned = takePreparedReply(result)
if (isNotify) {
return owned?.release()
}
line = owned?.line ?? encodeNdjson({ id: request.id, ok: true, payload: result })
replied = onReply
} catch (error) {
if (!isNotify) {
socket.write(
encodeNdjson({
id: request.id,
ok: false,
error: error instanceof Error ? error.message : String(error),
...(readTerminalStartFailure(error)
? { terminalStartFailure: readTerminalStartFailure(error) }
: {})
})
)
owned ??= takePreparedReply(error)
if (isNotify) {
return owned?.release()
}
try {
line = encodeNdjson({
id: request.id,
ok: false,
error: error instanceof Error ? error.message : String(error),
...(readTerminalStartFailure(error)
? { terminalStartFailure: readTerminalStartFailure(error) }
: {})
})
} catch {
// Never recurse into another error frame.
return owned?.release()
}
}
writeOwnedReply(socket, line, owned, replied)
}
/** Holds the reply's resources until the write settles or the socket closes, exactly once. */
function writeOwnedReply(
socket: Socket,
line: string,
owned: PreparedDaemonReply | undefined,
onReply: (() => void) | undefined
): void {
if (owned && socket.destroyed) {
// A connection that already closed can never settle a write.
return owned.release()
}
let settled = false
const settle = (): void => {
if (!settled) {
settled = true
socket.off('close', settle)
owned?.release()
}
}
if (owned) {
socket.once('close', settle)
}
try {
socket.write(line, () => {
settle()
onReply?.()
})
} catch {
settle()
}
}
@@ -1,21 +1,39 @@
import { performance } from 'node:perf_hooks'
import type { Socket } from 'node:net'
import type { TerminalHost } from '../terminal-host/terminal-host'
import { recordDaemonStreamBacklogEvent } from '../transport/stream/daemon-stream-backlog-probe'
import type { GetSnapshotRequest, GetSnapshotResult } from '../protocol/daemon-rpc-contract'
import type { FlushHistoryRequest, FlushHistoryResult } from '../protocol/daemon-history-protocol'
import type { TerminalHistoryJournals } from '../history/journal/terminal-history-journals'
import { resolveDaemonSessionScrollbackRows } from '../sessions/daemon-session-scrollback-window'
import type { CreateOrAttachResult } from '../terminal-host/terminal-host-create-contract'
import { TerminalAttachCanceledError } from '../protocol/daemon-errors'
import { TerminalHistoryUnavailableError } from '../protocol/daemon-history-protocol'
import { awaitDaemonValueWithinCallerDeadline } from '../launch/daemon-request-deadline'
import { encodeNdjson } from '../../../shared/main-process-ndjson-framer'
import { withPreparedReply } from './daemon-reply-obligation'
// Deep reads end by the caller's own budget; a client that sends none still gets a finite one.
const DEEP_SNAPSHOT_BUDGET_MS = 30_000
// Bounded like the former adapter overlay; the live terminal keeps running meanwhile.
const ATTACH_HISTORY_IMAGE_DEADLINE_MS = 5_000
export function answerDaemonHistoryRequest(
export async function answerDaemonHistoryRequest(
host: TerminalHost,
request: GetSnapshotRequest | FlushHistoryRequest
request: GetSnapshotRequest | FlushHistoryRequest,
socket: Socket | undefined
): Promise<GetSnapshotResult | FlushHistoryResult> {
// Aborts when this client's control socket closes, including one already closed.
const disconnect = new AbortController()
const abort = (): void => disconnect.abort(new Error('client_disconnected'))
if (!socket || socket.destroyed) {
abort()
}
socket?.once('close', abort)
try {
return await answerWithin(host, request, disconnect.signal)
} finally {
socket?.off('close', abort)
}
}
function answerWithin(
host: TerminalHost,
request: GetSnapshotRequest | FlushHistoryRequest,
disconnected: AbortSignal
): Promise<GetSnapshotResult | FlushHistoryResult> {
if (request.type === 'flushHistory') {
return flushDaemonHistory(host.historyJournals, request.payload)
@@ -25,11 +43,21 @@ export function answerDaemonHistoryRequest(
typeof requested === 'number' && Number.isFinite(requested)
? Math.max(0, Math.min(50_000, Math.floor(requested)))
: undefined
const budget = request.payload.remainingBudgetMs
const budgetMs =
typeof budget === 'number' && Number.isFinite(budget)
? Math.max(1, Math.min(DEEP_SNAPSHOT_BUDGET_MS, budget))
: DEEP_SNAPSHOT_BUDGET_MS
return host.historyJournals
? readDaemonHistorySnapshot(host, host.historyJournals, {
...request.payload,
scrollbackRows
})
? readDaemonHistorySnapshot(
host,
host.historyJournals,
{
id: request.id,
signal: AbortSignal.any([disconnected, AbortSignal.timeout(budgetMs)])
},
{ ...request.payload, scrollbackRows }
)
: readLiveDaemonSnapshot(host, request.payload.sessionId, scrollbackRows)
}
@@ -50,10 +78,11 @@ async function readLiveDaemonSnapshot(
return { snapshot }
}
/** Live window from the 1k model; deeper reads replay the journal's cut, never rebasing it. */
/** Live window from the 1k model; deeper reads share one flight and the latest derived answer. */
async function readDaemonHistorySnapshot(
host: TerminalHost,
journals: TerminalHistoryJournals,
request: { id: string; signal: AbortSignal },
payload: GetSnapshotRequest['payload']
): Promise<GetSnapshotResult> {
const { sessionId, expectedIncarnationId, scrollbackRows } = payload
@@ -66,33 +95,41 @@ async function readDaemonHistorySnapshot(
snapshot: null,
history: { kind: 'unavailable', incarnationId: session.incarnationId }
}
if (
journal.gapped ||
(scrollbackRows !== undefined && scrollbackRows <= resolveDaemonSessionScrollbackRows())
) {
// Public live0 never waits for deep admission, the cold lane or the cache.
if (scrollbackRows !== undefined && scrollbackRows <= resolveDaemonSessionScrollbackRows()) {
const snapshot = await host.getSettledSnapshot(sessionId, { scrollbackRows })
return snapshot && journals.live(sessionId, session.incarnationId) === journal
? { snapshot, history: journal.outcome(snapshot.outputSequence ?? 0) }
: unavailable
}
// Settle ownership proof first so the cut's owner matches its bytes.
await session.settleShellOwnershipConfirmation()
const capture = () => (journal.session ? journal.captureCut() : null)
const image = await journal.readImage(capture, { scrollbackRows })
if (journals.live(sessionId, session.incarnationId) !== journal) {
// The incarnation it was read for no longer owns the ID; never publish it for a successor.
// Past a gap no deeper answer exists; the live window stays its own operation.
const consumer = journal.gapped ? null : journals.reads.admit(request.signal)
if (!consumer) {
return unavailable
}
if (image) {
return { snapshot: image.snapshot, history: image.outcome }
const failed = (): GetSnapshotResult =>
withPreparedReply({ ...unavailable }, { release: () => consumer.release() })
try {
const found = await consumer.acquire(journal, scrollbackRows, async () => {
// Settle ownership proof and held startup bytes so the cut's owner matches its bytes.
await session.settleShellOwnershipConfirmation()
session.snapshotBarrier()
})
const ready =
found === 'image' ||
(found !== null && found.capture() && (await consumer.awaitFlight(found)))
const image = consumer.image
// The incarnation it was read for must still own the ID; never publish it for a successor.
if (!ready || !image || journals.live(sessionId, session.incarnationId) !== journal) {
return failed()
}
const result: GetSnapshotResult = { snapshot: image.snapshot, history: image.outcome }
// The existing encoder, once; an over-long line fails honestly, never as a smaller image.
const line = encodeNdjson({ id: request.id, ok: true, payload: result })
return withPreparedReply(result, { line, release: () => consumer.release() })
} catch {
return failed()
}
return journal.gapped
? readDaemonHistorySnapshot(host, journals, {
sessionId,
scrollbackRows: 0,
expectedIncarnationId: session.incarnationId
})
: unavailable
}
async function flushDaemonHistory(
@@ -110,56 +147,3 @@ async function flushDaemonHistory(
const committed = await journal.flush({ final: payload.final === true })
return { status: committed ? 'committed' : 'unavailable' }
}
/**
* Attach builds the image at the server-owned cut while this attempt's token is still held.
* Failure detaches only that token, so a later attempt keeps its stream and input.
*/
export async function withAttachHistoryImage(
host: TerminalHost,
sessionId: string,
result: CreateOrAttachResult,
isCanceled: () => boolean
): Promise<CreateOrAttachResult> {
const journal = host.historyJournals?.live(sessionId, result.incarnationId)
const cut = result.historyCut
if (result.isNew || !cut) {
const unavailable = { kind: 'unavailable' as const, incarnationId: result.incarnationId }
return { ...result, history: journal?.outcome(0) ?? unavailable }
}
try {
if (!journal || !result.snapshot) {
throw new TerminalHistoryUnavailableError()
}
let timedOut = false
const read = cut.gapped
? null
: await awaitDaemonValueWithinCallerDeadline(
journal.readImage(cut, { isCanceled: () => timedOut || isCanceled() }),
Date.now() + ATTACH_HISTORY_IMAGE_DEADLINE_MS
)
timedOut = true
const image = read?.completed ? read.value : null
if (isCanceled()) {
throw new TerminalAttachCanceledError(sessionId)
}
if (!image && !journal.gapped) {
// Transient: the live owner is known, so the same ID retries; never presumed gone.
throw new TerminalHistoryUnavailableError()
}
// Final membership check, with no await before the caller commits the attachment.
if (
host.historyJournals?.live(sessionId, result.incarnationId) !== journal ||
!journal.hasAttachedClient(result.attachToken)
) {
throw new TerminalAttachCanceledError(sessionId)
}
// A permanent gap still attaches the same live window, explicitly labelled.
return image
? { ...result, snapshot: image.snapshot, history: image.outcome }
: { ...result, history: journal.outcome(cut.outputSequence) }
} catch (error) {
host.detach(sessionId, result.attachToken)
throw error
}
}
@@ -0,0 +1,26 @@
/**
* What a reply owns until its bytes have actually left: an admitted consumer and any image it
* holds, and optionally the full line already encoded with the existing encoder. It travels to
* the outer writer beside the route's value and never enters the wire payload.
*/
export type PreparedDaemonReply = {
/** The complete `{id, ok, payload}` line; written as-is, never encoded again. */
readonly line?: string
release(): void
}
const prepared = new WeakMap<object, PreparedDaemonReply>()
export function withPreparedReply<T extends object>(value: T, reply: PreparedDaemonReply): T {
prepared.set(value, reply)
return value
}
export function takePreparedReply(value: unknown): PreparedDaemonReply | undefined {
if (value === null || typeof value !== 'object') {
return undefined
}
const reply = prepared.get(value)
prepared.delete(value)
return reply
}
@@ -168,7 +168,11 @@ export class DaemonRequestRouter {
return this.shutdownIfIdle(clientId, request.id)
case 'getSnapshot':
case 'flushHistory':
return answerDaemonHistoryRequest(this.options.host, request)
return answerDaemonHistoryRequest(
this.options.host,
request,
this.options.connections.get(clientId)?.controlSocket
)
case 'getSize':
return { size: this.options.host.getAppliedSize(request.payload.sessionId) }
case 'takePendingOutput':
@@ -27,7 +27,9 @@ import {
} from '../../../shared/agent-session/agent-session-host-authority'
import type { DaemonRequest } from '../protocol/daemon-rpc-contract'
import { TerminalAttachCanceledError } from '../protocol/daemon-errors'
import { withAttachHistoryImage } from './daemon-history-requests'
import { openAttachHistory } from './daemon-attach-history'
import { withPreparedReply, type PreparedDaemonReply } from './daemon-reply-obligation'
import { encodeNdjson } from '../../../shared/main-process-ndjson-framer'
type CreateOrAttachRequest = Extract<DaemonRequest, { type: 'createOrAttach' }>
@@ -86,6 +88,8 @@ export class DaemonTerminalAdmission {
let routedSessionId = payload.sessionId
let result: CreateOrAttachResult
let spawnPreparation: PendingPtySpawnPreparation | null = null
let prepared: PreparedDaemonReply | undefined
let attachHistory: ReturnType<typeof openAttachHistory> | undefined
try {
if (
payload.agentSessionEnsure !== undefined &&
@@ -115,7 +119,21 @@ export class DaemonTerminalAdmission {
? []
: [payload.historySeed]
: undefined
const preparation = spawnPreparation
attachHistory = this.options.host.historyJournals
? openAttachHistory(
this.options.host,
{
cancelSignal: preparation.controller.signal,
isCanceled: () => preparation.canceled === true
},
// The whole wire reply through the existing encoder, once; the writer sends this line.
(reply) =>
encodeNdjson({ id: request.id, ok: true, payload: toCreateOrAttachReply(reply) })
)
: undefined
result = await this.options.host.createOrAttach({
...(attachHistory ? { attachHistory: attachHistory.admission } : {}),
sessionId: payload.sessionId,
cols: payload.cols,
rows: payload.rows,
@@ -149,14 +167,14 @@ export class DaemonTerminalAdmission {
},
streamClient: this.createStreamClient(clientId, () => routedSessionId)
})
if (this.options.host.historyJournals) {
result = await withAttachHistoryImage(
this.options.host,
if (attachHistory) {
;({ result, prepared } = await attachHistory.finish(
result.agentSessionEnsure?.owner.ptyId ?? payload.sessionId,
result,
() => spawnPreparation?.canceled === true
)
result
))
}
} catch (error) {
throw attachHistory ? attachHistory.fail(error) : error
} finally {
if (spawnPreparation) {
this.options.preparations.finish(payload.sessionId, spawnPreparation)
@@ -172,7 +190,8 @@ export class DaemonTerminalAdmission {
client.streamSocket === null
) {
this.options.host.detach(routedSessionId, result.attachToken)
throw new TerminalAttachCanceledError(routedSessionId)
const canceled = new TerminalAttachCanceledError(routedSessionId)
throw prepared ? withPreparedReply(canceled, { release: prepared.release }) : canceled
}
this.options.attachments.attach(routedSessionId, clientId, result.attachToken)
this.options.streamDataBatcher.refreshSessionDroppability(routedSessionId)
@@ -188,23 +207,8 @@ export class DaemonTerminalAdmission {
sessionId: routedSessionId,
pid: result.pid
})
return {
isNew: result.isNew,
snapshot: result.snapshot,
pid: result.pid,
shellState: result.shellState,
incarnationId: result.incarnationId,
...(result.launchAgent ? { launchAgent: result.launchAgent } : {}),
...(result.launchNote !== undefined ? { launchNote: result.launchNote } : {}),
wslDistro: result.wslDistro,
...(result.historySeeded !== undefined ? { historySeeded: result.historySeeded } : {}),
...(result.agentSessionEnsure ? { agentSessionEnsure: result.agentSessionEnsure } : {}),
...(result.cwdReadableByDaemon !== undefined
? { cwdReadableByDaemon: result.cwdReadableByDaemon }
: {}),
...(result.inputClosed ? { inputClosed: true as const } : {}),
...(result.history ? { history: result.history } : {})
}
const reply = toCreateOrAttachReply(result)
return prepared ? withPreparedReply(reply, prepared) : reply
}
private createStreamClient(
@@ -263,3 +267,24 @@ export class DaemonTerminalAdmission {
}
}
}
/** The wire payload of a create or attach result; the attach token never leaves the daemon. */
function toCreateOrAttachReply(result: Omit<CreateOrAttachResult, 'attachToken'>) {
return {
isNew: result.isNew,
snapshot: result.snapshot,
pid: result.pid,
shellState: result.shellState,
incarnationId: result.incarnationId,
...(result.launchAgent ? { launchAgent: result.launchAgent } : {}),
...(result.launchNote !== undefined ? { launchNote: result.launchNote } : {}),
wslDistro: result.wslDistro,
...(result.historySeeded !== undefined ? { historySeeded: result.historySeeded } : {}),
...(result.agentSessionEnsure ? { agentSessionEnsure: result.agentSessionEnsure } : {}),
...(result.cwdReadableByDaemon !== undefined
? { cwdReadableByDaemon: result.cwdReadableByDaemon }
: {}),
...(result.inputClosed ? { inputClosed: true as const } : {}),
...(result.history ? { history: result.history } : {})
}
}
@@ -0,0 +1,106 @@
import { EventEmitter } from 'node:events'
import type { Socket } from 'node:net'
import { describe, expect, it, vi } from 'vitest'
import { answerDaemonControlRequest } from '../daemon-control-request'
import { withPreparedReply } from '../daemon-reply-obligation'
import type { DaemonRequest } from '../../protocol/daemon-rpc-contract'
type Write = { line: string; done: () => void }
function fakeSocket(opts: { destroyed?: boolean; throws?: boolean } = {}) {
const writes: Write[] = []
const socket = Object.assign(new EventEmitter(), {
destroyed: opts.destroyed === true,
write: (line: string, done: () => void) => {
if (opts.throws) {
throw new Error('write after end')
}
writes.push({ line, done })
return true
}
})
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the writer uses only write, destroyed and close events.
return { socket: socket as unknown as Socket, writes }
}
const request = (id = 'req-1'): DaemonRequest =>
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the writer reads only the id.
({ id, type: 'getSnapshot', payload: { sessionId: 's' } }) as DaemonRequest
describe('deep-history reply ownership at the outer writer', () => {
it('writes the prepared line verbatim and releases only when the write settles', async () => {
const { socket, writes } = fakeSocket()
const release = vi.fn()
const onReply = vi.fn()
const line = '{"id":"req-1","ok":true,"payload":{"marker":"\\u001b[1mPREPARED"}}\n'
await answerDaemonControlRequest(
socket,
request(),
async () => withPreparedReply({ ignored: true }, { line, release }),
onReply
)
expect(writes.map((write) => write.line)).toEqual([line])
// A caller timeout while bytes are still buffered must not free them.
expect(release).not.toHaveBeenCalled()
writes[0]!.done()
socket.emit('close')
expect(release).toHaveBeenCalledTimes(1)
expect(onReply).toHaveBeenCalledTimes(1)
})
it('releases once when the socket closes before the write settles', async () => {
const { socket, writes } = fakeSocket()
const release = vi.fn()
await answerDaemonControlRequest(
socket,
request(),
async () => withPreparedReply({}, { line: 'x\n', release }),
() => {}
)
socket.emit('close')
writes[0]!.done()
expect(release).toHaveBeenCalledTimes(1)
})
it.each([
['an already closed socket', { destroyed: true }, 'req-1'],
['a throwing write', { throws: true }, 'req-1'],
['a notification', {}, 'notify_1']
] as const)('releases %s without leaking the reply', async (_, opts, id) => {
const { socket, writes } = fakeSocket(opts)
const release = vi.fn()
await answerDaemonControlRequest(
socket,
request(id),
async () => withPreparedReply({}, { line: 'x\n', release }),
() => {}
)
expect(release).toHaveBeenCalledTimes(1)
expect(writes).toHaveLength(0)
})
it('writes a failed read as an ordinary error and releases its consumer after the write', async () => {
const { socket, writes } = fakeSocket()
const release = vi.fn()
await answerDaemonControlRequest(
socket,
request(),
async () => {
throw withPreparedReply(new Error('terminal_history_unavailable'), { release })
},
() => {}
)
expect(JSON.parse(writes[0]!.line)).toEqual({
id: 'req-1',
ok: false,
error: 'terminal_history_unavailable'
})
expect(release).not.toHaveBeenCalled()
writes[0]!.done()
expect(release).toHaveBeenCalledTimes(1)
})
})
+5 -1
View File
@@ -218,10 +218,14 @@ export class Session extends SessionProcessInspection {
}
getSnapshot(opts: { scrollbackRows?: number } = {}): TerminalSnapshot | null {
this.startupIngress.snapshotBarrier()
this.snapshotBarrier()
return this.output.getSnapshot(opts)
}
snapshotBarrier(): void {
this.startupIngress.snapshotBarrier()
}
getPartialEscapeTailAnsi(): string {
return this.output.getPartialEscapeTailAnsi()
}
@@ -11,11 +11,25 @@ import type {
} from '../../../shared/agent-session/agent-session-host-authority'
import type { PtyIncarnationId } from '../../../shared/terminal/pty/lifecycle/pty-incarnation'
import type { TerminalExitCause } from '../../../shared/terminal/pty/lifecycle/terminal-exit-cause'
import type { TerminalHistoryCut } from '../history/journal/terminal-session-journal'
import type { TerminalHistoryOutcome } from '../protocol/daemon-history-protocol'
/** Deep-history admission an attach takes before its atomic cut, while the old viewer stays. */
export type AttachHistoryAdmission = {
admit(sessionId: string, incarnationId: string): Promise<AttachHistoryHold | null>
}
export type AttachHistoryHold = {
/**
* Synchronous with the live snapshot and token attach: freezes the cut, or substitutes the
* image at a proved anchor and encodes the final reply. 'retry' leaves the old viewer intact.
*/
capture(result: Omit<CreateOrAttachResult, 'attachToken'>): 'captured' | 'retry'
release(): void
}
export type CreateOrAttachOptions = {
sessionId: string
attachHistory?: AttachHistoryAdmission
cols: number
rows: number
cwd?: string
@@ -64,7 +78,5 @@ export type CreateOrAttachResult = {
cwdReadableByDaemon?: boolean
/** The live child can no longer take input through its PTY master. */
inputClosed?: true
/** Internal: the attach cut for the host-owned history image, never sent on the wire. */
historyCut?: TerminalHistoryCut
history?: TerminalHistoryOutcome
}
@@ -67,24 +67,41 @@ export async function createOrAttachTerminalSession(
attachedSession.physicalCompletion,
terminalSessionExitCode(attachedSession)
)
const snapshot = existing.getSnapshot()
// Same turn as the live snapshot and stream attach, so the history image meets the stream exactly.
const historyCut = deps.historyJournals
?.live(opts.sessionId, existing.incarnationId)
?.captureCut()
existing.detachAllClients()
const token = existing.attachClient(opts.streamClient)
attachSessionInputViewer(existing, opts.streamClient)
return {
isNew: false,
snapshot,
pid: existing.pid,
shellState: existing.shellState,
incarnationId: existing.incarnationId,
...getDaemonSessionResultMetadata(existing),
...(isSessionInputClosed(existing) ? { inputClosed: true as const } : {}),
...(historyCut ? { historyCut } : {}),
attachToken: token
for (;;) {
// Admission waits here with the old viewer still attached; denial never detaches it.
const hold = await opts.attachHistory?.admit(opts.sessionId, attachedSession.incarnationId)
if (
deps.sessions.get(opts.sessionId) !== attachedSession ||
!attachedSession.isAlive ||
attachedSession.isTerminating
) {
hold?.release()
return createOrAttachTerminalSession(opts, deps)
}
try {
deps.assertCreateAllowed()
// One turn: snapshot, cut, encoded reply and stream attach meet; no await splits them.
const result = {
isNew: false,
snapshot: attachedSession.getSnapshot(),
pid: attachedSession.pid,
shellState: attachedSession.shellState,
incarnationId: attachedSession.incarnationId,
...getDaemonSessionResultMetadata(attachedSession),
...(isSessionInputClosed(attachedSession) ? { inputClosed: true as const } : {})
}
if (hold?.capture(result) === 'retry') {
hold.release()
continue
}
attachedSession.detachAllClients()
const token = attachedSession.attachClient(opts.streamClient)
attachSessionInputViewer(attachedSession, opts.streamClient)
return { ...result, attachToken: token }
} catch (error) {
hold?.release()
throw error
}
}
}
@@ -56,7 +56,9 @@ export function requestDaemonRpc<T>(opts: DaemonRpcRequestOptions): Promise<T> {
...payload,
cancelAfterMs: Math.max(1, opts.timeoutMs + opts.unmatchedCancelGraceMs)
}
: payload
: type === 'getSnapshot' && payload !== null && typeof payload === 'object'
? { ...payload, remainingBudgetMs: opts.timeoutMs }
: payload
const encoded = encodeNdjson({
id: opts.id,
type,