Run a line at a terminal's prompt through pty/run and read how it ended

/pane/<n>/pty/run takes factotum's rpc shape: write one line on an open,
read the answer on that same open. The answer is exit N once the command
ended and the shell is back at a prompt; busy at once when a command runs,
text is typed at the prompt, or the shell has not drawn its first prompt;
error not run when the shell refused the line without running it (fish on
a syntax error keeps it on the prompt, so it is taken back with Ctrl-U);
error shell gone when the pane closes or its shell is replaced; error no
prompt marks for a shell pardes could not instrument.

The end comes from the shell's OSC 133 marks. ghostty parses D's exit
status and drops it, so the stream now runs through a handler that wraps
ghostty's and follows prompt -> input -> running -> done. The marks pardes
injects into bash and fish carry aid=pardes and only those count, so fish
4's own marks (which doubled ours), a nested shell's, and a stray 133;D in
printed output are ignored.

Checked end to end against real bash and fish: false, exit 7, a syntax
error, sleep, busy while running, and the pane closing mid-command.

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

1 files changed, 16 insertions, 1 deletions

diff --git a/docs/fs.md b/docs/fs.md
index 9d95b36e..d46e3d21 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -194,7 +194,22 @@ Control characters in a record become spaces, so a record is one line. An
 open freezes the ring's text the way `/screen` freezes a frame: reads walk it
 and end. Writing `follow` to that same open makes reads past it park for the
 next record, one per read; a follower the ring outran reads `lost N` first.
-Closing the open is the only way back, as with rio's `consctl`. A record
+Closing the open is the only way back, as with rio's `consctl`.
+
+`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`
+once the command has ended and the shell is back at a prompt. It reads
+`busy` at once when a command is running, text is typed at the prompt or the
+shell has not drawn its first prompt; `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.
+It relies on the OSC 133 marks pardes injects into bash and fish, tagged
+`aid=pardes` so fish's own marks and a nested shell's are ignored. A second
+line on an open whose command still runs fails the write. `exec zsh` or a
+continuation prompt never reports an end; cancel the read. A read of `run`
+waits in pardes, so through 9ns it needs 9ns's concurrent requests or it
+holds up the rest of the mount. A record
 longer than a read comes in pieces, so a shell's `read` loop works. `tail -f`
 never writes `follow`, so it sees nothing new: use the follow open instead. `/screen` returns JSON with
 `cols`, `rows`, `cursor`, a `styles` table, and row-major `cells` of