interaction: attach flow mutates remote tmux configuration and cannot reliably restore user state

[richard950825-sys]

Summary

Hermes Gate currently rewrites remote tmux settings during attach in order to reserve Ctrl+B for detach/back behavior and to inject a custom status bar.

This is a release-blocking interaction bug because it mutates the user's existing tmux session state, and the restore path is only a best-effort reset to assumed defaults rather than a true restoration of prior values.

Current behavior

During _enter_viewer(), the app calls _configure_tmux_for_attach() before attaching and _restore_tmux_after_detach() afterwards.

The attach-time configuration currently does all of the following on the remote session:

• changes the session prefix from C-b to C-a
• binds C-b in the root table to detach-client
• forces status bar settings, styling, left text, and right text

The detach-time restore path then attempts to revert some settings by writing hard-coded values or unsetting a subset of options.

Why this matters

This breaks a core user expectation for terminal tooling: attaching to an existing tmux session should not silently rewrite their interactive environment.

Real-world failure modes include:

• a user with a custom tmux prefix loses expected keybindings
• a user with custom root-table bindings gets behavior changed underneath them
• custom status bar theming or plugins are overwritten during attach
• if Hermes Gate crashes, loses connection, or is interrupted before restoration, the remote session remains mutated
• the restore path may revert to an assumed default that is not the user's original state

Evidence

Observed in:

• hermes_gate/app.py:576-678

Relevant behavior:

• _enter_viewer() calls _configure_tmux_for_attach() before subprocess.call(cmd)
• _restore_tmux_after_detach() is only attempted after the attach returns
• _configure_tmux_for_attach() executes commands like:
  • tmux set-option -t <session> prefix C-a
  • tmux bind-key -T root C-b detach-client
  • multiple status-* mutations
• _restore_tmux_after_detach() resets to assumptions like prefix C-b rather than restoring a captured prior value

Expected behavior

Attaching through Hermes Gate should avoid destructive mutation of remote tmux configuration.

Preferred outcomes, in order:

1. do not mutate persistent tmux session settings at all
2. if temporary mutation is absolutely required, capture the exact prior state and restore it reliably
3. if restoration cannot be guaranteed across interrupts/crashes, do not ship the mutation-based design as the default attach flow

Suggested direction

A robust fix should be designed around preserving user state rather than overwriting it.

Potential approaches include:

• a non-mutating attach UX that does not depend on changing prefix/root bindings
• a wrapper/session-local mechanism that does not touch existing persistent tmux state
• if mutation is temporarily unavoidable, explicit state snapshot + restoration with crash-safe cleanup, not hard-coded defaults

Acceptance criteria

• attaching no longer rewrites persistent tmux settings in the common path, or the project has a provably safe state-preserving design
• no hard-coded assumption that the user's tmux prefix was originally C-b
• no permanent mutation remains after successful attach/detach
• interrupted attach flows do not leave the remote session in a broken or modified state
• documented keybinding behavior matches the actual implementation

Testing requirements

This issue requires real interaction validation, not just unit coverage.

Automated tests

• regression tests covering attach helper command generation
• tests proving user-specific tmux options are not clobbered by the new design
• tests for any state-capture / state-restore helper if one is introduced

Manual / integration validation

Validate against at least these scenarios on a real tmux server:

1. session with default tmux config
2. session with custom prefix
3. session with custom status bar
4. session with custom root-table bindings
5. interrupted attach flow (client disconnect, process kill, abrupt exit)

For each scenario, verify:

• attach works
• detach/back works
• the original tmux configuration is intact afterwards
• no stale status bar or keybinding mutation remains

Non-goals

• merely catching more exceptions around the current mutation logic
• restoring to guessed defaults instead of actual previous state
• updating docs only while preserving the current destructive behavior

[LehaoLin]

Valid concern, but deferring to a future release.

Why the current impact is limited:

1. All mutations are session-scoped (set-option -t), not global — only the attached session is affected
2. Most users run default tmux config (prefix C-b), so the restore path works correctly for the majority
3. Sessions are ephemeral — killing a session discards the mutated config entirely

Why not fixing now:

A proper fix would require an extra SSH round-trip to snapshot the current tmux options before mutation, then restore from the snapshot. This adds latency to every attach and significantly increases complexity for what is currently a non-issue for most users.

Marking as future enhancement — will revisit when there's demand for custom tmux config preservation.