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.

Stop Grok wheel from scrolling stale TUI frames

Catalin Waack1021cf05a02f
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 0806b3752..b38eb2032 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -25,11 +25,13 @@ class FakeStream implements TerminalStreamHandle {
resumes = 0
snapshotBegins = 0
snapshotEnds = 0
+ snapshotOptions: Array<{ tuiOwnsScrollback?: boolean } | undefined> = []
onEndSnapshot: (() => void) | null = null
beginSnapshot() { this.snapshotBegins++ }
- async snapshot(): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {
+ async snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {
this.snapshots++
+ this.snapshotOptions.push(options)
this.onSnapshot?.(this.snapshots)
return { state: 'succeeded', value: { bytes: this.snapshotBytes, cols: 120, rows: 40 } }
}
@@ -135,6 +137,19 @@ describe('TerminalStreamManager', () => {
expect(sent.at(-1)?.payload.code).toBe('TERMINAL_AGENT_NOT_FOUND')
})
+ it('tells a Grok snapshot not to seed tmux history, and leaves other engines alone', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-codex', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ expect(stream.snapshotOptions.at(-1)).toBeUndefined()
+
+ agents.set('grok-1', session('grok', 'grok-1'))
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-grok', protocolVersion: 3, agentId: 'grok-1', cols: 120, rows: 40,
+ })
+ expect(stream.snapshotOptions.at(-1)).toEqual({ tuiOwnsScrollback: true })
+ })
+
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: 3, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index f438af183..77a3d4dec 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -754,9 +754,9 @@ export class TerminalStreamManager {
/** Scroll gestures arrive stream-scoped, same as resize — no ordering/seq guard needed since,
* unlike input, an out-of-order or dropped scroll frame just means one gesture scrolled a little
- * more or less than intended, never a corrupted stream. The pane's live output stream (already
- * flowing via `sink.onData`) naturally carries the scrolled copy-mode view back to the client, so
- * no explicit keyframe push is needed here the way resize needs one. */
+ * more or less than intended, never a corrupted stream. PageUp/PageDown are written into the
+ * pty, so the program's own redraw rides the live output stream (`sink.onData`) back to the
+ * client; no explicit keyframe push is needed here the way resize needs one. */
private async scroll(connId: string, payload: FramePayload): Promise<void> {
const state = this.streamFor(connId, payload)
if (!state) return
@@ -923,7 +923,9 @@ export class TerminalStreamManager {
reason: 'tmux snapshot did not run',
}
try {
- snapshot = await state.handle.snapshot()
+ snapshot = await state.handle.snapshot(
+ state.engineId === 'grok' ? { tuiOwnsScrollback: true } : undefined,
+ )
} 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 908575213..c4255f96b 100644
--- a/cli/src/lib/terminalTypes.ts
+++ b/cli/src/lib/terminalTypes.ts
@@ -162,8 +162,13 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalR
beginSnapshot(): void
/** 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>>
+ * part of a keyframe.
+ *
+ * `tuiOwnsScrollback` is for a full-screen TUI that paints in tmux's *normal*
+ * buffer (Grok). Its tmux history is prior repaint frames, not a shell
+ * transcript, and must not be seeded; the snapshot is labelled as the
+ * alternate screen so the receiver routes the wheel to the program. */
+ snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<TerminalReadResult<TerminalStreamSnapshot>>
/** Release output produced strictly after the snapshot cut. */
endSnapshot(): void
writeRaw(bytes: Uint8Array): Promise<TerminalActionResult>
@@ -171,11 +176,12 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalR
* `pasteRawIntoTmux` for why a paste needs its own path instead of reusing the keystroke one. */
pasteRaw(text: string): Promise<TerminalActionResult>
resize(size: TerminalStreamSize): Promise<TerminalActionResult>
- /** Scroll via the backend's own history mechanism (tmux copy-mode for `TmuxControlStream`) rather
- * than writing bytes into the pty — a program that owns terminal mouse-tracking but doesn't
- * itself understand SGR wheel reports (confirmed live for Grok: it echoes the raw escape bytes
- * into its own prompt instead of scrolling) would otherwise treat wheel input as garbage
- * keystrokes. Backends with no such concept (anything not tmux-backed) may no-op. */
+ /** Scroll a full-screen TUI that owns mouse-tracking but mishandles SGR wheel
+ * reports (confirmed live for Grok: it echoes the raw escape bytes into its
+ * own prompt). The tmux backend sends PageUp/PageDown into the pty — Grok
+ * scrolls its conversation with those keys even while the prompt is focused.
+ * Do not use tmux copy-mode: alt-screen history is prior TUI repaint frames.
+ * Backends with no such concept (anything not tmux-backed) may no-op. */
scroll(direction: 'up' | 'down', lines: number): Promise<TerminalActionResult>
pauseOutput(): Promise<TerminalActionResult>
resumeOutput(): Promise<TerminalActionResult>
diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.ts
index dfbb0b691..f0ff494d6 100644
--- a/cli/src/lib/tmuxStream.real.spec.ts
+++ b/cli/src/lib/tmuxStream.real.spec.ts
@@ -80,6 +80,11 @@ run('TmuxControlStream real tmux', () => {
}
expect(Buffer.concat(chunks).includes(Buffer.from('HARNESS_STREAM_OK'))).toBe(true)
+ expect((await opened.value.scroll('up', 5)).state).toBe('succeeded')
+ expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_in_mode}'])).toBe('0')
+ expect((await opened.value.scroll('down', 1)).state).toBe('succeeded')
+ expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_in_mode}'])).toBe('0')
+
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()
diff --git a/cli/src/lib/tmuxStream.spec.ts b/cli/src/lib/tmuxStream.spec.ts
index ff4a769bb..7a26b02c8 100644
--- a/cli/src/lib/tmuxStream.spec.ts
+++ b/cli/src/lib/tmuxStream.spec.ts
@@ -6,8 +6,19 @@ import {
normalizeTmuxCaptureLines,
parseTmuxControlOutput,
synthesizeTmuxSnapshot,
+ tuiScrollPageCount,
} from './tmuxStream.js'
+describe('tuiScrollPageCount', () => {
+ it('is one page per gesture, never a stack', () => {
+ expect(tuiScrollPageCount(0)).toBe(0)
+ expect(tuiScrollPageCount(-1)).toBe(0)
+ expect(tuiScrollPageCount(1)).toBe(1)
+ expect(tuiScrollPageCount(12)).toBe(1)
+ expect(tuiScrollPageCount(400)).toBe(1)
+ })
+})
+
describe('tmux control-mode output decoding', () => {
it('decodes octal bytes without corrupting adjacent UTF-8', () => {
const decoded = decodeTmuxControlData('hello\\040世界\\015\\012\\033[31m')
diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.ts
index 7352c58dd..17b82fe73 100644
--- a/cli/src/lib/tmuxStream.ts
+++ b/cli/src/lib/tmuxStream.ts
@@ -25,6 +25,17 @@ const SNAPSHOT_BUFFER_MAX_BYTES = 2 * 1024 * 1024
const SNAPSHOT_QUIET_MS = 8
const SNAPSHOT_QUIET_MAX_MS = 40
const SNAPSHOT_HISTORY_LINES = 500
+/** Grok only exposes PageUp/PageDown while the prompt is focused, so a wheel
+ * burst is one page, never a stack of them. The desktop may still emit
+ * several `terminal_scroll` frames per flick (16ms coalesce on shipped
+ * builds); the interval below drops the extras. */
+const TUI_SCROLL_MIN_INTERVAL_MS = 180
+
+/** How many PageUp/PageDown keys a coalesced wheel burst should become. */
+export function tuiScrollPageCount(lines: number): number {
+ if (!Number.isFinite(lines) || lines <= 0) return 0
+ return 1
+}
const PANE_META_FORMAT = [
'#{session_id}', '#{window_id}', '#{window_panes}', '#{window_width}', '#{window_height}',
'#{pane_width}', '#{pane_height}', '#{alternate_on}', '#{cursor_x}', '#{cursor_y}',
@@ -427,9 +438,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
private snapshotPostCut: Buffer[] = []
private snapshotPostCutBytes = 0
private snapshotLastOutputAt = 0
- // Set by scroll() when it enters tmux copy-mode. Copy-mode swallows keyboard input for its own
- // navigation, so writeRaw() must exit it before the next real keystroke — see writeRaw()'s doc.
- private inCopyMode = false
+ private lastTuiScrollAt = 0
private constructor(
paneId: string,
@@ -586,7 +595,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
}
}
- async snapshot(): Promise<TerminalReadResult<TerminalStreamSnapshot>> {
+ async snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<TerminalReadResult<TerminalStreamSnapshot>> {
return this.serializeOperation(async () => {
if (!this.snapshotGated) return { state: 'failed', reason: 'tmux snapshot gate is not active' }
// -N is required for TUI fidelity: styled blank cells (for example the
@@ -610,7 +619,14 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
// local scrollback. It preserves SGR attributes without replaying old
// TUI cursor movement. Read it before the authoritative visible-grid cut
// so concurrent output is included there or in a post-cut delta.
- const history = meta.alternateOn
+ //
+ // Grok (and any TUI that paints in the normal buffer) is the other
+ // history trap: tmux reports alternate_on=0, so a naive capture would
+ // seed hundreds of prior full-screen repaint frames. The window then
+ // shows stacked empty chrome above the live header, and the wheel
+ // scrolls that junk locally instead of the program.
+ const tuiOwnsScrollback = options?.tuiOwnsScrollback === true
+ const history = (meta.alternateOn || tuiOwnsScrollback)
? Buffer.alloc(0)
: (await this.runControlCommand(
`capture-pane -p -e -N -t ${this.runtime.paneId} -S -${SNAPSHOT_HISTORY_LINES} -E -1`,
@@ -622,10 +638,11 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
this.snapshotPostCutBytes = 0
})
if (!capture.ok) return { state: 'failed', reason: 'tmux snapshot failed' }
+ const screenMeta = tuiOwnsScrollback ? { ...meta, alternateOn: true } : meta
return {
state: 'succeeded',
value: {
- bytes: synthesizeTmuxSnapshot(capture.stdout, meta, history),
+ bytes: synthesizeTmuxSnapshot(capture.stdout, screenMeta, history),
cols: meta.paneWidth,
rows: meta.paneHeight,
},
@@ -654,16 +671,7 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
async writeRaw(bytes: Uint8Array): Promise<TerminalActionResult> {
if (this.closed) return terminalActionNotStarted('terminal stream is closed')
if (bytes.length === 0) return TERMINAL_ACTION_SUCCEEDED
- // scroll() below leaves the pane in copy-mode, which captures all keyboard input for its own
- // navigation. Cancel it before the very next real keystroke, queued ahead of the input chunks
- // (the ControlCommandQueue is strict FIFO) so the pane is back to normal by the time tmux
- // applies them — otherwise the first keystroke after a scroll silently vanishes into copy-mode
- // instead of reaching the program, trading "can't scroll" for "can't type".
const sends: Array<Promise<ControlCommandResult>> = []
- if (this.inCopyMode) {
- this.inCopyMode = false
- sends.push(this.runControlCommand(`send-keys -X -t ${this.runtime.paneId} cancel`))
- }
// Every chunk is handed to the queue before any reply is awaited, so a paste costs one
// round-trip rather than one per chunk. tmux applies them in the order they were written.
for (let offset = 0; offset < bytes.length; offset += INPUT_CHUNK_BYTES) {
@@ -694,23 +702,32 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
: terminalActionNotStarted('tmux paste-buffer could not be sent')
}
- /** Scroll via tmux's own copy-mode rather than writing bytes into the pty. Some remote CLIs (e.g.
- * Claude Code) declare terminal mouse-tracking and correctly handle SGR wheel reports themselves;
- * others declare it but don't (confirmed live for Grok: it echoes the raw escape bytes into its
- * own prompt as literal characters instead of scrolling) — copy-mode works regardless, since it
- * never depends on the program in the pane understanding anything about the bytes at all. */
+ /** Scroll a full-screen TUI by sending PageUp/PageDown into the pty.
+ *
+ * Grok declares mouse-tracking but echoes SGR wheel reports as literal
+ * characters, so the desktop does not send wheel bytes. tmux copy-mode is
+ * the wrong substitute: for an alt-screen TUI, tmux history is prior
+ * full-screen repaint frames, which stacked as empty Grok chrome above the
+ * live screen. Grok's own PageUp/PageDown scroll the conversation even
+ * while the prompt is focused. */
async scroll(direction: 'up' | 'down', lines: number): Promise<TerminalActionResult> {
if (this.closed) return terminalActionNotStarted('terminal stream is closed')
- if (lines <= 0) return TERMINAL_ACTION_SUCCEEDED
- // Idempotent — safe even if already in copy-mode from a previous scroll.
- const entered = await this.runControlCommand(`copy-mode -t ${this.runtime.paneId}`)
- if (!entered.ok) return terminalActionNotStarted('tmux copy-mode could not be entered')
- this.inCopyMode = true
- const command = direction === 'up' ? 'scroll-up' : 'scroll-down'
- const scrolled = await this.runControlCommand(
- `send-keys -N ${lines} -X -t ${this.runtime.paneId} ${command}`,
+ const pages = tuiScrollPageCount(lines)
+ if (pages <= 0) return TERMINAL_ACTION_SUCCEEDED
+ const now = Date.now()
+ if (now - this.lastTuiScrollAt < TUI_SCROLL_MIN_INTERVAL_MS) return TERMINAL_ACTION_SUCCEEDED
+ this.lastTuiScrollAt = now
+ // Leave copy-mode if an older daemon (or a leftover gesture) parked there.
+ // `send-keys -X` fails when the pane is not in a mode; that is the common
+ // case and is ignored. Both commands are queued before either reply so
+ // cancel still runs first (the queue is FIFO) without an extra round-trip.
+ const key = direction === 'up' ? 'PageUp' : 'PageDown'
+ const cancel = this.runControlCommand(`send-keys -X -t ${this.runtime.paneId} cancel`)
+ const scrolled = this.runControlCommand(
+ `send-keys -N ${pages} -t ${this.runtime.paneId} ${key}`,
)
- if (!scrolled.ok) return terminalActionPossiblyExecuted('tmux scroll did not complete')
+ await cancel
+ if (!(await scrolled).ok) return terminalActionPossiblyExecuted('tmux TUI scroll did not complete')
return TERMINAL_ACTION_SUCCEEDED
}