The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat: upgrade terminal protocol to v3, add diagnostic tracking, and implement output buffer limits with improved snapshot resiliency
0xken1571b2d5e5fa27
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex 8daf10850..932d4088b 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -1238,12 +1238,13 @@ export class BackendSocket {/** Map a registered tmux session onto the web's Project shape (tabs in ProjectTabs). */private async toProject(s: RegisteredSession): Promise<{- id: string; userId: string; name: string; status: string+ id: string; sessionId: string; userId: string; name: string; status: stringcreatedAt: string; updatedAt: string; tmuxPane: string | null; terminal: { primary: string; runtimes: RegisteredSession['runtimes'] }; engine: RegisteredSession['engine']; selectedModel: string | null}> {const st = s.transcriptPath ? await stat(s.transcriptPath).catch(() => null) : nullreturn {id: s.agentId,+ sessionId: s.sessionId,userId: '',name: projectDisplayName(s),status: s.active ? 'active' : 'offline',diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex c787b5a57..7b1c0c5a6 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -412,6 +412,7 @@ async function projectFrame(s: RegisteredSession, selectedModel: string | null):const st = s.transcriptPath ? await stat(s.transcriptPath).catch(() => null) : nullreturn {id: s.agentId,+ sessionId: s.sessionId,userId: '',name: projectDisplayName(s),status: s.active ? 'active' : 'offline',@@ -773,6 +774,7 @@ async function runForeground(token: string): Promise<void> {sendTarget: (connId, type, payload) => backend.sendTerminalTo(connId, type, payload),sendBinaryTarget: (connId, frame) => backend.sendTerminalBinaryTo(connId, frame),streamingAvailable: tmuxBackend != null,+ diagnostic: (event, fields) => console.log(`[terminal-stream] ${event}`, fields),})backend.setTerminalStreamManager(terminalStreams)@@ -1366,7 +1368,15 @@ async function runForeground(token: string): Promise<void> {// Device: keep the busy tile alive through the turn AND the summarize window. Returns false when idle.const deviceBusy = mirror.heartbeat(sessionId)// Web: unchanged — heartbeat only while the turn itself is open (summarizing uses turn_summary_pending).- if (turnOpen) backend.send({ type: 'turn_heartbeat', dbSessionId: sessionId, payload: { sessionId } })+ if (turnOpen) {+ const agentId = agentIdFor(sessionId)+ backend.send({+ type: 'turn_heartbeat',+ agentId,+ dbSessionId: sessionId,+ payload: { agentId, sessionId },+ })+ }// Self-cancel only once the turn is closed AND the summarize is done (no more device heartbeat needed).if (!turnOpen && !deviceBusy) stopHeartbeat(sessionId)}, TURN_HEARTBEAT_MS)@@ -1376,7 +1386,13 @@ async function runForeground(token: string): Promise<void> {emitSessionEvents = (sessionId: string, events: ReturnType<CursorNormalizer['ingest']>): void => {if (!events.length || !registry.bySession(sessionId)?.active) returnfor (const event of events) {- backend.send({ ...event, dbSessionId: sessionId })+ const agentId = agentIdFor(sessionId)+ backend.send({+ ...event,+ agentId,+ dbSessionId: sessionId,+ payload: { ...event.payload, agentId, sessionId },+ })if (event.type === 'turn_started') {turnStartedAt.set(sessionId, Date.now())// Analytics: count HERE, inside the one funnel every engine's normalizer feeds and BEFOREdiff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.tsindex 4fa2c64f7..ea2225401 100644--- a/cli/src/lib/terminalBinary.spec.ts+++ b/cli/src/lib/terminalBinary.spec.ts@@ -10,10 +10,10 @@ import {const key = Uint8Array.from({ length: 32 }, (_, index) => index)const streamId = '00112233-4455-6677-8899-aabbccddeeff'-describe('terminal binary protocol v2', () => {+describe('terminal binary protocol v3', () => {it('derives the cross-platform terminal key in its own nonce domain', () => {expect(Buffer.from(deriveTerminalBinaryKey(key)).toString('hex')).toBe(- '319355ec420991f1458c3a0fb5e4b38a6475f227ec166cd8754e721ab827a733',+ 'f15a4e3a9c616916c38980baf864db0c65e282ebe7cd64a18aa0f723a6e254f5',)})@@ -58,6 +58,30 @@ describe('terminal binary protocol v2', () => {})})+ it('round-trips an empty uncompressed sync frame', () => {+ const sealed = sealTerminalBinary(key, 10, {+ kind: TerminalBinaryKind.sync,+ streamId,+ seq: 13,+ bytes: new Uint8Array(),+ compressed: false,+ })!+ expect(openTerminalBinary(key, sealed)?.frame).toEqual({+ kind: TerminalBinaryKind.sync,+ streamId,+ seq: 13,+ bytes: new Uint8Array(),+ compressed: false,+ })+ expect(sealTerminalBinary(key, 11, {+ kind: TerminalBinaryKind.sync,+ streamId,+ seq: 14,+ bytes: Uint8Array.of(1),+ compressed: false,+ })).toBeNull()+ })+it('rejects tamper, truncation and unsupported flags', () => {const sealed = sealTerminalBinary(key, 1, {kind: TerminalBinaryKind.output,diff --git a/cli/src/lib/terminalBinary.ts b/cli/src/lib/terminalBinary.tsindex 89d5ffef9..5e6becf23 100644--- a/cli/src/lib/terminalBinary.ts+++ b/cli/src/lib/terminalBinary.ts@@ -2,7 +2,7 @@ import { aeadOpen, aeadSeal, utf8 } from './e2ee/core.js'import { hkdf } from '@noble/hashes/hkdf'import { sha256 } from '@noble/hashes/sha2'-export const TERMINAL_BINARY_VERSION = 2+export const TERMINAL_BINARY_VERSION = 3export const TERMINAL_BINARY_HEADER_BYTES = 20export const TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES = 512 * 1024export const TERMINAL_HOP_HEADER_BYTES = 24@@ -11,6 +11,7 @@ export const enum TerminalBinaryKind {input = 1,output = 2,keyframe = 3,+ sync = 4,}export interface TerminalBinaryClear {@@ -34,7 +35,7 @@ export interface TerminalBinaryEnvelope {const MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4d) // HTRMconst HOP_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x48) // HTRHconst FLAG_ZLIB = 1-const TERMINAL_KEY_INFO = utf8('harness-terminal-binary-v2')+const TERMINAL_KEY_INFO = utf8('harness-terminal-binary-v3')/** Keep binary terminal nonces independent from JSON control-frame nonces. */export function deriveTerminalBinaryKey(sessionKey: Uint8Array): Uint8Array {@@ -58,19 +59,24 @@ function uuidString(bytes: Uint8Array): string {}function validKind(value: number): value is TerminalBinaryKind {- return value === TerminalBinaryKind.input || value === TerminalBinaryKind.output || value === TerminalBinaryKind.keyframe+ return value === TerminalBinaryKind.input+ || value === TerminalBinaryKind.output+ || value === TerminalBinaryKind.keyframe+ || value === TerminalBinaryKind.sync}export function terminalBinaryType(kind: TerminalBinaryKind): string {if (kind === TerminalBinaryKind.input) return 'terminal_input'if (kind === TerminalBinaryKind.output) return 'terminal_output'- return 'terminal_keyframe'+ if (kind === TerminalBinaryKind.keyframe) return 'terminal_keyframe'+ return 'terminal_sync'}export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | null {const id = uuidBytes(frame.streamId)if (!id || !Number.isSafeInteger(frame.seq) || frame.seq < 0) return null- if (frame.kind === TerminalBinaryKind.input && frame.compressed) return null+ if ((frame.kind === TerminalBinaryKind.input || frame.kind === TerminalBinaryKind.sync) && frame.compressed) return null+ if (frame.kind === TerminalBinaryKind.sync && frame.bytes.length !== 0) return nullconst metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24const out = new Uint8Array(metaBytes + frame.bytes.length)out.set(id, 0)@@ -87,9 +93,10 @@ export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | nu}export function decodeTerminalPlain(kind: TerminalBinaryKind, flags: number, plaintext: Uint8Array): TerminalBinaryClear | null {- if ((flags & ~FLAG_ZLIB) !== 0 || (kind === TerminalBinaryKind.input && flags !== 0)) return null+ if ((flags & ~FLAG_ZLIB) !== 0+ || ((kind === TerminalBinaryKind.input || kind === TerminalBinaryKind.sync) && flags !== 0)) return nullconst metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24- if (plaintext.length < metaBytes) return null+ if (plaintext.length < metaBytes || (kind === TerminalBinaryKind.sync && plaintext.length !== metaBytes)) return nullconst view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength)const seq = safeU64(view, 16)if (seq == null) return nulldiff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 7ed689e52..a3bdb3a46 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -17,13 +17,18 @@ class FakeStream implements TerminalStreamHandle {onSnapshot: ((count: number) => void) | null = nullpauses = 0resumes = 0+ snapshotBegins = 0+ snapshotEnds = 0+ onEndSnapshot: (() => void) | null = null+ beginSnapshot() { this.snapshotBegins++ }async snapshot(historyLines: number): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {this.snapshots++this.snapshotHistory.push(historyLines)this.onSnapshot?.(this.snapshots)return { state: 'succeeded', value: { bytes: this.snapshotBytes, cols: 120, rows: 40 } }}+ endSnapshot() { this.snapshotEnds++; this.onEndSnapshot?.() }async writeRaw(bytes: Uint8Array) { this.writes.push(bytes); return TERMINAL_ACTION_SUCCEEDED }async resize(size: { cols: number; rows: number }) { this.sizes.push(size); return TERMINAL_ACTION_SUCCEEDED }async pauseOutput() { this.pauses++; return TERMINAL_ACTION_SUCCEEDED }@@ -90,7 +95,7 @@ describe('TerminalStreamManager', () => {const agentId = `agent-generic-${index}`agents.set(agentId, session(engine, agentId))await manager.handleFrame('web-1', 'terminal_open', {- requestId: `open-${index}`, protocolVersion: 2, agentId, cols: 100, rows: 30,+ requestId: `open-${index}`, protocolVersion: 3, agentId, cols: 100, rows: 30,})const ready = sent.findLast((frame) => frame.type === 'terminal_ready')expect(ready?.payload.agentId).toBe(agentId)@@ -108,21 +113,21 @@ describe('TerminalStreamManager', () => {unsafe.engine = 'hostile-unregistered-engine'agents.set('agent-1', unsafe as unknown as RegisteredSession)await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'unsupported', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'unsupported', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})expect(sent.at(-1)?.payload.code).toBe('TERMINAL_ENGINE_UNSUPPORTED')})it('rejects an unknown agent without opening a stream', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'missing', protocolVersion: 2, agentId: 'does-not-exist', cols: 100, rows: 30,+ requestId: 'missing', protocolVersion: 3, agentId: 'does-not-exist', cols: 100, rows: 30,})expect(sent.at(-1)?.payload.code).toBe('TERMINAL_AGENT_NOT_FOUND')})it('opens with a keyframe, streams coalesced output, and writes ordered raw input', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],})expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])@@ -160,7 +165,7 @@ describe('TerminalStreamManager', () => {stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-snapshot', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40,+ requestId: 'open-snapshot', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,})await vi.advanceTimersByTimeAsync(20)@@ -169,18 +174,17 @@ describe('TerminalStreamManager', () => {expect(binarySent[0].frame.seq).toBe(0)})- it('recaptures and discards a TUI repaint that arrives during snapshot', async () => {+ it('takes one ordered snapshot and releases its output gate after the keyframe', async () => {stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')- stream.onSnapshot = (count) => {- if (count === 1) sink!.onData(Buffer.from('\u001b[2Jin-flight stale repaint'))- }await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-racing-snapshot', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40,+ requestId: 'open-racing-snapshot', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,})await vi.advanceTimersByTimeAsync(20)- expect(stream.snapshots).toBe(2)+ expect(stream.snapshots).toBe(1)+ expect(stream.snapshotBegins).toBe(1)+ expect(stream.snapshotEnds).toBe(1)expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])expect(binarySent[0].frame.seq).toBe(0)@@ -188,10 +192,10 @@ describe('TerminalStreamManager', () => {it('rejects a second controller and expires the first lease after heartbeat timeout', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})await manager.handleFrame('web-2', 'terminal_open', {- requestId: 'open-2', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})expect(sent.at(-1)?.payload.code).toBe('CONTROL_LEASE_HELD')@@ -203,17 +207,17 @@ describe('TerminalStreamManager', () => {it('rejects a second agent alias that resolves to the same tmux pane', async () => {agents.set('agent-alias', session('claude', 'agent-alias'))await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})await manager.handleFrame('web-2', 'terminal_open', {- requestId: 'open-2', protocolVersion: 2, agentId: 'agent-alias', cols: 100, rows: 30,+ requestId: 'open-2', protocolVersion: 3, agentId: 'agent-alias', cols: 100, rows: 30,})expect(sent.at(-1)?.payload.code).toBe('CONTROL_LEASE_HELD')})it('uses frequent ACKs rather than the five-second heartbeat for output backpressure', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})const streamId = sent[0].payload.streamId as stringawait manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })@@ -227,9 +231,47 @@ describe('TerminalStreamManager', () => {expect(stream.pauses).toBe(0)})+ it('emits an ordered sync frame every five seconds while idle', async () => {+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-sync', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,+ })+ await vi.advanceTimersByTimeAsync(5_000)+ expect(binarySent.map(({ frame }) => frame.kind)).toEqual([+ TerminalBinaryKind.keyframe,+ TerminalBinaryKind.sync,+ ])+ expect(binarySent[1].frame.seq).toBe(1)+ expect(binarySent[1].frame.bytes).toHaveLength(0)+ expect(binarySent[1].frame.compressed).toBe(false)+ })++ it('fails closed when pending plus queued output exceeds two MiB', async () => {+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-overflow', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,+ })+ sink!.onData(Buffer.alloc(2 * 1024 * 1024))+ await vi.advanceTimersByTimeAsync(1)+ expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)+ .toBe('TERMINAL_OUTPUT_OVERFLOW')+ expect(stream.closed).toBe(true)+ })++ it('forwards only output released after the ordered snapshot cut', async () => {+ stream.onEndSnapshot = () => sink!.onData(Buffer.from('post-cut'))+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-cut', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,+ })+ await vi.advanceTimersByTimeAsync(8)+ expect(binarySent.map(({ frame }) => frame.kind)).toEqual([+ TerminalBinaryKind.keyframe,+ TerminalBinaryKind.output,+ ])+ expect(Buffer.from(binarySent[1].frame.bytes).toString()).toBe('post-cut')+ })+it('pauses PTY output above the high watermark and resumes below the low watermark', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})const streamId = sent[0].payload.streamId as stringawait manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })@@ -237,16 +279,18 @@ describe('TerminalStreamManager', () => {await vi.advanceTimersByTimeAsync(1)expect(stream.pauses).toBe(1)expect(stream.resumes).toBe(0)+ sink!.onData(Buffer.from('buffered-while-renderer-paused'))const outputs = binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.output)await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: outputs[9].frame.seq })- await vi.advanceTimersByTimeAsync(1)+ await vi.advanceTimersByTimeAsync(8)expect(stream.resumes).toBe(1)+ expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('buffered-while-renderer-paused')expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(1)})it('closes a stream whose renderer stays stalled after tmux is paused', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-stall', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-stall', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})const streamId = sent[0].payload.streamId as stringawait manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })@@ -263,7 +307,7 @@ describe('TerminalStreamManager', () => {it('fails closed instead of emitting an oversized binary keyframe', async () => {stream.snapshotBytes = Buffer.alloc(481 * 1024, 0x61)await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'oversized', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'oversized', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})expect(stream.snapshotHistory).toEqual([1_000, 500, 250, 100, 0])expect(binarySent.some(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toBe(false)@@ -274,14 +318,14 @@ describe('TerminalStreamManager', () => {it('disconnect cleanup closes the stream and releases the controller', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})await manager.closeConnection('web-1')expect(stream.closed).toBe(true)const replacement = new FakeStream()stream = replacementawait manager.handleFrame('web-2', 'terminal_open', {- requestId: 'open-2', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})expect(sent.at(-1)?.type).toBe('terminal_ready')expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.keyframe)diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.tsindex 91a2d72f4..732662a39 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -9,17 +9,18 @@ import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.jtype FramePayload = Record<string, unknown>-const PROTOCOL_VERSION = 2+const PROTOCOL_VERSION = 3const HEARTBEAT_TIMEOUT_MS = 30_000+const SYNC_INTERVAL_MS = 5_000const OUTPUT_FLUSH_MS = 8const OUTPUT_CHUNK_BYTES = 32 * 1024const INPUT_MAX_BYTES = 64 * 1024const PAUSE_HIGH_WATERMARK_BYTES = 384 * 1024const RESUME_LOW_WATERMARK_BYTES = 128 * 1024const RENDER_STALL_TIMEOUT_MS = 10_000+const MAX_TOTAL_BUFFERED_BYTES = 2 * 1024 * 1024const KEYFRAME_MAX_BYTES = 480 * 1024const KEYFRAME_HISTORY_ATTEMPTS = [1_000, 500, 250, 100, 0] as const-const KEYFRAME_SETTLE_ATTEMPTS = 3const TERMINAL_ENGINES: ReadonlySet<string> = new Set(ENGINES)interface PendingOutput {@@ -36,6 +37,7 @@ interface ActiveStream {handle: TerminalStreamHandlecompression: 'none' | 'zlib'expiresAt: number+ lastSyncAt: numbernextSeq: numberlastInputSeq: numberlastResizeSeq: number@@ -49,6 +51,15 @@ interface ActiveStream {closing: booleanoutputPaused: booleanstallTimer: ReturnType<typeof setTimeout> | null+ openedAt: number+ outputFrames: number+ outputPlainBytes: number+ keyframes: number+ syncFrames: number+ resyncs: number+ peakBufferedBytes: number+ pausedAt: number | null+ pausedMs: number}export interface TerminalStreamManagerDeps {@@ -58,6 +69,7 @@ export interface TerminalStreamManagerDeps {sendBinaryTarget: (connId: string, frame: TerminalBinaryClear) => booleanstreamingAvailable: booleannow?: () => number+ diagnostic?: (event: string, fields: Record<string, unknown>) => void}function sizeFrom(payload: FramePayload): TerminalStreamSize | null {@@ -149,6 +161,7 @@ export class TerminalStreamManager {resize: true,mouse: true,keyframe: true,+ sync: true,compression: ['none', 'zlib'],},engines: terminalEngineCapabilities(this.deps.streamingAvailable),@@ -261,6 +274,7 @@ export class TerminalStreamManager {handle: opened.value,compression: requestedCompression.includes('zlib') ? 'zlib' : 'none',expiresAt: this.now() + HEARTBEAT_TIMEOUT_MS,+ lastSyncAt: this.now(),nextSeq: 0,lastInputSeq: -1,lastResizeSeq: -1,@@ -274,6 +288,15 @@ export class TerminalStreamManager {closing: false,outputPaused: false,stallTimer: null,+ openedAt: this.now(),+ outputFrames: 0,+ outputPlainBytes: 0,+ keyframes: 0,+ syncFrames: 0,+ resyncs: 0,+ peakBufferedBytes: 0,+ pausedAt: null,+ pausedMs: 0,}this.streams.set(streamId, state)if (!this.deps.sendTarget(connId, 'terminal_ready', {@@ -287,6 +310,7 @@ export class TerminalStreamManager {await this.closeStream(state, 'backend disconnected', false)return}+ this.diagnostic(state, 'opened', { cols: size.cols, rows: size.rows, compression: state.compression })await this.sendKeyframe(state)}@@ -349,7 +373,11 @@ export class TerminalStreamManager {private async resyncRequested(connId: string, payload: FramePayload): Promise<void> {const state = this.streamFor(connId, payload)- if (state) await this.sendKeyframe(state)+ if (state) {+ state.resyncs+++ this.diagnostic(state, 'resync_requested', { attempt: payload.attempt })+ await this.sendKeyframe(state)+ }}private async closeRequested(connId: string, payload: FramePayload): Promise<void> {@@ -359,6 +387,14 @@ export class TerminalStreamManager {private onOutput(state: ActiveStream, bytes: Uint8Array): void {if (state.closing || bytes.length === 0) return+ const nextBuffered = state.pendingBytes + state.outputBytes + bytes.length+ state.peakBufferedBytes = Math.max(state.peakBufferedBytes, nextBuffered)+ if (nextBuffered > MAX_TOTAL_BUFFERED_BYTES) {+ this.sendError(state.connId, 'TERMINAL_OUTPUT_OVERFLOW', { streamId: state.streamId })+ this.diagnostic(state, 'output_overflow', { bufferedBytes: nextBuffered })+ void this.closeStream(state, 'terminal output exceeded safe buffer limit', true)+ return+ }state.output.push(Buffer.from(bytes))state.outputBytes += bytes.lengthif (state.snapshotting || state.outputPaused) return@@ -391,6 +427,8 @@ export class TerminalStreamManager {}state.pending.push({ seq, bytes: body.plainBytes })state.pendingBytes += body.plainBytes+ state.outputFrames+++ state.outputPlainBytes += body.plainBytes}if (state.pendingBytes > PAUSE_HIGH_WATERMARK_BYTES && !state.outputPaused) void this.pauseOutput(state)}@@ -409,18 +447,22 @@ export class TerminalStreamManager {private async pauseOutput(state: ActiveStream): Promise<void> {if (state.closing || state.outputPaused) returnstate.outputPaused = true+ state.pausedAt = this.now()const result = await state.handle.pauseOutput()if (result.state !== 'succeeded') {this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', { streamId: state.streamId, message: result.reason })await this.closeStream(state, result.reason, true)return}+ this.diagnostic(state, 'output_paused', { pendingBytes: state.pendingBytes })this.armStallTimer(state)}private async resumeOutput(state: ActiveStream): Promise<void> {if (state.closing || !state.outputPaused) returnstate.outputPaused = false+ if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)+ state.pausedAt = nullif (state.stallTimer) clearTimeout(state.stallTimer)state.stallTimer = nullconst result = await state.handle.resumeOutput()@@ -429,54 +471,68 @@ export class TerminalStreamManager {await this.closeStream(state, result.reason, true)return}+ this.diagnostic(state, 'output_resumed', { pendingBytes: state.pendingBytes })this.flushOutput(state)}private async sendKeyframe(state: ActiveStream): Promise<void> {if (state.closing || state.resyncing) return+ const startedAt = this.now()state.resyncing = truestate.snapshotting = true+ state.handle.beginSnapshot()+ state.output = []+ state.outputBytes = 0if (state.outputPaused) {state.outputPaused = false+ if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)+ state.pausedAt = nullif (state.stallTimer) clearTimeout(state.stallTimer)state.stallTimer = null- await state.handle.resumeOutput().catch(() => ({ state: 'failed' as const, dispatch: 'not_started' as const, reason: 'resume failed' }))+ const resumed = await state.handle.resumeOutput().catch(() => ({+ state: 'failed' as const,+ dispatch: 'not_started' as const,+ reason: 'resume failed',+ }))+ if (resumed.state !== 'succeeded') {+ state.handle.endSnapshot()+ state.snapshotting = false+ state.resyncing = false+ this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', {+ streamId: state.streamId,+ message: resumed.reason,+ })+ await this.closeStream(state, resumed.reason, true)+ return+ }}if (state.flushTimer) { clearTimeout(state.flushTimer); state.flushTimer = null }let snapshot: Awaited<ReturnType<TerminalStreamHandle['snapshot']>> = {state: 'failed',reason: 'tmux snapshot did not run',}- for (const historyLines of KEYFRAME_HISTORY_ATTEMPTS) {- for (let settleAttempt = 0; settleAttempt < KEYFRAME_SETTLE_ATTEMPTS; settleAttempt++) {- // A resize makes Codex/Claude repaint while capture-pane is running.- // Deltas queued before or during that capture are already reflected in- // the snapshot and must never be replayed after it: doing so erased the- // Codex prompt while leaving its background and cursor behind.- state.output = []- state.outputBytes = 0+ try {+ for (const historyLines of KEYFRAME_HISTORY_ATTEMPTS) {snapshot = await state.handle.snapshot(historyLines)- const repaintedDuringCapture = state.outputBytes > 0- state.output = []- state.outputBytes = 0- if (snapshot.state !== 'succeeded'- || snapshot.value.bytes.length > KEYFRAME_MAX_BYTES- || !repaintedDuringCapture) break- // Capture again after the repaint so the keyframe contains its final- // state. Three attempts bound latency for continuously animated TUIs.+ if (snapshot.state !== 'succeeded' || snapshot.value.bytes.length <= KEYFRAME_MAX_BYTES) break}- if (snapshot.state !== 'succeeded' || snapshot.value.bytes.length <= KEYFRAME_MAX_BYTES) break+ } catch (error) {+ snapshot = { state: 'failed', reason: error instanceof Error ? error.message : 'tmux snapshot failed' }}if (snapshot.state !== 'succeeded') {+ state.handle.endSnapshot()state.snapshotting = falsestate.resyncing = false+ this.diagnostic(state, 'snapshot_failed', { reason: snapshot.reason })this.sendError(state.connId, 'TERMINAL_SNAPSHOT_FAILED', { streamId: state.streamId, message: snapshot.reason })await this.closeStream(state, snapshot.reason, false)return}if (snapshot.value.bytes.length > KEYFRAME_MAX_BYTES) {+ state.handle.endSnapshot()state.snapshotting = falsestate.resyncing = false+ this.diagnostic(state, 'snapshot_too_large', { plainBytes: snapshot.value.bytes.length })this.sendError(state.connId, 'TERMINAL_SNAPSHOT_TOO_LARGE', { streamId: state.streamId })await this.closeStream(state, 'terminal snapshot exceeds safe envelope size', false)return@@ -496,6 +552,7 @@ export class TerminalStreamManager {bytes: body.bytes,})if (!sent) {+ state.handle.endSnapshot()state.snapshotting = falsestate.resyncing = falseawait this.closeStream(state, 'backend disconnected', false)@@ -503,21 +560,74 @@ export class TerminalStreamManager {}state.pending.push({ seq, bytes: body.plainBytes })state.pendingBytes = body.plainBytes+ state.keyframes+++ state.lastSyncAt = this.now()+ state.peakBufferedBytes = Math.max(state.peakBufferedBytes, state.pendingBytes)+ this.diagnostic(state, 'keyframe_sent', {+ seq,+ plainBytes: body.plainBytes,+ compressedBytes: body.bytes.length,+ snapshotMs: Math.max(0, this.now() - startedAt),+ })+ state.handle.endSnapshot()state.snapshotting = falsestate.resyncing = falsethis.flushOutput(state)+ if (state.pendingBytes > PAUSE_HIGH_WATERMARK_BYTES && !state.outputPaused) void this.pauseOutput(state)+ }++ private sendSync(state: ActiveStream, now: number): void {+ if (state.closing || state.snapshotting || state.resyncing || state.outputPaused) return+ this.flushOutput(state)+ if (state.closing || state.outputPaused) return+ const seq = state.nextSeq+++ if (!this.deps.sendBinaryTarget(state.connId, {+ kind: TerminalBinaryKind.sync,+ streamId: state.streamId,+ seq,+ compressed: false,+ bytes: new Uint8Array(),+ })) {+ void this.closeStream(state, 'backend disconnected', false)+ return+ }+ state.pending.push({ seq, bytes: 0 })+ state.syncFrames+++ state.lastSyncAt = now}private expireLeases(): void {const now = this.now()for (const state of [...this.streams.values()]) {if (!state.closing && state.expiresAt <= now) void this.closeStream(state, 'heartbeat timeout', true)+ else if (!state.closing && now - state.lastSyncAt >= SYNC_INTERVAL_MS) this.sendSync(state, now)}}+ private diagnostic(state: ActiveStream, event: string, fields: Record<string, unknown> = {}): void {+ this.deps.diagnostic?.(event, {+ streamId: state.streamId.slice(0, 8),+ agentId: state.agentId.slice(0, 8),+ engineId: state.engineId,+ ...fields,+ })+ }+private async closeStream(state: ActiveStream, reason: string, notify: boolean): Promise<void> {if (state.closing) returnstate.closing = true+ if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)+ this.diagnostic(state, 'closed', {+ reason,+ lifetimeMs: Math.max(0, this.now() - state.openedAt),+ outputFrames: state.outputFrames,+ outputPlainBytes: state.outputPlainBytes,+ keyframes: state.keyframes,+ syncFrames: state.syncFrames,+ resyncs: state.resyncs,+ peakBufferedBytes: state.peakBufferedBytes,+ pausedMs: state.pausedMs,+ })if (state.flushTimer) clearTimeout(state.flushTimer)if (state.stallTimer) clearTimeout(state.stallTimer)state.flushTimer = nulldiff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.tsindex 57f1469e2..fe843884d 100644--- a/cli/src/lib/terminalTypes.ts+++ b/cli/src/lib/terminalTypes.ts@@ -136,7 +136,11 @@ export interface TerminalStreamSink {/** A live byte-oriented terminal stream. Implementations must preserve input/output order. */export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalRuntimeRef> {readonly runtime: Ref+ /** Gate live output before taking an ordered snapshot. */+ beginSnapshot(): voidsnapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>>+ /** Release output produced strictly after the snapshot cut. */+ endSnapshot(): voidwriteRaw(bytes: Uint8Array): Promise<TerminalActionResult>resize(size: TerminalStreamSize): Promise<TerminalActionResult>pauseOutput(): Promise<TerminalActionResult>diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.tsindex 8e8a455f3..6d4ef4fb5 100644--- a/cli/src/lib/tmuxStream.real.spec.ts+++ b/cli/src/lib/tmuxStream.real.spec.ts@@ -16,10 +16,10 @@ function tmux(args: string[]): Promise<string> {})}-async function eventually(predicate: () => boolean, timeoutMs = 3_000): Promise<void> {+async function eventually(predicate: () => boolean | Promise<boolean>, timeoutMs = 3_000): Promise<void> {const deadline = Date.now() + timeoutMs- while (!predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 20))- expect(predicate()).toBe(true)+ while (!await predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 20))+ expect(await predicate()).toBe(true)}run('TmuxControlStream real tmux', () => {@@ -44,14 +44,26 @@ run('TmuxControlStream real tmux', () => {expect(opened.state).toBe('succeeded')if (opened.state !== 'succeeded') return+ const snapshotMarker = 'HARNESS_SNAPSHOT_OK'+ await opened.value.writeRaw(Buffer.from(`printf '${snapshotMarker}\\n'\r`))+ await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes(snapshotMarker))+ opened.value.beginSnapshot()const snapshot = await opened.value.snapshot(100)expect(snapshot.state).toBe('succeeded')if (snapshot.state === 'succeeded') {expect(snapshot.value.cols).toBe(96)expect(snapshot.value.rows).toBe(28)expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from('\u001bc'))).toBe(true)+ expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from(snapshotMarker))).toBe(true)}+ const postCutMarker = 'HARNESS_POST_CUT_OK'+ await opened.value.writeRaw(Buffer.from(`printf '${postCutMarker}\\n'\r`))+ await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes(postCutMarker))+ expect(Buffer.concat(chunks).includes(Buffer.from(postCutMarker))).toBe(false)+ opened.value.endSnapshot()+ await eventually(() => Buffer.concat(chunks).includes(Buffer.from(postCutMarker)))+await opened.value.writeRaw(Buffer.from("printf 'HARNESS_STREAM_OK\\n'\r"))const deadline = Date.now() + 3_000while (!Buffer.concat(chunks).includes(Buffer.from('HARNESS_STREAM_OK')) && Date.now() < deadline) {@@ -95,7 +107,7 @@ run('TmuxControlStream real tmux', () => {try {await manager.handleFrame('matrix-client', 'terminal_open', {requestId: `open-${engine}`,- protocolVersion: 2,+ protocolVersion: 3,agentId,cols: 90 + index,rows: 24,diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.tsindex d30ac3df0..07e32bc78 100644--- a/cli/src/lib/tmuxStream.ts+++ b/cli/src/lib/tmuxStream.ts@@ -18,7 +18,13 @@ const MAX_COLS = 300const MIN_ROWS = 12const MAX_ROWS = 120const SMALL_INPUT_BYTES = 4 * 1024-const CONTROL_OUTPUT_SETTLE_MS = 24+const CONTROL_COMMAND_TIMEOUT_MS = 3_000+const SNAPSHOT_BUFFER_MAX_BYTES = 2 * 1024 * 1024+const PANE_META_FORMAT = [+ '#{session_id}', '#{window_id}', '#{window_panes}', '#{window_width}', '#{window_height}',+ '#{pane_width}', '#{pane_height}', '#{alternate_on}', '#{cursor_x}', '#{cursor_y}',+ '#{mouse_standard_flag}', '#{mouse_button_flag}', '#{mouse_all_flag}', '#{mouse_utf8_flag}', '#{mouse_sgr_flag}',+].join('|')interface PaneMeta {sessionId: string@@ -38,6 +44,15 @@ interface PaneMeta {mouseSgr: boolean}+interface PendingControlCommand {+ command: string+ lines: Buffer[]+ commandNumber: string | null+ timer: ReturnType<typeof setTimeout> | null+ onEnd?: () => void+ resolve: (result: { ok: boolean; stdout: Buffer }) => void+}+function boundedSize(size: TerminalStreamSize): TerminalStreamSize {return {cols: Math.max(MIN_COLS, Math.min(MAX_COLS, Math.floor(size.cols))),@@ -54,14 +69,13 @@ function execTmux(args: string[], timeout = 2_000): Promise<{ ok: boolean; stdou}async function paneMeta(paneId: string): Promise<PaneMeta | null> {- const format = [- '#{session_id}', '#{window_id}', '#{window_panes}', '#{window_width}', '#{window_height}',- '#{pane_width}', '#{pane_height}', '#{alternate_on}', '#{cursor_x}', '#{cursor_y}',- '#{mouse_standard_flag}', '#{mouse_button_flag}', '#{mouse_all_flag}', '#{mouse_utf8_flag}', '#{mouse_sgr_flag}',- ].join('|')- const result = await execTmux(['display-message', '-p', '-t', paneId, format])+ const result = await execTmux(['display-message', '-p', '-t', paneId, PANE_META_FORMAT])if (!result.ok) return null- const fields = result.stdout.toString('utf8').trim().split('|')+ return parsePaneMeta(result.stdout)+}++function parsePaneMeta(bytes: Uint8Array): PaneMeta | null {+ const fields = Buffer.from(bytes).toString('utf8').trim().split('|')if (fields.length !== 15 || !/^\$\d+$/.test(fields[0]) || !/^@\d+$/.test(fields[1])) return nullconst nums = fields.slice(2).map(Number)if (nums.some((value) => !Number.isFinite(value))) return null@@ -226,9 +240,14 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {private lineBuffer = Buffer.alloc(0)private closed = falseprivate closeNotified = false- private outputPaused = falseprivate original: PaneMetaprivate lastApplied: TerminalStreamSize | null = null+ private commandActive: PendingControlCommand | null = null+ private readonly commandQueue: PendingControlCommand[] = []+ private operationTail: Promise<void> = Promise.resolve()+ private snapshotGated = false+ private snapshotPostCut: Buffer[] = []+ private snapshotPostCutBytes = 0private constructor(paneId: string,@@ -281,53 +300,175 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {private onControlLine(line: Buffer): void {const output = parseTmuxControlOutput(line)if (output) {- if (output.paneId === this.runtime.paneId) this.sink.onData(output.data)+ if (output.paneId === this.runtime.paneId) this.routeOutput(output.data)return}const text = line.toString('ascii')+ const begin = /^%begin\s+\d+\s+(\d+)\s+\d+$/.exec(text)+ if (begin) {+ if (this.commandActive && this.commandActive.commandNumber == null) {+ this.commandActive.commandNumber = begin[1]+ }+ return+ }+ const completed = /^%(end|error)\s+\d+\s+(\d+)\s+\d+$/.exec(text)+ if (completed) {+ const active = this.commandActive+ if (active?.commandNumber === completed[2]) {+ if (completed[1] === 'end') active.onEnd?.()+ this.finishControlCommand(active, completed[1] === 'end')+ }+ return+ }const paused = /^%pause\s+(%\d+)$/.exec(text)- if (paused?.[1] === this.runtime.paneId && !this.closed && !this.outputPaused) {- this.child.stdin.write(`refresh-client -A ${this.runtime.paneId}:continue\n`)+ if (paused?.[1] === this.runtime.paneId && !this.closed) {+ // Manual tmux pause drops pane bytes rather than replaying them. Never+ // use it for app backpressure; recover an unexpected pause immediately.+ void this.runControlCommand(`refresh-client -A '${this.runtime.paneId}:continue'`)+ return+ }+ if (text.startsWith('%exit')) {+ this.failControlCommands()+ this.notifyClose(this.closed ? 'closed' : 'tmux pane/control client closed')+ return+ }+ // tmux escapes command output that starts with `%` as `%%`. Every other+ // leading-percent line is an asynchronous control-mode notification and+ // must not be mixed into a command response.+ if (text.startsWith('%') && !text.startsWith('%%')) return+ if (this.commandActive?.commandNumber != null) this.commandActive.lines.push(Buffer.from(line))+ }++ private routeOutput(bytes: Uint8Array): void {+ if (!this.snapshotGated) {+ this.sink.onData(bytes)return}- if (text.startsWith('%exit')) this.notifyClose(this.closed ? 'closed' : 'tmux pane/control client closed')+ const chunk = Buffer.from(bytes)+ this.snapshotPostCut.push(chunk)+ this.snapshotPostCutBytes += chunk.length+ if (this.snapshotPostCutBytes > SNAPSHOT_BUFFER_MAX_BYTES) {+ this.failControlCommands()+ this.notifyClose('tmux snapshot output exceeded safe buffer limit')+ void this.close()+ }+ }++ private runControlCommand(command: string, onEnd?: () => void): Promise<{ ok: boolean; stdout: Buffer }> {+ if (this.closed || !this.child.stdin.writable) return Promise.resolve({ ok: false, stdout: Buffer.alloc(0) })+ return new Promise((resolve) => {+ this.commandQueue.push({ command, lines: [], commandNumber: null, timer: null, onEnd, resolve })+ this.pumpControlCommand()+ })+ }++ private serializeOperation<T>(operation: () => Promise<T>): Promise<T> {+ const result = this.operationTail.then(operation, operation)+ this.operationTail = result.then(() => undefined, () => undefined)+ return result+ }++ private pumpControlCommand(): void {+ if (this.commandActive || this.closed) return+ const next = this.commandQueue.shift()+ if (!next) return+ this.commandActive = next+ next.timer = setTimeout(() => {+ if (this.commandActive !== next) return+ this.notifyClose('tmux control command timed out')+ void this.close()+ }, CONTROL_COMMAND_TIMEOUT_MS)+ try {+ this.child.stdin.write(`${next.command}\n`)+ } catch {+ this.finishControlCommand(next, false)+ }+ }++ private finishControlCommand(command: PendingControlCommand, ok: boolean): void {+ if (this.commandActive !== command) return+ if (command.timer) clearTimeout(command.timer)+ command.timer = null+ this.commandActive = null+ const chunks: Buffer[] = []+ for (const line of command.lines) {+ const escaped = line.subarray(0, 2).equals(Buffer.from('%%')) ? line.subarray(1) : line+ chunks.push(Buffer.from(decodeTmuxControlBytes(escaped)), Buffer.from('\n'))+ }+ command.resolve({ ok, stdout: Buffer.concat(chunks) })+ this.pumpControlCommand()+ }++ private failControlCommands(): void {+ const active = this.commandActive+ this.commandActive = null+ const queuedCommands = this.commandQueue.splice(0)+ if (active) {+ if (active.timer) clearTimeout(active.timer)+ active.timer = null+ active.resolve({ ok: false, stdout: Buffer.alloc(0) })+ }+ for (const queued of queuedCommands) {+ queued.resolve({ ok: false, stdout: Buffer.alloc(0) })+ }}private notifyClose(reason: string): void {if (this.closeNotified) returnthis.closeNotified = true+ this.failControlCommands()this.sink.onClose(reason)}+ beginSnapshot(): void {+ if (this.snapshotGated) return+ this.snapshotGated = true+ this.snapshotPostCut = []+ this.snapshotPostCutBytes = 0+ }+async snapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>> {- const meta = await paneMeta(this.runtime.paneId)- if (!meta) return { state: 'failed', reason: 'tmux pane disappeared' }- const boundedHistory = Math.max(0, Math.min(1_000, Math.floor(historyLines)))- // -N is required for TUI fidelity: styled blank cells (for example the- // Codex input box background) live in trailing spaces that tmux otherwise- // trims from each captured row.- const args = ['capture-pane', '-p', '-e', '-N', '-t', this.runtime.paneId]- if (!meta.alternateOn && boundedHistory > 0) args.push('-S', `-${boundedHistory}`)- // Give resize-triggered TUI output a short window to enter the manager's- // snapshot buffer before capture, then drain notifications queued just- // behind capture-pane's callback. The manager recaptures when either side- // of this window observed a repaint.- await new Promise((resolve) => setTimeout(resolve, CONTROL_OUTPUT_SETTLE_MS))- const capture = await execTmux(args, 3_000)- if (!capture.ok) return { state: 'failed', reason: 'tmux snapshot failed' }- // capture-pane runs in a separate tmux client. Its exec callback can win- // the event-loop race against repaint notifications already queued for the- // control client. Keep the manager in snapshotting mode long enough to- // observe those late deltas; it will then discard them and recapture.- await new Promise((resolve) => setTimeout(resolve, CONTROL_OUTPUT_SETTLE_MS))- return {- state: 'succeeded',- value: {- bytes: synthesizeTmuxSnapshot(capture.stdout, meta),- cols: meta.paneWidth,- rows: meta.paneHeight,- },- }+ return this.serializeOperation(async () => {+ if (!this.snapshotGated) return { state: 'failed', reason: 'tmux snapshot gate is not active' }+ const boundedHistory = Math.max(0, Math.min(1_000, Math.floor(historyLines)))+ // -N is required for TUI fidelity: styled blank cells (for example the+ // Codex input box background) live in trailing spaces that tmux otherwise+ // trims from each captured row.+ const baseCapture = `capture-pane -p -e -N -t ${this.runtime.paneId}`+ const metadata = await this.runControlCommand(+ `display-message -p -t ${this.runtime.paneId} '${PANE_META_FORMAT}'`,+ )+ if (!metadata.ok) return { state: 'failed', reason: 'tmux snapshot metadata is unavailable' }+ const meta = parsePaneMeta(metadata.stdout)+ if (!meta || meta.windowPanes !== 1) return { state: 'failed', reason: 'tmux snapshot metadata is invalid' }+ const captureCommand = !meta.alternateOn && boundedHistory > 0+ ? `${baseCapture} -S -${boundedHistory}`+ : baseCapture+ const capture = await this.runControlCommand(captureCommand, () => {+ // `%end` is the ordered cut. Notifications observed before it are+ // represented by capture-pane; only later output may follow the keyframe.+ this.snapshotPostCut = []+ this.snapshotPostCutBytes = 0+ })+ if (!capture.ok) return { state: 'failed', reason: 'tmux snapshot failed' }+ return {+ state: 'succeeded',+ value: {+ bytes: synthesizeTmuxSnapshot(capture.stdout, meta),+ cols: meta.paneWidth,+ rows: meta.paneHeight,+ },+ }+ })+ }++ endSnapshot(): void {+ if (!this.snapshotGated) return+ this.snapshotGated = false+ const postCut = this.snapshotPostCut+ this.snapshotPostCut = []+ this.snapshotPostCutBytes = 0+ for (const chunk of postCut) this.sink.onData(chunk)}async writeRaw(bytes: Uint8Array): Promise<TerminalActionResult> {@@ -339,39 +480,30 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {}async resize(requested: TerminalStreamSize): Promise<TerminalActionResult> {- if (this.closed) return terminalActionNotStarted('terminal stream is closed')- const meta = await paneMeta(this.runtime.paneId)- if (!meta) return terminalActionNotStarted('tmux pane disappeared')- if (meta.windowPanes !== 1) return terminalActionNotStarted('TERMINAL_MULTI_PANE_UNSUPPORTED')- const size = boundedSize(requested)- const result = await execTmux(['resize-window', '-t', meta.windowId, '-x', String(size.cols), '-y', String(size.rows)])- if (!result.ok) return terminalActionPossiblyExecuted('tmux resize did not complete')- this.lastApplied = size- return TERMINAL_ACTION_SUCCEEDED+ return this.serializeOperation(async () => {+ if (this.closed) return terminalActionNotStarted('terminal stream is closed')+ const meta = await paneMeta(this.runtime.paneId)+ if (!meta) return terminalActionNotStarted('tmux pane disappeared')+ if (meta.windowPanes !== 1) return terminalActionNotStarted('TERMINAL_MULTI_PANE_UNSUPPORTED')+ const size = boundedSize(requested)+ const result = await execTmux(['resize-window', '-t', meta.windowId, '-x', String(size.cols), '-y', String(size.rows)])+ if (!result.ok) return terminalActionPossiblyExecuted('tmux resize did not complete')+ this.lastApplied = size+ return TERMINAL_ACTION_SUCCEEDED+ })}async pauseOutput(): Promise<TerminalActionResult> {if (this.closed || !this.child.stdin.writable) return terminalActionNotStarted('terminal stream is closed')- try {- this.outputPaused = true- this.child.stdin.write(`refresh-client -A ${this.runtime.paneId}:pause\n`)- return TERMINAL_ACTION_SUCCEEDED- } catch {- this.outputPaused = false- return terminalActionPossiblyExecuted('tmux output pause did not complete')- }+ // TerminalStreamManager pauses downstream delivery while continuing to+ // drain exact tmux bytes into its bounded FIFO. tmux's manual `pause`+ // state is deliberately not used because it does not replay missed bytes.+ return TERMINAL_ACTION_SUCCEEDED}async resumeOutput(): Promise<TerminalActionResult> {if (this.closed || !this.child.stdin.writable) return terminalActionNotStarted('terminal stream is closed')- try {- this.outputPaused = false- this.child.stdin.write(`refresh-client -A ${this.runtime.paneId}:continue\n`)- return TERMINAL_ACTION_SUCCEEDED- } catch {- this.outputPaused = true- return terminalActionPossiblyExecuted('tmux output resume did not complete')- }+ return TERMINAL_ACTION_SUCCEEDED}async close(): Promise<void> {