runtime-mux: hosts, psmux and status
crates/runtime-mux runs sessions on a tmux-protocol multiplexer: tmux, psmux
or RMUX. thurbox's architecture decisions cover
the backend contract (ADR-11), the local server (ADR-12) and the peer adapters
(ADR-31). This page covers how a session reaches another machine, where psmux
differs from tmux, and the status channel of the contract.
Hosts and transports #
A host is another machine (ssh:<host>) or a WSL distro on this one
(wsl:<distro>). The multiplexer protocol is the same on every host. Only the
launch prefix differs.
tmux_compat::server::Server<M>holds aTmuxTransport. A transport is an optional launcher (shell::HostLauncher:Ssh { destination, ssh_opts }orWsl { distro }) and the multiplexer binary it runs.HostLauncher::for_hostis the one conversion from a host to a launcher. The launcher carries any command line unchanged (shell::launch). The transport adds the multiplexer's-L.- Everything after the launch is the same on every host: control mode, pane
registration,
send-keysand%output. The per-session commands travel over the control connection's stdin, so only the attach crosses the launcher. sshuses the system binary and~/.ssh/configfor keys, agents and multiplexing. WSL needs no credentials.- A host is a
HostDefin aHostRegistrythe embedder hands the factory (wiring::for_hosts). Theruntime-muxprogram builds one from the request's place (place::parse), with the keys of its table in Fleet's config (runtime-mux's places). A remote place's server runs on the program's socket,runtime-mux, unless the place names another.runtime-mux view --place <place>builds the same backend, so a view of a remote pane reads it through the place's control connection. - Each host gets one backend per adapter, keyed by its route
(
ssh:<host>:<mux>,wsl:<distro>:<mux>,wiring). - A host backend is registered, not connected. It connects on first use, on a worker, so a down host never blocks a caller.
wsl.exenever shares the caller's terminal (shell::wsl_exe:CREATE_NO_WINDOWon Windows,setsidon Unix). Awsl.exechild reads its parent console's keyboard even with every std stream redirected.
Rejected: a transport trait (a launcher plus a binary name is enough until a
launcher is not a command prefix), and an embedded SSH library (it would
reimplement ~/.ssh/config, agent forwarding and multiplexing).
A host's platform #
A session's place, the host's OS, the launcher and the multiplexer are four
independent choices. The route carries the place and the multiplexer. The OS is
HostDef::platform (Posix or Windows); this machine's is
shell::local_platform.
- A host entry's
platform = "posix" | "windows"declares it. Without it, a host whosemultiplexerispsmuxis Windows and any other is POSIX. A WSL distro is always POSIX. - Each decision reads the dimension it is about. The pane's shell, the
default-commandpin and the/bin/sh -lcwrap follow the host's platform, never the build OS or the multiplexer's name. - Every adapter is registered on every machine and every host. Which ones are
installed is
Multiplexer::available_on. - A restriction in
crates/architecture.tomlkeeps the route and the contract free of launchers, host entries, adapters andcfg(windows). Tests simulate the other OS throughshell::simulate_local.
A Windows host speaks PowerShell #
A native Windows host has no POSIX shell, and its ssh login shell is cmd.exe
or PowerShell.
shell::HostShell, built once from the host's platform, decides how a word is quoted, how a script runs and how a program is launched. It is a host property: a psmux and a tmux server on one Windows host get the same one.- A transport for a Windows host (
TmuxTransport::with_shell) sends a line of plain words ([A-Za-z0-9-_./:=+%]) as it is. Any other line runs aspowershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand. UTF-16LE base64 leaves nothing forcmd.exeor PowerShell to interpret. - The script starts the program through
ProcessStartInfo, with arguments quoted for the C runtime (shell::windows_arg_quote). PowerShell 5.1 drops an empty native argument and splits one at an embedded". - A line longer than
WINDOWS_CMD_LINE_MAX(8191,cmd.exe's limit) is refused withCommandLineTooLongbefore it reaches the host.
psmux divergences from tmux #
The control-mode protocol is the same, but psmux differs from tmux in the
places below. Each is the psmux adapter's answer to TmuxCompatible
(crates/runtime-mux/src/psmux.rs), never a branch on the binary's name in
shared code.
- Cold start.
new-session -dcan fail or return before the server answers. The adapter probes withlist-windows(psmux'shas-sessiondeletes the port file of a server still starting), retries a transientno server running, and scopes server options with-t <session>. - No
send-keys -H. Input is encoded fromsend-keys -lliteral runs and key names. An arrow is one named key. Shift+Enter isC-j. Any other complete escape sequence is one literal with the ESC as a0x1bargument. Literal runs go out as-l -N 1 "…", and a leading-or a0xNN-shaped argument is re-emitted as a0xNNargument. new-windowkeeps only its first token and ignores-e. Environment and command are one PowerShell script (psmux_window_powershell), run aspowershell.exe -NoLogo -EncodedCommand <base64>so that no shell on the way (Windows OpenSSH setsSHELL=cmd.exe) reads it.- A paste cannot be key-encoded. It goes out of band through psmux's own
send-pastewith a base64 payload (PsmuxPaste). A failed paste is dropped with a warning: typing it would submit each pasted line. - No per-window options.
set-option -wstores one value for the whole server, so the window stamp (ADR-25) is neither written nor read on psmux. A window resolves by name, and only when exactly one live pane has that name. - No reply to the attach on argv. tmux answers it with one block; psmux
does not, so the drain is asked only of a multiplexer that answers
(
ControlPolicy::implicit_attach_reply). - Ids are per session. Every pane or window id a command targets is
qualified with the session (
SESSION_SCOPED_IDS):thurbox:.%2,thurbox:@7. A window is killed through its pane (KILL_BY_PANE). - An unknown pane is answered for the active one.
register_paneasks for#{pane_id}too and keeps the answer only when it names the pane asked for. %window-closecan name the wrong window. For psmux a close is a hint (ControlPolicy::confirm_close): the session's panes are listed, and only a registered pane missing from the listing ends.- Errors on stdout. psmux can print
ERROR:on stdout and exit 0, so a structured listing rejects such a line. Captured pane text is not parsed. - An exit takes the window. The adapter sets no
remain-on-exit, so a dead agent reads asMissing. A create is confirmed by its own pane id afterSPAWN_SETTLE(confirm_spawned): psmux has nonew-window -P, so the id is the one new pane undertb-<name>.
psmux 3.3.8 is the floor #
Before 3.3.8, a pane could be born with corrupt std handles after the server
had been typed into, and a pane-slot target could act on the session's active
pane instead. So no pane is named to, or born on, an older psmux
(VERSION_FLOOR).
Server::target first asks both halves (admit_server): the running server's
#{version} and the client binary's -V. Each answer must be a plain dotted
version at or above the floor. psmux's own words for "no server" or "no
session" are let through. Anything else refuses. The answer is kept for the
control connection it was asked on. The paint's resize and the input loop's
claim_size and is_dead never wait for the question: they send nothing on a
connection not yet admitted.
Status channel #
SessionBackend's StatusChannel role (crates/runtime-mux/src/contract.rs)
carries a hook's state:
hook_signal_command— the command a hook in this backend's panes runs, with the state word appended.Nonemeans the backend has no channel.record_hook_state,hook_states,take_hook_state_events— write a pane's state, read every pane's state in one round trip, and drain the changes an attached connection received.
No method has a default body: a backend with no channel answers None or
Err, and a reader treats an unanswered question as no news, never as idle.
On a tmux-protocol server the channel is the @thurbox_state pane option, its
subscription and its poll. Each adapter says whether it has a channel
(TmuxCompatible::HOOK_STATUS); psmux does not.
The contract suite (crates/runtime-mux/tests/support/backend_contract.rs)
holds every backend to this behaviour. Neither thurbox nor the runtime protocol
calls the role: a session's state is Fleet's, derived from the agent's hooks
through fleet signal.