tmux 3.7: trial candidate features

[connorads]

Status (2026-07-07)

Bump + patch rebase are done and live — this issue now tracks only the candidate-feature trials.

• On tmux 3.7b (nixpkgs point-bumped 3.7 → 3.7b; patches rebased for 3.7 apply with zero fuzz to 3.7b). Running server on the main socket is 3.7b, patched (colour_dim + status_split_top_bottom symbols present in the resolved binary).
• Patch rebase landed in bd4c5fd (also excludes *.patch from hk whitespace fixers, which were corrupting diffs).
• None of the candidate features below have been started yet.

Context

Started on tmux 3.6a (nixpkgs-unstable). tmux 3.7 released 2026-06-26. The bump was parked deliberately: two days old (vs the repo's 4-day-quarantine ethos), nixpkgs hadn't shipped it, and the payoff features sit behind a 3-patch rebase over the most-churned subsystem.

The no-risk wins from the same audit were already done on 3.6a:

• tmux: theme copy-mode search highlighting (Catppuccin)
• tmux: revert update-environment to default
• zsh: self-heal SSH agent socket symlink on fresh login

Precondition — DONE

• nixpkgs-unstable ships tmux 3.7 (met: overlay appends patches to prev.tmux, no src override; landed as 3.7 then 3.7b).

Patch rebase — DONE (bd4c5fd)

Local patches in .config/nix/patches/, cut against 3.6a, rebased to 3.7 (apply clean on 3.7b). Bump procedure in patches/README.md.

• split-status-top-bottom.patch → 3.7 (9 hunks re-anchored; the highest-risk one).
• dim-inactive-panes.patch → 3.7 (screen-redraw draw_pane hunk).
• force-redraw-on-focus-change.patch → 3.7 (applied clean, untouched).
• Verify: colour_dim + status_split_top_bottom symbols present in compiled binary; full darwin-system build green; server restarted onto the new binary.

Candidate features — each is a test, not a blind adopt

• escape-time: dropped the 30 workaround → 10 (3.7 default) in aa648f1b. Both root-cause issues fixed upstream (tmux #4793, opentui #490); 3.7 also lengthens escape delay on buffered partial paste-end. Verified: throwaway parse + live reload + hand-checked opencode start/exit & Esc in kitty.

• pane-scrollbars — tested modal (Mocha-styled) on 3.7b; the live trial coincided with a server crash on this patched build (scrollbars redraw through the same path the dim + split-status patches hook). Declined — cosmetic, not worth the risk. Stale comment corrected in 4dae0873.

• copy-mode-line-numbers hybrid + line-number styles — verify against the dim patch.

• message-format / message overlay styling — verify against split-status-top-bottom.patch + message-line 1; likeliest fight.

• get-clipboard — default on 3.7b is buffer, not off (verified -f /dev/null): a pane requesting the clipboard already gets tmux's newest paste buffer. request/both escalate to the real system clipboard. Given many agent panes hold secrets, this is a security call (hold buffer or tighten to off), not a utility adopt — do not enable request. Test per-terminal + over SSH if changing.

• focus-follows-mouse — day-trial with mouse on; keep or bin.

• Floating panes (new-pane, default prefix + *) — trial as a persistent sidecar (logs/monitors/btm); keep popups for modal tools (lazygit, jjui, fzf pickers). Check interaction with dim/split patches. Optional pane_floating_flag status hint. Note: move/resize is mouse-only in 3.7.

• remain-on-exit key / new-pane -k — keep build/test panes open until a keypress instead of a popup.

• tree-mode-preview-* — themed the new 3.7 choose-tree preview indicator (and prefix + q display-panes, same source) to Mocha via display-panes-colour/-active-colour (active pink, others blue); default format + style kept. Commit "tmux: theme display-panes + tree-mode-preview to Mocha" (f10b3f57, hashes churn — match by title). Tested on 3.7b: throwaway parse clean, live reload took, agent panes survived, prefix + q + choose-tree previews hand-checked in kitty.

Explicitly skipped (decided)

• list-keys -F/-O live help popup — a future command palette will own searchable-fire-actions; keep curated help.md for grouping/prose; do not rebind prefix + / (already the help search).
• allow-set-title off — would break pane-border-format's #{pane_title} (apps set it via this option).
• explicit update-environment list — already reverted to default; don't reintroduce a hand-maintained list.

Notes

• WAYLAND_DISPLAY / XDG_* are 3.7 additions to the default update-environment (not in 3.6a) — a freebie now that we're bumped, no action needed.

[connorads]

Render-path investigation + permanent smoke harness (2026-07-08)

Floating panes finding

Ran an aggressive gauntlet against the exact live 3.7b binary + real config on a private -L socket: floats (create, full-size, copy-mode inside, churn over heavy output), focus dim transitions, copy-mode scrolling, display-panes, popups, splits/resizes in all directions, window resize under a live client, message/prompt rows on the split status, and pane-scrollbars on/modal + copy-mode. No crash, ever. No macOS crash report exists for the original incident either.

Code-reading confirmed the patched redraw path is coordinate-consistent: floats draw as ordinary panes through screen_redraw_draw_pane (the patches don't special-case them), occlusion is visible-range clipping, the dim flag is set/cleared per pane and reapplied per tty command, and all vertical offsets go through status_toplines/status_line_y. Documented in patches/README.md (commit "tmux: document verified redraw-path facts, point smoke checklist at harness").

The gauntlet is now a permanent bats harness (commit "tmux: crash-regression smoke harness for the patched render path"):

• tmux-render-smoke.bats - shared real-config server + pty client, every test ends in an assert_alive (server up AND drawing client attached - a dropped client is the "lost my pane" symptom too). Includes a pyte-composited screen check (status rows, borders, float drawn on top).
• tmux-patch-symbols.bats - fast nm guard that a rebuild hasn't silently dropped _colour_dim/_status_split_top_bottom.

The floating-panes box stays unticked: move/resize is mouse-only in 3.7, the one surface the harness can't drive. Adopt after the interactive mouse sign-off.

Found along the way (upstream 3.7 behaviour, reproduced with -f /dev/null, not the patches): resize-pane -x/-y on a floating pane leaks the resize into the tiled layout, and floats reuse remembered per-window geometry - a later float can land mostly off-screen.

pane-scrollbars: attribution unconfirmed, reconsider

The crash → modal attribution never reproduced: the historically implicated modal+copy-mode combination runs in the harness without incident. The tmux.conf comment now states this as standing rationale (commit "tmux: state pane-scrollbars standing rationale (off, reconsider after sign-off)"): off, but a candidate to reconsider adopting after the same interactive mouse sign-off (drag the scrollbar thumb in copy-mode).

Interactive sign-off recipe (mouse-only surfaces)

tmux -L mouse-test -f ~/.config/tmux/tmux.conf new-session

In a kitty window: create a float (prefix + *), mouse-drag to move it, mouse-resize it, set -g pane-scrollbars modal + copy-mode + drag the scrollbar thumb, click both status rows, confirm dim toggles on focus switch. Then tmux -L mouse-test kill-server. If clean: tick the floating-panes box and decide scrollbar adoption (separate commits).