An Edit filter that can never be reaped no longer holds the Edit's answer: at the limit the command's group is killed and reaped off the answer's path, the stdin writer owning its input, so a filter writing its own ctl with > or >> answers EIO at 10 s instead of hanging; a running Edit keeps its own copies of the names it reports, and the panes it changes refuse Del, delete, rmdir, Undo, Redo, Get and Zerox (busy, EBUSY); e and r say unreadable files in Get's words; the reference says both sides of a filter's own ctl write need <>

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

1 files changed, 13 insertions, 3 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index ed88905a..52a128cb 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -714,13 +714,23 @@ Each command runs in its file's directory through #word("Shell"), off the
 loop, so the editor goes on, with what a pane's command is given:
 `$PARDES_MOUNT`, `$PARDES_9P`, `$PARDES_PID`, and `$winid` the Edit's pane. The write that ran the Edit is held and
 answered when they are done, its connection serving other requests
-meanwhile (a command may read the session through its mount; one that writes the #file("ctl") its Edit came by must not truncate it, `1<>ctl` rather than `>ctl`, as Linux holds the inode lock through an O_TRUNC open and the write waits out the 10-second limit); a flush of
-that write (an interrupted writer) kills the commands and changes nothing.
+meanwhile (a command may read the session through its mount). A command
+that writes the #file("ctl") its Edit came by needs `<>` on both sides, the
+Edit's write (`exec 3<>$p/ctl; echo 'Edit ...' >&3`) and its own (`1<>`):
+with `>` or `>>` on either, the kernel holds the second write until the
+first is answered, the command is stopped at its 10-second limit, and the
+Edit fails (EIO), changing nothing. For the same reason a second Edit written
+with `>` to that #file("ctl") waits for the first to finish rather than being
+refused; through its own `<>` open, or another pane's #file("ctl"), it is
+refused `busy` (EBUSY) at once. A flush of the Edit's write (an interrupted
+writer) kills the commands and changes nothing.
 Such an Edit is a write of its own: one with other lines is refused before
 any runs. One Edit's commands run at a time in a session, at most 1024 of
 them. While they run, an Edit with no commands runs as usual unless it
 would change, undo, rename, close or write a file the running one changes;
-that, and a second Edit with commands, is refused `busy` (EBUSY). A command that fails (an exit status, 10 seconds, 1 MiB of output)
+that, and a second Edit with commands, is refused `busy` (EBUSY), as are
+#word("Del") (acme's `delete`), `rmdir`, #word("Undo"), #word("Redo"), #word("Get") and #word("Zerox") on a pane
+it changes or runs a command on; a session that ends lets the commands go. A command that fails (an exit status, 10 seconds, 1 MiB of output)
 fails the Edit, its stderr in `+Errors`. Each file's changes are one undo step, applied only if
 every command succeeds; a failure changes nothing and fails the write with
 acme's words (`Edit: no substitution`), as does a file edited while the