host-tmux: SSH transport for container-to-host tmux

[lroolle]

Description

Reach the host tmux server from inside a deva container over SSH: interactive attach, one-shot commands, and an authenticated replacement for the socat TCP bridge.

Type

• New feature

Details

deva-bridge-tmux{,-host} (Layer 1) works but has three structural problems:

• unauthenticated TCP 41555: any local process gains full tmux control (run-shell on host)
• host-side daemon must be started manually and dies on reboot; chicken-and-egg when you work from inside containers
• couples container tmux client protocol to host server version

sshd on macOS is launchd-managed and survives reboots. OpenSSH forwards unix sockets, so one tool covers both modes:

• host-tmux attach/ls/run/tmux: plain ssh, host-side tmux client (zero version coupling)
• host-tmux bridge: ssh -N -L /tmp/host-tmux.sock:, same socket path the docs already teach; native container tmux client and tmux-bridge Layer 2 work unchanged, socket is 0600 instead of an open TCP port
• host-tmux setup: one-time key install into the host authorized_keys via docker host-mount (prints undo); host user resolved from DEVA_HOST_USER / DEVA_CHROME_HOST_USER
• host-tmux doctor: layer-by-layer diagnosis

Verified live against an OrbStack/macOS host: attach, ls, run, bridge lifecycle, tmux-bridge composition through the forwarded socket.

Related Files

• scripts/host-tmux (new)
• docs/tmux-bridge-agent-comms.md (present ssh as default Layer 1 transport, socat pair as fallback)
• CHANGELOG.md

Test Plan

• host-tmux doctor from a fresh container: resolves target, auth, host tmux path
• host-tmux setup on a host without the key: installs, prints undo line
• host-tmux ls / attach / attach
• host-tmux bridge: socket up, tmux -S /tmp/host-tmux.sock ls works, bridge stop cleans pid+socket
• TMUX_BRIDGE_SOCKET=/tmp/host-tmux.sock tmux-bridge list against host server