# 9ns design `9ns` mounts a 9P2000 file tree served over a Unix or TCP stream socket into a **fresh mount namespace** and runs a program inside it. The program (fish, bash, `claude`, anything) sees the 9P tree as ordinary files, without root and without touching the host's mount table. ## Why FUSE The kernel's own `9p` filesystem is not mountable inside an unprivileged user namespace (it lacks `FS_USERNS_MOUNT`) and loading it needs root. FUSE has been user-namespace mountable since Linux 4.18, and `/dev/fuse` is world read/write. So 9ns is a tiny FUSE server that speaks 9P2000 to the real server: ``` program (fish/bash/claude) 9ns (parent) 9P server in new user+mount namespace │ (9proc-demo, /mnt/9p/ ─FUSE─▶ kernel ─▶│ fuse.zig ──▶ bridge.zig ──▶ nine.zig ──▶ ramfs, ...) │ (framing) (translation) (cloud9 Client) ``` No libfuse: `src/fuse.zig` implements the small subset of the kernel FUSE protocol we need directly against `/usr/include/linux/fuse.h`. ## Toolchain facts (Zig 0.16) * Zig 0.16.0 at `/usr/bin/zig`, std at `/usr/lib/zig/std`. **Grep the std tree before assuming an API exists**; 0.16 moved a lot of process/fs code behind `std.Io`. Raw Linux syscalls in `std.os.linux` (`fork`, `execve`, `mount`, `unshare`, `waitpid`, `pipe2`, `socketpair`, `poll`, `read`, `write`, `open`, `openat`, `getdents64`, `sigaction`, `kill`, `readlinkat`, `mkdirat`, `symlinkat`) are the intended low-level path. They return `usize`; decode with `std.os.linux.errno(rc)` (an `E` enum, `.SUCCESS` when ok). * `std.posix.poll`, `std.posix.sigaction`, `std.posix.read`, `std.posix.kill` exist. `std.posix.fork/execve/waitpid/pipe2/socketpair` do **not**. * `pub fn main() !void` and `pub fn main(init: std.process.Init) !void` are both supported. Prefer `main(init: std.process.Init)`; `init.gpa` is a general purpose allocator, `init.arena` an arena, `init.minimal.args` the argv (`toSlice(allocator)`), `init.minimal.environ.block` the envp block. * No libc is linked. Do not use `std.c.*`. Hostname lookups are therefore out of scope: `--tcp` takes IP literals only. * 9ns lives in the cloud9 repository as `cloud9/9ns/` and is built by the root `build.zig` through the fragment `9ns/build.zig` (steps `9ns`, `9ns-test`, `9ns-itest`, `9ns-adv`; toggle `-D9ns`). cloud9 itself is imported as module `cloud9` (`@import("cloud9")`). Read `../src/client.zig`, `Server.zig`, `wire.zig` and `../docs/design.md`. Its core is allocation-free and caller-driven: you push bytes in, take results out. The demo 9P server the tests mount is the sibling program `../9proc` (`zig build 9proc`). * Standalone module tests while other files are missing (from the cloud9 root): `zig test --dep cloud9 -Mroot=9ns/src/.zig -Mcloud9=src/root.zig`. * Format everything with `zig fmt`. ## Process model ``` 9ns [options] -- PROGRAM [ARGS...] ``` 1. Parent parses args, probes that `/dev/fuse` exists, connects to the 9P server, negotiates `version` and `attach`es (fid 0 = root). Connection failures are reported before anything is forked. 2. Parent forks with a `socketpair` status channel. **Child**: 1. `unshare(CLONE_NEWUSER | CLONE_NEWNS)`. 2. Writes `/proc/self/setgroups` = `deny`, `/proc/self/uid_map` = `" 1"`, `/proc/self/gid_map` = `" 1"` (same ids inside as outside; the child creating the namespace holds full capabilities in it until exec). 3. `mount(NULL, "/", NULL, MS_REC|MS_PRIVATE, NULL)` so nothing propagates. 4. Ensures the mountpoint exists (see below). 5. Opens `/dev/fuse` (`O_RDWR|O_CLOEXEC`). The kernel refuses to mount a fuse descriptor opened from a different user namespace than the mount ("wrong user namespace for fuse device"), so this must happen here, not in the parent. 6. `mount("9ns", mountpoint, "fuse", MS_NOSUID|MS_NODEV, "fd=,rootmode=40000,user_id=,group_id=,max_read=")`. 7. Sends the fuse fd to the parent over the status socket (`SCM_RIGHTS`). 8. `statx` of the mountpoint: this forces one GETATTR, which the parent serves. Without it the kernel keeps the root inode's initial uid 0 (unmapped in the namespace) and every create in the root gets `EACCES`. 9. Sets `NINE_MOUNT=` in the environment (replacing any inherited value; a nested 9ns overwrites it). 10. `execve` of PROGRAM with PATH search (implemented by hand; no libc). Exec failures are reported through the `CLOEXEC` status socket (errno + message); the parent prints them after the serve loop ends. 3. **Parent** receives the fuse fd, then runs the FUSE loop (`bridge.serve`) until either the child exits (SIGCHLD via self-pipe) or the FUSE fd reports `ENODEV` (last process in the namespace gone, mount destroyed). It then closes the fuse fd and exits with the child's status (`128+sig` if signalled). The self-pipe is also watched by the 9P session while a reply is outstanding (`Session.stop_fd` → `error.Stopped`), so a server that never answers cannot keep 9ns alive after the child is gone; a 3 s watchdog armed from the SIGCHLD handler is the last resort. The FUSE fd is watched during that wait too (`Session.interrupt`): a `FUSE_INTERRUPT` for the request being served becomes a `Tflush` (see *Interrupts* under `src/bridge.zig`). 4. Signals in the parent: `SIGINT`/`SIGQUIT` ignored (the child owns the tty and gets them itself); `SIGTERM`/`SIGHUP` forwarded to the child; `SIGPIPE` ignored; `SIGCHLD` → self-pipe. The FUSE fd is shared with the child only until exec (CLOEXEC); the parent's copy keeps the connection alive. ### mntgen: one mount, many servers (`9ns --mntgen`) `9ns --mntgen [--mount DIR] -- PROGRAM` (default mountpoint `/mnt/9p`) is a transport of its own, mutually exclusive with `--unix/--tcp/--fd/--spawn`; `--name` is rejected (there is no single server to name) while `--uname`, `--aname`, `--msize`, `--cache`, `--no-direct-io` and `--debug` apply to every per-server dial. The mount it builds is the `/srv` view of the posted-9P registry (`cloud9.post`, `$XDG_RUNTIME_DIR/9p`): a walk into a posted name reaches that server's whole 9P tree, and nothing is connected until something walks. XDG_RUNTIME_DIR unset is fatal before anything is forked (the registry is not guessable; no `/tmp` fallback). A registry entry that is a **directory** is served the same way the root is: a synthetic directory (its node id under the reserved index `synth_index`, the slot in the low bits) listing the real directory's entries, dialing the sockets found inside on walk and recursing into further directories — up to `max_synth_depth` (8) levels, bounded by `max_synth_dirs` (64) synthetic nodes per 9ns process. This is how multi-service providers organize themselves (zmx posts its sessions under `zmx/`), the plan9port `mntgen` shape: one tree, many mounts, each entry a mount point. Non-socket, non-directory entries inside a directory answer EIO on walk, exactly like a plain file in the registry itself; a directory's slots are freed when the kernel forgets the dentry. A synthetic node's slot comes back through FORGET, and the kernel sends most of them as `BATCH_FORGET`, whose header `nodeid` is 0 and whose body carries one `(nodeid, nlookup)` per forgotten node — for any mix of owners. The dispatcher therefore cannot route a batch by its header the way it routes every other request: `distributeForgets` unpacks the body and hands each entry to its owner (synthetic root, synthetic subdirectory or per-mount bridge). Routing the batch whole instead loses every entry in it, so the 64 slots leak and a subdirectory served once answers EIO forever. The forgets themselves arrive on the kernel's schedule, not at `close`, so a slot may take a moment to return; a listing that needs one meanwhile answers EIO rather than waiting. ``` program 9ns parent in new userns │ /mnt/9p ─FUSE─▶ kernel ─▶ │ dispatcher (main thread) alpha/ beta/ │ ├─ synthetic root (node 1): lists the registry ...each a server │ ├─ LOOKUP(alpha) ─▶ worker 1 ─ dial+attach+stat, then bridge ─ 9P session ─ server alpha │ └─ LOOKUP(beta) ─▶ worker 2 ─ dial+attach+stat, then bridge ─ 9P session ─ server beta ``` Threads and node ids: * **Dispatcher** (the main thread) is the only reader of `/dev/fuse`. It answers INIT/DESTROY, serves the **synthetic root** (node 1) itself, and routes every other request by the node id's top bits — the **mount index** — to the owning server's mount. It waits on no server, ever: the only blocking it does is the registry directory (a tmpfs) and the mount queues' locks. A FUSE_INTERRUPT is routed by scanning the mounts: a request still sitting in a mount's queue is taken out and answered `EINTR` on the spot (the kernel sends an INTERRUPT once, and a request that only runs later would otherwise run to the end with nobody left wanting it); one in flight gets its unique dropped into that mount's interrupt pipe. Queue and in-flight unique are read under the mount's mutex, which is also where the worker moves a request from one to the other, so an interrupt cannot fall between them. * A **mount** is a posted name walked into: the socket to dial, its own `nine.Session` and bridge state (inode table, handles — the ordinary single-server translation, unchanged) once dialed, and a **worker thread** that owns all of it (its transfer workers share the session). The dispatcher makes a mount without touching the network and hands it the walk; the worker dials while serving that first request. It pops copied requests off a queue and serves them one at a time, exactly the single-connection contract (READ and WRITE handed on to that mount's transfer workers, see *Concurrency* under `src/bridge.zig`); the dispatcher keeps reading `/dev/fuse` meanwhile, so one slow server never blocks the other names. Replies go straight back on the FUSE fd (one `writev` per reply; the kernel processes each write as one message). The queue is a plain list under a mutex and condition rather than an `std.Io.Queue` because an interrupt has to find and remove a request by unique from the middle of it — the same reason a 9P server keeps its pending requests in a list a Tflush can search. * Node id layout: `nodeid = (mount_index << 32) | local`. Index 0 is the synthetic root; per-mount local ids start at 1 (the server's 9P root) and never exceed 2^32 (a bridge never reuses one). Mount indexes are **ordinals and are never reused** (cap 4096 per process), so a stale kernel-side inode of a dead server can never be conflated with a fresh inode of its replacement. Reported `st_ino` mixes the index into the qid.path (`(index+1) << 48` XOR), so two servers handing out the same qid.path (two ramfs instances) still get distinct inode numbers. * **Lazy dial, on the worker**: LOOKUP of an unmounted name stats the registry entry (dispatcher), makes the mount and queues the LOOKUP to it; the worker dials (connect, `Tversion`, `Tattach`, `Tstat` of the root) as the first thing it does for that request, then answers it from the root stat. Every later LOOKUP of the name is queued the same way and answered from the remembered root attr, so the dispatcher never holds a session. No eager connection is ever made: `ls` of the root reads the registry directory only (a plain file dropped there is listed too — and yields EIO on the walk, never deleted). A dial that fails answers the walk that asked — `ENOENT` when the entry vanished, `EIO` for a stale entry (connect refused), a full backlog or a server that will not speak 9P — and leaves the mount undialed, so the next walk simply tries again. The dial is the request in flight, so it ends the way any request does: `stop_fd` (the program exited) fails it with `Stopped`; an interrupt of the walk abandons it at once, with nothing sent (`abort_on_cancel`: there is no session yet to flush anything out of) and the walk answers `EINTR`. A server that accepts but never answers `Tversion` therefore costs exactly the walks into its own name, and Ctrl-C ends those. A server whose listen backlog is full (it stopped accepting) makes the connect report `EAGAIN`; that is retried for 5s, polling `stop_fd` and the interrupt pipe between tries, then answers `EIO`. What no design can fix is the kernel side: the VFS serializes lookups of one *name*, so a second walker into the parked name waits in `d_wait_lookup` until the first walk ends — interrupt the first, and the second proceeds (and can be interrupted in its turn). * **FUSE_PARALLEL_DIROPS** is negotiated in the INIT reply. Without it the kernel takes the directory inode's lock around every LOOKUP and READDIR in it, so one parked walk would still hold up every other name under the same directory — the whole registry root, for a mntgen mount — however free the dispatcher is. * **Death and re-dial**: when a worker's session dies mid-request, dispatch has already answered that request (`ESTALE` for a lost connection, so the VFS redoes the path walk instead of failing; `EIO` for a protocol error), the mount is marked dead, its entry is invalidated in the kernel's dentry cache (`FUSE_NOTIFY_INVAL_ENTRY`, best effort), and everything further routed to that subtree answers `ESTALE` (a FORGET is dropped). Nothing reconnects eagerly. The next walk into the name LOOKUPs it again; a dead mount is skipped and the name gets a new mount under a new index, so kernel-held inodes of the corpse keep answering `ESTALE` until forgotten. `ls` still lists the dead name (listing connects to nothing). Death is discovered lazily: the first walk after a silent death takes the error (it marks the mount dead), the next walk re-dials. * **Interrupts** work per mount: the worker's session polls the mount's interrupt pipe while a 9P reply is outstanding; the dispatcher writes the interrupted request's unique into it and the usual `Tflush` dance (see *Interrupts*) follows — with a grace: a server that answers neither the request nor the `Tflush` within 3s (`nine.Session.flush_grace_ms`) is declared gone, the request answers `EINTR`, the session is wedged and the mount dies with it (the next walk makes a new one). The protocol says a client waits for the Rflush; a server that has not managed one in that long is not going to, and the process behind the interrupt is unkillable until we stop waiting. `stop_fd` (the child's death) is watched by every session, so no worker can stay blocked on a hung server past the program's exit; teardown wakes every worker, joins them, and tears down their sessions and bridge state. * The synthetic root is read-only (`dr-xr-xr-x`, like `/srv`): services are posted and unposted by their servers (`cloud9.post`'s `post`/`listenPosted`/`unpost`), not created and removed through files. Capability probes the kernel makes before trusting a file — xattr ops and `STATX` — answer `ENOSYS` (as they do on server subtrees through the ordinary dispatch): `EPERM` would leak into userland as "Operation not permitted" blamed on the mount root by `ls -l` and plain `stat`. Modifying ops (create, mkdir, rename, ...) keep `EPERM` — the root's read-only nature — and unknown ops are refused, never fatal. Root readdir snapshots the registry per OPENDIR (a new OPENDIR sees new posts); because nothing the kernel can cache is ever served stale (zero timeouts, snapshot per opendir), there is nothing to invalidate and no watcher is needed (`post.Watch` exists in the library for future caching). * Naming: `--mount` (default `/mnt/9p`) is the whole mount; `$NINE_MOUNT` points at it as usual. ### Mountpoint policy Default mountpoint: `/mnt/9p/`, where the name is `--name NAME` or is derived from the transport (`main.zig`, `defaultName`): | transport | default name | |---|---| | `--unix PATH` | basename of PATH with one trailing `.sock`/`.9p`/`.socket` removed (`/tmp/9debug.sock` → `9debug`) | | `--tcp IP:PORT` | `tcp-IP-PORT` with `:` → `-` (brackets are already gone: `[::1]:564` → `tcp---1-564`) | | `--spawn CMD` | basename of the first whitespace-separated word of CMD | | `--fd N` | `fdN` | A name is one path component: non-empty, no `/`, no NUL, not `.`/`..`. An invalid `--name` is a usage error (125); a derived name that is not valid (empty basename, `..`) falls back to `9p`. `--mount PATH` overrides all of this (the name is then PATH's last component and is not used for anything); a relative `--mount` is resolved against cwd; `/` is rejected. `ns.ensureMountpoint` then makes the path a directory inside the new namespace: * If the path is a directory: use it (a nested 9ns with the same name therefore mounts over the outer mount at that path). * Else walk up to the deepest existing ancestor (which must be a directory; a dangling symlink anywhere is an error) and `mkdir` the missing components under it one by one. If the first of those fails with `EACCES`/`EPERM`/`EROFS` (the normal case for `/mnt/9p/` as a plain user), **shadow that ancestor**: open an fd to it, mount a `tmpfs` over it, then recreate every existing entry inside the tmpfs: directories → `mkdir` + bind mount from `/proc/self/fd//`; symlinks → `readlinkat` + `symlink`; anything else → empty regular file + bind mount. Then create the missing components inside. Refuse (with a clear message) if the ancestor is `/` (also through `/proc/self/root`), is `/proc` or below it, or has more than 4096 entries. This only affects the new namespace. So on a host without `/mnt/9p` the shadow goes over `/mnt` and `9p/` is created inside; with a root-owned `/mnt/9p` it goes over `/mnt/9p`; inside a 9ns namespace `/mnt/9p` is a directory of the outer tmpfs owned by our uid, so a nested 9ns just creates `` next to the outer mount and both are visible. * Else fail with the errno and a hint to pass `--mount` an existing dir. ## Module contracts ### `src/fuse.zig` — kernel FUSE protocol (no policy) Extern structs mirroring `linux/fuse.h`, with `comptime` size asserts: `InHeader` (40), `OutHeader` (16), `Attr` (88), `EntryOut` (128), `AttrOut` (104), `GetattrIn` (16), `SetattrIn` (88), `OpenIn` (8), `OpenOut` (16), `ReleaseIn` (24), `FlushIn` (24), `ReadIn` (40), `WriteIn` (40), `WriteOut` (8), `CreateIn` (16), `MkdirIn` (8), `RenameIn` (8), `Rename2In` (16), `ForgetIn` (8), `BatchForgetIn` (8), `ForgetOne` (16), `FsyncIn` (16), `AccessIn` (8), `InterruptIn` (8), `Kstatfs` (80), `StatfsOut` (80), `InitIn` (64), `InitOut` (64), `Dirent` (24 header, name padded to 8), `LseekIn` (24). `pub const Opcode = enum(u32) { lookup = 1, forget = 2, getattr = 3, setattr = 4, readlink = 5, symlink = 6, mknod = 8, mkdir = 9, unlink = 10, rmdir = 11, rename = 12, link = 13, open = 14, read = 15, write = 16, statfs = 17, release = 18, fsync = 20, setxattr = 21, getxattr = 22, listxattr = 23, removexattr = 24, flush = 25, init = 26, opendir = 27, readdir = 28, releasedir = 29, fsyncdir = 30, getlk = 31, setlk = 32, setlkw = 33, access = 34, create = 35, interrupt = 36, bmap = 37, destroy = 38, ioctl = 39, poll = 40, notify_reply = 41, batch_forget = 42, fallocate = 43, readdirplus = 44, rename2 = 45, lseek = 46, copy_file_range = 47, setupmapping = 48, removemapping = 49, syncfs = 50, tmpfile = 51, statx = 52, _ }` Constants: `kernel_version = 7`, `kernel_minor = 31` (what we answer; the kernel adapts to the lower minor), `FOPEN_DIRECT_IO = 1`, `FOPEN_KEEP_CACHE = 2`, `FOPEN_NONSEEKABLE = 4`, `FUSE_ASYNC_READ = 1`, `FUSE_PARALLEL_DIROPS = 1<<18`, `FUSE_MAX_PAGES = 1<<22`, `FATTR_MODE=1, FATTR_UID=2, FATTR_GID=4, FATTR_SIZE=8, FATTR_ATIME=16, FATTR_MTIME=32, FATTR_FH=64, FATTR_ATIME_NOW=128, FATTR_MTIME_NOW=256, FATTR_LOCKOWNER=512, FATTR_CTIME=1024`. `root_id = 1`. I/O helpers (blocking fd, no allocation beyond the caller's buffer): ```zig pub const Request = struct { header: InHeader, body: []const u8 }; /// One kernel request. Returns null on ENODEV (unmounted). Retries EINTR/EAGAIN/ENOENT. pub fn readRequest(fd: i32, buf: []u8) !?Request; /// Same, one read(2) only: EINTR/EAGAIN/ENOENT → error.Retry (for reads that follow a poll). pub fn readRequestOnce(fd: i32, buf: []u8) !?Request; /// O_NONBLOCK on the device, so a request withdrawn between poll and read cannot block us. pub fn setNonblocking(fd: i32) !void; /// Success reply: header + concatenated payload slices, single writev. pub fn reply(fd: i32, unique: u64, payloads: []const []const u8) !void; /// Error reply: negative errno. pub fn replyError(fd: i32, unique: u64, err: std.os.linux.E) !void; /// Append a fuse_dirent (8-byte padded) to `buf`; returns false if it doesn't fit. pub fn addDirent(buf: []u8, used: *usize, ino: u64, off: u64, dtype: u32, name: []const u8) bool; pub fn body(comptime T: type, req: Request) !*const T; // aligned copy-free view, checks size pub fn nameAfter(comptime T: type, req: Request) ![]const u8; // NUL-terminated name after a struct ``` The request buffer must be ≥ `max_write + 4096`; 9ns uses 1 MiB + 4 KiB. Requests with an unknown/unsupported opcode get `ENOSYS`. ### `src/nine.zig` — 9P2000 session on a blocking fd, shared by threads Thin RPC layer over `cloud9.Client` (which is push/take, non-blocking-agnostic). Many requests may be in flight at once, each under its own tag; replies come back in any order. The connection is a `Session`; each thread that makes calls on it has a `Caller`. Fids are allocated from a free list (under the session's mutex). ```zig pub const Address = union(enum) { unix: []const u8, tcp: struct { host: []const u8, port: u16 }, fd: i32 }; /// Owner's hook into the reply wait (the bridge's FUSE fd, or an interrupt pipe); see "Interrupts" under bridge.zig. pub const Interrupt = struct { ctx: *anyopaque, watch: *const fn (ctx) i32, // fd to poll alongside the socket, or -1 onReadable: *const fn (ctx) Session.Error!bool, // consume it; true = flush the request in flight armed: *const fn (ctx) bool, // a flush was asked for the operation in progress }; pub const Session = struct { pub const Error = error{ Nine, Protocol, Io, Closed, Stopped, Interrupted, TooLarge, OutOfMemory }; msize: u32, stop_fd: i32 = -1, // readable → every waiting call fails with error.Stopped flush_grace_ms: i32 = 3000, // a Tflush unanswered this long wedges the session wedged: bool, // declared gone: every call → error.Closed pub fn connect(gpa: std.mem.Allocator, address: Address, msize: u32) !Session; // socket+connect, version pub fn deinit(s: *Session) void; // after every Caller is done pub fn allocFid(s: *Session) u32; pub fn freeFid(s: *Session, fid: u32) void; pub fn over(s: *Session) bool; // wedged, or the connection died }; pub const Caller = struct { session: *Session, /// After error.Nine, `ename` holds the server's Rerror text (copied, bounded). ename: [256]u8, ename_len: usize, interrupt: ?Interrupt = null, abort_on_cancel: bool = false, // handshake: a cancellation hangs up instead of flushing pub fn init(s: *Session) !Caller; // msize reply buffer + wake-up eventfd pub fn deinit(c: *Caller) void; /// Generic RPC. Result slices borrow the caller's reply buffer until its next call. pub fn rpc(c: *Caller, req: cloud9.Client.Request) Error!cloud9.Client.Result; // Conveniences (all built on rpc): pub fn version(c) Error!void; pub fn attach(c, fid: u32, uname: []const u8, aname: []const u8) Error!cloud9.Qid; pub fn walk(c, fid: u32, newfid: u32, names: []const []const u8) Error!Walk; // Walk = { nwqid, wqid[16] }; partial walk → error.Nine with ename "not found"-ish pub fn clone(c, fid: u32) Error!u32; // allocFid + walk with no names pub fn open(c, fid: u32, mode: u8) Error!Open; // Open = { qid, iounit } pub fn create(c, fid: u32, name: []const u8, perm: u32, mode: u8) Error!Open; pub fn read(c, fid: u32, offset: u64, buf: []u8) Error!usize; // chunks by maxRead/iounit; stops at short read pub fn write(c, fid: u32, offset: u64, data: []const u8) Error!usize; // chunks; stops at short write pub fn stat(c, fid: u32) Error!cloud9.Stat; // strings borrow the reply buffer pub fn wstat(c, fid: u32, st: cloud9.Stat) Error!void; pub fn clunk(c, fid: u32) Error!void; // frees the fid even on error pub fn remove(c, fid: u32) Error!void; // frees the fid even on error pub fn errno(c: *const Caller) std.os.linux.E; // map ename → errno (see below) }; pub const dontcare = cloud9.Stat{ .type = 0xFFFF, .dev = 0xFFFF_FFFF, .qid = .{ .type = 0xFF, .version = 0xFFFF_FFFF, .path = 0xFFFF_FFFF_FFFF_FFFF }, .mode = 0xFFFF_FFFF, .atime = 0xFFFF_FFFF, .mtime = 0xFFFF_FFFF, .length = 0xFFFF_FFFF_FFFF_FFFF, .name = "", .uid = "", .gid = "", .muid = "" }; ``` `connect`: for `.unix` and `.tcp` create a blocking `SOCK_STREAM|SOCK_CLOEXEC` socket and connect (`TCP_NODELAY` on TCP); for `.fd` adopt it. Buffers of `msize` bytes for in/out are heap allocated. Then a `version` rpc on a temporary caller. The negotiated msize is `result.version.msize`; if the server answered `"unknown"`, fail with `error.Protocol`. `rpc` multiplexes the way Plan 9's mount driver does (`kernel/devices/sys/devmnt.c` in principia-softwarica: `mountio`, `mountmux`, `mntgate`, `mntflushalloc`). Under the session's `wlock` (which serializes the client's output buffer and the socket's write side) and `mutex` (tags, input side, the waiter table) the call claims a tag, registers its waiter under it and writes the T-message; the write itself runs with only `wlock` held. Then it waits: the first waiter that finds nobody reading takes the **reading baton** (`m->rip`), reads the socket, `push`es and `take`s, copies each R-message into the caller its tag names (the client's input buffer belongs to whoever reads next) and pokes that caller's eventfd; when its own reply is in it lets go of the baton and pokes every waiter, one of which takes it over. Waiters without the baton poll their eventfd; all poll `stop_fd` (→ `error.Stopped`) and their own interrupt source. A socket EOF → `error.Closed`, a client protocol death → `error.Protocol`, for every waiter. When all `nine.max_tags` tags are taken a call waits on a starved list (reading if it gets the baton) until a reply frees one; nothing fails for lack of a tag. When the interrupt source asks for it the waiter first gives up the baton (a Tflush write that blocks must not stop everyone's replies, the Rflush among them, being read), then submits `.flush = .{ .oldtag = tag }` under a tag of its own and keeps waiting on both tags: the original reply first → it is honoured and returned (flush(5): a Twrite that completed changed state; the Rflush that follows is dropped); the Rflush first → `error.Interrupted`. The client does not reuse the flushed tag until the Rflush is in. A Tflush unanswered for `flush_grace_ms` wedges the session (every waiter → `error.Closed`). A `.fail` result copies the ename into the caller and returns `error.Nine`. `read`/`write` chunk loops (per call, per caller) stop between chunks once the source reports `armed`, and turn an `Interrupted` chunk into a short count when earlier chunks moved data. Rerror text → errno mapping (case-insensitive substring, in this order): `"interrupt"` → `EINTR` (a server answering a flushed request with an error); `"not exist"`, `"not found"`, `"no such"` → `ENOENT`; `"exists"` → `EEXIST`; `"not empty"` → `ENOTEMPTY`; `"not a dir"` → `ENOTDIR`; `"is a dir"` → `EISDIR`; `"permission"`, `"denied"` → `EACCES`; `"read-only"`, `"read only"`, `"readonly"` → `EROFS`; `"no space"` → `ENOSPC`; `"not allowed"`, `"not permitted"`, `"cannot"` → `EPERM`; `"fid"` → `EBADF`; `"bad offset"`, `"invalid"`, `"bad "` → `EINVAL`; `"busy"`, `"in use"` → `EBUSY`; `"too long"` → `ENAMETOOLONG`; `"not supported"`, `"unsupported"` → `ENOTSUP`; otherwise `EIO`. ### `src/bridge.zig` — FUSE ↔ 9P translation ```zig pub const Options = struct { uid: u32, gid: u32, // reported owner of every file attr_timeout_ns: u64 = 1e9, // attr/entry cache validity (0 = none) direct_io: bool = true, // FOPEN_DIRECT_IO on every regular file debug: bool = false, // trace to stderr }; /// Runs until the FUSE fd reports ENODEV or `stop_fd` becomes readable. pub fn serve(gpa: std.mem.Allocator, fuse_fd: i32, nine: *nine.Session, root_fid: u32, stop_fd: i32, opts: Options) !void; // mntgen (see "mntgen: one mount, many servers" under Process model): pub const MntgenOptions = struct { io: std.Io, // dispatcher-thread only: post.posted / registry stats env: post.Env, // XDG_RUNTIME_DIR names the registry uname: []const u8, aname: []const u8 = "", msize: u32 = 131072, }; /// One FUSE mount whose root lists the posted-9P registry; servers dialed /// lazily, one worker thread each; node ids carry the mount index in the /// top bits (`mount_shift = 32`, indexes are ordinals from 1, never reused, /// `max_mounts` = 4096; the registry snapshot buffer is 8 KiB, `max_root_dirs` /// = 64 concurrent OPENDIRs). Runs until ENODEV, DESTROY or `stop_fd`. pub fn serveMntgen(gpa: std.mem.Allocator, fuse_fd: i32, stop_fd: i32, mo: MntgenOptions, opts: Options) !void; pub fn mountNode(index: u32, local: u64) u64; // (index << 32) | local pub fn mountIndex(nodeid: u64) u32; // nodeid >> 32 pub fn nameIno(name: []const u8) u64; // FNV-1a of a name: synthetic-root dirent inos ``` State: * `inodes: AutoHashMap(u64 /*nodeid*/, Inode{ fid: u32, qid: Qid, nlookup: u64 })`. Node 1 is the root (`root_fid`, never forgotten). In mntgen mode the same machinery runs once per mount with node ids that already carry the mount index; the root node id is the `Bridge.root_id` field (`fuse.root_id` single-connection) and reported inode numbers are `qid.path ^ ino_xor` (`ino_xor` 0 single-connection). `cur_unique` is atomic so the mntgen dispatcher can scan it to route FUSE_INTERRUPTs. * `by_qid: AutoHashMap(u64 /*qid.path*/, u64 /*nodeid*/)` so that repeated lookups of the same file map to the same inode (the old fid is clunked and the fresh one kept). Dedupe only merges when the qid type (dir bit) also matches, so a server reusing a path across a file and a directory cannot poison an inode. `ino` in attrs is `qid.path` (root, or anything carrying the root's path: 1). * `handles: AutoHashMap(u64 /*fh*/, Handle{ fid: u32, dir: ?DirList })`. `DirList` is the entire directory read at first `READDIR` offset 0: `[]Entry{ name: []u8, ino: u64, dtype: u32 }` with synthetic `.` and `..` first. `READDIR` offsets are indices into that list; a `READDIR` at offset 0 re-reads the directory (rewinddir). Op mapping (9P2000 has no symlinks, links, xattrs, locks, mknod): | FUSE | 9P | |---|---| | INIT | reply `InitOut{ major=7, minor=31, max_readahead=in.max_readahead, flags = FUSE_ASYNC_READ \| FUSE_ATOMIC_O_TRUNC \| FUSE_AUTO_INVAL_DATA \| FUSE_BIG_WRITES (plus FUSE_MAX_PAGES with max_pages=256, and FUSE_PARALLEL_DIROPS, each if offered), max_background=16, congestion_threshold=12, max_write=1 MiB, time_gran=1 }`. Atomic O_TRUNC matters: without it the kernel truncates via a separate SETATTR(size=0) that synthetic control files reject; with it `O_TRUNC` becomes 9P `OTRUNC` inside the open | | LOOKUP(parent,name) | `walk(parent.fid → newfid, [name])`; `stat(newfid)`; dedupe by qid; `EntryOut` | | FORGET / BATCH_FORGET | `nlookup -= n`; at 0 `clunk` and drop (no reply) | | GETATTR | `stat(inode.fid)` → `AttrOut` | | SETATTR | `stat` then `wstat` with a *dontcare* Stat: `FATTR_SIZE`→length; `FATTR_MODE`→`(old.mode & ~0o777) \| (mode & 0o777)`; `FATTR_MTIME`→mtime (`FATTR_MTIME_NOW` → now); `FATTR_ATIME` ignored; `FATTR_UID/GID` → `EPERM` unless unchanged; then `stat` again for the reply | | OPEN | `clone(inode.fid)` then `open(newfid, mode)`; mode from `O_ACCMODE` (`oread/owrite/ordwr`), `O_TRUNC` → `otrunc`; reply `OpenOut{ fh, open_flags = FOPEN_DIRECT_IO }`; on failure clunk | | OPENDIR | same with `oread`; `fh` with `dir = null` | | READ | on a transfer worker: `read(fh.fid, offset, buf[0..min(size, 1 MiB)])`; reply data | | WRITE | on a transfer worker: `write(fh.fid, offset, data)`; `WriteOut{ size = n }` | | READDIR | fill `Dirent`s from the `DirList` starting at `offset`, up to `size` bytes | | RELEASE / RELEASEDIR | `clunk(fh.fid)`; free DirList | | FLUSH / FSYNC / FSYNCDIR | ok (no-op) | | CREATE(parent,name,flags,mode) | `clone(parent)`; `create(fid, name, mode & 0o777, openmode)` → this fid is the **open** file; then `walk(parent → fid2, [name])` + `stat(fid2)` for the inode; reply `EntryOut ++ OpenOut` | | MKDIR | `clone(parent)`; `create(fid, name, DMDIR \| (mode & 0o777), oread)`; `clunk`; then lookup as above | | UNLINK / RMDIR | `walk(parent → tmp, [name])`; `remove(tmp)` | | RENAME / RENAME2 | if `newdir != parent` → `EXDEV`; else `walk(parent → tmp, [oldname])`, `wstat(tmp, dontcare with .name = newname)`, `clunk`. 9P rename never replaces, POSIX does: when the target exists (and `RENAME_NOREPLACE` is not set) a directory target is removed first; a file target is parked under a temporary name, the rename retried, and the parked file removed only after success (restored on failure) | | STATFS | constant `Kstatfs{ bsize = 4096, namelen = 255, frsize = 4096 }` | | ACCESS | `ENOSYS` (kernel stops asking; the server enforces permissions on open) | | READLINK, SYMLINK, LINK, MKNOD, *XATTR, *LK, IOCTL, POLL, BMAP, FALLOCATE, LSEEK, COPY_FILE_RANGE, TMPFILE, STATX | `ENOSYS` | | INTERRUPT | read while a 9P reply is outstanding: for the request in flight → `Tflush` (see *Interrupts*); otherwise ignored (reply nothing) | | DESTROY | return from `serve` | Attr mapping from `cloud9.Stat`: `mode = (S_IFDIR if DMDIR else S_IFREG) | (st.mode & 0o777)`; `nlink = 1`; `size = length`; `blocks = (length+511)/512`; `blksize = 4096`; `atime/mtime/ctime = st.atime/st.mtime/st.mtime`; `uid/gid = opts.uid/gid`. `Dirent.type` = `DT_DIR` (4) / `DT_REG` (8). Errors: `nine.Session.Error.Nine` → `nine.errno()`; `Closed`/`Protocol`/`Io` → `EIO` and, since the session is dead, `serve` returns `error.Closed` after replying so 9ns can report "9P server went away". With `direct_io` the kernel never trusts `length` for reads: synthetic files that report length 0 (very common in 9P) still `cat` correctly, and reads run until the server returns a short read. With `--no-direct-io` the bridge forces `attr_timeout_ns = 0`, because a cached stale size truncates reads (observed data loss on a 4 MiB copy otherwise). Hostile-server rules: directory listings are capped at 64 MiB (a server that ignores read offsets otherwise loops forever); directory records with names containing `/`, NUL, empty, `.`/`..` or longer than `FUSE_NAME_MAX` are dropped rather than poisoning the whole READDIR reply; `length` near 2^64 is clamped to `i64` max; the errno of a failing 9P call is latched before any cleanup clunk overwrites the session's ename. #### Concurrency (transfer workers) One thread, the loop, owns the inode, handle and qid tables and serves every request that reads or changes them, one at a time; lookups and forgets are reconciled there and nowhere else. READ and WRITE are the requests a synthetic server parks (a blocking `log`, `event` or `run` file), and they need no table beyond the handle → fid lookup, so the loop does that lookup and hands the transfer to a **transfer worker** (`Pool`/`Worker` in `bridge.zig`): a thread with its own `nine.Caller`, data buffer and interrupt pipe, which makes the 9P calls, chunks by msize/iounit itself and writes the reply to the FUSE fd. The session multiplexes their tags, so a parked read holds up only its own process: with pardes's `log` parked, `cat status` answers in milliseconds instead of waiting for the read. Workers start on demand, up to `max_workers = nine.max_tags - 1` per bridge (the loop keeps the last tag); a transfer that finds every worker parked waits in the queue for one, where an INTERRUPT answers it `EINTR` at once. Every queued transfer gets an idle worker of its own or a new one, so a transfer never waits behind a parked one while the pool has room. The fid a worker uses is the handle's, and is clunked only on RELEASE, which the kernel sends once no read or write on that open file is in progress (FLUSH, sent on every `close`, clunks nothing). Two processes reading or writing one open file concurrently now run concurrently on the server too; one process's write-then-read stays ordered because each syscall waits for its reply, and 9P promises nothing more. This is devmnt's model with the waiting given threads: in Plan 9 every process blocked in a read is its own waiter on the mount; a FUSE server gets the kernel's requests on one descriptor, so the waiting processes are represented by workers here. #### Interrupts (FUSE_INTERRUPT → Tflush) The loop waits on the server too (its own lookups, opens, stats), but it is not deaf meanwhile. `serve` puts the FUSE fd in `O_NONBLOCK` mode (every read follows a poll) and installs a `nine.Interrupt` source on the loop's caller that `Caller.rpc` polls together with `stop_fd` (and the socket, when it holds the baton) whenever a reply is outstanding, including the initial root stat: * `onReadable` reads the request the kernel has ready into a second 8-aligned buffer of `request_buf_len` bytes (`spare_buf`). A `FUSE_INTERRUPT` whose `InterruptIn.unique` names the request being served (`cur_unique`) sets `interrupted` and returns true: `rpc` sends `Tflush(oldtag)` and keeps waiting until either the original reply arrives (the interrupt raced it: the result is returned as if nothing happened and the Rflush that follows is dropped by whoever reads it) or the Rflush does (`error.Interrupted` → `EINTR`; a server that instead answers the flushed request with an Rerror containing "interrupt", as Pardes does, lands on the same errno through the ename table). An INTERRUPT for a transfer worker's request goes to that worker: still queued, it is answered `EINTR` on the spot; in flight, its unique goes down the worker's interrupt pipe, and the worker's session sends the Tflush the same way. An INTERRUPT for any other unique is consumed and dropped (the kernel expects no reply); the loop routes one it reads while idle the same way. Any other request (FORGET, RELEASE, INIT during the root stat, a second process's LOOKUP) is copied into a queue that `serve` dispatches, in arrival order, before it polls again (a READ or WRITE goes to a worker on the spot instead, and an INTERRUPT for a request still in that queue answers it `EINTR`); the fd stays watched throughout, so an INTERRUPT is never stuck behind a parked request (a copy that cannot be allocated answers `ENOMEM` on the spot). * The INTERRUPT applies to `cur_unique` only and is consumed when read: the clunks that unwind a half-done lookup/create/mkdir after an `Interrupted` walk or stat are ordinary rpcs and are not re-interrupted by it. An interrupted walk clunks its new fid (the Rflush alone does not say whether the server bound it); an Rerror'd walk only frees it locally. * Multi-step operations fail with `EINTR` at whichever rpc was flushed and release the fids they had allocated (`--debug` prints `fids=N` per request; the interrupt suite checks it and the server-side count). The chunk loops (`Caller.read/write`, `loadDir`) also stop between chunks while `armed`, so a reply that won the race cannot lead into another blocking chunk: a read or write that already moved data returns the partial count like read(2), one that moved nothing and a directory listing return `EINTR`. * The kernel sends one INTERRUPT per request, for a fatal signal (SIGKILL included) as much as for a caught one, and then waits for the reply; our `EINTR` is what finally lets the killed task die. Limits: a server that ignores Tflush is given `flush_grace_ms` (3s) and then declared gone — flush(5) says the server "should answer the Tflush message immediately", and a client that waits longer leaves an unkillable process behind — so the reader gets `EINTR` and the session ends (the hostile `never` mode; in single-connection mode that is the mount, in mntgen that one name). A slow-but-alive server that cannot answer a flush inside its own blocking read pays the same price; the alternative was a hang that only SIGKILL of 9ns could end. When a worker's flush wedges the session the loop notices at its next request (every call on the session then fails) and the mount ends there. Budgets: a session's 9P client is `cloud9.ClientWith(nine.max_tags)`, 32 request tags plus one kept for flushes (cloud9's default `Client` has 16), so one mount has at most 32 requests on the server at once. 32 is the cloud9 file server engine's `slot_capacity` (`src/fs.zig`, what pardes serves with): the most reads, writes, opens and clunks it parks per connection, answering the one past it with Rerror "Resource temporarily unavailable" (which would reach the reader as `EIO`). A mount can therefore never meet that refusal. The two are raised together or not at all: the engine's default is also the ESP32 board's (its budget tests in `fs.zig` hold a default server to 24 KiB), so a bigger window is a per-server option (pardes's editor `fs.Options`) plus `nine.max_tags`, not a new default. When the window is full: the loop keeps a tag of its own, so lookups, opens, stats, listings and every other request the loop serves go on; 31 parked transfers occupy all the workers, and a 32nd READ or WRITE, quick or not (9ns cannot tell a `status` read from a `log` read), waits in the pool queue until a parked one ends or is interrupted. It blocks; it is never refused (`EAGAIN`) or failed (`EIO`), and an INTERRUPT answers it `EINTR` at once. A worker whose flushed request was answered before its Rflush holds the flushed tag until that Rflush; a call that meanwhile finds no tag waits for one the same way. ### `src/ns.zig` — namespace and process plumbing ```zig pub const Spawn = struct { argv: []const []const u8, // argv[0] is PATH-searched unless it contains '/' envp: [*:null]const ?[*:0]const u8, // inherited environment mountpoint: []const u8, // absolute fuse_fd: i32, uid: u32, gid: u32, max_read: u32, }; pub const Child = struct { pid: i32 }; /// fork; the child sets up the namespace, mounts, and execs. Returns once exec succeeded /// (status pipe closed) or fails with the child's error (message on stderr). pub fn spawn(gpa: std.mem.Allocator, s: Spawn) !Child; pub fn ensureMountpoint(gpa: Allocator, path: [:0]const u8) !void; // walk down, mkdir -p, shadow; testable alone pub fn resolveMountpoint(gpa, path: []const u8) ![:0]u8; // absolute, no trailing slash pub fn findInPath(gpa, envp, name) ![:0]u8; ``` Also exports the signal plumbing used by `main.zig`: `installSignals(child_pid_ptr: *i32) !i32` returning the SIGCHLD self-pipe read end (used as `stop_fd` for `bridge.serve`), and `waitChild(pid) !u8` → exit status (`128+sig` on signal death). ### `src/main.zig` — CLI ``` Usage: 9ns [options] -- PROGRAM [ARGS...] Transport (exactly one): --unix PATH Unix stream socket --tcp IP:PORT TCP (IPv4/IPv6 literal) --fd N already-connected inherited descriptor --spawn CMD run CMD (via /bin/sh -c) with a socketpair on its stdin/stdout --mntgen mount the posted-9P registry ($XDG_RUNTIME_DIR/9p): one mount whose root lists the posted names; walking into a name dials that server (mutually exclusive with the rest) Options: --name NAME mount name: the tree appears at /mnt/9p/NAME (one path component; default derived from the transport, see below; not with --mntgen) --mount PATH mountpoint inside the new namespace (overrides --name; with --mntgen the mount is the registry view itself, default /mnt/9p) --uname NAME 9P user name (default $USER, else "none") --aname NAME 9P tree to attach (default "") --msize BYTES maximum 9P message size to request (default 131072, max 16 MiB) --cache SECONDS attr/entry cache validity, may be fractional (default 1) --no-direct-io let the kernel cache file pages (trusts stat length) --debug trace FUSE and 9P operations on stderr --help, --version PROGRAM defaults to $SHELL (else /bin/sh). The mountpoint is exported as $NINE_MOUNT. Default name: --unix PATH -> basename of PATH without .sock/.9p/.socket; --tcp IP:PORT -> tcp-IP-PORT (':' becomes '-'); --spawn CMD -> basename of its first word; --fd N -> fdN; 9p when nothing usable comes out of that. --mntgen: no per-server name; the registry mount goes to --mount (default /mnt/9p). ``` `--name` and `--mount` may both be given; `--mount` wins. Exit codes: child's status; 125 for 9ns's own failures (usage including a bad `--name`, connect, mount, and for `--mntgen` an unset XDG_RUNTIME_DIR); 126/127 as usual for exec failures. ### `../9proc/demo/main.zig` — demo 9P2000 server (binary `9proc-demo`) The demo server is a separate program in this repository, built on the 9proc library; see `../9proc/docs/LIBRARY.md` for the library contract (freestanding core, value renderers, Linux debug probe). The tree it serves keeps the paths the integration tests read (`/build/*`, `/comptime/types//*`, `/comptime/decls`, `/runtime/fn/*`, `/runtime/ctl`, `/runtime/{pid,ppid,uptime,argv,cwd,env,clients}`, `/scratch/`) and adds `/vars`, `/threads`, `/addr`, `/mem`, `/hex`, `/breakpoints` and `/panic`. ## Integration test plan (`test/integration.sh`) Run by `zig build 9ns-itest`; args: path to `9ns`, path to `9proc-demo`. Everything under a temp dir. Skips (exit 0 with a notice) when `unshare -Urm true` fails or `/dev/fuse` is missing. 1. 9proc-demo on a Unix socket; `9ns --unix … -- sh -c` scripts: `cat /mnt/9p/build/zig_version` == `zig version`; `ls` listings; `stat` sizes; `/runtime/fn/now` is numeric; `ctl` round trip; `/scratch`: create, append (`>>`), overwrite, truncate, `mkdir -p a/b/c`, rename within dir, `mv` across dirs fails with `EXDEV`-ish message, `rm`, `rmdir`, 1 MiB random file round trip compared with `sha256sum`, `dd` with odd block sizes, many small files, `find`, exit-status propagation (`exit 7` → 7), `$NINE_MOUNT` set, nested `9ns` inside `9ns`. The suites pin the mountpoint with `--mount /mnt/9p`; the naming section then checks the default `/mnt/9p/` (unix socket basename, `--name`, `--name=`, invalid names → 125, nested runs with two names both visible under `/mnt/9p`, the same name twice mounting over, `--spawn` and `--tcp` derived names, `--mount` beating `--name`). 2. `--spawn "<9proc-demo> --stdio"` variant. 3. `--tcp 127.0.0.1:` variant. 4. If `/usr/lib/plan9/bin/ramfs` exists: `NAMESPACE=$tmp ramfs -s ramfs` creates `$tmp/ramfs`; run the scratch battery against it. 5. `--mount` with an existing dir, with a relative path, `/mnt/9p` and the default `/mnt/9p/` (both exercise the shadowing of `/mnt`; verify `/mnt`'s other entries are still visible inside and the host mount table is untouched). 6. Kill tests: 9ns exits when the child exits; server death during use yields `EIO`, not a hang. 7. `test/mntgen.sh` (also `9ns-itest`): `--mntgen` against a scratch registry (`XDG_RUNTIME_DIR` = temp dir, never the real one): two servers posted under two names (9proc-demo's socket created inside the registry directory — a socket at `$XDG_RUNTIME_DIR/9p/` is a posted name — plus plan9port `ramfs`, an independent 9P2000 implementation, posting with `NAMESPACE=$REG`), the synthetic root listing without dialing (including a non-socket file, which is listed, yields EIO on the walk, and is never removed), lazy dial and per-server routing in one program run, a post appearing after mount, server death → EIO on the subtree with the name still listed and a re-dial after re-post, parallel reads on both mounts, `$NINE_MOUNT` = `/mnt/9p` by default, and the usage errors (`--mntgen` + any transport, `--name`, `--mntgen=x`, unset `XDG_RUNTIME_DIR`). ## Verification `zig build 9ns-test` (unit), `zig build 9ns-itest` (integration.sh + the mntgen suite: end-to-end checks against 9proc-demo over unix/tcp/socketpair, plan9port's `ramfs`, and the posted-registry multi-server mode) and `zig build 9ns-adv` (adversarial suites: a scriptable hostile 9P server with ~30 misbehaviour modes, interrupt forwarding against its `never_flush`/`never` modes with 28 checks, FUSE semantics through the bridge, process/namespace/signal edge cases with 51 checks, and stress). The suites that attack the 9proc server itself (a hostile raw-9P client with 181 checks, the core, the Linux layer) moved with it to `../9proc/test` (`zig build 9proc-adv`). All pass in Debug and ReleaseSafe. ## Out of scope for v1 (documented, not hidden) * One 9P request in flight at a time, per server in mntgen mode (across servers they proceed in parallel, one worker each): a 9P read that blocks (event files) stalls that server's subtree while it is outstanding (but not past the child's exit). It can be interrupted: killing or Ctrl-C-ing the reader sends `FUSE_INTERRUPT`, which becomes `Tflush`; servers that honour it unblock immediately, servers that don't are given 3s and then declared gone: the reader gets `EINTR` and the session (single connection: the mount; mntgen: that name) ends. * mntgen: a name's dial runs on that name's worker, inside the walk that asked, with no timeout of its own beyond the 5s backlog retry: a server that accepts and never answers `Tversion` parks the walks into its own name, and only those, until each is interrupted or the program exits. The one wait nothing here can cut short is the kernel's own serialization of lookups of a single name (a second walker into the parked name waits for the first walk to end, uninterruptibly). * mntgen: mount indexes are ordinals and never reused (cap 4096 dials per process); per-mount node ids cap at 2^32 lookups. `st_ino` mixes the index with the qid.path via XOR — collisions remain theoretically possible, just not the practical ones (identical qid.paths across two servers). A dead mount releases its socket, its interrupt pipe and its bridge state at once (the pipe under the mount's mutex, where the dispatcher writes it) and keeps only its slot, so a server that dies and comes back costs one index per death and nothing else; after 4096 of them in one 9ns process no further name can be walked into (EIO) until the shell is restarted. Reclaiming a slot once the kernel has forgotten every node of the corpse is the next step, not taken here. * mntgen: no posting/unposting through the mount (the synthetic root is read-only; servers manage their registry entries through `cloud9.post`), and no per-name mount options: one set of `--uname/--aname/--msize/--cache` applies to every dial. * No 9P2000.u/.L: no symlinks, ownership, or extended attributes. * No PID namespace, no `/proc` remount. `--tcp` needs an IP literal. * Cross-directory rename returns `EXDEV` (9P2000 cannot move files).