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, 28 insertions, 12 deletions

diff --git a/docs/fs.md b/docs/fs.md
index 0bcc0313..8607a26f 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -79,19 +79,32 @@ Existing Plan9port/v9fs clients need a userspace bridge for QUIC.
 /log         one line per editor event: new|del|rename|save <serial> <name>; reads park
 /screen      rendered screen JSON; frozen per open handle
 /listeners   the session's dial addresses
-/pane/       create a directory here to open a pane; remove one to close it
+/pane/new    open it to make a pane; the read answers that pane's serial
 /pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll
              errors event look exec, plus pty/{ctl,status,data} on terminals
 /os/         the host filesystem
 /src/        the editor's embedded sources, only when built with -Dembed-sources=true
 ```
 
-Nothing in the tree is created by list, stat, walk or read. A pane is opened
-by Tcreate in `/pane` (`mkdir`) and closed by Tremove on `/pane/<n>` (`rmdir`),
-which is the only create and the only remove the tree serves. The name a
-create asks for is ignored, since a pane is named by the serial the editor
-gives it: the Rcreate qid names the new directory, and because `/index` is
-ordered by serial its last line is the pane just made.
+A pane is made by **opening** `/pane/new`, and closed by Tremove on
+`/pane/<n>` (`rmdir`), which is the only remove the tree serves; Tcreate is
+refused everywhere, as it is in acme. Reading the open fid answers the serial
+of the pane that open made, so `n=$(cat /pane/new)` makes one and names it in
+a line. Each open makes another pane, and two reads of one fid answer the same
+serial: the open acted, the read only observes. Closing the fid leaves the
+pane.
+
+This is `/net/tcp/clone`'s mechanism, not acme's `new`, and the difference is
+deliberate. acme allocates during the *walk* and lets the walk land inside the
+new window, so `/dev/new/body` works in one step (acme(4): "accessing any file
+in `new` creates a new window"). acme can also afford to list `new`, because a
+Plan 9 directory read carries the stat of every entry and nothing walks. A
+kernel or FUSE mount is not so lucky: it walks and stats each name a listing
+gave it, so an allocate-on-walk name would make a pane per `ls -l`. Allocating
+on open instead keeps `new` listed and `ls` honest — a stat is not an open —
+at the cost of acme's one-step `new/body`. Nothing in the tree is created by
+list, stat, walk or read; only that one open. Every other name in `/pane` is a
+serial.
 
 `/look` and `/exec` are the editor's two clicks, one per line of a write:
 
@@ -130,6 +143,9 @@ address expression (`#0,#5`, `/pattern/`, `2+1`); `addr` selects what `data`
 and `xdata` read or replace, `dot` is the editor's own selection and moving it
 scrolls the pane into view, and `limit` bounds a search and reads empty until
 it is set. Truncating a range file empties it; truncating `limit` lifts it.
+`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`.
 
 The three flag files `dirty`, `mark` and `scroll` read `0` or `1` and take
 `0` or `1`: whether the buffer differs from its file, whether a write pushes
@@ -164,8 +180,8 @@ enables the option by default, so the device can serve its own source.
 This is a control filesystem, not a complete POSIX export. Native filenames
 may contain up to 255 bytes. Existing regular OS files support read, write,
 and truncation to zero; under `/os` protocol create, remove, rename and other
-metadata changes are refused, as is every create and remove in the control
-tree but the pane directories. Ownership and permissions under `/os` are
+metadata changes are refused, as is every create in the control tree and every
+remove in it but a pane directory's. Ownership and permissions under `/os` are
 synthetic.
 Zero-length truncation accepts the accompanying `mtime` hint sent by Linux
 v9fs; the hint is not stored. Standalone timestamp changes remain refused.
@@ -180,9 +196,9 @@ for Unix and TCP, a poll loop for QUIC, and the 9P client for mounts);
 `src/fs.zig` keeps host access, mounts, resolution, find and grep.
 
 `zig build fs-test` drives real sessions using the independent Python client
-in `test/ninep.py`; `zig build fs-discovery-test` checks that browsing creates
-nothing, that a pane create and remove work, and that `look`, `exec`, `name`,
-`sel` and `log` behave. `zig build
+in `test/ninep.py`; `zig build fs-discovery-test` checks that browsing
+creates nothing, that the walk to `/pane/new` and a remove work, and that
+`look`, `exec`, `name`, `sel` and `log` behave. `zig build
 9p-test` checks the two engine configurations' budgets (the engine's own
 tests are cloud9's `zig build test`); `zig build fs-bench` measures
 filesystem transactions in the core.