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.

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.ts
index 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 = false
snapshots = 0
- snapshotHistory: number[] = []
snapshotBytes = Buffer.from('\u001bcfixture')
onSnapshot: ((count: number) => void) | null = null
pauses = 0
@@ -22,9 +21,8 @@ class FakeStream implements TerminalStreamHandle {
onEndSnapshot: (() => void) | null = null
beginSnapshot() { 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.ts
index 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 * 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 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.ts
index 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 = TerminalR
readonly 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(): void
writeRaw(bytes: Uint8Array): Promise<TerminalActionResult>
diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.ts
index 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.ts
index 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.ts
index 07e32bc78..b42f840eb 100644
--- a/cli/src/lib/tmuxStream.ts
+++ b/cli/src/lib/tmuxStream.ts
@@ -20,6 +20,8 @@ const MAX_ROWS = 120
const SMALL_INPUT_BYTES = 4 * 1024
const CONTROL_COMMAND_TIMEOUT_MS = 3_000
const SNAPSHOT_BUFFER_MAX_BYTES = 2 * 1024 * 1024
+const SNAPSHOT_QUIET_MS = 8
+const SNAPSHOT_QUIET_MAX_MS = 40
const 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 = false
private 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 = false
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 snapshotLastOutputAt = 0
private constructor(
paneId: string,
- original: PaneMeta,
child: ChildProcessWithoutNullStreams,
private readonly sink: TerminalStreamSink,
) {
this.runtime = { backend: 'tmux', paneId }
- this.original = original
this.child = child
child.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) return
const next = this.commandQueue.shift()
if (!next) return
this.commandActive = next
@@ -425,26 +456,40 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
this.snapshotGated = true
this.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 = size
return TERMINAL_ACTION_SUCCEEDED
})
}
@@ -509,14 +559,10 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
async close(): Promise<void> {
if (this.closed) return
this.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 }