Skip to content

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.

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.ts
index 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: string
createdAt: 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) : null
return {
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.ts
index 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) : null
return {
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) return
for (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 BEFORE
diff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.ts
index 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.ts
index 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 = 3
export const TERMINAL_BINARY_HEADER_BYTES = 20
export const TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES = 512 * 1024
export 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) // HTRM
const HOP_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x48) // HTRH
const 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 null
const metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24
const 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 null
const metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24
- if (plaintext.length < metaBytes) return null
+ if (plaintext.length < metaBytes || (kind === TerminalBinaryKind.sync && plaintext.length !== metaBytes)) return null
const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength)
const seq = safeU64(view, 16)
if (seq == null) return null
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 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 = null
pauses = 0
resumes = 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 string
await 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 string
await 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 string
await 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 = replacement
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)?.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.ts
index 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.j
type FramePayload = Record<string, unknown>
-const PROTOCOL_VERSION = 2
+const PROTOCOL_VERSION = 3
const HEARTBEAT_TIMEOUT_MS = 30_000
+const SYNC_INTERVAL_MS = 5_000
const OUTPUT_FLUSH_MS = 8
const OUTPUT_CHUNK_BYTES = 32 * 1024
const INPUT_MAX_BYTES = 64 * 1024
const PAUSE_HIGH_WATERMARK_BYTES = 384 * 1024
const RESUME_LOW_WATERMARK_BYTES = 128 * 1024
const RENDER_STALL_TIMEOUT_MS = 10_000
+const MAX_TOTAL_BUFFERED_BYTES = 2 * 1024 * 1024
const KEYFRAME_MAX_BYTES = 480 * 1024
const KEYFRAME_HISTORY_ATTEMPTS = [1_000, 500, 250, 100, 0] as const
-const KEYFRAME_SETTLE_ATTEMPTS = 3
const TERMINAL_ENGINES: ReadonlySet<string> = new Set(ENGINES)
interface PendingOutput {
@@ -36,6 +37,7 @@ interface ActiveStream {
handle: TerminalStreamHandle
compression: 'none' | 'zlib'
expiresAt: number
+ lastSyncAt: number
nextSeq: number
lastInputSeq: number
lastResizeSeq: number
@@ -49,6 +51,15 @@ interface ActiveStream {
closing: boolean
outputPaused: boolean
stallTimer: 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) => boolean
streamingAvailable: boolean
now?: () => 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.length
if (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) return
state.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) return
state.outputPaused = false
+ if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)
+ state.pausedAt = null
if (state.stallTimer) clearTimeout(state.stallTimer)
state.stallTimer = null
const 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 = true
state.snapshotting = true
+ state.handle.beginSnapshot()
+ state.output = []
+ state.outputBytes = 0
if (state.outputPaused) {
state.outputPaused = false
+ if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)
+ state.pausedAt = null
if (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 = false
state.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 = false
state.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 = false
state.resyncing = false
await 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 = false
state.resyncing = false
this.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) return
state.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 = null
diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.ts
index 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(): void
snapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>>
+ /** Release output produced strictly after the snapshot cut. */
+ endSnapshot(): void
writeRaw(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.ts
index 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_000
while (!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.ts
index d30ac3df0..07e32bc78 100644
--- a/cli/src/lib/tmuxStream.ts
+++ b/cli/src/lib/tmuxStream.ts
@@ -18,7 +18,13 @@ const MAX_COLS = 300
const MIN_ROWS = 12
const MAX_ROWS = 120
const 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 null
const 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 = false
private closeNotified = false
- private outputPaused = false
private original: PaneMeta
private 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 = 0
private 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) return
this.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> {