# Detached sessions

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

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

Bare `--detach` names the session after its process ID. Bare `--attach`
requires 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 the current window to
that session. `Detach` (`SPC s D`) closes only that frontend. It does not
turn a local editor into a detached session.

## Files and transport

The frontend socket is `pardes-detached-<name>.sock` under
`$XDG_RUNTIME_DIR`, or `~/.local/state/pardes` when no runtime directory is
set. A second session cannot replace a live listener with the same name.
Shared Unix socket handling lives in `src/9p_io.zig`.

The session also opens its default 9P socket. Optional TCP and QUIC listeners,
runtime mounts and the control filesystem belong to the session, not its
frontends. See [fs.md](fs.md).

## Ownership

One poll loop owns all core mutation, frontend connections, PTY I/O and file
watch notifications. LSP and selection-pipe workers own request snapshots and
post completions through a bounded mailbox. Each subprocess is reaped by its
owner; PTY reaping cannot consume a language server or filter's exit status.

Restore constructs a replacement core before changing the current one. It then
joins old work, clears obsolete completions, replaces panes and watches, and
sends a fresh frame to the existing frontends.

Frontends provide input and presentation. Clipboard writes are broadcast;
clipboard reads, browser opens and Detach go to the originating frontend,
falling back to the primary attachment. Frontends never spawn pane shells,
write session files or install file watches.

## Wire and tests

`src/detached/wire.zig` owns the versioned frontend protocol. Frames are full
grids or changes relative to each frontend's last queued frame. A new
attachment receives a full grid. Output queues and per-poll work are bounded;
a lagging frontend cannot hold the session's event loop.

`zig build unit-test` covers encoding, session ownership, real frontend
connections, worker completion and Restore. `zig build fs-test` drives
detached sessions through an independent 9P client. The snapshot suites also
exercise attach, detach and shared screen behavior.