perf(tui): full-screen MaxWidth pass makes View() 51% of CPU — laggy switching with ~55 sessions

[asheshgoplani]

Symptom

On a deck with ~55 live sessions the TUI sits at a high steady-state CPU share and
session switching (j/k) feels laggy — each keystroke visibly trails the input.

Sandboxed repro

Fully isolated: throwaway HOME, its own profile, its own tmux socket
([tmux] socket_name), TUI running inside that isolated tmux server. 60 synthetic
sessions created with --cmd "sleep 100000", terminal 220x50.

export HOME=$(mktemp -d); unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME TMUX TMUX_PANE
export TMUX_TMPDIR=$HOME/tmuxtmp AGENTDECK_PROFILE=perftest
printf '[tmux]\nsocket_name = "adperf"\n\n[logs]\npprof_enabled = true\n' > $HOME/.agent-deck/config.toml
for i in $(seq 1 60); do agent-deck add $HOME/work -t "perf$i" -cmd "sleep 100000" -g perf; done
for i in $(seq 1 60); do agent-deck -p perftest session start "perf$i"; done
# then run the TUI inside `tmux -L adperf` with AGENTDECK_DEBUG=1

Workload: 240 single-key j/k navigation events, one send-keys per key so no
paste coalescing hides render cost. Metric: the view_render perf log line, which
already records every View() duration.

Profile

go tool pprof against the sandbox process ([logs] pprof_enabled, localhost:6060)
during the switching workload:

      flat  flat%          cum   cum%
         0     0%         650ms 53.72%  bubbletea.(*Program).Run
         0     0%         620ms 51.24%  ui.(*Home).View
         0     0%         450ms 37.19%  ui.(*Home).renderDualColumnLayout
         0     0%         320ms 26.45%  lipgloss.Style.Render
     260ms 21.49%         260ms 21.49%  runtime.memclrNoHeapPointers

View() is 51% of all CPU samples, and renderDualColumnLayout is 37%. Line level:

ROUTINE ==== ui.(*Home).renderDualColumnLayout
         .      100ms  14312:	leftContent := h.renderSessionList(...)
         .       30ms  14343:	leftPanel = ensureExactWidth(leftPanel, leftWidth)
         .      100ms  14347:	mainContent := lipgloss.JoinHorizontal(...)
         .      170ms  14354:	mainContent = lipgloss.NewStyle().MaxWidth(h.width).Render(mainContent)

Root cause

Line 14354 is a "safety net" that runs MaxWidth(h.width) over the entire
already-composed screen on every single View() — i.e. on every keystroke and
every 2s tick. It re-parses and re-measures every line and every ANSI sequence of
the full frame, costing 170ms of the 450ms layout render (38%), ~14% of total
process CPU — and in the normal case it truncates nothing:

• splitPaneWidths() documents and guarantees
  left + paneSeparatorWidth + right == h.width.
• ensureExactWidth() is applied to both panels immediately before the join, and
  makes every panel line exactly its pane width in display cells.
• the separator is exactly paneSeparatorWidth display cells wide.

So every joined line is already exactly h.width cells and the pass is a pure
no-op. It can only matter in the degenerate branch of splitPaneWidths(), where a
pane width can come back non-positive and ensureExactWidth() returns its input
untouched.

Secondary, same function: the separator column re-renders the identical constant
" │ " through lipgloss once per screen row (contentHeight times) per frame,
when one render can be reused for every row.

Baseline over 3 runs of the identical workload (n≈748 renders each):

run	mean	median	p90
1	2.672 ms	2.197 ms	4.416 ms
2	2.542 ms	2.201 ms	3.371 ms
3	2.575 ms	2.083 ms	3.197 ms

Proposed fix

Keep the safety net, but only pay for it when it can actually do something: compute
the guaranteed joined width from the component widths and skip the full-screen
MaxWidth pass when it cannot overflow h.width. Hoist the constant separator
render out of the per-row loop. Both are O(1) changes in renderDualColumnLayout
with no behavioural difference on any non-degenerate terminal width.

[asheshgoplani]

Additional precise symptom from the maintainer's live fleet (~69 sessions, v1.10.11): detaching with Ctrl+Q back to the list intermittently takes noticeably long. Likely the attach-return catch-up burst: status sync is reduced while tea.Exec has the TUI suspended, and on return the code paths around home.go:4089/4176/4594 catch up for the whole fleet at once, plus a full list re-render — attachReturnPreviewGrace (home.go:4015-4022) softens previews but not the catch-up burst itself. Suggested direction: stagger the post-detach catch-up (visible rows first, rest amortized over the next ticks) and skip redundant capture work for sessions whose state generation is unchanged.

[asheshgoplani]

Correction to the "Proposed fix" section above, since the reasoning there turned
out to be wrong in an interesting way.

The original plan was to predict the joined width arithmetically and skip the
full-screen MaxWidth pass when
leftWidth + paneSeparatorWidth + rightWidth <= h.width. That rests on the claim
that ensureExactWidth makes every panel line exactly its pane width. It does
not. It pads a too-short line but never re-truncates a too-wide one, and
MaxWidth truncation of a keycap grapheme cluster can come back one cell over the
requested width:

ensureExactWidth(..., 8) on "ok 1️⃣2️⃣3️⃣"  ->  lipgloss.Width = 9
right block width = 9 (nominal 8)
joined rows = 81 in an 80-column terminal, even though 69 + 3 + 8 == 80

At width=80 with the minimum preview split the preview pane is 8 cells wide, so
an arithmetic guard would skip the safety net on a frame that overflows by a
column — exactly the wrap / cursor-drift case the net exists for. The adversarial
test written for the fix caught this on CI before it could ship.

The landed fix therefore measures instead of predicting:

if lipgloss.Width(mainContent) > h.width {
	mainContent = lipgloss.NewStyle().MaxWidth(h.width).Render(mainContent)
}

lipgloss.Width returns the widest line of a multi-line string on the same
ansi.StringWidth basis MaxWidth truncates by, so the two agree by construction
on whether the frame overflows. Measuring is much cheaper than rebuilding, so the
win holds: process CPU during the switching workload went 4.84% -> 2.04%,
renderDualColumnLayout 450ms -> 160ms, and the MaxWidth line 170ms -> 0
samples.

Two side observations for anyone touching this area later:

• MaxWidth cannot shrink that keycap cluster either, so the safety net is
  best-effort on such content. Pre-existing, unchanged by the fix, but it means
  the net is not a hard guarantee that a frame fits.
• ensureExactWidth's truncate branch only corrects an undershoot. An overshoot
  by a cell survives and propagates through JoinHorizontal, which pads every row
  to the inflated block width. Same lineage as fix: resolve TUI scroll artifacts from width measurement inconsistency #182 / Session titles with text-default emoji + VS16 (e.g. 🏷️, 🛠️, ⚙️) cause per-frame row-offset drift in TUI #937 / fix(ui): pad viewport rows to prevent iTerm2 ghost lines on scroll #1240.

Fix in #1756.

[asheshgoplani]

Third symptom from the maintainer's live fleet (same family): expanding a GROUP in the TUI visibly lags. Expanding makes many rows newly visible at once (expandedGroups toggle at home.go:697), which triggers the per-row refresh/preview burst for the whole group in one frame — same root as the detach catch-up burst and the O(fleet) tick. Any fix for visible-row bursts should treat group-expand as a first-class trigger case: render the rows instantly from snapshots, then refresh them amortized. Fleet context: ~57 live sessions, groups of 10-20 rows.

[asheshgoplani]

Confirmed on the real fleet: with #1764 installed (main tip), detach/switch feels fast at ~57 live agent sessions. Worth recording because the sandbox could not reproduce the original lag — its idle sleep panes measured ~11ms before the fix, while the real fleet's per-call cost is an order of magnitude higher. So the sandbox proved the SLOPE (detach no longer degrades under load: 11.0→17.1ms before vs 6.7→6.1ms after) and the real fleet proved the felt improvement. The five blocking tmux round-trips removed from the pre-first-frame path were the cause.

Remaining in this family: #1765 (adaptive refresh — off-screen quiescent sessions cost zero) is in a review-request loop for three closures, and group-expand bursts plus the wire-the-hook-watcher-callback work are the next levers.