docs: data's truncation is pardes's own, a second write inserts, and a waiting pty/run is cancelled

Review asked the docs to say what a script trips on: acme ignores OTRUNC on
data (fsys.c:543), so truncating it is an extension; addr sits past each write,
so a second echo x > data inserts after the first; and a pty/run line waiting
for a fresh terminal's first prompt waits for ever if none is drawn, so the way
out is to interrupt the read. The lock's retry advice was already there.

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

1 files changed, 9 insertions, 2 deletions

diff --git a/docs/fs.md b/docs/fs.md
index bd8ca055..7d0e797c 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -265,7 +265,11 @@ it is set. Truncating a range file empties it; truncating `limit` lifts it.
 Truncating `data` or `xdata` deletes the range `addr` names and nothing
 else, so a shell's `echo NEW > data` replaces that range, `: > data`
 deletes it, and `>>` inserts at it; only truncating `body` empties the
-whole buffer.
+whole buffer. Truncating `data` is pardes's own: acme ignores OTRUNC there
+(editors/acme/fsys.c:543) and every write inserts. And as in acme a write
+leaves `addr` just past what it wrote, so a second `echo x > data` deletes
+the empty range there and inserts after the first rather than replacing it
+again; write `addr` before each replacement.
 `addr` belongs to the pane rather than to a client and keeps what was written
 until someone writes or truncates it, so writing an address and reading it
 back evaluates it, which is what acme(4) promises of its own `addr`.
@@ -389,7 +393,10 @@ which is also when the third field of `pty/status` reads 1. A line written
 before a new terminal's shell has drawn its first prompt is not busy: it
 waits for that prompt (a respawn meanwhile keeps it waiting for the new
 shell's) and is sent then, so the first command a script gives a fresh
-terminal is not lost; `error not run` when the shell refused
+terminal is not lost. A shell that never draws a tagged prompt (one pardes
+could not instrument, or a startup that hangs) leaves such a line waiting
+for ever: cancel the read (interrupt it, or close the open) to give up;
+`error not run` when the shell refused
 the line without running it (a fish syntax error; the line is taken back off
 the prompt); `error shell gone` when the pane closed or its shell was
 replaced; `error no prompt marks` for a shell pardes could not instrument.