Sessions, terminals, and harnesses

• Shell sessionA real terminal running your shell. PowerShell, CMD, bash, a WSL distro shell, anything. It behaves exactly as it does outside swe-mux.
• Agent sessionThe same thing, with a harness swe-mux recognises running inside it. The difference is entirely the layer on top: normalized status, a transcript, a prompt queue, a context meter, cross-vendor history, and account switching.

A shell becomes an agent session in place when you type the CLI's command, because swe-mux puts its own launchers first on that terminal's PATH. Same pane, same scrollback. There is no separate start-an-agent action to learn, and the Run menu's agent entries are a convenience rather than the mechanism.

swe-mux is a terminal multiplexer first. Anything that runs in a terminal runs here unchanged. An unrecognised CLI gets a real pseudoterminal and nothing else; a recognised one gets the layer. That is the whole distinction, and it is worth being clear about because it is easy to read a harness list as a support list.

A supervisor process, separate from the daemon and from the UI, can hold every pseudoterminal. With it on, restarting the daemon or rebuilding the desktop app leaves the agents working, and reconnecting replays only the bytes you missed rather than the whole scrollback.

It ships off. Turn it on in Settings, Terminals. With it off, in-process spawning is the fallback and a daemon restart reaps every session - which is why the restart endpoint refuses outright unless it is forced.

Cold recovery is independent of the supervisor and ships on. A durable registry row is written when a session is registered, carrying an open marker; a clean shutdown closes it and a crash closes nothing, which is the entire signal. Sessions whose daemon and terminal owner both died come back as visible, dead, resumable rows rather than vanishing.

Terminal checkpoints are the optional half: a bounded slice of scrollback per session, so a recovered row is readable rather than merely present. Setting the checkpoint size to zero keeps the registry - which is the part that brings sessions back - and stores no terminal bytes.

A session can be attached from the desktop and the phone at once. Exactly one connection may write, and the terminal size is arbitrated rather than fought over, so a phone attaching does not reflow a desktop pane. Which device counts as the one you are at is decided once, application-wide, rather than guessed separately by each feature.

A named shell or agent launch: which executable, which arguments, which working directory. A WSL distro shell is a profile like any other. Profiles are edited in Settings, Harnesses and listed by mux profiles.

The WSL agent bridge reports whether the distro can actually reach the daemon rather than assuming it. Its failure mode is silence by construction - a bridged agent that cannot reach the daemon runs perfectly and simply never reports - so the reachability probe is not decoration.

A session whose process exited does not disappear from the sidebar. It stays as a readable, resumable row, because the thing you most often want after an agent finishes is to read what it did.