feat(cli): list and attach remote tmux sessions

Merged
AU
1mo ago
+3442-2859

Summary

Fixes the blank terminal left after a remote tmux mirror detaches while its workspace remains open. Detach now removes retired closed mirror containers and creates a usable local terminal when needed.

The same PR adds the narrow remote tmux CLI surface:

  • cmux ssh-tmux <destination> list / ls discovers sessions without opening a workspace.
  • attach <session> and --session <name> attach only the selected existing session.
  • The historical no-subcommand invocation still mirrors the whole server.

Testing

  • python3 scripts/verify-local.py — 17/17 selected checks passed.
  • Fleet exact-SHA build — passed:
    • Job: 9839192112d1337d56fd5399
    • SHA: 15c6ad6a89afb26fe8ce0a243ff785d8a9a207f1
    • Tag: pr-18645-remote-tmux-blank-v2
    • Artifact SHA-256: 6f0c096769452deeaf8eb30144e42f203712a94de9b30f80fd42639885adbb6a
  • Tagged end-to-end check against an isolated loopback SSH/tmux host:
    • ssh-tmux list --json returned the existing blank-check session.
    • Positional attach opened one workspace and one pane.
    • read-screen returned REMOTE-TMUX-MARKER\nsh-3.2$.
    • surface-health reported render_health: rendering and socket_binding: bound.
    • Killing the remote session removed the mirror workspace cleanly; no blank surface remained.
    • Screenshot evidence: remote tmux attach renders a live terminal.
  • Focused regression: detachingMirrorReplacesRetiredContainerWithUsableTerminal.

The hosted macOS compile-admission retries for the prior head failed before executing tests because cached modules were unavailable (CmuxControlSocketAtomicsC, CmuxSimulatorSystem, Sparkle, Iroh, and _SwiftSyntaxCShims). The latest head's hosted CI workflow also hit a runner startup_failure with no jobs. The exact-SHA fleet build above compiled and packaged the app successfully; these hosted failures are infrastructure issues, not compiler diagnostics from this change.

The CLA signature comment was posted through cmux browser. CLA Assistant still requires the historical cmux@users.noreply.github.com author to be linked to a GitHub account; no commit history was rewritten.

Changelog

Fixed: remote tmux detach no longer leaves a blank terminal container.

Issues

Impact map

  • Source of truth: Workspace owns mirror-detach cleanup; RemoteTmuxInvocation and the existing remote.tmux.sessions / mirror endpoints own CLI discovery and attach.
  • Covered entrypoints: list aliases, positional attach, --session attach, mirror detach, and session-ended cleanup.
  • No new v2 socket method or remote-relay allowlist entry was added.
  • Localized CLI help and contract docs were updated.

Mergeability

  • Base SHA: a0109c86d27f3ccd6e3203afb899f589c1376adf
  • Head SHA: 08bb846ba36002860246576b0d8b05447545ecaa
  • Conflict-only gate: PASS
  • Do not merge from this task.

[!NOTE]
Medium Risk
Changes remote tmux attach/reconcile and CLI parsing paths that touch SSH auth and workspace lifecycle; scope is bounded to existing socket methods but multiplexed single-session filtering adds behavioral complexity.

Overview
Extends cmux ssh-tmux with list/ls (optional --json) to discover remote tmux sessions without opening a workspace, and attach <session> / --session to mirror only one existing session; argument parsing moves into RemoteTmuxInvocation, and list uses remote.tmux.sessions with the same interactive SSH auth retry as mirror.

The app and socket layer pass an optional session into remote.tmux.mirror and attachHost, including multiplexed mode where reconcile skips creating workspaces for other sessions on the shared stream.

Detach fix: when a remote mirror workspace is kept open locally, retired closed mirror container panels are removed and a usable local terminal is created so users no longer see a blank tab.

Reviewed by Cursor Bugbot for commit 08bb846ba36002860246576b0d8b05447545ecaa. Bugbot is set up for automated code reviews on this repo. Configure here.

Main sync

Merged the current origin/main tip a0109c86d27f with scripts/merge-main.sh --remote origin --tip because the newest main commits had no green CI fast-guards run. The generated catalog and project-file conflicts were resolved by the repository resolver. The pushed merge commit is 08bb846ba36. python3 scripts/verify-local.py passed all 17/17 selected checks, and the conflict-only gate passed.

Summary by CodeRabbit

  • New Features
    • ssh-tmux list (or ls) discovers remote sessions, with optional JSON output and an interactive SSH-authentication retry when available.
    • Use ssh-tmux attach <session> to mirror a specific existing session; an error is reported if it is unavailable. Without a subcommand, whole-server mirroring remains the default.
  • Bug Fixes
    • Detaching a remote mirror restores a usable local terminal when its existing panels have closed.