Remote tmux multiplexer: aggregate a host's sessions over one shared -CC connection

Draft
EJ
2mo ago
+5228-44

What this adds

A multiplexer transport for remote tmux: aggregate all of a host's sessions through one shared tmux -CC view connection instead of one connection per session. This is what lets a host that permits only a single concurrent SSH connection (MaxSessions 1) mirror every session — each rendered by the exact same RemoteTmuxSessionMirror path a dedicated connection uses, so there is no mirror-side special-casing. Off by default behind remoteTmux.multiplexer.beta.

How it's built (reviewable in order)

  • RemoteTmuxSessionSource — the per-session protocol a mirror consumes; the GA RemoteTmuxControlConnection conforms directly (one connection = one session), and RemoteTmuxSessionChannel is a decorator that scopes the shared view stream to one session's windows/panes. The mirror consumes any RemoteTmuxSessionSource, so it renders both transports identically.
  • RemoteTmuxViewConnection / RemoteTmuxViewSession / RemoteTmuxLinkedViewPlan — the hidden cmux-view-* session and its link plan.
  • RemoteTmuxMultiplexReconciler / RemoteTmuxViewReconciler — pure session→workspace regrouping and intent-following by stable session id.
  • RemoteTmuxController+Multiplexer + isMultiplexed branches threaded through every teardown/reorder/new-tab/quit path.
  • Connection infra: queryWithTimeout on a .rawQuery kind, the cmux_sessions session-digest subscription + isSharedViewStream, shared RemoteTmuxHost.fnv1a64.
  • new-remote-workspace primitive (remote.tmux.new_workspace) + Cmd-N routing on a mirror workspace.

Review

CodeRabbit/Greptile findings are addressed and their threads resolved:

  • dedicated session create returns .createIndeterminate on a thrown transport/timeout error (so a retry can't create a duplicate); .createFailed is reserved for a returned command failure;
  • both handleMirrorNewTabRequested overloads route through one routeMirrorNewWindow helper — the pane-targeted one no longer uses the GA bare-target builder, which in multiplexer mode could create the tab in the hidden view session;
  • the settlement probe consults a channel's underlying shared connection for pending work and fails closed for an unrecognized source;
  • socket error copy is in product terms;
  • the fuzzer's leak probe keys on the mirror's live identity so a reused address still gets probed.

(The origin-colors sidebar tint that previously rode along on this branch is split out to its own PR, #7193.)

Verification

  • Builds green (app + cmux-unit).
  • Capstone fuzzer (RemoteTmuxMultiplexFuzzTests, 8 seeds × 250 steps): bidirectional churn — tmux-driven (add/remove/rename sessions, add/remove/shuffle windows, id-publication delay, name reuse/swaps) and cmux-driven (close/detach, pending-kill, new-remote-workspace, walk-across-sessions). It caught a real teardown bug (mirrors re-created after close because no kill intent was recorded), fixed here, and now also asserts no mirror/channel leaks after teardown.
  • Sibling mirror suites (pane input, split routing, lifecycle) green.
  • Live render dogfood — the real app mirroring a real MaxSessions 1 tmux host through remote-tmux-live-fuzz.sh, 3 seeds × 20 iterations of splits / kills / window-switches / resizes: 0 failures, every pane settling to the tmux-assigned grid with per-pane text equal to capture-pane.

Review follow-up

The New Workspace failure alert used to show whatever the remote produced — tmux's stderr on the plain ssh path, or a transport error's localizedDescription. It now always shows a localized sentence saying cmux could not start the session, that no workspace was created, and to check that the host is reachable. The raw detail still goes to the debug log, which is where it helps when someone is diagnosing the failure.

The two new dialog strings shipped with only en and ja, and the string catalog carries 20 locales. Both keys now have all 20. While checking that, two socket error strings that production already returns — workspace_id is required and the invalid session name message — turned out to have no catalog entry at all, so they were falling back to their English defaultValue in every language; both are in the catalog now with all 20 locales, and common.ok picked up the Khmer entry it was missing. Translations follow the wording the catalog already uses for these terms, so a tmux session reads as tmux-Sitzung in German and tmux 工作階段 in Traditional Chinese, and stays as tmux session in Khmer and Thai the way the neighbouring tmux strings do.

These two commits were verified statically: the locale coverage is machine-checked against the catalog and no user-facing literal bypasses String(localized:). Neither was compiled, since the branch does not currently apply to main.

A reconnect fix that fell out of testing the shared connection: after the shared stream reconnects and drains its seed batch, the control connection fires reconnect-ready and each mirror schedules its post-reconnect force-resize from it. The session channel forwarded every event except that one, so on a multiplexed host no mirror resized after a reconnect. The channel now fans it to all of its observers — it is host-global, with no pane or window id to scope it — and the red/green pair pins it with a channel test against a fake session source.

Summary by CodeRabbit

  • New Features
    • Added a beta “multiplexer” mode for remote tmux hosts to consolidate multiple sessions through a shared connection.
    • Added support for creating new remote workspaces from an existing remote-tmux workspace.
    • Added handling for new-terminal workspace requests in the remote-tmux mirror flow.
  • Bug Fixes
    • Improved shared-view/session-digest synchronization in multiplexer mode.
    • Strengthened timeout/cancellation behavior and correlated raw command results more reliably.
    • Improved newline/CRLF parsing for remote tmux session listings.
  • Tests
    • Expanded multiplexing/linked-view planning and reconcile fuzz coverage.
    • Improved robustness of test command/reply draining for window operations.