# 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/<name> ─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/<file>.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` =
      `"<uid> <uid> 1"`, `/proc/self/gid_map` = `"<gid> <gid> 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=<fusefd>,rootmode=40000,user_id=<uid>,group_id=<gid>,max_read=<n>")`.
   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=<mountpoint>` 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.

### Mountpoint policy

Default mountpoint: `/mnt/9p/<name>`, 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/<name>` 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/<fd>/<name>`; 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/<name>` 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 `<name>` 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_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` — synchronous 9P2000 session on a blocking fd

Thin, synchronous RPC layer over `cloud9.Client` (which is push/take,
non-blocking-agnostic). One outstanding request at a time (the FUSE loop is
single-threaded). Fids are allocated from a free list.

```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); 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 };
    /// After error.Nine, `ename` holds the server's Rerror text (copied, bounded).
    ename: [256]u8, ename_len: usize,
    msize: u32,
    stop_fd: i32 = -1,          // readable → pending rpc fails with error.Stopped
    interrupt: ?Interrupt = null,

    pub fn connect(gpa: std.mem.Allocator, address: Address, msize: u32) !Session; // socket+connect, version
    pub fn deinit(s: *Session) void;
    pub fn attach(s: *Session, fid: u32, uname: []const u8, aname: []const u8) Error!cloud9.Qid;
    pub fn allocFid(s: *Session) u32;
    pub fn freeFid(s: *Session, fid: u32) void;
    /// Generic RPC. Result slices borrow the input buffer until the next call.
    pub fn rpc(s: *Session, req: cloud9.Client.Request) Error!cloud9.Client.Result;
    // Conveniences (all built on rpc):
    pub fn walk(s, 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(s, fid: u32) Error!u32;             // allocFid + walk with no names
    pub fn open(s, fid: u32, mode: u8) Error!Open;    // Open = { qid, iounit }
    pub fn create(s, fid: u32, name: []const u8, perm: u32, mode: u8) Error!Open;
    pub fn read(s, fid: u32, offset: u64, buf: []u8) Error!usize;   // chunks by maxRead/iounit; stops at short read
    pub fn write(s, fid: u32, offset: u64, data: []const u8) Error!usize; // chunks; stops at short write
    pub fn stat(s, fid: u32) Error!cloud9.Stat;      // strings borrow the input buffer
    pub fn wstat(s, fid: u32, st: cloud9.Stat) Error!void;
    pub fn clunk(s, fid: u32) Error!void;            // frees the fid even on error
    pub fn remove(s, fid: u32) Error!void;           // frees the fid even on error
    pub fn errno(s: *const Session) 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 submit `.version`, drain
output to the socket, read until `take()` yields the version result. The
negotiated msize is `result.version.msize`; if the server answered
`"unknown"`, fail with `error.Protocol`.

`rpc`: submit, write all of `client.output()` (calling `wrote`), then loop:
`take()`; if null, poll the fd together with `stop_fd` and the interrupt
source's descriptor; when the fd is readable, `read` into a temp buffer and
`push` (push returns how much fit; the frame is at most msize so it always
fits after a `take`). If the fd returns 0 → `error.Closed`. If the client
dies → `error.Protocol`. `stop_fd` readable → `error.Stopped`. When the
interrupt source asks for it, submit `.flush = .{ .oldtag = tag }` and keep
waiting: the original reply → returned normally (the Rflush that follows is
skipped by a later call); the Rflush first → `error.Interrupted`. A `.fail`
result copies the ename and returns `error.Nine`. `read`/`write` chunk loops
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;
```

State:

* `inodes: AutoHashMap(u64 /*nodeid*/, Inode{ fid: u32, qid: Qid, nlookup: u64 })`.
  Node 1 is the root (`root_fid`, never forgotten).
* `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 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 | `read(fh.fid, offset, buf[0..min(size, 1 MiB)])`; reply data |
| WRITE | `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.

#### Interrupts (FUSE_INTERRUPT → Tflush)

One request at a time, but not deaf. `serve` puts the FUSE fd in `O_NONBLOCK`
mode (every read follows a poll) and installs a `nine.Interrupt` source that
`Session.rpc` polls together with the socket and `stop_fd` 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 swallowed by a later call) 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 any other unique is
  consumed and dropped (the kernel expects no reply). Any other request
  (FORGET, RELEASE, INIT during the root stat, a second process's LOOKUP) is
  stashed in a one-slot queue that `serve` dispatches, after swapping the two
  buffers, before it polls again; while the slot is full `watch` returns -1,
  so a second one cannot arrive.
* 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 (`Session.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 still blocks the mount until it answers
(the hostile `never` mode; `SIGTERM` to 9ns ends the session as before), and
while the stash is full the FUSE fd is not read, so an INTERRUPT that arrives
after another process's request was parked is seen only once the blocked
request completes (a multi-slot stash would lift that).

### `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
Options:
  --name NAME          mount name: the tree appears at /mnt/9p/NAME (one path
                       component; default derived from the transport, see below)
  --mount PATH         mountpoint inside the new namespace (overrides --name)
  --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.
```

`--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); 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/<T>/*`, `/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/<name>` (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:<port>` 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/<name>` (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.

## Verification

`zig build 9ns-test` (unit), `zig build 9ns-itest` (88 end-to-end
checks against 9proc-demo over unix/tcp/socketpair and against plan9port's
`ramfs`) 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: a 9P read that blocks (event files)
  stalls the whole mount 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 still block the mount until they answer.
* 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).