fix(terminal): load a shell from tmux's rendered history, not the byte recording

[timkjr]

A shell's automatic loads (tab select, dropped-output recovery, clear terminal, a split/grid tile's load) replayed session.terminalBuffer, the raw PTY recording. That recording holds full-screen repaints (an ssh'd tmux, less, any TUI) drawn for the pane height of the moment. Replayed into a terminal with fewer rows, each repaint's last newline pushes its top row into scrollback, so one line tmux holds once shows up dozens of times (26 copies in the case that found this, after the pane went from 24 to 23 rows). Remote SSH shells hit it constantly, since their inner tmux repaints often.

• Shells now load a bounded window of tmux's rendered history instead (SHELL_LOAD_QUERY: full=1&tail=1MiB&lines=10000), the same source the scroll-to-top pull from fix(terminal): let a Shell pane's scroll-up reach tmux history #494 already uses. Agent sessions are unchanged.
• lines=10000 bounds the synchronous capture-pane: measured at ~8 ms per 1000 lines, so ~0.1 s here vs ~0.8 s for a 100k-line history.
• That bound is shallower than xterm's scrollback, so the server now reports the cut. The capture's existing display-message query also reads #{history_size} (PaneCaptureOptions.capturedHistorySize), and the route marks a full capture truncated / 'tail' when tmux holds more than it read. The banner keeps offering Load full history and scroll-to-top keeps pulling older lines. The byte cap still reports 'capped', and keeps precedence.
• The banner no longer names an amount it cannot know ("less than 1 KB more") for a line cut; it says "Earlier output may still be retained".

Testing: route, capture, banner, flush-budget and tile tests updated/added; typecheck, lint, frontend syntax, format check and the full suite green on this branch. Running on my own deployment.

[Ark0N]

Thanks a lot for this, @timkjr, and welcome to Codeman. The PR moves a shell's automatic loads (tab select, dropped-output recovery, clear, a tile's load) off the raw PTY byte recording and onto a bounded window of tmux's rendered history, and has the server report when that line bound left older lines behind. The diagnosis of the repaint duplication is spot on, the measurements hold up (I got about 98 ms for a 10,000-line capture and 463 ms for 60,000 lines on tmux 3.4), and the full suite plus the static checks are green. A few things need changing before it can go in.

1. Nested-tmux shells lose their scrollback on every automatic load (src/web/public/constants.js:128, used at src/web/public/app.js:3215, :3316, :9341 and src/web/public/terminal-tile.js:775)

Remote SSH cases and Docker cases run the shell inside a second tmux (tmux -L codeman-remote on the host, or the in-container tmux), and that tmux's client puts the local pane into the alternate screen. tmux keeps no history for a pane in the alternate screen, so capture-pane -S -10000 returns one screen plus whatever the pane held before ssh attached. I reproduced it on tmux 3.4 with private sockets: after 300 lines inside a nested tmux the outer pane reported alternate_on=1 and history_size 29 (unchanged from before nesting), and the capture held 22 of the 300 lines.

The route returns a full capture on its own (src/web/routes/session-routes.ts:3143), and the shell paths skip the _replayWouldShrinkBuffer downgrade guard. So a tab switch, a drop recovery, a clear or a tile load now replaces the browser's scrollback with a single screen. truncated stays false (tmux reports almost no history), so no banner shows, and the scroll-to-top pull reads the same empty history. Before this PR those loads replayed the byte recording, which still carried the scrollback; it was only duplicated after a height change. The same happens in a local shell where someone runs tmux or ssh -t host tmux by hand.

Ask: add #{alternate_on} to the same display-message query that now reads #{history_size}, and keep the old tail= byte-recording load for a shell whose pane is in the alternate screen (decided in the route, or returned as a flag the client falls back on). Please add a route test for that branch. If you would rather fix the duplicates for nested shells in another way, say so here first, because that changes the trade-off for the remote case you mention in the description.

2. An unbounded full capture is reported as a 'tail' cut (src/web/routes/session-routes.ts:3172)

captureHistoryLines() always returns a number (the configured tmuxHistoryLimit when lines is absent), so the historyLimitLines !== undefined check never filters anything. On tmux older than 3.7, lowering the history limit only changes the global default, and live panes keep their deeper history. Every ?full=1 on such a pane, including the one Load full history sends, now comes back truncated: true, truncationReason: 'tail', and the banner offers a button that can never return more. I confirmed it with a throwaway route test (history_size 50,000, limit 10,000, ?full=1). Ask: only report the cut when the bound came from the client and is shallower than the ceiling (captureOpts.historyLimitLines < tmuxHistoryLimit && capturedHistorySize > captureOpts.historyLimitLines), with a test case for a request without lines.

3. Two docs still describe the old shell load (CLAUDE.md:279, docs/architecture-invariants.md:212)

Both say shell selection and drop recovery load "a bounded 1 MiB ?tail=". Please update them to SHELL_LOAD_QUERY, the new 'tail' report for a lines= cut, and the reason (repaints replayed at another height). CLAUDE.md is excluded from Prettier on purpose, so edit it by hand and do not run prettier --write on it.

Smaller things (fine to fold in, or I can do them at merge time):

• src/web/public/terminal-tile.js:775: a bounded grid tile's shell load sends lines=10000 instead of its own _historyLinesQuery(), and the split's Pane B now sends lines= too, while the paragraph you edited at docs/architecture-invariants.md:826 still says Pane B sends none. Either use _historyLinesQuery() for the bounded tile or adjust that sentence.
• src/web/public/constants.js:1918: when the 10,000-line window is also over 1 MiB, the banner's amount counts only the bytes the tail cut, while tmux holds more beyond the window.

Once 1 to 3 are addressed I will take another look and merge. Thanks again for digging into this one, the write-up made the bug easy to follow.

[timkjr]

Thanks for the review. Everything is in 063e6fc, on top of the original commit.

1. The display-message query now also reads #{alternate_on}. A request carrying alt=recording (only SHELL_LOAD_QUERY sends it) is answered the old way on such a pane: the visible frame over the tailed byte recording. The route makes the decision; it's a client flag rather than a mode check, since session-routes.ts can't branch on shell (cli-registry-no-id-branching). Route tests cover alt on, alt off or unreported, and no opt-in. One data point from a beta instance with a stock-config nested tmux, 300 lines printed inside it: the fallback recovered 78 distinct lines and the full capture 39. So the recording holds more than one screen but not the whole scrollback, since the inner tmux turns a burst into repaints. It's still the better of the two, so I kept it as you suggested. alternate_on also can't tell a nested tmux from vim or less, so a local shell with one of those open takes the same fallback while it's open; the docs say so.
2. Only a client bound below the ceiling is reported now. There's a test for full=1, full=1&tail=, and lines= at the ceiling.
3. CLAUDE.md, architecture-invariants (Full-scrollback replay, plus the tile paragraph) and api-reference describe SHELL_LOAD_QUERY, the 'tail' report, and why.

Both smaller ones are in too: a bounded tile's shell load sends its own _historyLinesQuery() (via SHELL_LOAD_BASE_QUERY), and the Pane B sentence now says what it sends. The response also carries a new historyLinesCut flag, and the banner names no amount when it's set.

On #602: with both in, a remote shell's local pane is in the alternate screen too (it's attached to the remote tmux). As written, this fallback would discard #602's remote splice on every remote shell tab switch. The adjustment is to skip the fallback when the remote scrollback override was used, and to read the cut from the remote history_size instead of the local one. Happy to write it on whichever lands second.

Typecheck, lint, format, frontend syntax, browser-excludes and the full npm test are green here (10,677 passed).