Skip to content

fix(tmux-link): faithful rendering, flow control and sturdier reconnect for remote tmux panes - #74

Merged
bsommers merged 3 commits into
mainfrom
feat/tmux-remote-robustness
Nov 10, 2026
Merged

bsommers merged 3 commits into
mainfrom
feat/tmux-remote-robustness

Conversation

@bsommers

Copy link
Copy Markdown
Owner

What

  • Sizing: the remote pane is resized to match the local pane.
  • Redraw after reconnect: hydrate restores alt-screen and cursor state.
  • Flood: output flow control; RSS under flood went from 3.2 GB to about 32 MB.
  • Paste: a 101000-byte paste was truncated to 4096 bytes; now delivered in full.
  • Reconnect: keepalive (5 s x 3) and jittered backoff.
  • Session survival: destroy-unattached off is set on the remote session so it survives a disconnect whatever the remote tmux.conf says.
  • Live integration test against a real tmux on a private socket; docs for link behaviour.

Not in this PR

The link is not yet persisted in saved session state: after a detach, bilterm attach restores a local shell instead of the remote link.

Verification

🤖 Generated with Claude Code

bsommers and others added 3 commits November 10, 2026 01:21
…ct for remote tmux panes

Found by driving a real tmux over a real ssh transport (private sshd, private
tmux socket):

Rendering
- The remote tmux client is now as large as the linked pane's terminal, not
  the whole Bilterm window (remote was 160x44 for a 78x42 pane, so vim and
  wrapped lines drew in the wrong place). A remote window shown in a pane of
  its own gets its own size (refresh-client -C @W:CxR).
- Hydrate restores alternate screen, cursor position/visibility, application
  cursor keys and mouse modes from one self-identifying display-message
  reply sent just before the captures. Reconnecting while vim runs used to
  leave the cursor at 30,41 instead of 8,0 and stale rows on the primary
  screen.
- %output bytes >= 0x80 are kept exact through the String line channel and a
  UTF-8 character split across two %output lines is reassembled (it became
  two U+FFFD).
- %extended-output is parsed.

Flow control
- refresh-client -f pause-after=2 after the hydrate; on %pause the pane's
  backlog is dropped, the screen re-captured and the pane continued (the
  continue argument must be quoted for tmux's parser). A flooding pane no
  longer starves input: Ctrl-C typed in Bilterm now reaches the remote.
- A paste larger than 4096 bytes was silently truncated; typed bytes are now
  kept in a bounded per-pane backlog and sent in order without overflowing
  the command queue.

Reconnect and usability
- Link transport uses ServerAliveInterval=5 (dead peer noticed in ~15s, was
  ~55s) and jittered backoff in live mode.
- The driver no longer sleeps 50 ms on the UI thread to learn the exit code.
- tmux_link_state() reports the real machine state; removing the link's
  fleet node forgets the link at once instead of reading "idle" while the
  transport was still attached.
- `:ssh-tmux -- <host> [session]` reaches hosts named info, reconnect,
  disconnect or prefill.
- Missing or too-old remote tmux is named in the failure text.
- PtyLinkConnector::with_program lets tests run the link over a stand-in.

Tests: tests/tmux_link_transcripts.rs feeds recorded control-mode
transcripts through the real splitter, bridge and pumps into a pane.
Pinned expectations that encoded the old sizes, the 4096-byte cap and the
15s link keepalive are updated.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…te socket

Gated behind BILTERM_TMUX_LIVE=1. Uses an ssh stand-in that runs the remote
command locally in a PTY with a private TMUX_TMPDIR and HOME: connect, size
and render check, kill the transport, assert the remote session and its
counter loop are alive, automatic reconnect, assert same session, same pane
mapping, output produced while away is hydrated and nothing is duplicated.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…document link behaviour

- After the hydrate the link sets destroy-unattached off on the session it
  attached to, so a remote tmux.conf with destroy-unattached on cannot make
  a disconnect destroy the session.
- env's "'tmux': No such file or directory" (the text a real remote prints
  for the link command) is recognised as a missing tmux.
- User guide chapter 5: pane-sized remote windows, state-aware hydrate,
  what survives each kind of disconnect, the -- escape, flow control and
  the known limits; troubleshooting keepalive text; README; CHANGELOG.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@bsommers
bsommers merged commit 2efb58d into main Nov 10, 2026
3 checks passed
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.

1 participant