summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 10:48:56 -0300
committerGabriel Schneider <[email protected]>2026-10-29 12:13:25 -0300
commit9be47b76e4edf4ddb56e4d572c14b54bf45fdd39 (patch)
tree602d0943dc1c48bb4e90a7f9d9de16e541cdb981
parent5c23bd8b1bbdbbacd99b11e75d38f7ce1801cd8a (diff)
downloadpardes-9be47b76e4edf4ddb56e4d572c14b54bf45fdd39.tar.gz
pardes-9be47b76e4edf4ddb56e4d572c14b54bf45fdd39.zip
docs: the daemon, Detach, --attach and Adopt; phase 3 notes in docs/next-daemon.md
building.typ's detached sessions are the daemon and its sessions; the guide, cheatsheet and reference say what Detach, a closing terminal, --attach of each kind and Adopt do, and that attaching from another machine waits for phase 5. docs/next-daemon.md records the forks taken (sessions register and are not the daemon's children, and why; how it starts; masters; Adopt as a word; the stub's signals and job control; --detach; the Attach word; the harness switch), the known gaps, and the termios trap. Co-Authored-By: Claude Opus 5.5 <[email protected]>
-rw-r--r--docs/next-daemon.md98
-rw-r--r--docs/typ/building.typ51
-rw-r--r--docs/typ/reference.typ22
-rw-r--r--src/CHANGELOG.md23
4 files changed, 163 insertions, 31 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index 8bc9b38c..d164eced 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -169,3 +169,101 @@ open.
terminal's scope ever kills it]
5. The join writer: a fork child, or a metadata copy serialised on a
worker. [fork first, measure the page-table copy]
+
+## Phase 3 notes
+
+Built 2026-10-29 (`src/daemon.zig`, the tty and GUI hosts, `main.zig`).
+Decisions taken at the forks, with the ponytail lens:
+
+- **Sessions are not the daemon's children; every one registers.** The
+ design had the daemon spawn a terminal's session from the fd, cwd, env
+ and argv the stub passes. That proved wrong here:
+ - the user's terminals each run in a `9ns --mntgen` user and mount
+ namespace (`unshare(CLONE_NEWUSER|CLONE_NEWNS)`); a session the daemon
+ spawned would run in whichever namespace the daemon was started from,
+ its `/mnt/9p` served by a 9ns that may be gone. Its cgroup, rlimits,
+ umask and stdin (`pardes -`) would be the daemon's too, or have to be
+ carried and re-execed;
+ - startup would pay an IPC round trip and an exec of a 100+ MB binary;
+ - the snapshot harness's idleness probe walks the launched process's
+ tree, and a daemon-spawned session is outside it.
+
+ So `pardes` in a terminal forks its session off itself before anything
+ starts (`daemon.forkSession`): the child calls `setsid` and draws on the
+ `/dev/tty` the parent opened; the parent stays as its stub. GUI windows
+ and `--detach` sessions just register. The daemon spawns nothing, so it
+ is no subreaper: a detached session is reparented to the system's reaper
+ (systemd --user or init), which reaps it, as it reaps a crashed
+ session's shells. Nothing dangles: the daemon lists every session (its
+ connection) and holds every master, and exits a second after it holds
+ neither.
+- **Starting the daemon.** The first session takes the flock, binds and
+ listens itself and queues its own connection; `pardes --daemon` is then
+ double-forked and exec'd onto that listener and lock (fds 3 and 4), by
+ a terminal's stub after the session's fork, so no session waits for it:
+ its hello sits queued until the daemon runs, and is not waited on (the
+ daemon's `ok` is the reader thread's; Detach waits for it, up to 2 s).
+ With the spawn before the fork, a cold start measured +0.38 ms (+7.6%).
+ The daemon's reader thread likewise starts after the first frame.
+ Another starter waits on the lock; a stale socket is the lock holder's
+ to replace. Messages are `SOCK_SEQPACKET` datagrams, a line of words and
+ the fds it carries.
+- **pty masters.** `forkShell` sends a dup; a host's close sends `close`;
+ a session's end sends `quit` (its shells hang up); a master whose shell
+ is gone (`POLLHUP`, polled with no events) is dropped. TERM, HUP and INT
+ handlers send `quit` too (one `send`, async-signal-safe), so only a
+ session killed outright or crashed leaves shells behind.
+- **Adoption is a word, `Adopt`,** calling the host through a vtable entry
+ (no Effect): the daemon hands over every orphaned master, and each
+ becomes a pane through the `Tty` word, its spawn taking the pty instead
+ of forking; a 1x1 size then the pane's makes it redraw. Adopting at
+ startup was rejected: an `EDITOR='pardes --wait'` session would take the
+ shells and hang them up when the editor exits.
+- **The stub.** It forwards WINCH, TERM, INT, QUIT and HUP by `kill`, and
+ ends with the session's status (a forked stub `waitpid`s; an attaching
+ one reads `x<code>`). A HUP is the terminal's end: kept by a daemon, a
+ session takes HUP on its signal thread (sigwait, beside WINCH) and
+ detaches, as on EIO; HUP never ends a kept session, since the terminal's
+ own EIO and HUP arrive in either order. Ctrl-Z stays a key for the pane
+ (the terminal is raw, as before); a TSTP sent to the stub is ignored,
+ since a stopped stub hands the terminal back under a session still
+ drawing; a background start stops at a `tcsetattr` before the fork, as
+ the old raw mode did. `--wait`, nested forwarding and `--tty` run before
+ any of this and are unchanged.
+- **`--detach` is a session started detached:** the tty host with no
+ terminal, the GUI with a hidden window closed at once. With the frames
+ gone, `detached/server.zig` was a third host with nothing left to do
+ that the other two could not.
+- **`Attach` (the word) is deleted:** it switched a session's own terminal
+ to another session through the frames.
+- **Harnesses.** `PARDES_DAEMON=off` (the e2e harness sets it) runs a
+ session as before: in the terminal's own process, ended by its hangup,
+ for a harness that kills by pid and closes the terminal. A GUI test
+ window (`PARDES_TEST`) has none unless `PARDES_DAEMON=on`.
+- **Known gaps.** A stub killed with SIGKILL while its terminal stays open
+ leaves the session drawing there until the terminal closes or Detach. A
+ reattached terminal keeps the first one's environment (TERM, COLORTERM);
+ vaxis queries its capabilities again. A daemon killed outright leaves
+ its sessions unregistered, and Detach then refuses. A daemon of an older
+ protocol answers `version`, and a session then runs without one. A
+ GUI started in a terminal's foreground stays that terminal's job.
+
+Measured (ReleaseFast, base main a7369739 against these changes, both
+live at once and their samples alternating A, B, A, B; A/A the base
+against itself; p50 ratio new/base):
+
+| | tty | A/A | GUI (test mode) | A/A |
+|---|---|---|---|---|
+| startup, no daemon running | 1.017 (4.73 to 4.81 ms) | 0.998 | 0.982 (295 to 290 ms) | 0.999 |
+| startup, daemon running | 1.014 (4.66 to 4.72 ms) | | 1.014 (noisy) | |
+| key in a file, to its frame | 0.992 | 1.009 | 1.003 | 0.986 |
+| key echoed by bash, to its frame | 1.016 | 1.005 | | |
+
+What is left of the tty's startup is the stub's fork (about 70 us), which
+the design cannot do without: the job the shell waits on must be able to
+end while the session runs on.
+
+Trap found on the way: glibc's `tcgetattr` writes its 60-byte `struct
+termios` into Zig's `std.c.termios`, which is 44 (the kernel's layout),
+and overran the stack, clobbering a neighbouring local in the forked
+child; `std.posix.tcgetattr` (an ioctl on that layout) is the right one.
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index d551c251..152be838 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -1,6 +1,6 @@
// Building pardes, for contributors: platforms, options, tests, the
// release gates and sending patches, then how the pieces fit: the core
-// and its shells, the threads, detached sessions, the 9P engine, the
+// and its shells, the threads, the daemon and its sessions, the 9P engine, the
// listeners and mounts.
#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
@@ -177,8 +177,9 @@ Code map: `src/panes.zig` and the pane kinds it names (`src/File.zig`,
`src/Terminal.zig`, ...), `src/layout.zig`, `src/fs.zig` (host access,
mounts and resolution) and `src/pardes.zig` (input), with one file per
thing beside them (`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`,
-`mouse.zig`, ...). `src/ninep/` is the control tree, `src/detached/` the
-wire, the detached core and the frontend client, `src/lsp/` the
+`mouse.zig`, ...). `src/ninep/` is the control tree, `src/daemon.zig` the
+per-user daemon and a terminal's stub, `src/detached/wire.zig` the input
+wire a remote client will speak, `src/lsp/` the
language-server client; `test/` holds harnesses, goldens and helix cases,
`build/` the snapshot suite's build step.
@@ -197,26 +198,34 @@ reading the live core, and a request id, the pane's serial and (for an
edit) the file's revision reject a stale reply. A process that never calls
`turn.start` (the tests, the ESP32-P4, the browser) has no second thread.
-== Detached sessions
+== The daemon and detached sessions
-One poll loop in `src/detached/server.zig` owns core mutation, frontend
-connections, pty I/O and file watches. The frontend socket is
-`pardes-detached-<name>.sock` beside the session's 9P socket; a second
-session cannot take a live name. Up to 32 frontends attach; frames go to
-every one, while clipboard reads, browser opens and #word("Detach") go to
-the frontend that asked (else the first attached). Frames are full grids
-or changes against what each frontend last received, never queued: a
-frontend with unsent bytes skips that frame, and one that stops draining
-past 1 MiB of control backlog is closed, its peers untouched. Frontends
-never spawn shells, write session files or watch files. #word("Attach")
-connects first and swaps second: only after the handshake does a shell
-give up its own core. #word("Restore") builds the replacement core before touching
-the current one.
+One `pardes --daemon` per user (`src/daemon.zig`) listens on
+`pardes-daemon.sock` in the runtime directory, its `.lock` flocked for its
+life; the first session that finds none starts it (a double fork and an
+exec) and it exits a second after it holds nothing. It is nobody's parent:
+a session registers on one connection, sends it a dup of every pty master
+it forks (so a session killed outright never hangs its shells up, and
+#word("Adopt") takes them into another), says whether a terminal or a
+window shows it, and is handed a terminal (`pardes --attach`) or a window
+request (`pardes-gui --attach`) through it. Messages are `SOCK_SEQPACKET`
+datagrams: a line of words and the fds it carries.
-`src/detached/wire.zig` is the versioned protocol (version 10): fixed-width
-little-endian fields, a 5-byte header (tag, then a u32 length), payloads up
-to 16 MiB and grids up to 512 by 128. A comptime hash of `pardes.Chrome`
-forces a version bump when that struct changes.
+`pardes` in a terminal forks its session off before anything starts: the
+session, in a session of its own (`setsid`), draws on the terminal it
+opened, and the process the shell waits on stays as its stub, passing it
+`SIGWINCH`, `SIGTERM`, `SIGINT` and `SIGQUIT` and ending with its status.
+#word("Detach"), or the terminal's end (EIO, a hangup), puts
+the terminal back and lets it go; the stub ends (exit 0) and the session
+runs on with nothing drawn, until `pardes --attach` hands it another
+terminal. A window's #word("Detach") closes the window and keeps the
+process; `pardes-gui --attach` opens one again. `PARDES_DAEMON=off` (the
+snapshot harness) runs a session as before the daemon: in the terminal's
+own process, ended by its hangup.
+
+`src/detached/wire.zig` is the input half of the protocol a remote client
+will speak (version 13): fixed-width little-endian fields, a 5-byte header
+(tag, then a u32 length), the hello and its version, the input events.
= 9P
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index b83b4a83..c95a574a 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -386,9 +386,9 @@ Writes take settings and session builtins (`scope = .session` in
record for why. A #word("ThemeFile") the dump names that fails to load changes
nothing.
- #word("Kill") `[word...]` (above), #word("Mount") `name dial`, #word("Unmount") `name`, #word("Theme") `x`.
-- `size C R` sizes a `--detach` session no frontend is attached to (160x50
- until then): from 20x6 to 4096x4096, else `invalid size`; refused while a
- frontend owns the size, and when a column would lose its panes' minimum
+- `size C R` sizes a session no terminal or window is attached to (160x50
+ for a `--detach` one until then): from 20x6 to 4096x4096, else `invalid
+ size`; refused while a terminal or window owns the size, and when a column would lose its panes' minimum
rows (`size: too small for the panes, each its tag and 2 rows`). A bad
`size` is refused quoting the value it got (`"5 2"`).
@@ -454,8 +454,7 @@ turning it off: #word("PanelSlide"), #word("PanelZoom"),
#word("PanelDissolve"), #word("PanelAscii"), #word("PanelVertical"),
#word("PanelEdges"), #word("PanelFall"), #word("PanelWave"),
#word("PanelCurtain"), #word("PanelScramble"), #word("PanelType"); all
-start off, and the web shell has none. Scene passes (the SDL window, and
-one attached to a detached session), each at a level 0-3 (`on` is 2), all
+start off, and the web shell has none. Scene passes (the SDL window), each at a level 0-3 (`on` is 2), all
off: #word("Crt"), #word("Bloom"), #word("Vignette"), #word("Grain").
#word("Shader") `<file.glsl>` adds a Shadertoy file written for ghostty to the
chain (#word("Shader") `off` removes it; it recompiles when saved);
@@ -1011,11 +1010,14 @@ to its end before the write is answered, and one that finds nothing fails,
git's `a/` `b/` (and `c/ i/ w/ o/`) prefixes are dropped; a
`--no-prefix` diff's paths are kept.
- *Sessions.* Bare `--detach` names the session after its pid; bare
- `--attach` needs exactly one session; a second `--detach=NAME` while NAME
- runs (a plain session is named by its pid) says so in words and exits 1. Frontends share the smallest common size. With
- none attached, `size C R` sets the screen, messages clear by the clock,
- and a pty reports its size in pixels at the last frontend's cell size
- (8×16 before any), as CSI 14, 16 and 18 t do.
+ `--attach` needs exactly one detached session of its kind (a terminal's
+ for `pardes`, a window's for `pardes-gui`); a second `--detach=NAME`
+ while NAME runs (a plain session is named by its pid) says so in words
+ and exits 1. One terminal or window shows a session at a time. With none
+ attached, `size C R` sets the screen, messages clear by the clock, and a
+ pty reports its size in pixels at the last cell size (8×16 before any),
+ as CSI 14, 16 and 18 t do. Attaching from another machine is gone until
+ the replicated clients (docs/next-daemon.md, phase 5).
- *Config.* The startup file is `$XDG_CONFIG_HOME/pardes/init` when that is
absolute, else `~/.config/pardes/init` (macOS:
`~/Library/Application Support/pardes/init`). A line that fails is a
diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md
index 4466ad26..10cc451d 100644
--- a/src/CHANGELOG.md
+++ b/src/CHANGELOG.md
@@ -2,6 +2,29 @@
## Unreleased
+- One `pardes --daemon` per user keeps sessions, started by the first
+ session and gone once it keeps nothing. `pardes` in a terminal forks
+ its session off and stays as its stub: `Detach` (`SPC s D`), or a
+ terminal that closes, puts the terminal back and leaves the session
+ running in place (no fork of the core, no dump), and the stub ends.
+ `pardes --attach[=name]` in any terminal takes it back there. A
+ window's Detach closes the window and keeps the process;
+ `pardes-gui --attach[=name]` opens it again. A terminal session takes a
+ terminal and a window session a window, and the other is refused in
+ words. The daemon holds a dup of every shell's pty: a session killed
+ outright leaves its shells running, and `Adopt` in another session
+ takes them in as terminal panes (what they showed is gone; a resize
+ makes them redraw). A hangup never ends a session the daemon keeps (it
+ is the terminal's end); TERM and INT do, its shells with it.
+ `PARDES_DAEMON=off` runs a session as before.
+- The frame wire goes: `src/detached/server.zig`, `client.zig` and the
+ cell frames of `wire.zig`, the frontends that drew a session's screen
+ from them, the smallest-common-grid rule, and the `Attach` word that
+ switched a session's own terminal to another. A `--detach` session is
+ now a terminal (or window) session with none attached yet. Attaching
+ from another machine is gone until the replicated clients
+ (docs/next-daemon.md, phase 5); `wire.zig` keeps the framing, the hello
+ and the input events for them.
- One PNG and one JPEG decoder in a binary: images decode through wuffs,
the decoders ghostty uses (ghostty-vt already links them), and stb_image
keeps only the other formats. stb's own inflate and image writer go, as