# 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. Protocol version 6
also carries the pointer shape, compact source-context body layers, source-gap
separators and independently sized tag text. Pointer
updates work even when no grid cells change, and graphical clients use the
same compact row and tag geometry for drawing and mouse input. Tag text positions
are separate from physical pane and drag-handle coordinates. Terminal clients retain
the ordinary fixed grid.

`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.