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, 16 insertions, 0 deletions

diff --git a/examples/README.md b/examples/README.md
index 6112a696..aaaf5920 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -56,6 +56,8 @@ lines.
   new/           dir  looking up ANY name here creates a pane
   <id>/          dir  one per pane; id is the pane serial, never reused
     addr  body  ctl  data  errors  event  rdsel  tag  wrsel  xdata
+    pty/         dir  TERMINAL PANES ONLY; absent on a pane with a document
+      ctl  status  data
 ```
 
 | file | mode | semantics |
@@ -73,12 +75,26 @@ lines.
 | `rdsel` | r | the pane's current selection. |
 | `wrsel` | w | replaces the pane's current selection. |
 | `event` | rw | the pane's action stream, both directions. See below. |
+| `pty/` | dir | present only when the pane is a terminal, so `test -d $PARDES_FS/<id>/pty` is how a script asks. Absent — not empty — on a file pane, and every file under it answers ENOENT there. |
+| `pty/ctl` | w | newline separated verbs, several per write, applied all or nothing: `winsize <cols> <rows>`, `sig INT\|TERM\|HUP\|QUIT\|KILL`, `exec`. Anything else is EINVAL and applies nothing. |
+| `pty/status` | r | three `%11d` fields: columns, rows, and 1 while a program (vim, a pager, a build) holds the tty rather than the shell prompt. Seekable. |
+| `pty/data` | rw | the raw stream. A write is input to the program, offset ignored, short at a character boundary. A read hands back as much of the pending output as the count allows and keeps the rest — raw bytes have no records, so unlike `event` a small read is served rather than refused — and blocks while there is nothing. Output is only recorded while the file is OPEN. |
 
 `ctl` verbs: `addr=dot`, `clean`, `dirty`, `cleartag`, `del`, `delete`,
 `dot=addr`, `get`, `limit=addr`, `mark`, `nomark`, `name <name>`, `noscroll`,
 `scroll`, `put`, `show`. An unknown verb fails the whole write with EINVAL and
 applies nothing, so a batch is safe to send blind.
 
+`pty/ctl` verbs in detail. `winsize` is `TIOCSWINSZ` and nothing more: it tells
+the program a size and does not move the pane, whose grid is its rectangle on
+screen, so the next time you drag that pane the layout's size wins again.
+`sig` goes to the tty's foreground process group — what ^C would reach — and
+not to the shell, which ignores SIGINT while it waits for a job. `exec`
+respawns the pane's configured shell in the pane's own directory and takes NO
+argument: `exec /bin/sh` is EINVAL rather than an argument silently dropped.
+`raw` and `cooked` do not exist, because the termios belongs to the program on
+the far side of the pty and it never tells us.
+
 Addresses, all in bytes: `#n` an offset, `n` a line, `0` the start, `$` the
 end, `.` the selection, `a,b` a range (`,` alone is the whole body), `+` and
 `-` with a count or a regex, `/re/` forwards, `?re?` backwards. Anything else