acmefs: a pane's terminal gets pty/data, pty/ctl and pty/status

Step 3 of the 9P chain (docs/9p.typ 12.3, docs/registry.typ 9P-8). Nothing here
is about 9P: it lands in the FUSE-served tree and any later transport inherits it.

A script could write into a terminal that already existed and read its rendered
scrollback. It could not START one, RESIZE one or SIGNAL one. Two of those were
already effects the core emits, so `exec` and `winsize` are existing
capabilities acquiring a name; only `sig` is new, and it brings the one new
host method, `push_pty_signal`.

  pty/ctl     winsize <cols> <rows> | sig INT|TERM|HUP|QUIT|KILL | exec
              one verb per line, validate-all then apply-all, EINVAL applies
              nothing -- `writeCtl`'s shape and `writeCtl`'s reason
  pty/status  cols, rows, tty-taken as three %11d fields
  pty/data    write is input to the process; read is the RAW output stream,
              gated on a reader count so a pane nobody reads costs one branch

A pane that is not a terminal has no pty/ at all: the lookup is ENOENT and
readdir does not list it.

`PaneFile` is an enum(u4) and this takes it from 11 values to 15. ONE REMAINS.
That is also why pty/ is a DIRECTORY and not three more flat names -- a
subdirectory costs one value and buys its own namespace, so `ctl` and `data`
did not have to be renamed.

Two things the core does not know, and which are therefore not invented: a
child's EXIT STATUS (a shell's death is `Event.eof`, which removes the pane,
so there is no directory left to read it in) and RAW/COOKED (the core never
sets a termios; the mode belongs to the program on the far side).

Verified live against a daemon: pty/ appears only on the terminal pane; a
`winsize 0 24` and a `sig SIGINT` are refused; a bad verb beside a good one
applies neither; `echo pty-works` written to pty/data runs in the shell and its
output reaches the body; and a blocking read of pty/data returns the raw stream,
OSC 133 marks and all. fs-bench unchanged and still zero allocations.

1 files changed, 55 insertions, 1 deletions

diff --git a/docs/acme-fs.md b/docs/acme-fs.md
index 15f45c4f..25cbcc2d 100644
--- a/docs/acme-fs.md
+++ b/docs/acme-fs.md
@@ -3,7 +3,8 @@
 `pardes --fs` serves plan9 [acme(4)](https://man.cat-v.org/plan_9/4/acme)'s control
 filesystem over Linux FUSE: a directory per pane, named by the pane's serial and
 holding `addr`, `body`, `ctl`, `data`, `errors`, `event`, `rdsel`, `tag`, `wrsel`
-and `xdata`, plus `index`, `cons` and `new/` at the root (`PaneFile` and
+and `xdata`, plus a `pty/` directory on a terminal pane, plus `index`, `cons`
+and `new/` at the root (`PaneFile` and
 `TopFile` in `src/acmefs.zig`). A program that opens those files IS an editor
 extension — no plugin API, no embedded interpreter, no rebuild.
 `examples/acmefs/` has four of them: `clock.py`, `eventlog`, `life.py` and
@@ -368,6 +369,59 @@ has no `log` either; it is a plan9port addition. No example needed it, and a
 script that wants to notice panes it did not open reads `index`, which is what
 acme gives it.
 
+## What is served that acme does not have: `pty/`
+
+One directory, three files, and **no prior art anywhere**: acme has no terminals
+and `ad` — the other editor that serves a control filesystem over 9P — has no
+terminal surface at all (its tree is `{ctl, minibuffer, scratch, log,
+buffers/…}`). So there is nobody's mistakes to learn from and nobody's scripts
+to keep compatible, which is the argument for keeping it to three files and
+stopping.
+
+A pty is a file interface wearing the wrong clothes: everything one wants to do
+to it is an `ioctl`, and neither 9P nor FUSE has one. They become writes.
+
+| ioctl | here |
+|---|---|
+| `TIOCSWINSZ` | `winsize 80 24` → `pty/ctl` |
+| `kill` | `sig INT` → `pty/ctl` |
+| spawn | `exec` → `pty/ctl` |
+| `TIOCGWINSZ` | read `pty/status` |
+| `read`/`write` | `pty/data` |
+
+Two of the three verbs are effects the core already had — `push_spawn` and
+`push_pty_resize` — so `exec` and `winsize` are existing capabilities acquiring
+a name. `sig` is the one new host capability in the whole directory
+(`push_pty_signal`, and there was no `kill` anywhere in `host_io.zig` before
+it); it targets the tty's foreground process group rather than the shell's pid,
+because an interactive shell ignores SIGINT while it waits for a job.
+
+The directory is **absent** on a pane that is not a terminal, rather than
+present and refusing, so `test -d <id>/pty` is how a script asks what kind of
+pane it has. `pty/data`'s read is the only new state: the core keeps no raw pty
+bytes anywhere (they go into the emulator grid, which is a rendering and cannot
+be turned back into a stream), so they are queued as they arrive — gated on a
+reader count exactly as `event` is, so a pane nobody is reading costs one
+branch and no memory, and capped drop-oldest by the same `queue_cap`. Unlike
+`event`, a read smaller than one arrival is SERVED and the remainder kept: raw
+bytes have no record framing to split down the middle.
+
+Three things it deliberately does not have. There is no **exit status**,
+because the core does not track one: a shell's death arrives as `Event.eof`,
+whose whole handler is `removePane`, so by the time anyone could read a status
+the directory is gone. There is no **`raw`/`cooked`**, because the termios
+belongs to the program on the far side of the pty and it never reports one. And
+`exec` takes **no argv**, because `Effect.spawn` carries a pane and a cwd and
+has nowhere to put one — so `exec /bin/sh` is EINVAL rather than an argument
+accepted and silently ignored.
+
+`Node.file` is a `u4`. These four variants (`pty`, `pty_ctl`, `pty_status`,
+`pty_data`) take it to fifteen of sixteen used: **one value is left**, and the
+next file added to a pane's directory needs a wider field and therefore a new
+node-id layout. That is also why `pty/` is a directory rather than three more
+names beside `body` — a subdirectory costs one value and buys a namespace, so
+`ctl` and `data` did not have to be spelled twice.
+
 ## Reading order
 
 `src/acmefs.zig` (semantics; start at its header), `src/fuse.zig` (the wire),