Make a pane by opening /pane/new, and a Plan 9 idiom pass

The Tcreate that replaced acme's /new was a step away from the idiom dressed
up as a step toward it. A pane is named by a server-assigned serial, so the
create ignored the client's name: `mkdir /pane/foo` succeeded and left you
/pane/12. A mkdir that does not make the directory you named is worse than the
read-with-side-effect it replaced, and it broke in the shell workflow that
motivated the change. `create` is out of the declared features, so Tcreate is
EPERM again; Tremove stays, since `rm` to close a pane is unambiguously right.

/pane/new is now opened, not created: the open makes the pane, the read of
that fid answers its serial, two reads agree, and closing it leaves the pane.
That is /net/tcp/clone's mechanism (kernel/network/ip/devip.c, in ipopen),
not acme's, and the difference is deliberate. acme allocates during the walk
and lands inside the new window, so /dev/new/body works in one step, and it
can afford to list `new` because a Plan 9 directory read carries every entry's
stat and nothing walks. A kernel or FUSE mount walks and stats each name a
listing gave it, so allocate-on-walk would make a pane per `ls -l`. Allocating
on open keeps `new` listed -- a stat is not an open -- at the cost of the
one-step new/body. `new` stays unreachable from an editor path, because that
resolution serves Look hover previews.

The idiom pass behind it, read out of the Plan 9 tree at
~/05-genizah/principia-softwarica rather than recalled:

Rerror carries a string, not an errno (man 5 error: `ename[s]`), and acme
names every refusal. The five refusals pardes shares with acme now say what
they mean; the generic sites keep their bare errno rather than invent strings
acme does not have. body and tag declare DMAPPEND, which they had always
behaved as (acme(4): "always appended; the file offset is ignored"), checked
first against Linux's fs/9p, which never maps the bit. excl stays unset
everywhere, because acme sets DMEXCL on nothing. Blocking reads, per-object
addr scope and the readable pane ctl were already right. Real stat sizes and
qid versions stay: acme reports length 0 and version 0 for everything, and
Linux clients need better.

One bug fell out of it. open reset the addr range, so `echo '#0,#5' >addr;
cat addr` answered `0 0` and `cp addr dot` copied zeros. acme(4) makes the
contract explicit -- "a regular expression may be evaluated by writing it to
addr and reading it back" -- and acme gets away with resetting on the 0-to-1
open only because its clients hold the fid across both. A shell cannot: that
is two opens. The register is cleared by truncating it now.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

1 files changed, 9 insertions, 0 deletions

diff --git a/docs/v9fs.md b/docs/v9fs.md
index 8cc97ff9..1b14c21f 100644
--- a/docs/v9fs.md
+++ b/docs/v9fs.md
@@ -13,8 +13,17 @@ cat "$PARDES_MOUNT/index"
 cat "$PARDES_MOUNT/README"
 cat "$PARDES_MOUNT/pane/$PARDES_PANE/body"
 echo 'Msg hello' > "$PARDES_MOUNT/exec"
+awk '{print $1}' "$PARDES_MOUNT/pane/new/ctl"
 ```
 
+Walking to `pane/new` opens a pane, and the walk lands on that pane's own
+directory, so its `ctl` answers the serial to use afterwards. The kernel keeps
+the name it walked rather than the one the server answers back, so
+`pane/new` stays in the dentry cache as a name of its own; address the pane as
+`pane/<serial>` once you have it, and expect a fresh path resolution of
+`pane/new` to open another pane. It is not listed in `pane/`, so `ls -l` and
+`find` over the mount create nothing.
+
 The mount belongs to that pane's subprocess tree. Other panes and the editor
 core keep their original mount namespace. It works in native Linux TTY and SDL
 sessions, including detached sessions. A frontend attaching from elsewhere does