From aec4d35a0bef01089a1fe2f9da32807259cb40ad Mon Sep 17 00:00:00 2001 From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com> Date: Thu, 12 Nov 2026 08:49:06 -0800 Subject: [PATCH] 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) --- .../daemon/emulation/headless-emulator.ts | 10 +- .../journal/terminal-history-derived-image.ts | 95 +++++++ .../terminal-history-detached-snapshot.ts | 25 ++ .../journal/terminal-history-journals.ts | 25 +- .../terminal-history-pending-source.ts | 36 +++ .../terminal-history-read-admission.ts | 264 ++++++++++++++++++ .../journal/terminal-history-read-consumer.ts | 139 +++++++++ .../terminal-session-journal-contract.ts | 12 +- .../journal/terminal-session-journal-reads.ts | 145 ++++++++-- .../terminal-session-journal-source.ts | 37 ++- .../journal/terminal-session-journal.ts | 12 +- .../terminal-history-read-flight.test.ts | 227 +++++++++++++++ .../testing/terminal-session-journal.test.ts | 15 +- .../restoration/cold-restore-replay-writer.ts | 82 ++++++ .../history/restoration/history-reader.ts | 2 +- .../restoration/terminal-history-replay.ts | 25 +- .../daemon/protocol/daemon-rpc-contract.ts | 2 + .../daemon-pty-adapter-host-history.test.ts | 34 +++ .../daemon/server/daemon-attach-history.ts | 160 +++++++++++ .../daemon/server/daemon-control-request.ts | 71 ++++- .../daemon/server/daemon-history-requests.ts | 156 +++++------ .../daemon/server/daemon-reply-obligation.ts | 26 ++ .../daemon/server/daemon-request-router.ts | 6 +- .../server/daemon-terminal-admission.ts | 75 +++-- .../testing/daemon-control-request.test.ts | 106 +++++++ src/main/daemon/sessions/session.ts | 6 +- .../terminal-host-create-contract.ts | 18 +- .../terminal-host-session-create.ts | 53 ++-- .../client/daemon-client-rpc-request.ts | 4 +- 29 files changed, 1642 insertions(+), 226 deletions(-) create mode 100644 src/main/daemon/history/journal/terminal-history-derived-image.ts create mode 100644 src/main/daemon/history/journal/terminal-history-detached-snapshot.ts create mode 100644 src/main/daemon/history/journal/terminal-history-pending-source.ts create mode 100644 src/main/daemon/history/journal/terminal-history-read-admission.ts create mode 100644 src/main/daemon/history/journal/terminal-history-read-consumer.ts create mode 100644 src/main/daemon/history/journal/testing/terminal-history-read-flight.test.ts create mode 100644 src/main/daemon/server/daemon-attach-history.ts create mode 100644 src/main/daemon/server/daemon-reply-obligation.ts create mode 100644 src/main/daemon/server/testing/daemon-control-request.test.ts diff --git a/src/main/daemon/emulation/headless-emulator.ts b/src/main/daemon/emulation/headless-emulator.ts index 092f1bacd97..3da261f74c1 100644 --- a/src/main/daemon/emulation/headless-emulator.ts +++ b/src/main/daemon/emulation/headless-emulator.ts @@ -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) - } } diff --git a/src/main/daemon/history/journal/terminal-history-derived-image.ts b/src/main/daemon/history/journal/terminal-history-derived-image.ts new file mode 100644 index 00000000000..c09cf44b630 --- /dev/null +++ b/src/main/daemon/history/journal/terminal-history-derived-image.ts @@ -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() + + 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 +} diff --git a/src/main/daemon/history/journal/terminal-history-detached-snapshot.ts b/src/main/daemon/history/journal/terminal-history-detached-snapshot.ts new file mode 100644 index 00000000000..e0e109e7d08 --- /dev/null +++ b/src/main/daemon/history/journal/terminal-history-detached-snapshot.ts @@ -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) })) } + : {}) + } +} diff --git a/src/main/daemon/history/journal/terminal-history-journals.ts b/src/main/daemon/history/journal/terminal-history-journals.ts index 645e25b9223..60975922a62 100644 --- a/src/main/daemon/history/journal/terminal-history-journals.ts +++ b/src/main/daemon/history/journal/terminal-history-journals.ts @@ -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() private readonly open = new Set() @@ -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 diff --git a/src/main/daemon/history/journal/terminal-history-pending-source.ts b/src/main/daemon/history/journal/terminal-history-pending-source.ts new file mode 100644 index 00000000000..4c21687bde0 --- /dev/null +++ b/src/main/daemon/history/journal/terminal-history-pending-source.ts @@ -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?.() + } +} diff --git a/src/main/daemon/history/journal/terminal-history-read-admission.ts b/src/main/daemon/history/journal/terminal-history-read-admission.ts new file mode 100644 index 00000000000..9869f062a79 --- /dev/null +++ b/src/main/daemon/history/journal/terminal-history-read-admission.ts @@ -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 + 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((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 { + 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() + } + } + } + } + } +} diff --git a/src/main/daemon/history/journal/terminal-history-read-consumer.ts b/src/main/daemon/history/journal/terminal-history-read-consumer.ts new file mode 100644 index 00000000000..7b931a7f265 --- /dev/null +++ b/src/main/daemon/history/journal/terminal-history-read-consumer.ts @@ -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 + ): Promise { + 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 { + 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 { + const interest = this.interest! + const abort = Promise.withResolvers() + 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) + } + } +} diff --git a/src/main/daemon/history/journal/terminal-session-journal-contract.ts b/src/main/daemon/history/journal/terminal-session-journal-contract.ts index 74ad45eb4ab..9138430e2ca 100644 --- a/src/main/daemon/history/journal/terminal-session-journal-contract.ts +++ b/src/main/daemon/history/journal/terminal-session-journal-contract.ts @@ -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): 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 & { + source: RevocablePendingSource +} + export type TerminalJournalSession = { readonly incarnationId: string readonly historySeeded: boolean | undefined readonly isAlive: boolean settleShellOwnershipConfirmation(): Promise + /** Releases held startup bytes into the stream, as a live snapshot would first. */ + snapshotBarrier(): void prepareForFinalSnapshot(): string } diff --git a/src/main/daemon/history/journal/terminal-session-journal-reads.ts b/src/main/daemon/history/journal/terminal-session-journal-reads.ts index b108b69f6a7..50561d4df55 100644 --- a/src/main/daemon/history/journal/terminal-session-journal-reads.ts +++ b/src/main/daemon/history/journal/terminal-session-journal-reads.ts @@ -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 { - 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 { + // 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 { return replayTerminalJournalSource( diff --git a/src/main/daemon/history/journal/terminal-session-journal-source.ts b/src/main/daemon/history/journal/terminal-session-journal-source.ts index ca560fdd4d9..e8d7bbf09ae 100644 --- a/src/main/daemon/history/journal/terminal-session-journal-source.ts +++ b/src/main/daemon/history/journal/terminal-session-journal-source.ts @@ -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 { - 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) { diff --git a/src/main/daemon/history/journal/terminal-session-journal.ts b/src/main/daemon/history/journal/terminal-session-journal.ts index 13859082c2f..48c5c686dbc 100644 --- a/src/main/daemon/history/journal/terminal-session-journal.ts +++ b/src/main/daemon/history/journal/terminal-session-journal.ts @@ -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() diff --git a/src/main/daemon/history/journal/testing/terminal-history-read-flight.test.ts b/src/main/daemon/history/journal/testing/terminal-history-read-flight.test.ts new file mode 100644 index 00000000000..1fea110c623 --- /dev/null +++ b/src/main/daemon/history/journal/testing/terminal-history-read-flight.test.ts @@ -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 => { + 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 { + 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() + 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() + 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() + }) +}) diff --git a/src/main/daemon/history/journal/testing/terminal-session-journal.test.ts b/src/main/daemon/history/journal/testing/terminal-session-journal.test.ts index 2b9a544d5c8..72e69f80fe9 100644 --- a/src/main/daemon/history/journal/testing/terminal-session-journal.test.ts +++ b/src/main/daemon/history/journal/testing/terminal-session-journal.test.ts @@ -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) diff --git a/src/main/daemon/history/restoration/cold-restore-replay-writer.ts b/src/main/daemon/history/restoration/cold-restore-replay-writer.ts index 698347edc2b..06e42b5c71a 100644 --- a/src/main/daemon/history/restoration/cold-restore-replay-writer.ts +++ b/src/main/daemon/history/restoration/cold-restore-replay-writer.ts @@ -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 { + 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 { const pendingYield = this.takeBudgetYield() if (pendingYield) { diff --git a/src/main/daemon/history/restoration/history-reader.ts b/src/main/daemon/history/restoration/history-reader.ts index 78e0ff3f461..980b1acd567 100644 --- a/src/main/daemon/history/restoration/history-reader.ts +++ b/src/main/daemon/history/restoration/history-reader.ts @@ -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() diff --git a/src/main/daemon/history/restoration/terminal-history-replay.ts b/src/main/daemon/history/restoration/terminal-history-replay.ts index cc9283a65fe..dd67ac7d196 100644 --- a/src/main/daemon/history/restoration/terminal-history-replay.ts +++ b/src/main/daemon/history/restoration/terminal-history-replay.ts @@ -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, + records: ReplayRecordSource, isCanceled: () => boolean = () => false ): Promise { 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() } diff --git a/src/main/daemon/protocol/daemon-rpc-contract.ts b/src/main/daemon/protocol/daemon-rpc-contract.ts index 327a188f7f5..75063730e7a 100644 --- a/src/main/daemon/protocol/daemon-rpc-contract.ts +++ b/src/main/daemon/protocol/daemon-rpc-contract.ts @@ -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 } } diff --git a/src/main/daemon/providers/adapter/testing/daemon-pty-adapter-host-history.test.ts b/src/main/daemon/providers/adapter/testing/daemon-pty-adapter-host-history.test.ts index c21179d783f..1e7c936962a 100644 --- a/src/main/daemon/providers/adapter/testing/daemon-pty-adapter-host-history.test.ts +++ b/src/main/daemon/providers/adapter/testing/daemon-pty-adapter-host-history.test.ts @@ -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() diff --git a/src/main/daemon/server/daemon-attach-history.ts b/src/main/daemon/server/daemon-attach-history.ts new file mode 100644 index 00000000000..bab09fbd5ae --- /dev/null +++ b/src/main/daemon/server/daemon-attach-history.ts @@ -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) => 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 +): string { + try { + return encodeReply(result) + } catch { + throw new TerminalHistoryUnavailableError() + } +} diff --git a/src/main/daemon/server/daemon-control-request.ts b/src/main/daemon/server/daemon-control-request.ts index 011a004520b..c223cb42c41 100644 --- a/src/main/daemon/server/daemon-control-request.ts +++ b/src/main/daemon/server/daemon-control-request.ts @@ -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 { 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() + } } diff --git a/src/main/daemon/server/daemon-history-requests.ts b/src/main/daemon/server/daemon-history-requests.ts index 83021c61f90..ec733f31990 100644 --- a/src/main/daemon/server/daemon-history-requests.ts +++ b/src/main/daemon/server/daemon-history-requests.ts @@ -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 { + // 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 { 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 { 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 { - 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 - } -} diff --git a/src/main/daemon/server/daemon-reply-obligation.ts b/src/main/daemon/server/daemon-reply-obligation.ts new file mode 100644 index 00000000000..0eef4ceb62b --- /dev/null +++ b/src/main/daemon/server/daemon-reply-obligation.ts @@ -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() + +export function withPreparedReply(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 +} diff --git a/src/main/daemon/server/daemon-request-router.ts b/src/main/daemon/server/daemon-request-router.ts index 36fe595409c..c362c6ecb05 100644 --- a/src/main/daemon/server/daemon-request-router.ts +++ b/src/main/daemon/server/daemon-request-router.ts @@ -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': diff --git a/src/main/daemon/server/daemon-terminal-admission.ts b/src/main/daemon/server/daemon-terminal-admission.ts index 322379272ed..444005af956 100644 --- a/src/main/daemon/server/daemon-terminal-admission.ts +++ b/src/main/daemon/server/daemon-terminal-admission.ts @@ -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 @@ -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 | 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) { + 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 } : {}) + } +} diff --git a/src/main/daemon/server/testing/daemon-control-request.test.ts b/src/main/daemon/server/testing/daemon-control-request.test.ts new file mode 100644 index 00000000000..267a6ce8266 --- /dev/null +++ b/src/main/daemon/server/testing/daemon-control-request.test.ts @@ -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) + }) +}) diff --git a/src/main/daemon/sessions/session.ts b/src/main/daemon/sessions/session.ts index 44a003553b7..8ff2d2c9645 100644 --- a/src/main/daemon/sessions/session.ts +++ b/src/main/daemon/sessions/session.ts @@ -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() } diff --git a/src/main/daemon/terminal-host/terminal-host-create-contract.ts b/src/main/daemon/terminal-host/terminal-host-create-contract.ts index 8f9ebd1e633..91ec791edcc 100644 --- a/src/main/daemon/terminal-host/terminal-host-create-contract.ts +++ b/src/main/daemon/terminal-host/terminal-host-create-contract.ts @@ -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 +} + +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): '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 } diff --git a/src/main/daemon/terminal-host/terminal-host-session-create.ts b/src/main/daemon/terminal-host/terminal-host-session-create.ts index be2f60bf4d9..fb5db2ed402 100644 --- a/src/main/daemon/terminal-host/terminal-host-session-create.ts +++ b/src/main/daemon/terminal-host/terminal-host-session-create.ts @@ -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 + } } } diff --git a/src/main/daemon/transport/client/daemon-client-rpc-request.ts b/src/main/daemon/transport/client/daemon-client-rpc-request.ts index a58ca18ec51..ef82c38e28a 100644 --- a/src/main/daemon/transport/client/daemon-client-rpc-request.ts +++ b/src/main/daemon/transport/client/daemon-client-rpc-request.ts @@ -56,7 +56,9 @@ export function requestDaemonRpc(opts: DaemonRpcRequestOptions): Promise { ...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,