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
refactor: improve tmux snapshot reliability with quiet-wait logic and absolute row positioning
0xken154b100800edb9
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 316b3dd90..0d7d33c52 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -12,7 +12,6 @@ class FakeStream implements TerminalStreamHandle {sizes: Array<{ cols: number; rows: number }> = []closed = falsesnapshots = 0- snapshotHistory: number[] = []snapshotBytes = Buffer.from('\u001bcfixture')onSnapshot: ((count: number) => void) | null = nullpauses = 0@@ -22,9 +21,8 @@ class FakeStream implements TerminalStreamHandle {onEndSnapshot: (() => void) | null = nullbeginSnapshot() { this.snapshotBegins++ }- async snapshot(historyLines: number): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {+ async snapshot(): 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 } }}@@ -328,7 +326,7 @@ describe('TerminalStreamManager', () => {await manager.handleFrame('web-1', 'terminal_open', {requestId: 'oversized', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,})- expect(stream.snapshotHistory).toEqual([1_000, 500, 250, 100, 0])+ expect(stream.snapshots).toBe(1)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')diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.tsindex 4218f14c0..9e10ce48c 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -20,7 +20,6 @@ const RESUME_LOW_WATERMARK_BYTES = 128 * 1024const RENDER_STALL_TIMEOUT_MS = 10_000const MAX_TOTAL_BUFFERED_BYTES = 2 * 1024 * 1024const KEYFRAME_MAX_BYTES = 480 * 1024-const KEYFRAME_HISTORY_ATTEMPTS = [1_000, 500, 250, 100, 0] as constconst TERMINAL_ENGINES: ReadonlySet<string> = new Set(ENGINES)interface PendingOutput {@@ -530,10 +529,7 @@ export class TerminalStreamManager {reason: 'tmux snapshot did not run',}try {- for (const historyLines of KEYFRAME_HISTORY_ATTEMPTS) {- snapshot = await state.handle.snapshot(historyLines)- if (snapshot.state !== 'succeeded' || snapshot.value.bytes.length <= KEYFRAME_MAX_BYTES) break- }+ snapshot = await state.handle.snapshot()} catch (error) {snapshot = { state: 'failed', reason: error instanceof Error ? error.message : 'tmux snapshot failed' }}diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.tsindex 7e98986cd..942c0543d 100644--- a/cli/src/lib/terminalTypes.ts+++ b/cli/src/lib/terminalTypes.ts@@ -140,7 +140,10 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalRreadonly runtime: Ref/** Gate live output before taking an ordered snapshot. */beginSnapshot(): void- snapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>>+ /** Capture only the authoritative visible viewport. Terminal scrollback can+ * contain prior full-screen TUI repaint frames and must never be replayed as+ * part of a keyframe. */+ snapshot(): Promise<TerminalReadResult<TerminalStreamSnapshot>>/** Release output produced strictly after the snapshot cut. */endSnapshot(): voidwriteRaw(bytes: Uint8Array): Promise<TerminalActionResult>diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.tsindex 6d4ef4fb5..e77acdb32 100644--- a/cli/src/lib/tmuxStream.real.spec.ts+++ b/cli/src/lib/tmuxStream.real.spec.ts@@ -44,17 +44,21 @@ run('TmuxControlStream real tmux', () => {expect(opened.state).toBe('succeeded')if (opened.state !== 'succeeded') return+ const historyMarker = 'HARNESS_OLD_TUI_FRAME_MUST_NOT_REPLAY'const snapshotMarker = 'HARNESS_SNAPSHOT_OK'- await opened.value.writeRaw(Buffer.from(`printf '${snapshotMarker}\\n'\r`))+ await opened.value.writeRaw(Buffer.from(+ `printf '${historyMarker}\\n'; for i in {1..40}; do printf 'filler-%s\\n' "$i"; done; 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)+ const snapshot = await opened.value.snapshot()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)+ expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from(historyMarker))).toBe(false)}const postCutMarker = 'HARNESS_POST_CUT_OK'@@ -74,6 +78,7 @@ run('TmuxControlStream real tmux', () => {expect((await opened.value.resize({ cols: 110, rows: 35 })).state).toBe('succeeded')expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe('110x35')await opened.value.close()+ expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe('110x35')expect(closedReason === '' || closedReason === 'closed').toBe(true)})@@ -145,4 +150,20 @@ run('TmuxControlStream real tmux', () => {}}}, 60_000)++ it('never mistakes the control client handshake for the first snapshot command', async () => {+ for (let attempt = 0; attempt < 12; attempt++) {+ const opened = await TmuxControlStream.open(paneId, { cols: 100, rows: 30 }, {+ onData: () => {},+ onClose: () => {},+ })+ expect(opened.state).toBe('succeeded')+ if (opened.state !== 'succeeded') continue+ opened.value.beginSnapshot()+ const snapshot = await opened.value.snapshot()+ expect(snapshot.state).toBe('succeeded')+ opened.value.endSnapshot()+ await opened.value.close()+ }+ })})diff --git a/cli/src/lib/tmuxStream.spec.ts b/cli/src/lib/tmuxStream.spec.tsindex 3315ea3c3..a4ca4c0ec 100644--- a/cli/src/lib/tmuxStream.spec.ts+++ b/cli/src/lib/tmuxStream.spec.ts@@ -3,6 +3,7 @@ import {decodeTmuxControlData,normalizeTmuxCaptureLines,parseTmuxControlOutput,+ synthesizeTmuxSnapshot,} from './tmuxStream.js'describe('tmux control-mode output decoding', () => {@@ -48,4 +49,22 @@ describe('tmux snapshot row normalization', () => {'\u001b[48;5;237mprompt \u001b[0m\r\n\u001b[0m\r\n\u001b[49mreply\u001b[0m',)})++ it('places every captured row absolutely while autowrap is disabled', () => {+ const snapshot = Buffer.from(synthesizeTmuxSnapshot(+ Buffer.from('wide 世界 row\nsecond row\n'),+ {+ sessionId: '$1', windowId: '@1', windowPanes: 1,+ windowWidth: 80, windowHeight: 2, paneWidth: 80, paneHeight: 2,+ alternateOn: false, cursorX: 4, cursorY: 1,+ mouseStandard: false, mouseButton: false, mouseAll: false,+ mouseUtf8: false, mouseSgr: false,+ },+ )).toString()++ expect(snapshot).toContain('\u001b[?7l')+ expect(snapshot).toContain('\u001b[1;1Hwide 世界 row\u001b[0m')+ expect(snapshot).toContain('\u001b[2;1Hsecond row\u001b[0m')+ expect(snapshot).toContain('\u001b[2;5H\u001b[?7h\u001b[?25h')+ })})diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.tsindex 07e32bc78..b42f840eb 100644--- a/cli/src/lib/tmuxStream.ts+++ b/cli/src/lib/tmuxStream.ts@@ -20,6 +20,8 @@ const MAX_ROWS = 120const SMALL_INPUT_BYTES = 4 * 1024const CONTROL_COMMAND_TIMEOUT_MS = 3_000const SNAPSHOT_BUFFER_MAX_BYTES = 2 * 1024 * 1024+const SNAPSHOT_QUIET_MS = 8+const SNAPSHOT_QUIET_MAX_MS = 40const PANE_META_FORMAT = ['#{session_id}', '#{window_id}', '#{window_panes}', '#{window_width}', '#{window_height}','#{pane_width}', '#{pane_height}', '#{alternate_on}', '#{cursor_x}', '#{cursor_y}',@@ -201,9 +203,32 @@ export function normalizeTmuxCaptureLines(capture: Uint8Array): Uint8Array {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, normalizeTmuxCaptureLines(capture), suffix])+ const prefix = Buffer.from(+ `\u001bc\u001b[?25l\u001b[?7l\u001b[H\u001b[2J\u001b[3J${mouseModes(meta)}`,+ 'utf8',+ )+ const raw = Buffer.from(capture)+ const rows: Buffer[] = []+ let start = 0+ let rowIndex = 0+ for (let index = 0; index <= raw.length && rowIndex < meta.paneHeight; index++) {+ if (index !== raw.length && raw[index] !== 0x0a) continue+ let end = index+ if (end > start && raw[end - 1] === 0x0d) end--+ // Position every tmux row independently. tmux and the receiving emulator+ // can disagree on the display width of Unicode scalars; replaying rows via+ // CRLF lets that disagreement wrap one row into another. Absolute row+ // placement with autowrap disabled makes the captured grid authoritative.+ rows.push(+ Buffer.from(`\u001b[${rowIndex + 1};1H`, 'utf8'),+ raw.subarray(start, end),+ Buffer.from('\u001b[0m', 'utf8'),+ )+ rowIndex+++ start = index + 1+ }+ const suffix = Buffer.from(`\u001b[${cursorRow};${cursorCol}H\u001b[?7h\u001b[?25h`, 'utf8')+ return Buffer.concat([prefix, ...rows, suffix])}async function loadAndPaste(paneId: string, bytes: Uint8Array): Promise<TerminalActionResult> {@@ -240,23 +265,23 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {private lineBuffer = Buffer.alloc(0)private closed = falseprivate closeNotified = false- private original: PaneMeta- private lastApplied: TerminalStreamSize | null = null+ // `tmux -C attach-session` emits its own initial %begin/%end transaction.+ // Do not assign that command number to our first queued command.+ private controlReady = falseprivate commandActive: PendingControlCommand | null = nullprivate readonly commandQueue: PendingControlCommand[] = []private operationTail: Promise<void> = Promise.resolve()private snapshotGated = falseprivate snapshotPostCut: Buffer[] = []private snapshotPostCutBytes = 0+ private snapshotLastOutputAt = 0private constructor(paneId: string,- original: PaneMeta,child: ChildProcessWithoutNullStreams,private readonly sink: TerminalStreamSink,) {this.runtime = { backend: 'tmux', paneId }- this.original = originalthis.child = childchild.stdout.on('data', (chunk: Buffer) => this.onStdout(chunk))child.once('error', (error) => this.notifyClose(`tmux control client error: ${error.message}`))@@ -276,7 +301,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {child.once('error', () => { if (!settled) { settled = true; resolve(false) } })})if (!spawned) return { state: 'failed', reason: 'tmux control client could not start' }- const stream = new TmuxControlStream(paneId, original, child, sink)+ const stream = new TmuxControlStream(paneId, child, sink)const resized = await stream.resize(size)if (resized.state !== 'succeeded') {await stream.close()@@ -314,6 +339,11 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {const completed = /^%(end|error)\s+\d+\s+(\d+)\s+\d+$/.exec(text)if (completed) {const active = this.commandActive+ if (!this.controlReady && active == null) {+ this.controlReady = true+ this.pumpControlCommand()+ return+ }if (active?.commandNumber === completed[2]) {if (completed[1] === 'end') active.onEnd?.()this.finishControlCommand(active, completed[1] === 'end')@@ -347,6 +377,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {const chunk = Buffer.from(bytes)this.snapshotPostCut.push(chunk)this.snapshotPostCutBytes += chunk.length+ this.snapshotLastOutputAt = Date.now()if (this.snapshotPostCutBytes > SNAPSHOT_BUFFER_MAX_BYTES) {this.failControlCommands()this.notifyClose('tmux snapshot output exceeded safe buffer limit')@@ -369,7 +400,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {}private pumpControlCommand(): void {- if (this.commandActive || this.closed) return+ if (!this.controlReady || this.commandActive || this.closed) returnconst next = this.commandQueue.shift()if (!next) returnthis.commandActive = next@@ -425,26 +456,40 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {this.snapshotGated = truethis.snapshotPostCut = []this.snapshotPostCutBytes = 0+ this.snapshotLastOutputAt = Date.now()+ }++ private async waitForSnapshotQuiet(): Promise<void> {+ const deadline = Date.now() + SNAPSHOT_QUIET_MAX_MS+ while (!this.closed) {+ const now = Date.now()+ const remainingQuiet = SNAPSHOT_QUIET_MS - (now - this.snapshotLastOutputAt)+ if (remainingQuiet <= 0 || now >= deadline) return+ await new Promise((resolve) => setTimeout(resolve, Math.min(remainingQuiet, deadline - now)))+ }}- async snapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>> {+ async snapshot(): Promise<TerminalReadResult<TerminalStreamSnapshot>> {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.+ // trims from each captured row. Deliberately do not use capture-pane -S:+ // tmux scrollback contains old full-screen TUI repaint frames. Replaying+ // those frames into a fresh emulator corrupts the visible screen.const baseCapture = `capture-pane -p -e -N -t ${this.runtime.paneId}`+ // Attaching a control client can trigger an immediate TUI repaint. Wait+ // before reading both cursor metadata and the grid so the synthesized+ // keyframe cannot combine a post-repaint grid with pre-repaint cursor+ // coordinates.+ await this.waitForSnapshotQuiet()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, () => {+ const capture = await this.runControlCommand(baseCapture, () => {// `%end` is the ordered cut. Notifications observed before it are// represented by capture-pane; only later output may follow the keyframe.this.snapshotPostCut = []@@ -486,9 +531,14 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {if (!meta) return terminalActionNotStarted('tmux pane disappeared')if (meta.windowPanes !== 1) return terminalActionNotStarted('TERMINAL_MULTI_PANE_UNSUPPORTED')const size = boundedSize(requested)+ // A repeated open/focus can legitimately ask for the grid already in+ // use. Avoid a redundant resize-window because full-screen TUIs may+ // repaint on SIGWINCH even when the dimensions did not change.+ if (meta.windowWidth === size.cols && meta.windowHeight === size.rows) {+ return TERMINAL_ACTION_SUCCEEDED+ }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 = sizereturn TERMINAL_ACTION_SUCCEEDED})}@@ -509,14 +559,10 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {async close(): Promise<void> {if (this.closed) returnthis.closed = true- const current = await paneMeta(this.runtime.paneId)- if (current && current.windowPanes === 1 && this.lastApplied- && current.windowWidth === this.lastApplied.cols && current.windowHeight === this.lastApplied.rows) {- await execTmux([- 'resize-window', '-t', current.windowId,- '-x', String(this.original.windowWidth), '-y', String(this.original.windowHeight),- ])- }+ // Keep the last applied grid. Restoring the headless tmux default here+ // makes agent switching shrink and immediately re-expand the pane; TUIs+ // such as Grok preserve those intermediate repaint fragments in the live+ // screen. The next controller will resize only if its grid truly differs.try { this.child.stdin.write('detach-client\n') } catch { /* ignore */ }const exited = await new Promise<boolean>((resolve) => {if (this.child.exitCode != null || this.child.signalCode != null) { resolve(true); return }