# Detached sessions

A detached session owns the editor core, pane shells, files, undo history
and layout. TTY and SDL frontends join and leave without ending it.

```sh
pardes --detach=work &
pardes --attach=work
pardes-gui --attach=work
```

Bare `--detach` names the session after its pid; bare `--attach` needs
exactly one listening session. The detached process runs in the foreground
unless the shell backgrounds it. Inside an editor, `Attach work` (`SPC s a`)
switches this window to that session and `Detach` (`SPC s D`) closes only
this frontend.

With no frontend attached, `/ctl`'s `size C R` sets the screen (160x50 until
then; [fs.md](fs.md#the-root-ctl)), and messages clear after `MessageLinger`
on the clock, since no key will come to dismiss them.

## Files and transport

The frontend socket is `pardes-detached-<name>.sock` under
`$XDG_RUNTIME_DIR`, else `~/.local/state/pardes`, beside the session's 9P
socket `pardes-9p-<name>.sock`. A second session cannot take a live name.
TCP and QUIC listeners, mounts and the control filesystem belong to the
session, not its frontends.

## Ownership

One poll loop owns core mutation, frontend connections, PTY I/O and file
watches; LSP and selection-pipe workers post completions through a bounded
mailbox. Restore builds the replacement core before changing the current
one, then sends existing frontends a fresh frame. Frontends provide input
and presentation only: clipboard writes are broadcast; clipboard reads,
browser opens and Detach go to the frontend that asked (else the first
attached). Frontends never spawn shells, write session files or watch files.

## Wire and tests

`src/detached/wire.zig` owns the versioned frontend protocol (version 8).
Frames are full grids or changes against each frontend's last frame; a new
attachment gets a full grid. Queues are bounded, so a lagging frontend
cannot hold up the session.

`zig build unit-test` covers the wire, ownership, real frontend connections
and Restore; `zig build fs-test` drives detached sessions over 9P; the
snapshot suites exercise attach, detach and shared screens.