Skip to content

fix(web): manual Reload history action for the tmux repaint gap above live output (#814) - #815

Open
HadrienKerlero wants to merge 12 commits into
Ark0N:masterfrom
HadrienKerlero:fix/814-early-history-repull
Open

HadrienKerlero wants to merge 12 commits into
Ark0N:masterfrom
HadrienKerlero:fix/814-early-history-repull

Conversation

@HadrienKerlero

@HadrienKerlero HadrienKerlero commented Nov 14, 2026 •

Copy link
Copy Markdown

Fixes #814.

Current version (21582a77): eighth review addressed, #814 recipe run live

Same design as b052d686 (folded below): scrolling pulls history only at the top, and the early repair is a manual Reload history action in the existing history banner, on by default and toggleable per device. 73364f8d addresses the third review and fixes two reading-position problems found while testing. ebba82e5 fixes a regression the live #814 run found in 73364f8d (see point 1 and the thread). 408894a3 addresses the fourth review, 0e5170e8 retires Reload history after an answer that is not a full mux capture, afab324b addresses the fifth review, 982a11e3 the sixth, 9f5c6683 the seventh and 21582a77 the eighth (see the thread).

Eighth review, points 1 and 2

  1. Anchor window. _restoreViewportAnchor searches expected - 4000 + rows to expected + rows (same 4,001 candidates, at most 4,064 line reads), so gaps up to 4000 - rows filled below the reader land exactly, including at the scrollback cap.
  2. Stale drop recovery. _resetAllAppState and _cleanupPreviousSession clear _pendingDroppedOutputRecovery next to the recovery timer, so a reconnect's own load does not resume it.

Seventh review

  • Load full history anchor. When the revealed notice's Load full history button is shown in place of Reload history, it now pulls with anchor: 'content' (eligibility read at click time), so the reader keeps their line; otherwise it keeps anchor: 'top'.

Sixth review, points 1 to 3

  1. Drop-recovery shrink fallback. When _onSessionNeedsRefresh falls back to ?tail= because the full capture would shrink the buffer, it adds the session to _historyReloadDismissed past the ownership guard, so a no-history pane is not re-captured by the next tap.
  2. Changeset. Scoped to agent sessions (seen with OMP).
  3. CLAUDE.md. One ⚠️ sentence in the Full-scrollback replay paragraph states the Reload history rules and points to the invariants paragraph.

Also: the terminal-resilience "every replay path clears through that helper" test reads each whole method instead of a 4,000-character window, which point 1's comment had pushed the reset call past.

Fifth review, points 1 to 3

  1. Gated test for the scrollback-cap fix. test/terminal-viewport-marker.test.ts (in npm test) drives the real flushPendingWrites and _restoreTerminalViewport over @xterm/headless 6.0.0 at a full scrollback: the reading row stays on line 140 with the marker and ends on line 160 without it.
  2. Drop-recovery refresh. _onSessionNeedsRefresh clears _liveOutputSinceFullPull and _historyReloadDismissed after replaying a mux-full-history capture, while it still owns the active session and the live-output generation sampled before its fetch is unchanged. The ?tail= fallback never clears them.
  3. Anchor docs. The sentence now matches minimumScore: a viewport with one distinct row matches on that row alone.

Fourth review, points 1 to 3

  1. Reload history during the incoming tab's load. _historyReloadActionEligible() also requires !this.terminalLoadStates?.has(sessionId); selectSession sets that state before it switches activeSessionId. _clearTerminalLoadState() re-syncs the action, so a marked tab offers Reload once its load ends.
  2. Release note. The changeset now covers the flushPendingWrites reading-position change, which applies in every mode with the setting on or off.
  3. Scrollback has a gap right above the live screen until scrolling to the very top triggers a full-history re-pull (OMP session) #814 recipe. Run live; before and after in the thread.

Third review, points 1 to 6

  1. Refused pulls. A pull refused by _replayWouldShrinkBuffer adds the session to _historyReloadDismissed until the next successful mux-full-history replay, so a pane with no tmux history (fullscreen Claude in the alternate screen) stops offering Reload after one refused tap. A tap on a stale button re-checks eligibility before fetching. 73364f8d also required _paneHistoryLines not to be 0; the live run showed that this value is recorded at the last load, so a session first opened empty kept 0 after the burst and never offered Reload. ebba82e5 removes that check.
  2. _isLoadingBuffer. Part of eligibility; _finishBufferLoad re-syncs the action, so a marked tab offers Reload after its own load, not during it.
  3. Byte-history replays. Documented: live-output marking covers only live writes, and a ?tail= replay never marks the session, so that gap relies on the top-of-buffer pull.
  4. Docs. A History Reload Button row in docs/wiki/Settings-Reference.md; docs/wiki/The-Dashboard.md describes Reload history in the same bar and says it is withdrawn after a reload that finds nothing more, as for fullscreen Claude.
  5. Capture cost. About 1 s (1,068 ms median, 100k lines of 120 characters, 12.1 MB) in docs/architecture-invariants.md and the _maybeRefetchFullHistory JSDoc.
  6. × during Loading…. Hides the bar immediately; the pull continues and the bar stays hidden when it settles.

Also fixed

  • Content anchor on repeated TUI furniture. The three-row signature locked onto the nearest copy of an OMP border or status line. The anchor now captures up to 64 visible rows; each distinct row scores at most one point; the best match must cover at least 60% of the distinct rows and be unique in the window, otherwise the old viewport index is kept. Still bounded to 2,000 rows either side (at most 4,064 line reads).
  • Reading position at the scrollback cap. At a full scrollback each live flush trims the oldest rows, and restoring the absolute viewportY moved the reader up on every flush. flushPendingWrites now tracks the row with an xterm marker.

Tests

  • test/shell-scroll-history-pull.test.ts: _isLoadingBuffer and a terminal load state in the eligibility table, and a stale paneHistoryLines: 0 that must not hide the action; clearing the matching load state shows the action; a refused pull retires the action and a stale second tap does not fetch; the action appears when a marked session's load finishes; × during Loading… keeps the bar hidden after the pull; anchor cases for repeated borders, ambiguous copies, a lone distinctive row among blanks and the 50k-row bound.
  • test/history-gap-repair.browser.test.ts: real xterm with OMP-like repaint history (CSI S plus cursor-addressed redraws) at a 50,000-row scrollback cap; the reading row keeps its offset through the replay and a later live flush. A tab switch to a marked session with its capture held open shows no Reload history until the load finishes.
  • Live Scrollback has a gap right above the live screen until scrolling to the very top triggers a full-history re-pull (OMP session) #814 recipe (isolated Codeman servers, tmux 3.4, headless Chromium, a non-shell strip-mux-only session running bash): on master the browser kept a fraction of the 540 lines and only a scroll to the top repaired them; on ebba82e5 Reload history appeared mid-history and one click restored all 540 in order. Numbers in the thread.
  • Real OMP session on a phone and a PC: works as intended on both.

Checks run on 21582a77

  • npm run build, typecheck, lint, format:check, check:frontend-syntax, check:frontend-dead, check:browser-excludes: pass.
  • npm test: 757 files passed, 1 skipped; 17213 tests passed, 13 skipped, 0 failed.
  • npx vitest run --config config/vitest.browser.config.ts test/history-gap-repair.browser.test.ts test/capture-load-window.browser.test.ts: 14/14.

Not done

  • Grid tiles and the split view's second pane keep the top-only pull.

Third version (b052d686): manual Reload history action, no automatic early pull

The design question from the review is answered in the comment on this PR: I drop the automatic early pull. Below is what the current version does. The two earlier versions are folded underneath.

What it does

  1. Scrolling is top-only again. _maybeLoadMoreHistoryOnScroll pulls only when the viewport reaches row 0, as on master (Scrollback in terminal not working #205). The repair branch on any upward scroll is gone, and so is its notice-reveal change. A pull still starts only at the top. After a pull that grows the buffer and puts the reader back below row 0, the notice is now still revealed.

  2. "Reload history" in the existing #historyTruncationBar, on desktop and touch. It is offered when all of these hold:

    • the setting is on;
    • the active session is non-shell and marked (live output since its last mux-full-history replay);
    • the terminal is not at the bottom;
    • no pull is in flight;
    • the session is not detached;
    • the tile grid does not own the terminal.

    A tap runs _maybeRefetchFullHistory({ force: true, anchor: 'content' }), the same explicit-choice path as "Load full history". If the revealed notice already offers "Load full history", no second load control is added. Otherwise "Reload history" is added to the notice, or shown alone with "Recent output may be missing from this view." One × dismisses what the bar carried: the notice for the page, as before, and the reload action until the next successful mux-full-history replay clears the mark.

  3. Setting. "History Reload Button" in Settings > Terminal & Input > Scrolling & rendering (historyReloadAction). It is per device, on by default, wired like terminalWheelLocalScrollback (load, save, stripped from the PUT, in _displaySettingKeySet()), and not in SettingsUpdateSchema.

  4. Kept from 0f890a97:

    • the load opens before the fetch, and every exit flushes the queue;
    • the mark is cleared only on mux-full-history;
    • the content anchor;
    • session-scoped _earlyReplayTravel, which still records travel during a tapped replay.

Second review, points 1 to 5

  1. Button covering the banner: the floating #historyReloadBtn is removed. The action lives inside the banner, so nothing overlaps it.
  2. Sync per scrolled line:
    • _syncHistoryReloadAction() re-renders the banner only when eligibility, the active session or the loading state changes;
    • terminal.onScroll is registered on all devices and coalesced to one requestAnimationFrame per frame;
    • state checks run before isTerminalAtBottom().
  3. i18n: zh-CN entries for the banner message, "Reload history", "Load full history", and the setting's label and description. The text nodes no longer contain a glyph.
  4. z-index 20: removed together with the button, so there is no new layer.
  5. Deferred recovery attempt: _pendingDroppedOutputRecovery is now { sessionId, attempt }, and _finishBufferLoad resumes at that attempt.

Tests

  • test/shell-scroll-history-pull.test.ts:
    • a marked session does not pull mid-history, and still pulls at the top;
    • the eligibility table: setting on and off, shell, at the bottom, unmarked, in flight, tiles, inactive, detached, with desktop and touch both eligible;
    • a tap forces a content-anchored pull and settles out of "Loading…";
    • never two load controls, for the recoverable, exhausted and capped notices;
    • no banner work without a transition, and 100 onScroll calls give one frame;
    • × dismissal until an actual mux-full-history replay;
    • a combined notice: one × dismisses both and scroll frames keep the bar hidden;
    • a notice-only × does not block a later reload action;
    • the deferred recovery resumes at its saved attempt.
  • test/history-notice-reveal.test.ts: the notice is revealed only from a top pull, including when the replay grows the buffer.
  • test/settings-admin-only-ui.test.ts: the setting loads, saves, stays per device and is never sent to the server.
  • test/history-gap-repair.browser.test.ts (Playwright, real xterm, touch and desktop contexts):
    • a repair from mid-history through the banner action, with every line present and contiguous and the reading line at the same offset;
    • output arriving during the download, present exactly once;
    • with a truncation notice also showing, exactly one load control, and elementFromPoint on each banner button returns that button;
    • no action when the setting is off.

Checks run on b052d686

  • npm run build, typecheck, lint, format:check, check:frontend-syntax, check:frontend-dead, check:browser-excludes: pass.
  • npm test: 756 files passed, 1 skipped; 17183 tests passed, 13 skipped, 0 failed.
  • npx vitest run --config config/vitest.browser.config.ts test/history-gap-repair.browser.test.ts test/capture-load-window.browser.test.ts: 12/12.
  • The pre-commit Prettier hook passed. The pre-push static checks were skipped because of an unrelated local build artifact. They are the same checks listed above, already run on this tree.

Not done

  • Not yet watched on a real phone or a real OMP session; the browser test emulates touch.
  • Grid tiles and the split view's second pane (_pullHistory in terminal-tile.js) are unchanged and keep the top-only pull.
Second version (0f890a97): automatic pull on any upward scroll, touch-only floating button

Update: the phone case and the review on this PR

The first version of this PR only repaired the gap when a scroll-up started at the live bottom. On a phone that's not how it's used: you scroll up, keep reading while OMP keeps writing, and a new gap opens below where you are (the case confirmed on #814). The bottom-only trigger never fires there, so on a smartphone the fix did nothing in practice.

The new commit, 0f890a97, changes the trigger to any upward scroll and adds a touch-only reload button. It also addresses the six points of the review on this PR. Each change is described below with what it does, the upside, the downside and what's missing.

What I measured before changing the trigger

These are measurements with plain tmux 3.4 and @xterm/headless 6.0.0 (the version Codeman ships), outside Codeman:

  • 80×24 pane, status off, 40 lines printed slowly then 500 at once. The attached client's stream had many CSI n S (including the full-screen CSI 24 S) and only carried 94 to 268 of the 540 lines. After feeding that stream into xterm with the alt-screen switches stripped (what strip-mux-only does), the browser held baseY 20 to 25. tmux held history_size 517. Only a re-pull from tmux brings those rows back.
  • 200 lines at 20 ms plus in-place redraws (OMP style) sent no CSI S and lost nothing.

I did not switch the trigger to a CSI S burst signal. I only checked that slow output sends none, not that every gap comes with one, so it's not proven as a gap detector. The trigger stays "any live output since the last full pull", the same signal as before.


The changes

1. The buffer load opens before the capture fetch (review point 1)

What it does. _maybeRefetchFullHistory calls _beginBufferLoad() before _fetchTerminalCapture and passes that owner token to chunkedTerminalWrite. Before, the third argument was the session id. Live output arriving while the capture downloads now goes into _loadBufferQueue instead of the old buffer. A replay keeps the existing header-time cutoff (_bufferLoadFinishOpts). Every other exit flushes the whole queue into the untouched buffer through a single finally (_finishBufferLoad(owner, { flushQueued: true, since: 0 })): no buffer, tab switch, bounded-shell skip, downgrade refusal, or catch. A stale owner (a tab switch took over) is a no-op there.

Holding the queue for the whole download has a side effect: in a busy session it can now hit the 128 KiB cap in _onSessionTerminal. A dropped frame calls _scheduleDroppedOutputRecovery, and _onSessionNeedsRefresh refuses to run while _isLoadingBuffer is set. So the recovery could burn its five attempts (2 s apart) against our own open load, and the dropped frames would never come back. It now remembers a pending recovery for the active session without spending an attempt (_pendingDroppedOutputRecovery), and _finishBufferLoad resumes it when the load ends.

Upside. Your scratch test confirmed that rows written during the download used to be wiped by _resetTerminalForReplay(). They're kept now, and appear exactly once. This is the same pattern selectSession already used.

Downside. For the length of the download, live output is held back from the screen instead of written right away. On a slow link and a large capture that's visible as the terminal pausing, then catching up. Drop recovery now has a deferred state, which is one more piece of state in a path that has already had bugs (#464).

Missing. The duplicate window described in _bufferLoadFinishOpts (a batch already pending when the capture ran comes after the headers and is replayed) is unchanged. Its fix belongs on the server.

2. The mark is cleared based on what came back (review point 3)

What it does. Both clears of _liveOutputSinceFullPull now also require source === 'mux-full-history': the scroll re-pull and the tab-switch ?full=1 load. A full=1 that fell back to the byte history (source: 'history') carries the same hole, so it keeps the session marked. The generation check stays, so output newer than the capture also keeps the mark.

Upside. A capture failure no longer passes for a repair.

Downside. If captures keep failing for a session, each later upward scroll asks again (at most every 4 s). Nothing loops on its own; every attempt needs a gesture.

Missing. Nothing known.

3. The repair runs on any upward scroll, not only from the bottom

What it does. _maybeLoadMoreHistoryOnScroll drops the viewportY >= baseY - 2 - |lines| condition. A marked non-shell session now repairs on any upward scroll: mid-history, near the bottom, or at the top, with one pull per gesture. The guards inside _maybeRefetchFullHistory are unchanged: 4 s cooldown, 60 s useless-pull latch, _replayWouldShrinkBuffer, select generation, detached sessions and tiles. An unmarked session still pulls only at the top, as in #205. Shell is unchanged.

anchor: 'bottom' is replaced by anchor: 'content'. Before the reset, _captureViewportAnchor() records the first non-empty row in the viewport, the two rows after it, its offset in the viewport and the distance from the bottom. After the replay, _restoreViewportAnchor() looks outward from the expected row for the nearest 3-row match and puts that row back at the same offset. If none matches it uses the nearest first-row match, and failing that the distance from the bottom. The search is bounded: at most 2,000 rows either side of the expected row, so 4,001 candidates and 12,003 line reads at most.

The partial-history notice: a marked pull started from mid-history doesn't reveal it. A pull whose gesture had reached row 0 does, even if the anchor then moves the viewport off row 0.

Upside. This is the case that was broken on phones: a gap opening below the reader is repaired on the next upward scroll, without going back to the bottom first. The line being read stays where it was, even when recovered rows land below it (keeping the distance from the bottom can't do that, because the bottom moves).

Downside. This widens the cost you raised in the review. In an active session, nearly every upward scroll more than 4 s after the last pull runs an unbounded ?full=1: capturePaneBuffer through execSync over up to 100k lines, about 0.3 s on the event loop for every client and session (docs/architecture-invariants.md). The browser then resets and replays while the user reads. That's now true from anywhere in history, not just from the bottom. The anchor is a text heuristic: on very repetitive TUI output (borders, separator rows, identical status lines) the nearest match can be the wrong copy, and it falls back to the distance from the bottom. The pull can still flicker during the replay.

Missing.

  • No cheaper signal than "any live output". A bounded lines= capture could only work if the replay could splice rather than reset, and _replayWouldShrinkBuffer refuses a short capture today.
  • No check after the fetch to drop a replay the user has scrolled far from.
  • Grid tiles and the split view's second pane (_pullHistory in terminal-tile.js) are untouched and keep the top-only behaviour.
  • Scrollbar drag and keyboard scrolling don't go through this hook and still depend on the top of the buffer.

4. Replay travel is tied to its session (review point 6)

What it does. _earlyReplayTravel is now { sessionId, moves: [] }. Moves are recorded only while that session is active; on another tab they go through the normal path. The finally always resets it.

Upside. After a tab switch takes over an in-flight repair, scrolling on the new tab is no longer swallowed until the old replay settles.

Downside. It's still a single app-level field. That works because one pull at a time is guaranteed by _fullHistoryRepullInFlight.

Missing. Nothing known.

5. "Reload history" button for touch devices

What it does. #historyReloadBtn in index.html: a floating button at the top right of the terminal, at least 44×44 px, aria-label="Reload history", styled in styles.css. It isn't in mobile.css, because that sheet is only loaded below 1024 px and a landscape tablet would get an unstyled button that takes room from the terminal. _syncHistoryReloadButton() alone decides whether it shows. It shows when all of these hold: touch device, non-shell session, viewport not at the bottom, session marked, no tiles, no pull in flight. Tapping it runs _maybeRefetchFullHistory({ force: true, anchor: 'content' }), showing "Loading…" while it runs. The button is updated on terminal scroll (listener registered only on touch devices), when a session is first marked in flushPendingWrites, at the end of a pull, and on tab switch. On a non-touch page the method returns at its first line.

Upside. It gives a phone user a direct way to repair, independent of how they scroll and of the 4 s cooldown (force). It's only shown when there is probably something to recover.

Downside. One more piece of UI over the terminal: it covers part of the top-right rows while it's visible. It shows whenever the session is marked, even if the gap may not exist (same proxy as change 3). force skips the cooldown, so repeated taps each run a full capture on the server; each tap waits for the previous one to finish (disabled, plus the in-flight guard).

Missing. No translation; the label is in English like the rest of the UI. It doesn't hide while the user is actively swiping. Nothing on desktop, by design.

6. Docs and changeset (review point 4)

What it does. docs/architecture-invariants.md (Full-scrollback replay) gets a "Repair while reading (#814)" paragraph covering:

  • the trigger, still guarded;
  • opening the load before the fetch, and the deferred drop recovery;
  • the mux-full-history-only clear;
  • the content anchor and its search bound;
  • the button;
  • the cost.

The JSDoc of _maybeRefetchFullHistory and _maybeLoadMoreHistoryOnScroll no longer says "only at the top" or "on demand rather than automatic". .changeset/814-history-repair-while-reading.md is a patch.

Missing. npx prettier --check docs/architecture-invariants.md flags about twenty spots that were already in the file; I only fixed the one I added. format:check only covers src/**.


Tests (review points 2 and 5)

test/shell-scroll-history-pull.test.ts (VM, mocked xterm). The #814 block is rewritten for the new contract:

  • mid-history pull on a marked session; none on an unmarked one; never on shell;
  • download-time output queued, then replayed on the replay path and flushed on each non-replay path (no buffer, tab switch, refusal, fetch rejection), with _isLoadingBuffer false afterwards;
  • the 128 KiB cap during an open load;
  • the deferred drop recovery, driven through the real scheduler with fake timers across a 20 s download, including a timer that was already armed and a session that's no longer active;
  • the mark kept on source: 'history' and cleared on mux-full-history, for both the scroll pull and the real selectSession;
  • an early replay cancelled by a tab switch: the mark is kept and travel on the new tab isn't swallowed;
  • the content anchor: a match after rows are inserted below; the fallback when nothing matches; 50k-row buffers with only a first-row match or no match, and an exact match beyond the bound, checking that the number of getLine calls stays within it;
  • the button's visibility table, and that a tap calls the forced pull.

test/history-notice-reveal.test.ts: the notice for a marked pull started from the top versus from mid-history.

test/history-gap-repair.browser.test.ts (new, Playwright, real xterm, listed in BROWSER_TEST_GLOBS). It uses a hasTouch/isMobile 390×640 context and trusted CDP touch events (Input.dispatchTouchEvent). Live output goes through the real _onSessionTerminal → batchTerminalWrite → flushPendingWrites path. The burst is shaped like tmux's: CSI 24 S, then a repaint of the last 24 rows, with the middle lines never sent. /terminal is stubbed with a mux-full-history capture. Five scenarios:

  1. Repair from mid-history after a real touch scroll: every line present and contiguous, and the line being read at the same offset.
  2. Output injected while the capture downloads (from inside json()): present exactly once.
  3. The button appears on touch while reading; tapping it brings back the missing lines.
  4. 1280×800 touch context: the button floats, is ≥ 44 px, and the terminal's size doesn't change.
  5. No button in a non-touch context.

This test was flaky at first. The cause was the test setup, not the app: its forced terminal.resize(80, 24) disagreed with the fitted 62×36 container, so the existing resize path (terminal-ui.js, \x1b[3J\x1b[H\x1b[2J on a real size change) cleared the seed rows. The setup now waits for startup, font and render readiness, and a size that holds across frames before it seeds anything. On failure it dumps the state (baseY, queues, load owner, generations). It passed 3 full runs in a row.

Checks run

On this branch, commit 0f890a97:

  • npm run typecheck, lint, format:check, check:frontend-syntax, check:frontend-dead, check:browser-excludes: pass. The pre-push hook passed.
  • npm run build: pass.
  • npm test:
    • Earlier run, before the final fixes: 751 passed, 5 failed out of 757 files.
    • Only one failure came from this change. file-browser-search checks that _activateFileBrowserSession is called right after this.activeSessionId = sessionId; I moved my call one line down, and it passes now.
    • Three are unrelated (tab-layout-editing, webhook-push-glue, webview-sse) and pass on rerun.
    • spreadsheet-preview-worker ("2,000,001 empty runs") also times out on a9a3c6f3 without this commit. The machine was at load 11 to 25 on 4 cores.
    • I haven't rerun the full suite on the exact final commit. Run on it: the targeted files (232 tests, including every file touched here plus terminal-flush-budget, mobile-ime-preview-structure and file-browser-search), and both browser files (7 tests).
  • npx vitest run --config config/vitest.browser.config.ts test/history-gap-repair.browser.test.ts test/capture-load-window.browser.test.ts: 7/7.

Manual check

The same change, ported onto a local 1.51.0 install (with this PR's first two commits under it), passes the same targeted tests and both browser files. It's built into that install. I haven't watched it on a real phone yet. The phone-only behaviour (swipe, button, on-screen keyboard) is covered only by the emulated touch test above. I'll report back after using it.

What's left to decide

The design question from your review is still open, and this commit makes it harder to avoid: is "any live output → unbounded full capture on any upward scroll" an acceptable cost? If not, the cheapest path I see is on the server: serve ?full=1 from an asynchronous capture-pane, or a bounded one with a client-side splice. That would make this trigger much cheaper without changing the client contract. I didn't do it here because it changes the server's hot path.

Original description (first two commits, ede2d9f and a9a3c6f)

Problem

In a non-shell session (seen with OMP), scrolling up from the live screen shows a hole: recent output just above the screen is missing and the rows jump to older history. tmux still holds those rows. When output outpaces tmux's flush interval, tmux repaints the pane rectangle instead of emitting linefeeds, so rows that were on screen get overwritten and never reach xterm's scrollback. The repair for this (#205, _maybeRefetchFullHistory) only runs when the viewport reaches viewportY === 0. The gap sits near the bottom of the buffer, so the user has to scroll past it to the top before the history is fixed.

What this changes

Frontend only: src/web/public/app.js and src/web/public/terminal-ui.js.

  1. A per-session "live output since last full pull" flag. flushPendingWrites sets _liveOutputSinceFullPull and increments _liveOutputGen[sessionId] for every live chunk it writes, but not while _isLoadingBuffer is set, because a replay cannot open a new gap. A full-history replay clears the flag only if the generation has not changed since its capture could have been taken. The scroll re-pull samples the generation before its fetch, because nothing gates live output while the capture downloads. The tab-switch ?full=1 load samples it at the replay, because it already queues live output during its fetch, and it clears the flag only if it completed without falling back to the tail. Live output newer than the capture therefore keeps the session marked, and the next scroll-up pulls again.
  2. An early trigger in _maybeLoadMoreHistoryOnScroll. If the gesture is upward, started at the live bottom (viewportY >= baseY - 2 - |lines|, which allows for the travel scrollLines already applied), the session is not shell and is marked, and no pull or load is running, it calls _maybeRefetchFullHistory({ anchor: 'bottom' }). This hook is only reached from Codeman's own wheel, touch and smooth-scroll routes. Scrollbar drags and keyboard scrolling do not get the early repair, and still depend on the unchanged top-of-buffer path, as before.
  3. anchor: 'bottom' in _maybeRefetchFullHistory. The existing restore keeps the position measured from the top, which is right when the user is at row 0. Here the user is a few rows above the live screen, so the restore keeps the distance from the bottom instead. While the replay runs, the reset buffer cannot scroll. Wheel and touch moves are recorded in order in _earlyReplayTravel and replayed once the replay ends, each clamped to [0, baseY] as it would have been live, so scrolling down to the bottom and back up does not cancel out. That way the gesture is neither lost nor fed into the top-of-buffer path partway through. If that travel reaches the top, the partial-history notice is still shown.
  4. Cleanup: both new maps are cleared with the other per-session state when a session is removed.

The existing guards still apply unchanged: the 4 s cooldown, the 60 s latch after a useless pull, _replayWouldShrinkBuffer, the select-generation check, detached sessions, and tiles.

Why this shape, and what I rejected

  • The issue suggested comparing baseY with _paneHistoryLines. I did not do that. _paneHistoryLines is recorded at tab switch, so it is stale exactly when it matters, after a burst. A fresh #{history_size} would need a probe round trip, and probably a new server route, for every scroll-up. The dirty flag is free and always current. The cost is that it is a coarser proxy (see below).
  • Trying to detect repaint bursts in the stream. The client sees a PTY byte stream, and nothing in it reliably separates "tmux repainted because it fell behind" from a TUI that redraws in place on purpose, which OMP does all the time. Any heuristic for that would be fragile and hard to test.
  • Showing the "Load full history" notice earlier. That still asks the user to act on something that should not happen. It would also mean detecting the gap, which is the same problem as above.
  • Shell is excluded. Shell captures can be many MB, and shell already gets a bounded 1 MiB window on scroll-to-top. An unbounded pull on every first scroll-up would be a regression there.

Downsides and risks

  • The trigger over-fires by design. Any live write marks the session, not just a burst that actually opened a gap. So in practice, in an active Claude, Codex or OMP session, the first scroll-up from the bottom after new output costs an unbounded ?full=1 capture: tmux capture-pane over up to history-limit lines on the server, plus a full reset and chunked replay in the browser. The cooldown limits this to one pull every 4 s, and the flag limits it to once per batch of output. On a long session this is still far more capture traffic than before, when it happened only at the top of the buffer. On mobile data it also costs bandwidth. I think this is the main thing to review.
  • It is visible. The terminal resets and replays right as the user starts scrolling, not after they scroll to the top. On a large history the replay runs over several animation frames, and the buffer briefly shows a partial rewrite. The restore puts the viewport back at the right distance from the bottom, but it can flicker.
  • Repaint-mode panes pay for a useless pull. Where tmux keeps less history than the browser, the pull is refused by _replayWouldShrinkBuffer and latched for 60 s. That is correct, but it still costs one wasted capture per minute per session on scroll-up. The test for this case checks that the buffer is not reset and the flag stays set.
  • The repair is not guaranteed. The early trigger needs the gesture to start at the bottom. If the user scrolls up a little, stops, new output marks the session, and they scroll further, nothing fires early, and the top-of-buffer path is the fallback as before. Scrollbar and keyboard scrolling never trigger it (see item 2).
  • It can still reset while the user reads. The request starts only near the bottom, but a slow capture of a large history can finish after the user has scrolled further and started reading. The reset and replay then happen under them. Their position is restored, counted from the bottom, but the flicker lands mid-read. A check after the fetch could drop the replay in that case. I did not add one, because it would throw away the capture the user scrolled for.
  • _earlyReplayTravel is one app-level field, not per session. It works because only one pull can run at a time (_fullHistoryRepullInFlight) and the finally always resets it. It is still shared state that a future concurrent path could break.

Tests

New describe block in test/shell-scroll-history-pull.test.ts ("early full-history recovery above live output (#814)"). It covers:

  • the first scroll-up after live output pulls once and keeps the distance from the new bottom
  • no second pull without new output
  • travel during an unfinished replay is replayed in order with a clamp after each move: up, down, past the top, and reversals after hitting the bottom and the top
  • live output that lands while the capture downloads keeps the session marked
  • shell never takes the early path
  • no early pull while loading or already pulling
  • the cooldown still applies
  • a refused (shrinking) pull does not reset the buffer and keeps the flag

The shared makeApp fixture now sets viewportY: 0, because the scroll path reads it. The reversal and download-time tests fail on the previous version of this branch and pass now.

These are VM-loaded unit tests with a mocked xterm. They pin the logic but not real xterm behavior during a reset and replay, nor the real buffer-load queue. They do not cover an early replay cancelled by a tab switch, or the tab-switch path clearing the flag. No browser test covers this path. I did not run npm run test:browser.

Run on this branch (based on master @ e99b42c3):

  • npm test (on the first commit): 757 files, 17130 passed, 13 skipped, 1 failed. The failure is frontend-public-tooling.test.ts > runs the public asset check script. It failed because my worktree lacked the gitignored src/web/public/vendor/* bundles that postinstall builds. With those copied in, the file passes 4/4. It is unrelated to this change.
  • After the review follow-up commit: the 33 scroll, history, flush and selection test files pass (778 tests). I did not rerun the full suite on that commit.
  • npm run lint, format:check, typecheck, check:frontend-syntax, check:frontend-dead, check:browser-excludes: pass on both commits. The pre-push hook passed on the second push.
  • npm run build: passes.

Manual verification: not done

The first commit was built into a local 1.51.0 install (Linux, tmux 3.4, OMP 18.20.0, Zen Browser), but I have no recorded before/after observation that it removes the gap. The follow-up commit has not been run in a browser at all. Please treat the behavior as unverified until someone reproduces #814 and checks that the first scroll-up after an OMP burst shows the recent rows without a jump.

…irst scroll-up (Ark0N#814)

A tmux repaint burst overwrites rows that never reach xterm scrollback,
leaving a hole just above the live screen. The Ark0N#205 re-pull only fired at
viewportY 0, so the user had to scroll past the hole first.

Mark a non-shell session dirty on each live write; the first upward scroll
from the bottom of a dirty session runs the existing full-history re-pull
anchored to the bottom, keeping the viewport's distance from live output and
replaying travel made during the replay. Cooldown, downgrade guard and the
top-of-buffer path are unchanged.
…ve (Ark0N#814)

Review follow-up. The early re-pull sampled the live-output generation after
its fetch, but nothing gates live output while the capture downloads, so
output newer than the capture was overwritten and the session marked clean.
Sample before the fetch.

Travel made during the replay was one signed sum clamped once, so scrolling
to the bottom and back up cancelled out. Record moves in order and clamp
after each, as live scrolling does.
@Ark0N

Ark0N commented Nov 14, 2026

Copy link
Copy Markdown
Owner

Thanks for this, Hadrien, and for the careful write-up. The PR repairs the tmux repaint gap from #814 by re-pulling the full tmux history on the first scroll-up from the live screen, instead of waiting until the scroll reaches the top of the buffer.

The open design question

One decision on #814 is still open, and this PR makes it: whether the history repair may fire before the top of the buffer, and on which signal. That has to be settled before more work goes into the code.

The signal here is any live output. flushPendingWrites marks the session on every chunk it writes (src/web/public/terminal-ui.js:4689), which includes spinner ticks, status-line repaints and the echo of what the user types. The generation check then keeps it marked whenever output arrives during the pull. So in a session that is producing output, every scroll-up that starts at the bottom more than 4 s after the last pull runs GET /api/sessions/:id/terminal?full=1. On the server that is capturePaneBuffer running execSync over up to 100k lines of history, and it blocks the event loop for every client and session while it runs (docs/architecture-invariants.md gives about 0.3 s at 100k lines). In the browser it is a reset and a replay of that payload over several frames, just as the user starts reading. The same doc gives this cost as the reason the pull only runs at the top today ("On-demand rather than automatic because at a 100k history limit the capture can be megabytes").

There are narrower options, and picking one is the open part: keep the top-only behaviour, use a stream signal that only fires on a burst (the reproduction on #814 found that tmux sends a full-screen CSI <rows> S and then repaints when it falls behind), or do a bounded early pull, since the gap sits at the bottom of the buffer. Your notes in the PR description on the cost and the over-firing feed straight into that decision.

Code points, if the any-output trigger is kept

  1. Output that arrives during the download disappears from the screen (src/web/public/app.js:9654 and :9751). The pull opens the buffer load only inside chunkedTerminalWrite, after the fetch. Live output that reaches the browser while the capture downloads is written into the old buffer and then cleared by _resetTerminalForReplay(). The capture doesn't contain it, and the since replay in _finishBufferLoad only covers the queue opened later. Your comment at app.js:9648 keeps the session marked for this case, but the rows are still missing on screen, right above the prompt, which is the Scrollback has a gap right above the live screen until scrolling to the very top triggers a full-history re-pull (OMP session) #814 symptom. I confirmed this with a scratch test that drives the real _maybeRefetchFullHistory, batchTerminalWrite, flushPendingWrites and chunkedTerminalWrite into @xterm/headless. With the change below patched in, the same test keeps the line. The fix is to open the load before the fetch, the way selectSession does (app.js:10195): call _beginBufferLoad() before _fetchTerminalCapture, pass that owner to chunkedTerminalWrite, and on every return that does not replay (no buffer, tab switch, bounded skip, downgrade refusal, catch) call _finishBufferLoad(owner, { flushQueued: true, since: 0 }). Please add a test for the 128 KiB queue cap in _onSessionTerminal (app.js:2564), since a long download in a busy session now queues there.
  2. Run it in a browser. The new tests load the methods in a VM with a mocked xterm and a mocked chunkedTerminalWrite, so they can't see the reset and replay, and point 1 is that kind of problem. CONTRIBUTING asks that changes have been run, so please reproduce Scrollback has a gap right above the live screen until scrolling to the very top triggers a full-history re-pull (OMP session) #814 before and after in a non-shell session (the recipe on the issue: 40 lines printed slowly, then 500 at once) and add a browser test in the style of test/capture-load-window.browser.test.ts.
  3. Clear the mark based on what came back, not on what was requested (src/web/public/app.js:9764 and :10440). When the capture fails, the route still answers full=1, with the byte history and source: 'history', and that carries the same hole. Please key both clears on source === 'mux-full-history'.
  4. Docs. docs/architecture-invariants.md:254 (Full-scrollback replay) still says other modes re-pull "at the TOP" and "on demand rather than automatic", and so does the JSDoc of _maybeRefetchFullHistory (app.js:9586) and _maybeLoadMoreHistoryOnScroll (terminal-ui.js:4053). These change along with whichever trigger is accepted.
  5. Tests for the tab-switch half (src/web/public/app.js:10440). The select path's clear and an early replay cancelled by a tab switch have no tests, as your description says.
  6. A small one: _earlyReplayTravel (src/web/public/terminal-ui.js:4067) isn't tied to its session. After a tab switch supersedes an early replay, moves on the new tab are swallowed until the old replay settles. Storing the session id with the moves, and only pushing while that session is active, fixes it.

Typecheck, lint, format, the frontend syntax and dead-code checks, and the full test suite (17134 tests) pass on this branch, and 9 of the new tests fail on master as intended.

The trigger question is open, so the PR stays as it is for now. The code points above only apply if the any-output trigger is kept.

…utput, add a phone reload control (Ark0N#814)

Review follow-up on Ark0N#815, and the phone case from Ark0N#814: the gap opens
below a reader who stays scrolled up while output arrives, and the
bottom-only trigger never fired there.

- Open the buffer load before the capture fetch so output arriving during
  the download is queued and replayed, not wiped by the reset. Every
  non-replay exit flushes the queue. A drop at the 128 KiB cap during an
  open load is deferred and resumed when the load ends instead of
  spending its retries against it.
- Clear the live-output mark only when the response is
  source 'mux-full-history', on the scroll and tab-switch paths.
- Repair on any upward scroll in a marked non-shell session, not only
  from the bottom. A content anchor (3-row signature, searched at most
  2000 rows either side) keeps the row being read in place; no match
  falls back to distance from the bottom.
- Tie replay travel to its session so a tab switch does not swallow
  moves on the new tab.
- Reveal the partial-history notice when the initiating gesture
  reached the top, even if the anchor moved the viewport off row 0.
- Touch-only Reload history button (#historyReloadBtn), styled in
  styles.css so wide touch viewports get it too. Non-touch pages skip
  its work entirely.
- Docs, JSDoc and a changeset. Unit tests, and a Playwright browser test
  with trusted touch events and real xterm.

Fixes Ark0N#814
@HadrienKerlero HadrienKerlero changed the title fix(web): recover the tmux repaint gap above the live screen on the first scroll-up (#814) fix(web): repair the tmux repaint gap above live output on any upward scroll, with a phone reload control (#814) Nov 16, 2026
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N I've updated the PR with your recommandations + ported the fix for mobile

@Ark0N

Ark0N commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Thanks for the update, Hadrien, and for writing out the upside and downside of each change. This revision repairs the tmux repaint gap from #814 on any upward wheel or touch scroll in a non-shell session that has had live output since its last full capture. It holds the line being read in place with a content anchor and adds a touch-only "Reload history" button.

All six code points from the earlier review are addressed. The load opens before the fetch and every exit flushes the queue, the mark is cleared only on mux-full-history, replay travel is tied to its session, the docs and JSDoc follow the new trigger, and the tab-switch half and the 128 KiB cap have tests. 39 of the new unit tests fail against master's frontend code. Here, test/history-gap-repair.browser.test.ts passes, and so do typecheck, lint, format and the frontend checks.

The open design question

The question from the earlier review is still open, and this commit widens it: whether the history repair may run before the top of the buffer, and on which signal. With this commit, once the 4 s cooldown has passed, any upward scroll anywhere in a session that has had live output since its last full pull runs an unbounded ?full=1. That is a synchronous capture-pane that blocks the server's event loop for every client (about 0.3 s at 100k lines), followed by a reset and replay in the browser while the user is reading. In an active session the next spinner tick marks the session again, so this covers nearly every upward gesture, and on desktop it also covers TUIs without mouse tracking. Your description already sets out this trade-off and the server-side alternatives (an asynchronous capture, or a bounded one with a client splice). That decision has to be made before the rest of the PR can move.

Code points

The first two come from the Reload history button. Both were confirmed in a real Chromium page.

  1. The button covers the partial-history banner's buttons (src/web/public/styles.css:4405, src/web/public/terminal-ui.js:4060). Both sit at the top right of .terminal-wrap, and the button (z-index 20) is drawn over the end of .history-trunc-bar (z-index 6). With both visible, document.elementFromPoint at the centre of the banner's "Load full history" and × buttons returns #historyReloadBtn, at 390×640 and at 1280×800 with touch. The two show together when a marked session is scrolled to the top while its history state is still truncated. That happens after a full capture that hit the byte cap (a long session, where the × is the banner's only control, so the banner can no longer be dismissed), after a pull that failed, or on a gesture inside the cooldown or the 60 s latch after a tab switch replayed a tail. Please hide the button while #historyTruncationBar is visible (add bar.hidden to the visibility test and call _syncHistoryReloadButton() from _renderHistoryTruncationBanner()), or place it below the banner, and add an assertion for it to the browser test.

  2. The onScroll sync runs once per scrolled line and rewrites the button each time (src/web/public/terminal-ui.js:1064 and :4060). xterm 6.0 fires onScroll for every line a write scrolls (476 events for one 500-line write in @xterm/headless). Each call looks up the button, assigns a new onclick closure and sets textContent, which replaces the text node even when nothing changed. The body-wide MutationObserver in i18n.js then processes each of those changes. On a 390×640 touch page, a 2,000-line live burst made 1,957 calls and 1,957 mutations on the hidden button. Under 4x CPU throttling, a 50,000-line chunkedTerminalWrite replay (the first ?full=1 load of a tab) took 3.8 to 4.9 s with the hook and 2.5 s with it stubbed. Please make the sync idempotent (cache the element, return when nothing changed, write hidden, disabled and the label only on transitions, assign onclick once) and coalesce the onScroll calls to one per animation frame. Keep the listener itself, since it is what sees scrollbar drags.

Smaller ones:

  1. src/web/public/index.html:480: "Reload history" has no zh-CN entry in src/web/public/i18n.js. The arrow glyph inside the text node also keeps a 'Reload history' key from ever matching, because the translator looks up the whole text. Please move the glyph into an aria-hidden span or a CSS ::before and add entries for the label and the aria-label.
  2. src/web/public/styles.css:4409: z-index 20 is a new layer. Please add it to the z-index stack in src/web/CLAUDE.md and in docs/architecture-invariants.md (Z-index layers).
  3. src/web/public/terminal-ui.js:5097: a deferred drop recovery resumes at attempt 0, so one deferred at attempt 3 starts its count over. If the intent is "without spending an attempt", carry the attempt number with _pendingDroppedOutputRecovery.

Next

The trigger question is open, so the PR stays as it is for now. Points 1 to 5 apply as long as the Reload history button and this recovery path are part of it.

Ark0N#814)

- Scrolling pulls tmux history only at the top of the buffer again (Ark0N#205);
  the automatic pull on any upward scroll is removed.
- Reload history lives in the existing #historyTruncationBar on desktop and
  touch, shown for a marked non-shell session scrolled away from live output.
  It never duplicates Load full history; one × dismisses what the bar carried.
- New per-device setting historyReloadAction (Terminal & Input > Scrolling &
  rendering), default on, kept out of SettingsUpdateSchema.
- Eligibility sync is transition-only and onScroll is coalesced per frame.
- Remove the floating #historyReloadBtn and its z-index 20 layer.
- Deferred dropped-output recovery resumes at its saved attempt.
- zh-CN entries for the new strings; docs and changeset updated.
@HadrienKerlero HadrienKerlero changed the title fix(web): repair the tmux repaint gap above live output on any upward scroll, with a phone reload control (#814) fix(web): manual Reload history action for the tmux repaint gap above live output (#814) Nov 16, 2026
@HadrienKerlero

HadrienKerlero commented Nov 16, 2026 •

Copy link
Copy Markdown
Author

@Ark0N, thanks for the second review. Here is my answer to the design question, and the PR is reworked to match (b052d686).

Decision: no automatic early pull. The early repair is a manual action.

Before answering I measured the tmux side: tmux 3.4 on a private socket, attached through node-pty the way Codeman does (xterm-256color, status off, window-size manual, history-limit 100000), the same alt-screen stripping as strip-mux-only, replayed into @xterm/headless 6.0.0, with a unique ID on every emitted line.

Workload Lost, 80×24 Lost, 195×51 CSI n S sent
40 slow lines, then 500 at once (the #814 recipe) 500 490 yes
OMP-like: 300 lines at 20 ms with in-place footer redraws 0 0 no
300k-line flood ~98k ~99k yes
Same burst in a split (half-width) pane 517 490 no
Burst inside an app-set scroll region (DECSTBM) 500 492 yes
2,000 slow lines 0 0 no

client_discarded stayed at 0 in every run, so the tty_block_maybe drain path never fired here.

Cost on 100k lines of 120 characters:

Capture Size Wall time (median of 5)
capture-pane -p -e -J -S -100000 12.1 MB 1,068 ms
capture-pane -p -e -J -S -2000 248 KB 29 ms

Writing the 12 MB capture into headless xterm took another 0.56 s.

What I take from it:

  • The cost you raised is real, and higher than the docs say on long lines: about 1 s of blocked event loop per pull, not 0.3 s. "Any live output → unbounded full capture on any upward scroll" is too expensive as a default.
  • CSI n S is a good gap signal for full-width panes, but not a complete detector. A split pane lost everything without one, because tmux redraws the region instead of scrolling (tty_redraw_region, tty.c:1969). In a split pane a full capture only reads the active pane anyway. These were seq-style workloads, not real OMP output, so I haven't measured how often real OMP output sends it.
  • A bounded capture is about 37× cheaper, but it needs a replay that can splice instead of reset, and a new contract for _replayWouldShrinkBuffer. That doesn't belong in this PR.

So the PR now does this:

  1. Automatic pulls are top-only again, exactly as on master (Scrollback in terminal not working #205). Scrolling no longer starts a pull before the top of the buffer.
  2. A manual "Reload history" action, inside the existing #historyTruncationBar, on desktop and mobile. It is offered while a non-shell session is scrolled up and has had live output since its last mux-full-history capture. A tap runs _maybeRefetchFullHistory({ force: true, anchor: 'content' }), the same explicit-choice path as "Load full history". The only new full captures are explicit taps; the top-of-buffer pull is unchanged.
  3. A per-device setting to turn it off: Settings > Terminal & Input > Scrolling & rendering > "History Reload Button" (historyReloadAction). It is on by default and kept out of SettingsUpdateSchema, like terminalWheelLocalScrollback.
  4. The correctness fixes stay:
    • the load opens before the fetch, and every exit flushes the queue;
    • the mark is cleared only on mux-full-history;
    • the content anchor, since a tap can come from mid-history;
    • the session-scoped _earlyReplayTravel, so scrolling during a tapped replay isn't lost.

Your second review, points 1 to 5

  1. Covering the banner: the floating button is gone. The action is a button inside the banner, so it can't overlap the banner's controls. When the notice already offers "Load full history", no second load control is added.
  2. onScroll per line: the sync is transition-only (no DOM work unless eligibility, the session or the loading state changes). onScroll is coalesced to one requestAnimationFrame per frame.
  3. i18n: zh-CN entries for the new strings, and no glyph in the text nodes.
  4. z-index 20: removed together with the button, so there is no new layer.
  5. Deferred recovery attempt: _pendingDroppedOutputRecovery carries { sessionId, attempt }, and the recovery resumes at that attempt.

On b052d686:

  • build, typecheck, lint, format and the frontend checks pass;
  • npm test: 17183 passed, 13 skipped, 0 failed;
  • the two browser files pass 12/12, including history-gap-repair.browser.test.ts in both touch and desktop contexts.

The PR description has the details; the earlier versions are folded underneath.

Possible follow-ups, your call and not in this PR: a bounded capture with a client-side splice would make an automatic early repair affordable. A CSI S handler could make the action more prominent when a full-width gap is likely.

@Ark0N

Ark0N commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Thanks for the third round, Hadrien, and for the tmux measurements in the thread. This revision keeps scrolling top-only as on master and adds a manual Reload history action to the existing history banner, together with the content anchor, the load opened before the fetch, the mux-only clear and a per-device setting.

You addressed every point from both earlier reviews. Typecheck, lint, format, the frontend checks, the full test suite (17183 tests) and both browser files pass here, and 52 of the new unit tests fail against master's frontend code as intended.

Needs a fix

  1. Reload history stays on offer where the pull is always refused, and each tap is a full capture (src/web/public/app.js:9908, refusal path at :9745). _historyReloadActionEligible() checks neither _paneHistoryLines nor a refused pull. Take a capture that is thinner than the browser buffer, for example a repaint-mode pane in the alternate screen with history_size 0, such as fullscreen Claude scrolled locally with Shift+wheel or terminalWheelLocalScrollback. _replayWouldShrinkBuffer refuses it and marks the history exhausted, but _liveOutputSinceFullPull stays set, so the button comes straight back. The tap passes force: true, which skips the 60 s latch, so every tap is another unbounded ?full=1: a synchronous capture-pane that blocks the server for every client (about 1 s at 100k lines by your own measurement). In your makeScrollApp harness the action is eligible before and after the refused reload, three taps send three /terminal?full=1 requests, and it is still eligible with _paneHistoryLines set to 0. The partial-history notice already hides for paneHistoryLines === 0 for this reason. Please require this._paneHistoryLines?.get(sessionId) !== 0, stop offering the action after a refused content pull (clear the mark or add the session to _historyReloadDismissed on that refusal), update the test at test/shell-scroll-history-pull.test.ts:476, and add a test that a second tap after a refusal fetches nothing.

Smaller ones

  1. src/web/public/app.js:9908: the eligibility check ignores _isLoadingBuffer, but _maybeRefetchFullHistory returns at once while it is set. selectSession re-renders the banner right after it switches activeSessionId (:10121), and the snapshot restore can leave the viewport off the bottom. A tab that was marked earlier can therefore show Reload during its own load, and a tap there does nothing. Please add !this._isLoadingBuffer.
  2. src/web/public/terminal-ui.js:4720: a replay of the server's byte history (?tail=) is the same tmux client stream that carried the repaint, so it can hold the gap as well, yet it never marks the session. If an agent bursts in a background tab and then goes idle, the user finds the gap on return and no Reload is offered. Please either mark a non-shell session when a non-capture replay lands, or note in the docs paragraph that this case relies on the top-of-buffer pull.
  3. docs/wiki/Settings-Reference.md (Terminal & Input table) needs a row for History Reload Button, and docs/wiki/The-Dashboard.md:241 still says the history notice only appears at the top and never for fullscreen Claude.
  4. docs/architecture-invariants.md:256 puts the capture cost at about 0.3 s. Your 1,068 ms measurement is the better figure to cite.
  5. src/web/public/app.js:10009: pressing × during Loading… leaves the bar up until the pull ends. Hiding it on × (or disabling × while loading) would match the click.

Open question

One design point is still open, and it is not something to change in this round. The action ships ON by default and keys on any live output, so in a working session the bar appears on nearly every scroll-up, covers the top rows being read and is announced by aria-live, while your measurements show that slow output loses nothing. It is undecided whether it stays ON by default, ships OFF, or is offered only after a burst signal such as a full-screen CSI n S. Point 1 needs fixing either way.

Once 1 to 4 are in, the PR is ready for another review. If you can try the #814 recipe (40 slow lines, then 500 at once) in a real non-shell session, please post the before and after in the thread.

…0N#814)

- Reload history requires pane history and no buffer load in flight; a
  downgrade-refused pull hides it until the next mux-full-history replay,
  and a stale tap re-checks eligibility before fetching.
- x during Loading... hides the bar at once; the pull continues.
- The content anchor scores up to 64 visible rows, so repeated TUI borders
  cannot outvote the row being read; ambiguous matches keep the viewport.
- Live flushes track the reading row with an xterm marker across
  scrollback trimming at the cap.
- Docs: Settings-Reference row, Dashboard notice text, ~1 s capture cost,
  byte-history replays rely on the top-of-buffer pull.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, thanks for the third review. The PR is updated (73364f8d).

Points 1 to 6

  1. Reload offered where the pull is always refused. _historyReloadActionEligible() now requires _paneHistoryLines not to be 0, so a pane with no tmux history (fullscreen Claude in the alternate screen, scrolled locally) never shows Reload. A pull refused by _replayWouldShrinkBuffer also adds the session to _historyReloadDismissed, so the action stays hidden until the next successful mux-full-history replay, and a tap on a stale button re-checks eligibility before it fetches. A refused pull can no longer be repeated by tapping.
  2. _isLoadingBuffer. Added to the eligibility check, and _finishBufferLoad re-syncs the action, so a marked tab offers Reload once its own load finishes, not during it.
  3. Byte-history replays. I took the docs option: the "Repair while reading" paragraph now says that live-output marking covers only live writes, and that a ?tail= replay (a burst in a background tab, for example) never marks the session, so that gap relies on the top-of-buffer pull.
  4. Docs. docs/wiki/Settings-Reference.md has a History Reload Button row. docs/wiki/The-Dashboard.md describes Reload history in the same bar and says it is not offered for panes with no tmux history, such as fullscreen Claude.
  5. Capture cost. docs/architecture-invariants.md and the JSDoc of _maybeRefetchFullHistory now give about 1 s (1,068 ms median for capture-pane -p -e -J -S -100000 over 100k lines of 120 characters, 12.1 MB).
  6. × during Loading…. × now hides the bar immediately. The pull in flight continues, and the bar stays hidden when it settles.

Two other fixes found while testing

  • Content anchor on repeated TUI furniture. The three-row signature locked onto the nearest copy of an OMP box border or status line rather than the text being read. The anchor now captures up to 64 visible rows, and each distinct row scores at most one point, so repeated borders cannot outvote a distinctive tool result. The match must cover at least 60% of the distinct rows and be unique in the window; otherwise the old viewport index is kept. The search is still bounded to 2,000 rows either side (at most 4,064 line reads).
  • Reading position at the scrollback cap. When xterm's scrollback is full, every live flush trims the oldest rows, and the absolute viewportY that flushPendingWrites restored moved the reader up on each flush. The flush now tracks the reading row with an xterm marker, which follows the trim.

Tests

  • test/shell-scroll-history-pull.test.ts: paneHistoryLines: 0 and _isLoadingBuffer in the eligibility table; a refused pull retires the action and a second tap on the stale button does not fetch; the action appears once a marked session's load finishes; × during Loading… hides the bar and keeps it hidden after the pull; the new anchor cases (repeated borders, ambiguous copies, a lone distinctive row among blanks, the 50k-row bound).
  • test/history-gap-repair.browser.test.ts: a new case in real xterm with OMP-like repeated repaint history (CSI S plus cursor-addressed redraws) at a 50,000-row scrollback cap. The reading row keeps its offset through the Reload replay and through a later live flush.

On 73364f8d:

  • typecheck, lint, format and the frontend checks pass;
  • npm test: 756 files passed, 1 skipped; 17193 tests passed, 13 skipped, 0 failed;
  • test/history-gap-repair.browser.test.ts: 11/11.

I haven't yet run the #814 recipe in a real non-shell session; I'll post the before and after in the thread when I have.

Open question: on by default

I'd keep it on by default. Without this action, the only way to see output that has fallen outside the screen is to scroll all the way up to the top of the buffer, every time, to trigger the full-history pull. That is the #814 symptom itself: the history looks broken until you find that workaround. A default-off action would leave most users with that, and they wouldn't know there is a setting to change. The bar only appears while you are scrolled up in a session that has had output since its last full capture, and anyone who finds it in the way can turn it off per device in Settings > Terminal & Input > History Reload Button.

Ark0N#814)

- _historyReloadActionEligible() no longer reads _paneHistoryLines: it is
  recorded at the last load, so a session first opened empty kept 0 after
  the burst that opens the gap, and the action never appeared (found by the
  live Ark0N#814 recipe).
- A pane with no tmux history is still retired by the downgrade refusal,
  which dismisses the action until the next mux-full-history replay.
@Ark0N

Ark0N commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Thanks for the fourth round, Hadrien, and for answering the default question directly. This revision keeps the manual Reload history action in the history banner and closes the points from the third review. It also makes the content anchor hold up against repeated TUI borders, and an xterm marker now keeps the reading row in place at the scrollback cap.

Every point from the third review is in. Typecheck, lint, format, the frontend syntax, dead-code and browser-excludes checks, the full test suite (17,192 tests) and both browser files (13 tests) pass here. 13 of the new unit tests and the new browser case at the 50k cap fail against b052d686, as they should.

Needs a fix

  1. Reload history still shows for the incoming tab during its load (src/web/public/app.js:10130 and :10139, eligibility at :9910). selectSession syncs and renders the banner right after it switches activeSessionId, before _beginBufferLoad at :10271. At that point _isLoadingBuffer is still false, isTerminalAtBottom() reads the outgoing tab's buffer, and nothing re-renders the banner when the load opens. If you were scrolled up in one tab and switch to a marked tab, the bar shows for that tab's whole load. In Chromium, with the incoming capture taking 1.5 s, the bar read "Recent output may be missing from this view. Reload history ×" at 50, 400 and 1,000 ms while _historyReloadActionEligible() returned false, and it hid once the load finished. Tapping it in that window only hides it. Please keep the action off while the session has a terminal load state, for example by adding !this.terminalLoadStates?.has(sessionId) to _historyReloadActionEligible() (selectSession sets that state at :10117, before the switch) and calling this._syncHistoryReloadAction?.() from _clearTerminalLoadState() (:6688) after the delete. Please also add the case to the eligibility table in test/shell-scroll-history-pull.test.ts and an assertion to test/history-gap-repair.browser.test.ts.

Smaller ones

  1. .changeset/814-history-repair-while-reading.md doesn't mention the reading-position fix in flushPendingWrites (src/web/public/terminal-ui.js:4712). That change runs on every live flush while scrolled up, in every mode, even with the setting off, so it should get a sentence in the release note.
  2. The Scrollback has a gap right above the live screen until scrolling to the very top triggers a full-history re-pull (OMP session) #814 recipe (40 lines printed slowly, then 500 at once) still hasn't been run in a real non-shell session. The browser test stubs /terminal, so a real capture through Reload history hasn't been exercised end to end. Please post the before and after in the thread.

Open question

The default is still undecided: Reload history could ship ON keyed on any live output, ship OFF, or be offered only after a burst signal such as a full-screen CSI n S. Thanks for laying out your case for ON. Here is one more measurement for that decision, from Chromium. After a successful Reload (mark cleared, bar hidden), a single in-place redraw of the status row (\r\x1b[2K* Thinking (1s), no new line) marks the session again and brings back "Recent output may be missing from this view." with the Reload button (src/web/public/terminal-ui.js:4754). So in a working agent session the bar comes back right after each use, and its sentence reports missing output in the cases your tmux measurements show lose nothing (slow output and in-place redraws). This isn't a change request for this round.

Next

Point 1 is the only code fix this round needs, and points 2 and 3 are small. The default question above is still open.

@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, here is the #814 recipe run live, before and after, as you asked.

Setup

  • Real Codeman servers on isolated instances (CODEMAN_INSTANCE, own data directory and tmux socket), tmux 3.4, a managed headless Chromium tab at 1280×800, real wheel input. Nothing mocked.
  • Master e99b42c3 against this branch.
  • The session is a custom CLI entry running bash. Custom entries are kind: 'agent' with altScreen: 'strip-mux-only', the same stream handling as OMP, so this is a non-shell session without spending model tokens.
  • The session is selected and its first load finishes before the recipe runs, and the tab stays on it throughout:
for i in $(seq 1 40); do echo slow-$i; sleep 0.1; done; seq -f burst-%g 1 500
  • Counts come from capture-pane -p -S - on the isolated socket (tmux) and from every row of app.terminal.buffer.active (browser). A line counts only if the whole row is slow-N or burst-N.

Results

Run tmux holds Browser after the burst After the repair
master all 540 slow-1–9, burst-470–500; 10–40 and 1–469 missing scrolling to the very top pulled the full history: all 540, in order
branch 73364f8d all 540 10–40 and most of 1–469 missing no Reload history button (see below)
branch ebba82e5 all 540 slow-11–20 and most of burst-8–468 missing Reload history shown mid-history; one click restored all 540, in order, with nothing missing

The gap size differs from run to run, since it depends on how tmux samples the burst. Either way the browser kept a fraction of the 540 lines while tmux held all of them, and a mid-history wheel scroll on master shows rows jumping from slow-9 straight to burst-470.

A bug the run found, now fixed

On 73364f8d the button never appeared in this exact scenario: _liveOutputSinceFullPull was set, but _paneHistoryLines was 0. That value is recorded at the session's last load, and a session first opened empty records 0 before the burst that opens the gap. The !== 0 check I added for review point 1 therefore hid the action in the very case it exists for. A run where the pane held 100 lines before the first load did show the button, and one click there restored all 540 lines with the reading row (seed-56) still at the top.

ebba82e5 removes that check. The case from point 1 is still covered by the other half of the fix: a pane that really keeps no history (fullscreen Claude) captures one screen, _replayWouldShrinkBuffer refuses it, and the refusal dismisses the action until the next mux-full-history replay. The test table now asserts that a stale paneHistoryLines: 0 does not hide the action. The docs paragraph says the cached size is deliberately not consulted.

The reading position on that run

The top visible row was burst-7 before the click and burst-9 after. Before the reload, the browser showed burst-7 directly followed by burst-10, because 8 and 9 were in the gap. The anchor matched the 31 rows from burst-10 down and kept them where they were, so the two recovered rows were inserted above them. Most of what was on screen stayed in place, and the recovered lines appeared just above it.

After the reload, scrolling to the bottom and back up with no new output did not bring the button back, since the mark had been cleared.

Checks on ebba82e5

  • build, typecheck, lint, format and the frontend checks pass;
  • test/shell-scroll-history-pull.test.ts and test/history-notice-reveal.test.ts: 97/97;
  • test/history-gap-repair.browser.test.ts: 11/11;
  • npm test: 756 files passed, 1 skipped; 17193 tests passed, 13 skipped, 0 failed.

On a real OMP session

I also tested the fix with a real OMP session, on my phone and on my PC, and it works as intended on both.

…#814)

- _historyReloadActionEligible() also requires no terminal load state:
  selectSession sets it before switching activeSessionId, so the sync
  right after the switch no longer offers Reload for the loading tab.
- _clearTerminalLoadState() re-syncs the action, so a marked tab offers
  Reload once its load ends.
- Changeset: note the reading-position fix for live flushes at the
  scrollback cap.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, thanks for the fourth review. The PR is updated (408894a3).

Point 1: Reload history during the incoming tab's load

Fixed as you suggested:

  • _historyReloadActionEligible() now also requires !this.terminalLoadStates?.has(sessionId). selectSession sets that state before it switches activeSessionId, so the sync and render right after the switch no longer offer Reload for the tab being loaded.
  • _clearTerminalLoadState() calls _syncHistoryReloadAction() after it deletes the state, so a marked tab offers Reload once its load has ended, without waiting for a scroll.
  • docs/architecture-invariants.md lists the new condition.

Tests:

  • test/shell-scroll-history-pull.test.ts: a loadState row in the eligibility table (hidden), and a test that clearing the matching load state alone shows the button.
  • test/history-gap-repair.browser.test.ts: a new case in a real page. The user is scrolled up in one session, and a second, marked session has its /terminal response held open. The test switches to it with selectSession and checks that #historyTruncationBar is hidden and has no Reload history button while the fetch is pending. It then releases the response and checks that the load finishes and the capture is on screen. With the terminalLoadStates check removed, this case fails while the incoming session's load state is fetching and _isLoadingBuffer is true.

Point 2: release note

.changeset/814-history-repair-while-reading.md now has a sentence on the flushPendingWrites change: while you are scrolled up, new output no longer moves the text you are reading once the terminal's scrollback is full, in every session type, whether or not the Reload history setting is on.

Point 3: the #814 recipe

Posted just after your review, in this comment. It has the live before and after: real isolated Codeman servers, real tmux captures through Reload history, no stubbed /terminal. It also covers my own test on a real OMP session, on a phone and a PC.

Checks on 408894a3

  • build, typecheck, lint, format and the frontend syntax, dead-code and browser-excludes checks pass;
  • npm test: 756 files passed, 1 skipped; 17195 tests passed, 13 skipped, 0 failed;
  • test/history-gap-repair.browser.test.ts and test/capture-load-window.browser.test.ts: 14/14.

- A content-anchored reload answered by anything but mux-full-history (an
  empty response, or the byte-history fallback for a blank or failed pane
  capture) adds the session to _historyReloadDismissed until the next mux
  replay; only a mux replay clears the mark, so each tap repeated a forced,
  unbounded capture. An error envelope leaves it available.
- Only the request still current (active session and select generation)
  may dismiss: a slow answer from before an A -> B -> A switch must not
  retire the action a newer capture already cleared.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, one follow-up on top of 408894a3, from a review of my last two commits (0e5170e8).

When ebba82e5 removed the cached paneHistoryLines !== 0 check, it left one way for Reload history to come straight back after every tap: an answer to the manual reload that is not a full mux capture. That is an empty response, or the byte-history fallback the route returns when the pane capture is blank or failed (source: 'history'). None of those reached the downgrade refusal, and only a mux-full-history replay clears the mark. In a pane with no tmux history and a blank frame, every tap would have run another forced, unbounded capture.

  • _maybeRefetchFullHistory now retires the action (_historyReloadDismissed) when a content-anchored reload is answered by anything but mux-full-history, until the next mux replay. A transient error envelope (success: false) leaves it available, since a retry can succeed.
  • The dismissal applies only to the request that is still current (activeSessionId and the select generation). A slow answer from before an A → B → A switch cannot retire the action after a newer capture of A has cleared it.
  • docs/architecture-invariants.md describes both rules.

Tests in test/shell-scroll-history-pull.test.ts: a byte-history fallback and an empty response each retire the action, an error envelope does not, and a fallback that arrives after an A → B → A switch leaves it available. With the guard disabled, the first two fail; without the session and generation check, the third fails.

On 0e5170e8: build, typecheck, lint, format and the frontend checks pass; npm test: 756 files passed, 1 skipped; 17199 tests passed, 13 skipped, 0 failed; both history browser files: 14/14.

@Ark0N

Ark0N commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Thanks for the fifth round, Hadrien, and for running the #814 recipe live with real captures. This revision keeps Reload history off while the incoming tab loads, adds the reading-position fix to the release note, and retires the action when a manual reload comes back with anything but a full mux capture.

Every point from the fourth review is in. Typecheck, lint, format, the frontend syntax, dead-code and browser-excludes checks, the full test suite (17,199 tests) and both history browser files (14 tests) pass here. Two of the new tests from 0e5170e8 fail against 408894a3, as they should.

Small ones

  1. The scrollback-cap fix has no test in npm test (src/web/public/terminal-ui.js:4716). The marker path runs on every live flush while scrolled up, in every session mode. The vm harnesses mock xterm without registerMarker, so they take the old branch, and the only test that reaches the new code is test/history-gap-repair.browser.test.ts, which the gate excludes. The fix itself is right. In @xterm/headless 6.0.0 (10 rows, scrollback 100, 200 lines, reading line 140), five flushes of four lines end on line 160 with master's absolute restore and stay on line 140 with the marker. Please add a small gated test that drives flushPendingWrites over @xterm/headless at a full scrollback, the way test/terminal-osc52-clipboard.test.ts drives chunkedTerminalWrite.
  2. The drop-recovery refresh leaves the session marked (src/web/public/app.js:3531). _onSessionNeedsRefresh resets and replays a ?full=1 capture for every non-shell session, but it clears neither _liveOutputSinceFullPull nor _historyReloadDismissed. Right after a recovery has re-pulled the whole history, the bar still offers Reload, and a tap repeats the same forced capture. Please clear both there when the answer is mux-full-history and a live-output generation sampled before that fetch is unchanged, as _maybeRefetchFullHistory does. If this path should keep the mark, say so in the invariants paragraph instead.
  3. docs/architecture-invariants.md:256 says the best anchor match "must cover at least two distinct rows", but minimumScore (src/web/public/terminal-ui.js:4048) takes Math.min(frequencies.size, ...). A viewport with one distinct row therefore matches on that row alone, and the test at test/shell-scroll-history-pull.test.ts:974 relies on that. Please make the sentence match the code.

Open question

The default is still undecided: Reload history can ship ON keyed on any live output, ship OFF, or be offered only after a burst signal such as a full-screen CSI n S. Points 1 to 3 do not depend on that answer.

Next

Points 1 to 3 are the only changes this round needs.

)

- _onSessionNeedsRefresh samples the live-output generation before its
  fetch and, after replaying a mux-full-history capture, clears
  _liveOutputSinceFullPull and _historyReloadDismissed while it still owns
  the active session and the generation is unchanged; the ?tail= fallback
  never clears them.
- test/terminal-viewport-marker.test.ts: gated test driving the real
  flushPendingWrites over @xterm/headless at a full scrollback; the reading
  row holds with the marker and drifts without it.
- Docs: the anchor sentence matches minimumScore, and the refresh rule is
  in the Repair while reading paragraph.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, thanks for the fifth review. The PR is updated (afab324b).

Point 1: a gated test for the scrollback-cap fix

New test/terminal-viewport-marker.test.ts, in npm test, in the style of test/terminal-osc52-clipboard.test.ts. It runs constants.js and terminal-ui.js in a vm against a real @xterm/headless 6.0.0 terminal, with the real flushPendingWrites and _restoreTerminalViewport. It uses your setup: 10 rows, scrollback 100, 200 lines, reading line 140, then five flushes of four lines, each awaited through xterm's write callback.

  • With the marker path, the top row is still line 140.
  • With registerMarker hidden (the absolute restore), it ends on line 160, matching your measurement. The test asserts both, so it fails if the marker path regresses.

Point 2: the drop-recovery refresh clears the mark

_onSessionNeedsRefresh now samples the live-output generation before its fetch. After replaying the capture, it clears _liveOutputSinceFullPull and _historyReloadDismissed and re-syncs the action, under the same rule as _maybeRefetchFullHistory:

  • the answer is mux-full-history;
  • the generation sampled before the fetch is unchanged;
  • the refresh still owns the active session.

The ?tail= fallback, used when the full capture would shrink the buffer, never clears them. The invariants paragraph says so.

Tests in test/shell-scroll-history-pull.test.ts:

  • a mux-full-history answer clears both;
  • a history answer keeps the mark;
  • live output during the fetch keeps it;
  • the tail fallback keeps it;
  • a session switch or a lost refresh owner during the replay keeps it.

The first one fails with the clear removed.

Point 3: the anchor sentence

docs/architecture-invariants.md now matches minimumScore. The best match must score at least 60% of the distinct rows and at least two of them, capped at the number of distinct rows. A viewport with one distinct row (a lone tool result among blanks) therefore matches on that row alone, as the test at test/shell-scroll-history-pull.test.ts:974 expects.

Checks on afab324b

  • build, typecheck, lint, format and the frontend syntax, dead-code and browser-excludes checks pass;
  • npm test: 757 files passed, 1 skipped; 17207 tests passed, 13 skipped, 0 failed;
  • test/history-gap-repair.browser.test.ts and test/capture-load-window.browser.test.ts: 14/14.

Open question: the default

For me this question is already answered. Without this button, the history isn't reliable: after a burst, part of what the agent printed is simply not in the browser, and the only way to see it is to scroll all the way to the top of the buffer every time. That's the #814 problem itself, and on a phone it's often not practical at all. Having history you can actually trust and read outweighs the downsides of the bar coming back after use, including after status-line redraws when nothing was lost. Anyone who finds it in the way can turn it off per device. So I'd keep it on by default.

@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks for the sixth round, Hadrien, and for the gated marker test. This revision clears the Reload mark after a drop-recovery capture, adds test/terminal-viewport-marker.test.ts to npm test, and brings the anchor sentence in the invariants paragraph in line with minimumScore.

All three points from the fifth review are in. Typecheck, lint, format, the frontend syntax, dead-code and browser-excludes checks, the full test suite (757 files, 17,207 tests) and both history browser files (14 tests) pass here. The new drop-recovery test fails against 0e5170e8, as it should, and the marker test's negative control ends on line 160.

Small ones

These don't depend on the open question below.

  1. src/web/public/app.js:3508: when the drop-recovery refresh falls back to ?tail= because the full capture would shrink the buffer, Reload history stays on offer. _maybeRefetchFullHistory retires the action on the same signal (:9781). On a pane with no tmux history, the next tap therefore runs one more forced full capture before its own refusal retires it. Please add the session to _historyReloadDismissed in that branch, under the same active-session and refresh-owner checks as the new clear, and add a row for it to the drop-recovery tests.
  2. .changeset/814-history-repair-while-reading.md:5 says "above live OMP output", but the action covers every non-shell session (Claude, Codex, OpenCode and the rest). Please reword it, for example to "in agent sessions (seen with OMP)".
  3. The Full-scrollback replay paragraph in the root CLAUDE.md:229 doesn't mention Reload history. Please add one warning sentence there that points to the invariants paragraph and states the rules this PR settled: only a mux-full-history replay with an unchanged live-output generation clears the mark, a refused or non-mux answer to a manual reload retires the action, and the buffer load opens before the fetch.

Open question

The default for Reload history is still open. The options are to ship it ON keyed on any live output, ship it OFF, or offer it only after a burst signal such as a full-screen CSI n S. Thanks for making your case for ON again. That's a product decision, not a code question, and it hasn't been made yet.

Next

Every code point from the earlier reviews is addressed, and the three small ones above are the only code changes needed this round. The default is the one open item left.

…rk0N#814)

- _onSessionNeedsRefresh adds the session to _historyReloadDismissed when
  the full capture would shrink the buffer and it falls back to ?tail=,
  past the ownership guard, so a no-history pane is not re-captured by
  the next tap.
- Changeset: scope the note to agent sessions (seen with OMP).
- CLAUDE.md: one warning sentence on the Reload history rules.
- terminal-resilience test reads each whole method instead of a
  4,000-character window.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, thanks for the sixth review. The PR is updated (982a11e3).

Point 1: the drop-recovery fallback retires Reload history

When _onSessionNeedsRefresh falls back to ?tail= because the full capture would shrink the buffer, it now adds the session to _historyReloadDismissed and re-syncs the action. That is the same refusal signal _maybeRefetchFullHistory retires on. It happens only past the existing ownership guard, so only while the refresh still owns the active session. A pane with no tmux history therefore no longer gets one more forced full capture from the next tap.

Two rows in the drop-recovery tests in test/shell-scroll-history-pull.test.ts:

  • the shrink fallback retires the action, while the live-output mark stays set;
  • a fallback whose refresh lost its owner during the tail fetch does not retire it.

The first one fails with the new branch disabled. The invariants paragraph mentions the rule next to the clear.

Point 2: changeset wording

.changeset/814-history-repair-while-reading.md now reads "missing terminal history above live output in agent sessions (seen with OMP)".

Point 3: CLAUDE.md

The Full-scrollback replay paragraph has one ⚠️ sentence on Reload history that points to the invariants paragraph and states the three rules:

  • only a mux-full-history replay with an unchanged live-output generation clears the mark and dismissal;
  • a refused or non-mux answer to a manual reload retires the action;
  • the buffer load opens before the fetch.

Also changed

test/terminal-resilience.test.ts ("every replay path clears through that helper") read the first 4,000 characters of _onSessionNeedsRefresh and checked that _resetTerminalForReplay() was in them. Point 1's comment pushed that call to character 4,320, so the full suite failed on a method that is still correct. The test now reads the whole method, up to the next method, the way methodSource does in test/shell-scroll-history-pull.test.ts, so a later comment can't break it again.

Open question

Understood that the default is a product decision and yours to make. My view hasn't changed since my last comment, and I'm happy to switch the default if you decide otherwise.

Checks on 982a11e3

  • build, typecheck, lint, format and the frontend syntax, dead-code and browser-excludes checks pass;
  • npm test: 757 files passed, 1 skipped; 17208 tests passed, 13 skipped, 0 failed;
  • test/history-gap-repair.browser.test.ts and test/capture-load-window.browser.test.ts: 14/14.

@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks for the seventh round, Hadrien. This PR repairs the tmux repaint gap from #814 with a manual Reload history action in the history banner, which re-pulls the full tmux history and keeps the line you are reading where it was.

The three points from the sixth review are all in:

  • the drop-recovery shrink fallback retires Reload history (src/web/public/app.js:3528), with tests for both ownership cases;
  • the changeset is scoped to agent sessions;
  • root CLAUDE.md has the warning sentence.

Typecheck, lint, format, and the frontend syntax, dead-code and browser-excludes checks pass here, and so do the full test suite (757 files, 17,208 tests) and both history browser files (14 tests). With the refusedFullCapture block removed, the new fallback test fails, which is what it should do.

One small one

src/web/public/app.js:10025: when the revealed partial-history notice already offers Load full history, the bar shows that button instead of Reload history (:10016 and :10030), as the invariants paragraph describes. That button still calls _maybeRefetchFullHistory({ force: true }) with the default anchor: 'top', so after the replay the reader lands on the old row 0 (:9849-9853) instead of the row they were reading.

The notice stays revealed until a downward scroll reaches live output. Someone who reached the top, scrolled partway back down and then got new output is shown this button, where Reload history would have kept their place.

Please make two changes:

  • pass the content anchor when the reload action is eligible, for example this._maybeRefetchFullHistory({ force: true, anchor: eligible ? 'content' : 'top' });
  • assert the anchor argument in the recoverable row of never duplicates the %s notice load control (test/shell-scroll-history-pull.test.ts:1213).

Open question

The default for Reload history hasn't been decided. The options are:

  1. ship it ON, keyed on any live output, as the code does now;
  2. ship it OFF;
  3. offer it only after a burst signal such as a full-screen CSI n S.

That is a product decision, and it has not been made yet. The anchor point above doesn't depend on it.

Next

The default is the one open item. The anchor fix is the only code change this round asks for.

… Reload (Ark0N#814)

- The notice's Load full history button pulls with anchor 'content' when
  Reload history is eligible (read at click time, since the bar only
  re-renders on eligibility transitions) and keeps 'top' otherwise.
- Tests: the single load control asserts the content anchor; an
  ineligible session keeps the top anchor.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, thanks for the seventh review. The PR is updated (9f5c6683).

Load full history keeps the reader's line when Reload is eligible

src/web/public/app.js: the notice's Load full history button now passes anchor: 'content' when Reload history is eligible, and keeps anchor: 'top' otherwise. That's the case you described, where it's shown in place of Reload history.

I read eligibility at click time (this._historyReloadActionEligible()), not from the eligible value captured at render. The bar only re-renders when eligibility changes, so a value captured at render can be out of date by the time of the click. The scenario you gave is one example: the reader reached the top, scrolled partway back down, and then new output arrived.

Tests in test/shell-scroll-history-pull.test.ts:

  • never duplicates the %s notice load control now clicks the single load control and asserts force: true, anchor: 'content'. The recoverable row fails with the old top anchor.
  • A new case checks that an unmarked session (Reload not eligible) still gets { force: true, anchor: 'top' } from Load full history.

The invariants paragraph describes the rule.

Open question

Noted that the default is still your decision.

Checks on 9f5c6683

  • build, typecheck, lint, format and the frontend syntax, dead-code and browser-excludes checks pass;
  • npm test: 757 files passed, 1 skipped; 17209 tests passed, 13 skipped, 0 failed;
  • test/history-gap-repair.browser.test.ts and test/capture-load-window.browser.test.ts: 14/14.

@Ark0N

Ark0N commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Thanks for the eighth round, Hadrien. This PR repairs the tmux repaint gap from #814 with a manual Reload history action in the history banner, which re-pulls the full tmux history and keeps the line you are reading in place.

The point from the seventh review is in: Load full history now pulls with the content anchor when Reload history is eligible (read at click time), and the new test pins both anchors. Typecheck, lint, format, and the frontend syntax, dead-code, browser-excludes and public-asset checks pass here. So do the full test suite (757 files, 17,209 tests) and both history browser files (14 tests).

Two small ones

  1. The content anchor loses the reader at the scrollback cap when the gap is wider than 2,000 rows (src/web/public/terminal-ui.js:4049-4050). The search window is centred on the old distance from the bottom (:4036). Every row Reload fills in below the reader moves the reader's row one row up from that point, so once the gap passes 2,000 rows the match falls outside the window and the code keeps the old absolute index (:4032). That index is right as long as the top of the buffer stays put. At xterm's scrollback cap, though, the replay trims the top by the same number of rows, and the reader lands that many rows further down. Running the real _captureViewportAnchor and _restoreViewportAnchor in a vm over a capped buffer, gaps of 500 and 1,900 rows land exactly, while gaps of 2,500 and 10,000 rows land 2,500 and 10,000 rows off. Your own measurements show a large flood losing about 98k rows, so a long session can get there. Filled rows only ever move the reader's row up, and a capture with fewer rows below moves it down by at most the one screen the downgrade guard tolerates. So please:

    • shift the window up at the same budget, for example first = expected - 4000 + rows and last = expected + rows (rows being this.terminal.rows), which keeps the 4,001 candidates and the 4,064 line reads;
    • add a capped-buffer case with a gap above 2,000 rows to content anchors hold the reader through a history repair in test/shell-scroll-history-pull.test.ts;
    • say in the "Repair while reading" paragraph of docs/architecture-invariants.md what happens to a gap beyond the window.

    With that window the same run lands gaps up to 3,900 rows exactly, and your existing anchor cases still pass.

  2. A deferred drop recovery survives a reconnect reset (src/web/public/app.js:5010 and :9497). _resetAllAppState and _cleanupPreviousSession cancel an armed recovery with _clearTimer('_clientDropRecoveryTimer') but leave _pendingDroppedOutputRecovery set. After an SSE reconnect that lands back on the same session, the restore's own _onSessionNeedsRefresh reload ends its load, _finishBufferLoad picks up the stale recovery, and two seconds later a second full capture and replay runs. Please clear _pendingDroppedOutputRecovery next to both _clearTimer calls.

Open question

The default for Reload history is still open. The options are:

  1. ship it ON, keyed on any live output, as the code does now;
  2. ship it OFF;
  3. offer it only after a burst signal such as a full-screen CSI n S.

That is a product decision, and it has not been made yet. Points 1 and 2 above do not depend on it.

Next

Points 1 and 2 are the only code changes this round asks for. The default is the one open item.

…coveries (Ark0N#814)

- _restoreViewportAnchor searches expected - 4000 + rows .. expected + rows
  (same 4,001 candidates / 4,064 reads): filled rows only move the reader
  up, so gaps up to 4000 - rows land exactly, also at the scrollback cap.
- _resetAllAppState and _cleanupPreviousSession clear
  _pendingDroppedOutputRecovery next to the recovery timer, so a reconnect
  load does not resume a stale recovery and run a second full capture.
- Tests: capped 2,500- and 3,900-row gaps; both real cleanup methods drop
  the pending recovery. Docs: the window and the beyond-window fallback.
@HadrienKerlero

Copy link
Copy Markdown
Author

@Ark0N, thanks for the eighth review. The PR is updated (21582a77).

Point 1: the anchor window leans up

_restoreViewportAnchor (src/web/public/terminal-ui.js) now searches from expected - 4000 + rows to expected + rows, with rows being this.terminal.rows. It's the window you suggested: the same 4,001 candidates and at most 4,064 line reads. Filled rows below the reader only move their row up, and a capture with fewer rows below moves it down by at most the one screen the downgrade guard tolerates. So gaps up to 4000 - rows now land exactly, including at the scrollback cap.

Tests in content anchors hold the reader through a history repair:

  • New: a capped 10,000-row buffer, reader on line 6000 with a 30-row screen, gaps of 2,500 and 3,900 rows filled below the reader while the top is trimmed by the same amount. Both land on line 6000. Both fail with the old centred window.
  • keeps the old viewport when two complete contexts match equally well placed its second exact copy 6 rows below the expected row. That's outside the new window, which only reaches one screen below, so the test was no longer testing ambiguity. I moved both copies inside the window; it still asserts the old viewport is kept.

The "Repair while reading" paragraph describes the window. It also says what happens to a wider gap: the match falls outside, the restore keeps the old absolute index, and at the cap that lands the reader the whole gap below their line.

Point 2: a deferred recovery no longer survives a reset

_resetAllAppState and _cleanupPreviousSession now set _pendingDroppedOutputRecovery = null next to _clearTimer('_clientDropRecoveryTimer').

New test in test/shell-scroll-history-pull.test.ts, one case per method. It runs the real method with an explicit fixture and a recovery pending for the active session. It checks the recovery is gone, then finishes a load on the same tab through the real _beginBufferLoad / _finishBufferLoad, the way the reconnect's own refresh would, and checks that no recovery is scheduled. With the two new lines removed, both cases fail.

Open question

Noted that the default is still your decision.

Checks on 21582a77

  • build, typecheck, lint, format and the frontend syntax, dead-code and browser-excludes checks pass;
  • npm test: 757 files passed, 1 skipped; 17213 tests passed, 13 skipped, 0 failed;
  • test/history-gap-repair.browser.test.ts and test/capture-load-window.browser.test.ts: 14/14.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scrollback has a gap right above the live screen until scrolling to the very top triggers a full-history re-pull (OMP session)

2 participants