Answer a held read by its cloud9 ticket, refuse a second, and say a pane shut down

The held read is now kept by the Ticket cloud9's Conn.hold() gives its
park and answered through Conn.answerWith(), which makes the answer only
while that very park still waits, instead of walking the engine's slots
by tag; pardes no longer reaches into the engine for it. A second read on
an open whose read is held fails with file in use rather than sitting
parked where nothing answers it, and a read that waits with no open
record to hold it is logged and asserted on. A read on an event or
pty/data open whose pane closed answers acme's "window shut down"
(editors/acme/xfid.c:1005). The pane keeps its run's and its lock's open
handles, checked through openOf on use, not record indices. Docs: lock
from a shell needs a held fd, and a command that clears the screen may
read as cut.

Needs cloud9 zvuqvnzy (cca47d63), which adds Conn.hold, waiting and
answerWith; build.zig.zon still pins 82d8152c until that is pushed and
re-pinned.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 16 insertions, 7 deletions

diff --git a/docs/fs.md b/docs/fs.md
index c5c5b2e0..da4f4e68 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -161,7 +161,10 @@ it: a `lock` while another open holds it waits until that open writes
 `unlock` or closes (or the pane does), and nothing else is refused for it --
 not a write to any other file, not the person at the keyboard. It belongs to
 the open that wrote it, so only that open's `unlock` is taken; a write on an
-open that cannot write (or the editor's own, on none) cannot lock.
+open that cannot write (or the editor's own, on none) cannot lock. From a
+shell the lock needs an open held across the edit, since `echo lock > ctl`
+closes, and so unlocks, at once: `exec 3>ctl; echo lock >&3; ...edits...;
+exec 3>&-`.
 
 The three range files `addr`, `dot` and `limit` each read the pair of offsets
 they also accept, so copying one onto another is all that acme's `addr=dot`,
@@ -207,11 +210,15 @@ A read with nothing to give yet -- a following `log`, `event`, `pty/data`, a
 `pty/run` before its answer -- is held, the way factotum holds its log's reads
 (security/auth/factotum/log.c) and acme an event read: the core keeps it, and
 whoever next has news for it (a record, output, a run's answer, the pane
-closing, which answers "No such file or directory") answers it on the connection it
-came on as the turn is given up. Nothing else parked is retried for it. A
-read the client flushed meanwhile is dropped unanswered, so no record is
-spent on it. An open waits with one read at a time, as acme's window keeps
-one `eventx`. QUIC connections still retry their parked reads each tick.
+closing, which answers acme's "window shut down") answers it on the
+connection it came on as the turn is given up. Nothing else parked is
+retried for it. The core keeps the ticket cloud9 gave the park
+(`Conn.hold`) and answers only while that very park waits, so a read the
+client flushed or whose fid it clunked meanwhile is dropped unanswered, no
+record is spent on it, and a tag the client reuses is never answered with
+what was meant for the old one. An open waits with one read at a time, as
+acme's window keeps one `eventx`; a second read on it meanwhile fails with
+"file in use". QUIC connections still retry their parked reads each tick.
 
 `pty/run` runs one line at a terminal's prompt and answers how it ended, on
 the same open (factotum's `rpc` shape): write the line, then read `exit N`
@@ -226,7 +233,9 @@ printed before its PROMPT_COMMAND lands in the next run's output. Only its
 last 64 KiB are kept, from a line start, and the header then reads `exit N
 cut M` (M bytes left out). `exit N cut`, with no count, says the output's
 start is not there to read: it scrolled out of the history, the command
-erased it (`clear`, a reset), a start or end mark came on the alternate
+erased the screen (`clear`, `watch`, a full-screen program's redraw, a
+reset -- so such a command's output may read as cut), a start or end mark
+came on the alternate
 screen, or the command printed more than 8192 rows, of which only the last
 are read so that the answer costs the editor a bounded amount. `exit ?` is a
 command whose end mark carried no status, which is not a success; `error out