Pane viewport scrolls up and snaps back while agent panes produce output

[mkpoli]

Is this a reproducible bug?

• I confirm this is a reproducible bug, not a feature request, idea, question, contribution proposal, or direction check.
• I reproduced this bug on the version and environment reported below using the exact steps provided.

Current behavior

While agent panes are producing output, the pane viewport jumps on its own: the content scrolls up by several lines and then snaps back down to the bottom. I am not touching the mouse or the keyboard when it happens. The movement is purely vertical, with no width change or reflow.

It shows up in almost any pane, and it is most obvious when Claude Code prints a permission prompt or a selection menu. It happens more often the more agent panes are working at the same time, and I stop noticing it when only one or two agents are active.

The same behavior was reported in #2521, which was closed for not following the template.

Expected behavior

The viewport stays where it is while a pane prints new output.

Reproduction

1. Open a session with roughly 14 workspaces and Claude Code running in roughly 16 panes.
2. Leave four or more of those agents working at the same time.
3. Watch any pane where Claude Code prints a permission prompt or a selection menu.
4. The viewport scrolls up a few lines and then snaps back to the bottom.

Impact

It is hard to read agent output while it arrives. When I am reviewing what an agent did, the jump moves the text I am reading, and I lose my place and have to scroll back. With several agents running it happens often enough to interrupt reviewing throughout the day.

Environment

• Herdr version: 0.8.0
• Update channel (stable or preview): stable
• Operating system: Windows 11, WSL2, Ubuntu 22.04.5 LTS
• Terminal: Windows Terminal
• Shell, if relevant: fish
• Relevant config, if any: ui.pane_scrollbars at its default of true, experimental.pane_history = true

[onsails]

Additional OMP-specific evidence from a currently affected pane:

Environment

• Herdr 0.8.0
• OMP 17.2.12
• Linux, TERM=xterm-256color, HERDR_ENV=1
• Pane wX:p1

Live state

While scrolling appeared ineffective, herdr pane get wX:p1 reported:

"scroll": {
  "max_offset_from_bottom": 2581,
  "offset_from_bottom": 0,
  "viewport_rows": 52
}

The pane therefore had substantial retained history, but remained at the live bottom while OMP was producing output.

Input routing

This does not look like leaked child mouse tracking. OMP was on its normal screen with no fullscreen overlay. Herdr's routing for this state is WheelRouting::HostScroll, which calls rt.scroll_up(...) in src/app/input/mouse.rs. OMP does not receive the wheel event.

Output pattern

OMP performs frequent in-place repaint writes during active turns, even when it is not appending ordinary prose. Examples include its loader animation (roughly one frame per 80 ms) and cursor/changed-row repaint sequences. The repaint path ends in terminal.write(...) in OMP's TUI.

Herdr passes each PTY batch to core.terminal.write(...) in src/pane/terminal.rs::process_pty_bytes(). The observed behavior is that a wheel scroll briefly changes the viewport, then a subsequent PTY repaint returns offset_from_bottom to 0. When OMP becomes idle and repaint traffic stops, scrolling starts working again. This explains why the failure appears intermittent or "hung" for the duration of an active turn.

I also checked OMP's runtime log during the affected period. There were no ui.loop-blocked watchdog events, so this was not OMP's event loop failing to process input.

Potential minimal regression shape for Herdr: create primary-screen scrollback, set offset_from_bottom > 0, then feed a cursor-position/in-place row rewrite PTY batch without appended lines. Assert that offset_from_bottom remains nonzero. Existing pane_scrollback_controls_round_trip_and_clamp_without_ui_interference and resize preservation tests do not appear to cover PTY repaint writes while already scrolled.

[CodeSmile-0000011110110111]

Was just about to report the same issue. I'll add to the report with some details from my end:

Current Behaviour

• The agent has to be idle (not actively writing output)
• There has to be enough content already printed to allow for vertical scrolling
• After activating/selecting an agent view, the viewport starts scrolling upward on its own after a short delay, typically within 1-5 seconds. It scrolls up for about 3-5 seconds, then returns to the bottom.
• When left alone, the "scroll-up and back down" behaviour repeats indefinitely (after a short pause)!
• It does not need many agents! It happens with just two for me.
• It is 100% reproducible, every idle agent.
• Using Claude.

Environment

• Herdr version: 0.8.0
• Update channel (stable or preview): git clone https://github.com/herdrdev/herdr is what i can say for certain
• Operating system: Windows 11 (build 10.0.26200.8875), WSL 2.6.3.0, running Ubuntu 24.04.4 LTS (Noble Numbat) inside WSL2
• Terminal: /bin/bash (output of echo $SHELL)
• Relevant config, if any: no scroll-follow or idle-redraw-related setting anywhere in Herdr's config

[mkpoli]

Environment detail for this report: Windows Terminal hosting a Linux herdr build under WSL2 (Ubuntu 22.04.5), herdr 0.8.0 stable, fish.

Cross-terminal data point: the original reporter in #2521 saw the same behavior on macOS through Warp and through the Moshi mobile client on the same session, so it is not tied to one terminal emulator.

[mkpoli]

Shorter reproduction, no plugin needed. Against an idle agent pane on the alternate screen holding more history than the requested line count:

herdr agent read <pane-id> --source recent-unwrapped --lines 500 --format text

The pane scrolls upward in steps and then returns to the bottom while the command runs. It took 11.87s here.

herdr pane read on the same pane does the same thing and takes the same time:

agent read  --source recent-unwrapped --lines 500 --format text    11.87s   (pane scrolls)
pane  read  --source recent-unwrapped --lines 500 --format text    11.88s   (pane scrolls)
pane  read  --source recent-unwrapped --lines 500 --format ansi     0.00s
pane  read  --source visible          --lines 500 --format text     0.01s

Two things to watch for when measuring. A read issued while a harvest is already pending on that terminal returns immediately from a frozen snapshot rather than starting its own, and a pane whose retained rows already reach the requested count does not harvest either, so repeat timings against the same pane are not comparable and each measurement needs a pane that has not just been read. And a read of a working agent returns agent_not_idle immediately without moving the pane, so only idle agents show it.

On my machine these reads were being issued continuously by an installed plugin that indexes panes on pane.agent_status_changed with a short debounce, which is why it looked spontaneous and repeated indefinitely.

[mkpoli]

Where the movement comes from, since the reproduction above shows it but does not say why.

The scroll is herdr's own. src/server/alt_screen_read.rs captures an alternate-screen agent's history by injecting real wheel events into the pane — send_wheel(runtime, MouseEventKind::ScrollUp, WHEEL_STEP_EVENTS, &snapshot) driving Phase::Harvest → merge_scrolled_up → restore, bounded by MAX_DURATION 15s at STEP_SETTLE 120ms. That is the ~12s up and snap back. The refusal message for a busy agent already describes the design: "its alternate-screen history can only be captured by scrolling while idle".

alt_screen_read_spec in src/server/headless.rs selects it for Method::AgentRead, and for Method::PaneRead when intent == ReadIntent::Interactive. It returns early when format != ReadFormat::Text or the source is not Recent/RecentUnwrapped, which is why --format ansi and --source visible return instantly and leave the pane alone.

The part that seems worth surfacing: ReadIntent derives Default with #[default] Interactive, and intent is #[serde(skip)] on PaneReadParams, so a pane.read arriving over the socket always deserializes as interactive. ReadIntent::Passive is set only from in-process callers (src/api/wait.rs, src/api/subscriptions.rs). An API client has no way to ask for a read that does not move the pane, other than by changing format or source. src/api/schema/tests.rs asserts this default.

The remaining gates explain why it looks intermittent rather than constant: a known agent in Idle state, alternate screen, wheel routing of MouseReport, and a requested line count above the rows already retained. Panes failing any of those return in well under a second and never move.

So anything that polls panes re-triggers it. In my case a plugin indexing on pane.agent_status_changed at 500 lines kept every idle agent's viewport moving; pointing its reads at a non-text format stopped it, and the panes have been still for a day since.

One measurement note that cost me a while: api_request_completed emits info! only when outcome != "ok", otherwise debug!, so successful reads never appear under the default herdr=info filter. Server logs at the default level show nothing during a harvest — timing a read, or HERDR_LOG=herdr=debug and grepping alternate-screen read, is what actually shows it.

[mkpoli]

Note for anyone tracking this: brchue-ux#145 (merged in that fork, not upstream) fixes a synchronized-output tearing race under this same symptom description. It is a real problem and its measurements are convincing, but it does not cover what I reported above, so this issue should not be closed by it.

That fix addresses a frame in which the viewport never actually moved — herdr repainting a pane while its child sits mid-DEC-2026 batch, corrected on the next frame.

What the reproduction in my earlier comment shows is a viewport that does move: alt_screen_read.rs sends real ScrollUp wheel events into the pane and restores it afterwards, taking 11.87s on an eligible pane. That is not a rendering artifact and no repaint-timing change affects it.

The two also select opposite panes. The tearing race needs a pane actively producing output; the wheel harvest refuses any non-idle agent with agent_not_idle and only ever fires on idle ones.

So the reports here may be two distinct causes sharing a description. The macOS/Warp report in #2521 involved actively working panes, which the harvest cannot explain and the tearing race can. Mine were idle agents being read at 500 lines, which is the reverse. Stopping those reads stopped my jumping entirely, and has held for a day.