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: implement binary terminal protocol with encryption support for optimized communication
0xken1584fbf8d42983
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex 290d8ae40..8daf10850 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -45,6 +45,12 @@ import { readOpencodeMessages } from './engines/opencode/reader.js'import { readKiloMessages } from './engines/kilo/reader.js'import { E2eeManager, type PairResult } from './lib/e2ee/manager.js'import type { TerminalStreamManager } from './lib/terminalStreamManager.js'+import {+ decodeTerminalHop,+ encodeTerminalHop,+ TerminalHopDirection,+ type TerminalBinaryClear,+} from './lib/terminalBinary.js'import { ENCRYPTED_RPC_RESULT_TYPES, isEncryptedDownType, isWrapped } from './lib/e2ee/core.js'import { DEVICE_RECENT_SAFE_FRAME_BYTES, fitRecentReplyPayloadForDevice } from './lib/deviceRecentTrim.js'import { shouldReplayCommander } from './lib/commanderReplay.js'@@ -412,7 +418,12 @@ export class BackendSocket {this.appPing = setInterval(() => this.sendBestEffort({ t: 'ping' }), APP_PING_MS)})- ws.on('message', (raw) => {+ ws.on('message', (raw, isBinary) => {+ if (isBinary) {+ const hop = decodeTerminalHop(new Uint8Array(raw as Buffer))+ if (hop?.direction === TerminalHopDirection.down) this.enqueueTerminalBinary(hop.connId, hop.clientFrame)+ return+ }let env_: DownEnvelopetry { env_ = JSON.parse(raw.toString()) as DownEnvelope } catch { return }if (env_.t === 'down' && env_.frame) {@@ -497,6 +508,16 @@ export class BackendSocket {})}+ /** Pairwise-encrypted binary terminal output/keyframe. The hop prefix exposes+ * only connId and direction to the opaque backend relay. */+ sendTerminalBinaryTo(connId: string, clear: TerminalBinaryClear): boolean {+ const clientFrame = this.e2ee.wrapTerminalBinary(connId, clear)+ if (!clientFrame) return false+ const packet = encodeTerminalHop(TerminalHopDirection.up, connId, clientFrame)+ if (!packet || !this.ws || this.ws.readyState !== WebSocket.OPEN) return false+ try { this.ws.send(packet); return true } catch { return false }+ }+/** Send a user-level notification to every logged-in browser that owns this machine. */sendUser(frame: Frame): void {this.enqueue({ t: 'up', userEligible: true, webEligible: false, frame })@@ -544,6 +565,24 @@ export class BackendSocket {this.downChains.set(key, next)}+ private enqueueTerminalBinary(connId: string, raw: Uint8Array): void {+ const key = connId || '__backend__'+ const previous = this.downChains.get(key) ?? Promise.resolve()+ const next = previous+ .catch(() => { /* prior failure is already logged */ })+ .then(async () => {+ const clear = this.e2ee.unwrapTerminalBinary(connId, raw)+ if (clear) await this.terminalStreams?.handleBinary(connId, clear)+ })+ .catch((err) => {+ console.error('[backend] binary terminal dispatch failed:', err instanceof Error ? err.message : err)+ })+ .finally(() => {+ if (this.downChains.get(key) === next) this.downChains.delete(key)+ })+ this.downChains.set(key, next)+ }+private drainQueue(): void {if (this.draining || !this.queue.length) returnconst ws = this.wsdiff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 3119f7fe2..c787b5a57 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -771,6 +771,7 @@ async function runForeground(token: string): Promise<void> {terminals,resolveAgent: (agentId) => registry.resolve(agentId),sendTarget: (connId, type, payload) => backend.sendTerminalTo(connId, type, payload),+ sendBinaryTarget: (connId, frame) => backend.sendTerminalBinaryTo(connId, frame),streamingAvailable: tmuxBackend != null,})backend.setTerminalStreamManager(terminalStreams)diff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.tsindex 067a6665c..49ca254fd 100644--- a/cli/src/lib/e2ee/manager.ts+++ b/cli/src/lib/e2ee/manager.ts@@ -11,6 +11,13 @@* The relay never sees plaintext user content: only ciphertext envelopes + public PAKE messages.*/import * as C from './core.js'+import {+ deriveTerminalBinaryKey,+ openTerminalBinary,+ parseTerminalBinaryEnvelope,+ sealTerminalBinary,+ type TerminalBinaryClear,+} from '../terminalBinary.js'import { E2eeStore } from './store.js'type Frame = Record<string, unknown>@@ -53,6 +60,10 @@ interface Session {s2c: Uint8Array // adapter → web (welcome + targeted RPC replies)s2cCounter: number // next send counter (0 was the welcome)c2sRecv: number // highest counter seen (replay guard)+ terminalC2s: Uint8Array+ terminalS2c: Uint8Array+ terminalS2cCounter: number+ terminalC2sRecv: number}const PAIR_TTL_MS = 60_000@@ -257,6 +268,29 @@ export class E2eeManager {return { type, payload: wrapped }}+ /** Pairwise-encrypt binary terminal data in a domain-separated counter space. */+ wrapTerminalBinary(connId: string, clear: TerminalBinaryClear): Uint8Array | null {+ const session = this.sessions.get(connId)+ if (!session) return null+ const sealed = sealTerminalBinary(session.terminalS2c, session.terminalS2cCounter, clear)+ if (!sealed) return null+ session.terminalS2cCounter+++ return sealed+ }++ /** Open one client→adapter binary terminal frame with the existing pairwise+ * replay guard. Authenticated but stale/reordered frames are dropped. */+ unwrapTerminalBinary(connId: string, raw: Uint8Array): TerminalBinaryClear | null {+ const session = this.sessions.get(connId)+ if (!session) return null+ const envelope = parseTerminalBinaryEnvelope(raw)+ if (!envelope || (session.terminalC2sRecv !== -1 && envelope.counter <= session.terminalC2sRecv)) return null+ const opened = openTerminalBinary(session.terminalC2s, raw)+ if (!opened) return null+ session.terminalC2sRecv = opened.counter+ return opened.frame+ }+// ── inbound down `message` decryption ────────────────────────────────────────────────────────────/** Decrypt an encrypted down `message`; plaintext passes through; undecryptable → null (drop). */@@ -518,7 +552,18 @@ export class E2eeManager {return true}this.evictIfFull()- this.sessions.set(connId, { webIdentityPub: identityPub, role, c2s: keys.c2s, s2c: keys.s2c, s2cCounter: 1, c2sRecv: -1 })+ this.sessions.set(connId, {+ webIdentityPub: identityPub,+ role,+ c2s: keys.c2s,+ s2c: keys.s2c,+ s2cCounter: 1,+ c2sRecv: -1,+ terminalC2s: deriveTerminalBinaryKey(keys.c2s),+ terminalS2c: deriveTerminalBinaryKey(keys.s2c),+ terminalS2cCounter: 0,+ terminalC2sRecv: -1,+ })const id = this.store.getIdentity()const enc = C.aeadSeal(keys.s2c, 0, C.utf8('e2e-welcome'), C.utf8(JSON.stringify({ groupKey: C.b64e(this.groupKey), epoch: this.epoch })))this.deps.sendTo(connId, {diff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.tsnew file mode 100644index 000000000..4fa2c64f7--- /dev/null+++ b/cli/src/lib/terminalBinary.spec.ts@@ -0,0 +1,75 @@+import { describe, expect, it } from 'vitest'+import {+ deriveTerminalBinaryKey,+ openTerminalBinary,+ parseTerminalBinaryEnvelope,+ sealTerminalBinary,+ TerminalBinaryKind,+} from './terminalBinary.js'++const key = Uint8Array.from({ length: 32 }, (_, index) => index)+const streamId = '00112233-4455-6677-8899-aabbccddeeff'++describe('terminal binary protocol v2', () => {+ it('derives the cross-platform terminal key in its own nonce domain', () => {+ expect(Buffer.from(deriveTerminalBinaryKey(key)).toString('hex')).toBe(+ '319355ec420991f1458c3a0fb5e4b38a6475f227ec166cd8754e721ab827a733',+ )+ })++ it('round-trips raw input without JSON or base64', () => {+ const sealed = sealTerminalBinary(key, 7, {+ kind: TerminalBinaryKind.input,+ streamId,+ seq: 3,+ bytes: new TextEncoder().encode('xin chào\r'),+ compressed: false,+ })!+ expect(Buffer.from(sealed.subarray(0, 4)).toString()).toBe('HTRM')+ expect(openTerminalBinary(key, sealed)).toEqual({+ counter: 7,+ frame: {+ kind: TerminalBinaryKind.input,+ streamId,+ seq: 3,+ bytes: new TextEncoder().encode('xin chào\r'),+ compressed: false,+ },+ })+ })++ it('round-trips a compressed keyframe with dimensions', () => {+ const sealed = sealTerminalBinary(key, 9, {+ kind: TerminalBinaryKind.keyframe,+ streamId,+ seq: 12,+ cols: 144,+ rows: 43,+ bytes: Uint8Array.of(0x78, 0x9c, 0x03),+ compressed: true,+ })!+ expect(openTerminalBinary(key, sealed)?.frame).toMatchObject({+ kind: TerminalBinaryKind.keyframe,+ streamId,+ seq: 12,+ cols: 144,+ rows: 43,+ compressed: true,+ })+ })++ it('rejects tamper, truncation and unsupported flags', () => {+ const sealed = sealTerminalBinary(key, 1, {+ kind: TerminalBinaryKind.output,+ streamId,+ seq: 0,+ bytes: Uint8Array.of(1, 2, 3),+ compressed: false,+ })!+ const tampered = sealed.slice(); tampered[tampered.length - 1] ^= 1+ expect(openTerminalBinary(key, tampered)).toBeNull()+ expect(parseTerminalBinaryEnvelope(sealed.subarray(0, sealed.length - 1))).toBeNull()+ const badFlags = sealed.slice(); badFlags[6] = 0x80+ expect(openTerminalBinary(key, badFlags)).toBeNull()+ })+})diff --git a/cli/src/lib/terminalBinary.ts b/cli/src/lib/terminalBinary.tsnew file mode 100644index 000000000..89d5ffef9--- /dev/null+++ b/cli/src/lib/terminalBinary.ts@@ -0,0 +1,190 @@+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_HEADER_BYTES = 20+export const TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES = 512 * 1024+export const TERMINAL_HOP_HEADER_BYTES = 24++export const enum TerminalBinaryKind {+ input = 1,+ output = 2,+ keyframe = 3,+}++export interface TerminalBinaryClear {+ kind: TerminalBinaryKind+ streamId: string+ seq: number+ bytes: Uint8Array+ compressed: boolean+ cols?: number+ rows?: number+}++export interface TerminalBinaryEnvelope {+ kind: TerminalBinaryKind+ flags: number+ counter: number+ ciphertext: Uint8Array+ aad: Uint8Array+}++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')++/** Keep binary terminal nonces independent from JSON control-frame nonces. */+export function deriveTerminalBinaryKey(sessionKey: Uint8Array): Uint8Array {+ return hkdf(sha256, sessionKey, new Uint8Array(), TERMINAL_KEY_INFO, 32)+}++function safeU64(view: DataView, offset: number): number | null {+ const value = view.getBigUint64(offset, false)+ return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : null+}++function uuidBytes(id: string): Uint8Array | null {+ const hex = id.replaceAll('-', '')+ if (!/^[0-9a-fA-F]{32}$/.test(hex)) return null+ return Uint8Array.from({ length: 16 }, (_, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16))+}++function uuidString(bytes: Uint8Array): string {+ const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`+}++function validKind(value: number): value is TerminalBinaryKind {+ return value === TerminalBinaryKind.input || value === TerminalBinaryKind.output || value === TerminalBinaryKind.keyframe+}++export function terminalBinaryType(kind: TerminalBinaryKind): string {+ if (kind === TerminalBinaryKind.input) return 'terminal_input'+ if (kind === TerminalBinaryKind.output) return 'terminal_output'+ return 'terminal_keyframe'+}++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+ const metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24+ const out = new Uint8Array(metaBytes + frame.bytes.length)+ out.set(id, 0)+ const view = new DataView(out.buffer)+ view.setBigUint64(16, BigInt(frame.seq), false)+ if (frame.kind === TerminalBinaryKind.keyframe) {+ if (!Number.isSafeInteger(frame.cols) || !Number.isSafeInteger(frame.rows)+ || frame.cols! < 1 || frame.cols! > 0xffff || frame.rows! < 1 || frame.rows! > 0xffff) return null+ view.setUint16(24, frame.cols!, false)+ view.setUint16(26, frame.rows!, false)+ }+ out.set(frame.bytes, metaBytes)+ return out+}++export function decodeTerminalPlain(kind: TerminalBinaryKind, flags: number, plaintext: Uint8Array): TerminalBinaryClear | null {+ if ((flags & ~FLAG_ZLIB) !== 0 || (kind === TerminalBinaryKind.input && flags !== 0)) return null+ const metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24+ if (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+ return {+ kind,+ streamId: uuidString(plaintext.subarray(0, 16)),+ seq,+ bytes: plaintext.slice(metaBytes),+ compressed: (flags & FLAG_ZLIB) !== 0,+ ...(kind === TerminalBinaryKind.keyframe ? { cols: view.getUint16(24, false), rows: view.getUint16(26, false) } : {}),+ }+}++export function parseTerminalBinaryEnvelope(raw: Uint8Array): TerminalBinaryEnvelope | null {+ const bytes = Uint8Array.from(raw)+ if (bytes.length < TERMINAL_BINARY_HEADER_BYTES + 16) return null+ for (let i = 0; i < MAGIC.length; i++) if (bytes[i] !== MAGIC[i]) return null+ if (bytes[4] !== TERMINAL_BINARY_VERSION || !validKind(bytes[5]) || bytes[7] !== 0) return null+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)+ const counter = safeU64(view, 8)+ const length = view.getUint32(16, false)+ if (counter == null || length < 16 || length > TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES+ || bytes.length !== TERMINAL_BINARY_HEADER_BYTES + length) return null+ return {+ kind: bytes[5],+ flags: bytes[6],+ counter,+ ciphertext: bytes.slice(TERMINAL_BINARY_HEADER_BYTES),+ aad: bytes.slice(0, 16),+ }+}++export function sealTerminalBinary(key: Uint8Array, counter: number, frame: TerminalBinaryClear): Uint8Array | null {+ if (!Number.isSafeInteger(counter) || counter < 0) return null+ const plaintext = encodeTerminalPlain(frame)+ if (!plaintext) return null+ const flags = frame.compressed ? FLAG_ZLIB : 0+ const header = new Uint8Array(TERMINAL_BINARY_HEADER_BYTES)+ header.set(MAGIC, 0)+ header[4] = TERMINAL_BINARY_VERSION+ header[5] = frame.kind+ header[6] = flags+ const view = new DataView(header.buffer)+ view.setBigUint64(8, BigInt(counter), false)+ const ciphertext = aeadSeal(key, counter, header.subarray(0, 16), plaintext)+ if (ciphertext.length > TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES) return null+ view.setUint32(16, ciphertext.length, false)+ const out = new Uint8Array(header.length + ciphertext.length)+ out.set(header)+ out.set(ciphertext, header.length)+ return out+}++export function openTerminalBinary(key: Uint8Array, raw: Uint8Array): { counter: number; frame: TerminalBinaryClear } | null {+ const envelope = parseTerminalBinaryEnvelope(raw)+ if (!envelope) return null+ const plaintext = aeadOpen(key, envelope.counter, envelope.aad, envelope.ciphertext)+ if (!plaintext) return null+ const frame = decodeTerminalPlain(envelope.kind, envelope.flags, plaintext)+ return frame ? { counter: envelope.counter, frame } : null+}++export const enum TerminalHopDirection {+ down = 1,+ up = 2,+}++export function encodeTerminalHop(direction: TerminalHopDirection, connId: string, clientFrame: Uint8Array): Uint8Array | null {+ const id = uuidBytes(connId)+ if (!id || (direction !== TerminalHopDirection.down && direction !== TerminalHopDirection.up)) return null+ const out = new Uint8Array(TERMINAL_HOP_HEADER_BYTES + clientFrame.length)+ out.set(HOP_MAGIC, 0)+ out[4] = TERMINAL_BINARY_VERSION+ out[5] = direction+ out.set(id, 8)+ out.set(clientFrame, TERMINAL_HOP_HEADER_BYTES)+ return out+}++export function decodeTerminalHop(raw: Uint8Array): { direction: TerminalHopDirection; connId: string; clientFrame: Uint8Array } | null {+ const bytes = Uint8Array.from(raw)+ if (bytes.length < TERMINAL_HOP_HEADER_BYTES + TERMINAL_BINARY_HEADER_BYTES + 16) return null+ for (let index = 0; index < HOP_MAGIC.length; index++) if (bytes[index] !== HOP_MAGIC[index]) return null+ if (bytes[4] !== TERMINAL_BINARY_VERSION || bytes[6] !== 0 || bytes[7] !== 0+ || (bytes[5] !== TerminalHopDirection.down && bytes[5] !== TerminalHopDirection.up)) return null+ const clientFrame = bytes.slice(TERMINAL_HOP_HEADER_BYTES)+ if (!parseTerminalBinaryEnvelope(clientFrame)) return null+ return {+ direction: bytes[5],+ connId: uuidString(bytes.subarray(8, 24)),+ clientFrame,+ }+}++/** Stable bytes used by cross-language golden tests and protocol diagnostics. */+export function terminalBinaryAadLabel(kind: TerminalBinaryKind): Uint8Array {+ return utf8(`HTRM|${TERMINAL_BINARY_VERSION}|${terminalBinaryType(kind)}`)+}diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 9b0d712e7..7ed689e52 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -4,6 +4,7 @@ import type { RegisteredSession } from './registry.js'import { TerminalStreamManager, terminalEngineCapabilities } from './terminalStreamManager.js'import { TERMINAL_ACTION_SUCCEEDED, type TerminalStreamHandle, type TerminalStreamSink } from './terminalTypes.js'import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'class FakeStream implements TerminalStreamHandle {readonly runtime = { backend: 'tmux' as const, paneId: '%1' }@@ -13,14 +14,20 @@ class FakeStream implements TerminalStreamHandle {snapshots = 0snapshotHistory: number[] = []snapshotBytes = Buffer.from('\u001bcfixture')+ onSnapshot: ((count: number) => void) | null = null+ pauses = 0+ resumes = 0async 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 } }}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 }+ async resumeOutput() { this.resumes++; return TERMINAL_ACTION_SUCCEEDED }async close(): Promise<void> { this.closed = true }}@@ -36,18 +43,23 @@ describe('TerminalStreamManager', () => {let sink: TerminalStreamSink | nulllet stream: FakeStreamlet sent: Array<{ connId: string; type: string; payload: Record<string, unknown> }>+ let binarySent: Array<{ connId: string; frame: TerminalBinaryClear }>let manager: TerminalStreamManagerlet agents: Map<string, RegisteredSession>+ let outputBeforeOpen: Uint8Array | nullbeforeEach(() => {vi.useFakeTimers()sink = nullstream = new FakeStream()sent = []+ binarySent = []+ outputBeforeOpen = nullagents = new Map([['agent-1', session()]])const terminals = {openStream: async (_session: RegisteredSession, _size: unknown, nextSink: TerminalStreamSink) => {sink = nextSink+ if (outputBeforeOpen) nextSink.onData(outputBeforeOpen)return { state: 'succeeded' as const, value: stream }},} as unknown as TerminalBackendCoordinator@@ -55,6 +67,7 @@ describe('TerminalStreamManager', () => {terminals,resolveAgent: (id) => agents.get(id),sendTarget: (connId, type, payload) => { sent.push({ connId, type, payload }); return true },+ sendBinaryTarget: (connId, frame) => { binarySent.push({ connId, frame }); return true },streamingAvailable: true,now: () => Date.now(),})@@ -77,7 +90,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: 1, agentId, cols: 100, rows: 30,+ requestId: `open-${index}`, protocolVersion: 2, agentId, cols: 100, rows: 30,})const ready = sent.findLast((frame) => frame.type === 'terminal_ready')expect(ready?.payload.agentId).toBe(agentId)@@ -95,43 +108,44 @@ 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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'unsupported', protocolVersion: 2, 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: 1, agentId: 'does-not-exist', cols: 100, rows: 30,+ requestId: 'missing', protocolVersion: 2, 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: 1, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],})- expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready', 'terminal_keyframe'])+ expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])+ expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])const streamId = sent[0].payload.streamId as stringsink!.onData(Buffer.from('hello'))await vi.advanceTimersByTimeAsync(8)- expect(sent.at(-1)?.type).toBe('terminal_output')- expect(sent.at(-1)?.payload.seq).toBe(1)+ expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.output)+ expect(binarySent.at(-1)?.frame.seq).toBe(1)- await manager.handleFrame('web-1', 'terminal_input', {- streamId, inputSeq: 0, data: Buffer.from('abc').toString('base64'),+ await manager.handleBinary('web-1', {+ kind: TerminalBinaryKind.input, streamId, seq: 0, compressed: false, bytes: Buffer.from('abc'),})expect(Buffer.from(stream.writes[0]).toString()).toBe('abc')- await manager.handleFrame('web-1', 'terminal_input', {- streamId, inputSeq: 2, data: Buffer.from('out-of-order').toString('base64'),+ await manager.handleBinary('web-1', {+ kind: TerminalBinaryKind.input, streamId, seq: 2, compressed: false, bytes: Buffer.from('out-of-order'),})expect(stream.writes).toHaveLength(1)expect(sent.at(-1)?.payload.code).toBe('TERMINAL_INPUT_INVALID')const mouse = Buffer.from('\u001b[<0;12;8M')- await manager.handleFrame('web-1', 'terminal_input', {- streamId, inputSeq: 1, data: mouse.toString('base64'),+ await manager.handleBinary('web-1', {+ kind: TerminalBinaryKind.input, streamId, seq: 1, compressed: false, bytes: mouse,})expect(Buffer.from(stream.writes.at(-1)!).equals(mouse)).toBe(true)@@ -141,12 +155,43 @@ describe('TerminalStreamManager', () => {expect(stream.sizes.at(-1)).toEqual({ cols: 140, rows: 50 })})+ it('does not replay pre-snapshot repaint bytes after the authoritative keyframe', async () => {+ outputBeforeOpen = Buffer.from('\u001b[2Jstale repaint')+ 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,+ })+ await vi.advanceTimersByTimeAsync(20)++ 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)+ })++ it('recaptures and discards a TUI repaint that arrives during snapshot', 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,+ })+ await vi.advanceTimersByTimeAsync(20)++ expect(stream.snapshots).toBe(2)+ 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)+ })+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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,})await manager.handleFrame('web-2', 'terminal_open', {- requestId: 'open-2', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-2', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,})expect(sent.at(-1)?.payload.code).toBe('CONTROL_LEASE_HELD')@@ -158,45 +203,70 @@ 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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,})await manager.handleFrame('web-2', 'terminal_open', {- requestId: 'open-2', protocolVersion: 1, agentId: 'agent-alias', cols: 100, rows: 30,+ requestId: 'open-2', protocolVersion: 2, 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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 2, 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 })for (let i = 0; i < 40; i++) {sink!.onData(Buffer.alloc(32 * 1024, i))- const output = sent.at(-1)!- expect(output.type).toBe('terminal_output')- await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: output.payload.seq })+ const output = binarySent.at(-1)!.frame+ expect(output.kind).toBe(TerminalBinaryKind.output)+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: output.seq })}- expect(sent.filter((frame) => frame.type === 'terminal_keyframe')).toHaveLength(1)+ expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(1)+ expect(stream.pauses).toBe(0)})- it('bounds unacked output by replacing the backlog with a keyframe', async () => {+ 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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,})- for (let i = 0; i < 33; i++) sink!.onData(Buffer.alloc(32 * 1024, i))+ const streamId = sent[0].payload.streamId as string+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })+ for (let i = 0; i < 13; i++) sink!.onData(Buffer.alloc(32 * 1024, i))+ await vi.advanceTimersByTimeAsync(1)+ expect(stream.pauses).toBe(1)+ expect(stream.resumes).toBe(0)+ 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)- expect(stream.snapshots).toBeGreaterThanOrEqual(2)- expect(sent.filter((frame) => frame.type === 'terminal_keyframe').length).toBeGreaterThanOrEqual(2)+ expect(stream.resumes).toBe(1)+ 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,+ })+ const streamId = sent[0].payload.streamId as string+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })+ for (let i = 0; i < 13; i++) sink!.onData(Buffer.alloc(32 * 1024, i))+ expect(stream.pauses).toBe(1)++ await vi.advanceTimersByTimeAsync(10_000)++ expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)+ .toBe('TERMINAL_RENDER_STALLED')+ expect(stream.closed).toBe(true)})- it('fails closed instead of emitting an oversized doubly-base64 keyframe', async () => {- stream.snapshotBytes = Buffer.alloc(241 * 1024, 0x61)+ 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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'oversized', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,})expect(stream.snapshotHistory).toEqual([1_000, 500, 250, 100, 0])- expect(sent.some((frame) => frame.type === 'terminal_keyframe')).toBe(false)+ expect(binarySent.some(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toBe(false)expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code).toBe('TERMINAL_SNAPSHOT_TOO_LARGE')expect(stream.closed).toBe(true)@@ -204,15 +274,16 @@ describe('TerminalStreamManager', () => {it('disconnect cleanup closes the stream and releases the controller', async () => {await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-1', protocolVersion: 2, 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: 1, agentId: 'agent-1', cols: 100, rows: 30,+ requestId: 'open-2', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,})- expect(sent.at(-2)?.type).toBe('terminal_ready')+ 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 61b44c1f1..91a2d72f4 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -5,21 +5,21 @@ import type { RegisteredSession } from './registry.js'import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'import { terminalPlacementKey, terminalRouteKey } from './terminalRuntime.js'import type { TerminalStreamHandle, TerminalStreamSize } from './terminalTypes.js'+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'type FramePayload = Record<string, unknown>-const PROTOCOL_VERSION = 1+const PROTOCOL_VERSION = 2const HEARTBEAT_TIMEOUT_MS = 30_000const OUTPUT_FLUSH_MS = 8const OUTPUT_CHUNK_BYTES = 32 * 1024const INPUT_MAX_BYTES = 64 * 1024-const MAX_UNACKED_FRAMES = 256-const MAX_UNACKED_BYTES = 1024 * 1024-// Terminal data is base64 inside the clear payload, then the entire E2EE-// ciphertext is base64 again. Keep enough headroom below Backend's 512 KiB-// outer-envelope limit for both JSON layers, AEAD tag and routing fields.-const KEYFRAME_MAX_BYTES = 240 * 1024+const PAUSE_HIGH_WATERMARK_BYTES = 384 * 1024+const RESUME_LOW_WATERMARK_BYTES = 128 * 1024+const RENDER_STALL_TIMEOUT_MS = 10_000+const 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 {@@ -47,12 +47,15 @@ interface ActiveStream {snapshotting: booleanresyncing: booleanclosing: boolean+ outputPaused: boolean+ stallTimer: ReturnType<typeof setTimeout> | null}export interface TerminalStreamManagerDeps {terminals: TerminalBackendCoordinatorresolveAgent: (agentId: string) => RegisteredSession | undefinedsendTarget: (connId: string, type: string, payload: FramePayload) => boolean+ sendBinaryTarget: (connId: string, frame: TerminalBinaryClear) => booleanstreamingAvailable: booleannow?: () => number}@@ -64,19 +67,13 @@ function sizeFrom(payload: FramePayload): TerminalStreamSize | null {return { cols, rows }}-function strictBase64(raw: unknown): Buffer | null {- if (typeof raw !== 'string' || raw.length === 0 || raw.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(raw)) return null- const bytes = Buffer.from(raw, 'base64')- return bytes.toString('base64') === raw ? bytes : null-}--function encoded(bytes: Uint8Array, compression: 'none' | 'zlib'): { encoding: 'none' | 'zlib'; data: string; plainBytes: number } {+function encoded(bytes: Uint8Array, compression: 'none' | 'zlib'): { compressed: boolean; bytes: Uint8Array; plainBytes: number } {const raw = Buffer.from(bytes)if (compression === 'zlib' && raw.length > 1024) {const compressed = deflateSync(raw, { level: 1 })- if (compressed.length < raw.length) return { encoding: 'zlib', data: compressed.toString('base64'), plainBytes: raw.length }+ if (compressed.length < raw.length) return { compressed: true, bytes: compressed, plainBytes: raw.length }}- return { encoding: 'none', data: raw.toString('base64'), plainBytes: raw.length }+ return { compressed: false, bytes: raw, plainBytes: raw.length }}export function terminalEngineCapabilities(@@ -118,7 +115,7 @@ export class TerminalStreamManager {this.ack(connId, payload)return truecase 'terminal_input':- await this.input(connId, payload)+ this.sendError(connId, 'TERMINAL_BINARY_REQUIRED', { streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined })return truecase 'terminal_resize':await this.resize(connId, payload)@@ -134,6 +131,13 @@ export class TerminalStreamManager {}}+ async handleBinary(connId: string, frame: TerminalBinaryClear): Promise<void> {+ if (frame.kind !== TerminalBinaryKind.input) return+ const state = this.streams.get(frame.streamId)+ if (!state || state.connId !== connId || state.closing) return+ await this.input(state, frame.seq, frame.bytes)+ }+private capabilities(connId: string, requestId: unknown): void {this.deps.sendTarget(connId, 'terminal_capabilities_result', {requestId,@@ -268,6 +272,8 @@ export class TerminalStreamManager {snapshotting: false,resyncing: false,closing: false,+ outputPaused: false,+ stallTimer: null,}this.streams.set(streamId, state)if (!this.deps.sendTarget(connId, 'terminal_ready', {@@ -301,25 +307,26 @@ export class TerminalStreamManager {if (!state) returnconst lastSeq = Number(payload.lastSeq)if (!Number.isSafeInteger(lastSeq) || lastSeq < -1 || lastSeq >= state.nextSeq) return+ let progressed = falsewhile (state.pending.length && state.pending[0].seq <= lastSeq) {state.pendingBytes -= state.pending.shift()!.bytes+ progressed = true}+ if (!progressed) return+ if (state.outputPaused && state.pendingBytes < RESUME_LOW_WATERMARK_BYTES) void this.resumeOutput(state)+ else if (state.outputPaused) this.armStallTimer(state)}- private async input(connId: string, payload: FramePayload): Promise<void> {- const state = this.streamFor(connId, payload)- if (!state) return- const inputSeq = Number(payload.inputSeq)- const bytes = strictBase64(payload.data)- if (!Number.isSafeInteger(inputSeq) || inputSeq !== state.lastInputSeq + 1 || !bytes || bytes.length > INPUT_MAX_BYTES) {- this.sendError(connId, 'TERMINAL_INPUT_INVALID', { streamId: state.streamId })+ private async input(state: ActiveStream, inputSeq: number, bytes: Uint8Array): Promise<void> {+ if (!Number.isSafeInteger(inputSeq) || inputSeq !== state.lastInputSeq + 1 || bytes.length === 0 || bytes.length > INPUT_MAX_BYTES) {+ this.sendError(state.connId, 'TERMINAL_INPUT_INVALID', { streamId: state.streamId })return}state.lastInputSeq = inputSeqstate.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MSconst result = await state.handle.writeRaw(bytes)if (result.state !== 'succeeded') {- this.sendError(connId, 'TERMINAL_INPUT_FAILED', { streamId: state.streamId, message: result.reason })+ this.sendError(state.connId, 'TERMINAL_INPUT_FAILED', { streamId: state.streamId, message: result.reason })if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state)}}@@ -354,7 +361,7 @@ export class TerminalStreamManager {if (state.closing || bytes.length === 0) returnstate.output.push(Buffer.from(bytes))state.outputBytes += bytes.length- if (state.snapshotting) return+ if (state.snapshotting || state.outputPaused) returnif (state.outputBytes >= OUTPUT_CHUNK_BYTES) {this.flushOutput(state)return@@ -372,12 +379,12 @@ export class TerminalStreamManager {const chunk = all.subarray(offset, offset + OUTPUT_CHUNK_BYTES)const seq = state.nextSeq++const body = encoded(chunk, state.compression)- if (!this.deps.sendTarget(state.connId, 'terminal_output', {- protocolVersion: PROTOCOL_VERSION,+ if (!this.deps.sendBinaryTarget(state.connId, {+ kind: TerminalBinaryKind.output,streamId: state.streamId,seq,- encoding: body.encoding,- data: body.data,+ compressed: body.compressed,+ bytes: body.bytes,})) {void this.closeStream(state, 'backend disconnected', false)return@@ -385,22 +392,79 @@ export class TerminalStreamManager {state.pending.push({ seq, bytes: body.plainBytes })state.pendingBytes += body.plainBytes}- if ((state.pending.length > MAX_UNACKED_FRAMES || state.pendingBytes > MAX_UNACKED_BYTES) && !state.resyncing) {- void this.sendKeyframe(state)+ if (state.pendingBytes > PAUSE_HIGH_WATERMARK_BYTES && !state.outputPaused) void this.pauseOutput(state)+ }++ private armStallTimer(state: ActiveStream): void {+ if (state.stallTimer) clearTimeout(state.stallTimer)+ state.stallTimer = setTimeout(() => {+ state.stallTimer = null+ if (!state.closing && state.outputPaused) {+ this.sendError(state.connId, 'TERMINAL_RENDER_STALLED', { streamId: state.streamId })+ void this.closeStream(state, 'renderer did not acknowledge terminal output', true)+ }+ }, RENDER_STALL_TIMEOUT_MS)+ }++ private async pauseOutput(state: ActiveStream): Promise<void> {+ if (state.closing || state.outputPaused) return+ state.outputPaused = true+ 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.armStallTimer(state)+ }++ private async resumeOutput(state: ActiveStream): Promise<void> {+ if (state.closing || !state.outputPaused) return+ state.outputPaused = false+ if (state.stallTimer) clearTimeout(state.stallTimer)+ state.stallTimer = null+ const result = await state.handle.resumeOutput()+ 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.flushOutput(state)}private async sendKeyframe(state: ActiveStream): Promise<void> {if (state.closing || state.resyncing) returnstate.resyncing = truestate.snapshotting = true+ if (state.outputPaused) {+ state.outputPaused = false+ 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' }))+ }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) {- snapshot = await state.handle.snapshot(historyLines)+ 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+ 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') {@@ -422,14 +486,14 @@ export class TerminalStreamManager {state.pendingBytes = 0const seq = state.nextSeq++const body = encoded(bytes, state.compression)- const sent = this.deps.sendTarget(state.connId, 'terminal_keyframe', {- protocolVersion: PROTOCOL_VERSION,+ const sent = this.deps.sendBinaryTarget(state.connId, {+ kind: TerminalBinaryKind.keyframe,streamId: state.streamId,seq,cols: snapshot.value.cols,rows: snapshot.value.rows,- encoding: body.encoding,- data: body.data,+ compressed: body.compressed,+ bytes: body.bytes,})if (!sent) {state.snapshotting = false@@ -455,10 +519,13 @@ export class TerminalStreamManager {if (state.closing) returnstate.closing = trueif (state.flushTimer) clearTimeout(state.flushTimer)+ if (state.stallTimer) clearTimeout(state.stallTimer)state.flushTimer = null+ state.stallTimer = nullthis.streams.delete(state.streamId)if (this.controllerByAgent.get(state.agentId) === state.connId) this.controllerByAgent.delete(state.agentId)if (this.controllerByPlacement.get(state.placementKey) === state.connId) this.controllerByPlacement.delete(state.placementKey)+ if (state.outputPaused) await state.handle.resumeOutput().catch(() => { /* best effort */ })await state.handle.close().catch(() => { /* best effort */ })if (notify) this.deps.sendTarget(state.connId, 'terminal_closed', {protocolVersion: PROTOCOL_VERSION,diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.tsindex bcd8aefd3..57f1469e2 100644--- a/cli/src/lib/terminalTypes.ts+++ b/cli/src/lib/terminalTypes.ts@@ -139,6 +139,8 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalRsnapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>>writeRaw(bytes: Uint8Array): Promise<TerminalActionResult>resize(size: TerminalStreamSize): Promise<TerminalActionResult>+ pauseOutput(): Promise<TerminalActionResult>+ resumeOutput(): Promise<TerminalActionResult>close(): Promise<void>}diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.tsindex 8b5192cb9..8e8a455f3 100644--- a/cli/src/lib/tmuxStream.real.spec.ts+++ b/cli/src/lib/tmuxStream.real.spec.ts@@ -6,6 +6,7 @@ import type { RegisteredSession } from './registry.js'import { TerminalStreamManager } from './terminalStreamManager.js'import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'import { TmuxControlStream } from './tmuxStream.js'+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'const run = process.env.RUN_REAL_TMUX_STREAM === '1' ? describe : describe.skip@@ -78,6 +79,7 @@ run('TmuxControlStream real tmux', () => {primaryRuntimeKey: `tmux:default:${paneId}`,} as unknown as RegisteredSessionconst frames: Array<{ type: string; payload: Record<string, unknown> }> = []+ const binaryFrames: TerminalBinaryClear[] = []const terminals = {openStream: async (_session: RegisteredSession, size: { cols: number; rows: number }, sink: Parameters<typeof TmuxControlStream.open>[2]) =>TmuxControlStream.open(paneId, size, sink),@@ -86,13 +88,14 @@ run('TmuxControlStream real tmux', () => {terminals,resolveAgent: (candidate) => candidate === agentId ? registered : undefined,sendTarget: (_connId, type, payload) => { frames.push({ type, payload }); return true },+ sendBinaryTarget: (_connId, frame) => { binaryFrames.push(frame); return true },streamingAvailable: true,})try {await manager.handleFrame('matrix-client', 'terminal_open', {requestId: `open-${engine}`,- protocolVersion: 1,+ protocolVersion: 2,agentId,cols: 90 + index,rows: 24,@@ -104,14 +107,16 @@ run('TmuxControlStream real tmux', () => {expect(typeof streamId).toBe('string')const marker = `HARNESS_ENGINE_STREAM_${engine.toUpperCase()}`- await manager.handleFrame('matrix-client', 'terminal_input', {- streamId,- inputSeq: 0,- data: Buffer.from(`printf '${marker}\\n'\r`).toString('base64'),+ await manager.handleBinary('matrix-client', {+ kind: TerminalBinaryKind.input,+ streamId: streamId as string,+ seq: 0,+ compressed: false,+ bytes: Buffer.from(`printf '${marker}\\n'\r`),})- await eventually(() => frames.some((frame) => {- if (frame.type !== 'terminal_output' || frame.payload.encoding !== 'none') return false- return Buffer.from(String(frame.payload.data), 'base64').includes(Buffer.from(marker))+ await eventually(() => binaryFrames.some((frame) => {+ if (frame.kind !== TerminalBinaryKind.output || frame.compressed) return false+ return Buffer.from(frame.bytes).includes(Buffer.from(marker))}))await manager.handleFrame('matrix-client', 'terminal_resize', {diff --git a/cli/src/lib/tmuxStream.spec.ts b/cli/src/lib/tmuxStream.spec.tsindex 206455586..3315ea3c3 100644--- a/cli/src/lib/tmuxStream.spec.ts+++ b/cli/src/lib/tmuxStream.spec.ts@@ -1,5 +1,9 @@import { describe, expect, it } from 'vitest'-import { decodeTmuxControlData } from './tmuxStream.js'+import {+ decodeTmuxControlData,+ normalizeTmuxCaptureLines,+ parseTmuxControlOutput,+} from './tmuxStream.js'describe('tmux control-mode output decoding', () => {it('decodes octal bytes without corrupting adjacent UTF-8', () => {@@ -10,4 +14,38 @@ describe('tmux control-mode output decoding', () => {it('preserves ordinary backslashes that are not octal escapes', () => {expect(Buffer.from(decodeTmuxControlData('C:\\Users\\name')).toString()).toBe('C:\\Users\\name')})++ it('preserves a UTF-8 scalar split across separate output records', () => {+ const first = parseTmuxControlOutput(Buffer.concat([+ Buffer.from('%output %7 '),+ Buffer.from([0xe2, 0x94]),+ ]))+ const second = parseTmuxControlOutput(Buffer.concat([+ Buffer.from('%output %7 '),+ Buffer.from([0x80]),+ ]))++ expect(first?.paneId).toBe('%7')+ expect(second?.paneId).toBe('%7')+ expect(Buffer.concat([+ Buffer.from(first!.data),+ Buffer.from(second!.data),+ ])).toEqual(Buffer.from('─'))+ })+})++describe('tmux snapshot row normalization', () => {+ it('turns capture-pane LF rows into VT CRLF and drops its final output delimiter', () => {+ const capture = Buffer.from('first\n\u001b[31m世界\nlast\r\n')+ expect(Buffer.from(normalizeTmuxCaptureLines(capture))).toEqual(+ Buffer.from('first\u001b[0m\r\n\u001b[31m世界\u001b[0m\r\nlast\u001b[0m'),+ )+ })++ it('stops a styled trailing background from bleeding into the next blank row', () => {+ const capture = Buffer.from('\u001b[48;5;237mprompt \n\n\u001b[49mreply\n')+ expect(Buffer.from(normalizeTmuxCaptureLines(capture)).toString()).toBe(+ '\u001b[48;5;237mprompt \u001b[0m\r\n\u001b[0m\r\n\u001b[49mreply\u001b[0m',+ )+ })})diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.tsindex 1b324ced6..d30ac3df0 100644--- a/cli/src/lib/tmuxStream.ts+++ b/cli/src/lib/tmuxStream.ts@@ -1,6 +1,5 @@import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'import { randomUUID } from 'node:crypto'-import { StringDecoder } from 'node:string_decoder'import {TERMINAL_ACTION_SUCCEEDED,terminalActionNotStarted,@@ -19,6 +18,7 @@ const MAX_COLS = 300const MIN_ROWS = 12const MAX_ROWS = 120const SMALL_INPUT_BYTES = 4 * 1024+const CONTROL_OUTPUT_SETTLE_MS = 24interface PaneMeta {sessionId: string@@ -86,19 +86,54 @@ async function paneMeta(paneId: string): Promise<PaneMeta | null> {/** Decode the octal escaping used by tmux control-mode `%output` notifications. */export function decodeTmuxControlData(encoded: string): Uint8Array {+ return decodeTmuxControlBytes(Buffer.from(encoded, 'utf8'))+}++/** Decode control-mode escaping without first interpreting payload bytes as+ * UTF-8. A Unicode scalar may be split across separate `%output` records; a+ * string decoder would permanently replace both halves with U+FFFD. */+export function decodeTmuxControlBytes(encoded: Uint8Array): Uint8Array {+ const input = Buffer.from(encoded)const chunks: Buffer[] = []let plainStart = 0- for (let i = 0; i < encoded.length; i++) {- if (encoded[i] !== '\\' || !/^[0-7]{3}$/.test(encoded.slice(i + 1, i + 4))) continue- if (i > plainStart) chunks.push(Buffer.from(encoded.slice(plainStart, i), 'utf8'))- chunks.push(Buffer.from([Number.parseInt(encoded.slice(i + 1, i + 4), 8)]))+ for (let i = 0; i < input.length; i++) {+ if (input[i] !== 0x5c+ || i + 3 >= input.length+ || input[i + 1] < 0x30 || input[i + 1] > 0x37+ || input[i + 2] < 0x30 || input[i + 2] > 0x37+ || input[i + 3] < 0x30 || input[i + 3] > 0x37) continue+ if (i > plainStart) chunks.push(input.subarray(plainStart, i))+ const value = ((input[i + 1] - 0x30) << 6)+ | ((input[i + 2] - 0x30) << 3)+ | (input[i + 3] - 0x30)+ chunks.push(Buffer.from([value]))i += 3plainStart = i + 1}- if (plainStart < encoded.length) chunks.push(Buffer.from(encoded.slice(plainStart), 'utf8'))+ if (plainStart < input.length) chunks.push(input.subarray(plainStart))return Buffer.concat(chunks)}+export function parseTmuxControlOutput(lineBytes: Uint8Array): { paneId: string; data: Uint8Array } | null {+ const line = Buffer.from(lineBytes)+ const plainPrefix = Buffer.from('%output ')+ if (line.subarray(0, plainPrefix.length).equals(plainPrefix)) {+ const separator = line.indexOf(0x20, plainPrefix.length)+ if (separator < 0) return null+ const paneId = line.subarray(plainPrefix.length, separator).toString('ascii')+ if (!/^%\d+$/.test(paneId)) return null+ return { paneId, data: decodeTmuxControlBytes(line.subarray(separator + 1)) }+ }++ const extendedPrefix = Buffer.from('%extended-output ')+ if (!line.subarray(0, extendedPrefix.length).equals(extendedPrefix)) return null+ // latin1 is deliberately used only to locate the ASCII protocol header;+ // each code unit still maps one-to-one to the original payload byte.+ const header = /^%extended-output\s+(%\d+)\s+\d+\s+:?\s?/.exec(line.toString('latin1'))+ if (!header) return null+ return { paneId: header[1], data: decodeTmuxControlBytes(line.subarray(header[0].length)) }+}+function mouseModes(meta: PaneMeta): string {let out = ''if (meta.mouseAll) out += '\u001b[?1003h'@@ -109,12 +144,52 @@ function mouseModes(meta: PaneMeta): string {return out}+/** `capture-pane -p` separates screen rows with a bare LF. A VT terminal's+ * LF moves down without returning to column zero, so replaying the capture as+ * received makes every row staircase to the right. tmux also encodes each+ * captured row independently: it may leave a background SGR active at EOL+ * while emitting the following default-style blank row as an empty string.+ * Reset SGR at every row boundary so styled trailing cells remain on their row+ * instead of bleeding into the next one when the snapshot is replayed. */+export function normalizeTmuxCaptureLines(capture: Uint8Array): Uint8Array {+ const raw = Buffer.from(capture)+ // `capture-pane -p` prints a line terminator after its final screen row.+ // Replaying that terminator in a terminal already containing paneHeight rows+ // scrolls the snapshot by one, while cursor metadata stays in tmux's original+ // coordinate space. Drop only this command-output delimiter; separators+ // between captured rows are still normalized below.+ let end = raw.length+ if (end > 0 && raw[end - 1] === 0x0a) {+ end--+ if (end > 0 && raw[end - 1] === 0x0d) end--+ }+ const input = raw.subarray(0, end)+ let loneLf = 0+ for (let index = 0; index < input.length; index++) {+ if (input[index] === 0x0a && (index === 0 || input[index - 1] !== 0x0d)) loneLf+++ }+ const sgrReset = Buffer.from('\u001b[0m')+ const output = Buffer.allocUnsafe(input.length + loneLf * (1 + sgrReset.length) + sgrReset.length)+ let write = 0+ for (let index = 0; index < input.length; index++) {+ if (input[index] === 0x0a && (index === 0 || input[index - 1] !== 0x0d)) {+ sgrReset.copy(output, write)+ write += sgrReset.length+ output[write++] = 0x0d+ }+ output[write++] = input[index]+ }+ sgrReset.copy(output, write)+ write += sgrReset.length+ return output.subarray(0, write)+}+export function synthesizeTmuxSnapshot(capture: Uint8Array, meta: PaneMeta): Uint8Array {const cursorRow = Math.max(1, Math.min(meta.paneHeight, meta.cursorY + 1))const cursorCol = Math.max(1, Math.min(meta.paneWidth, meta.cursorX + 1))const prefix = Buffer.from(`\u001bc\u001b[?25l\u001b[H\u001b[2J\u001b[3J${mouseModes(meta)}`, 'utf8')const suffix = Buffer.from(`\u001b[${cursorRow};${cursorCol}H\u001b[?25h`, 'utf8')- return Buffer.concat([prefix, Buffer.from(capture), suffix])+ return Buffer.concat([prefix, normalizeTmuxCaptureLines(capture), suffix])}async function loadAndPaste(paneId: string, bytes: Uint8Array): Promise<TerminalActionResult> {@@ -148,10 +223,10 @@ async function sendHexBytes(paneId: string, bytes: Uint8Array): Promise<Terminalexport class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {readonly runtime: TmuxRuntimeRefprivate readonly child: ChildProcessWithoutNullStreams- private readonly decoder = new StringDecoder('utf8')- private lineBuffer = ''+ private lineBuffer = Buffer.alloc(0)private closed = falseprivate closeNotified = false+ private outputPaused = falseprivate original: PaneMetaprivate lastApplied: TerminalStreamSize | null = null@@ -192,33 +267,30 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {}private onStdout(chunk: Buffer): void {- this.lineBuffer += this.decoder.write(chunk)+ this.lineBuffer = Buffer.concat([this.lineBuffer, chunk])while (true) {- const newline = this.lineBuffer.indexOf('\n')+ const newline = this.lineBuffer.indexOf(0x0a)if (newline < 0) break- const line = this.lineBuffer.slice(0, newline).replace(/\r$/, '')- this.lineBuffer = this.lineBuffer.slice(newline + 1)+ let line = this.lineBuffer.subarray(0, newline)+ if (line.at(-1) === 0x0d) line = line.subarray(0, line.length - 1)+ this.lineBuffer = this.lineBuffer.subarray(newline + 1)this.onControlLine(line)}}- private onControlLine(line: string): void {- const output = /^%output\s+(%\d+)\s(.*)$/.exec(line)+ private onControlLine(line: Buffer): void {+ const output = parseTmuxControlOutput(line)if (output) {- if (output[1] === this.runtime.paneId) this.sink.onData(decodeTmuxControlData(output[2]))- return- }- const extended = /^%extended-output\s+(%\d+)\s+\d+\s+:?\s?(.*)$/.exec(line)- if (extended) {- if (extended[1] === this.runtime.paneId) this.sink.onData(decodeTmuxControlData(extended[2]))+ if (output.paneId === this.runtime.paneId) this.sink.onData(output.data)return}- const paused = /^%pause\s+(%\d+)$/.exec(line)- if (paused?.[1] === this.runtime.paneId && !this.closed) {+ const text = line.toString('ascii')+ 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`)return}- if (line.startsWith('%exit')) this.notifyClose(this.closed ? 'closed' : 'tmux pane/control client closed')+ if (text.startsWith('%exit')) this.notifyClose(this.closed ? 'closed' : 'tmux pane/control client closed')}private notifyClose(reason: string): void {@@ -231,10 +303,23 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {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)))- const args = ['capture-pane', '-p', '-e', '-t', this.runtime.paneId]+ // -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: {@@ -265,6 +350,30 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {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')+ }+ }++ 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')+ }+ }+async close(): Promise<void> {if (this.closed) returnthis.closed = true