path: root/9agents/src/tree.zig

//! The harness file tree served over 9P2000: a unified, read-only,
//! fresh-from-disk view of every AI-agent harness's state on the machine.
//!
//!   /README                 what the tree is and how to read it
//!   /pid /uptime            daemon facts, one line each
//!   /claude/                projects/ (mirror of ~/.claude/projects),
//!                           history (~/.claude/history.jsonl),
//!                           skills/ (mirror of ~/.claude/skills)
//!   /codex/                 sessions/ (~/.codex/sessions),
//!                           session-index (~/.codex/session_index.jsonl),
//!                           history (~/.codex/history.jsonl)
//!   /omp/                   mirror of ~/.omp/agent, raw blobs
//!   /hermes/                mirror of ~/.hermes, raw
//!   /dsh/                   mirror of ~/.dsh
//!   /skills/{claude,codex,omp}/   the same skills trees the harnesses own
//!
//! Everything below the named mount points is a lazy mirror: a lookup,
//! getattr or readdir walks the real filesystem at request time, so a
//! session transcript grows as its harness writes it and a new session
//! appears as soon as its file lands. No cache, no invalidation.
//!
//! Security boundary — the exclusion rule is absolute and unit-tested:
//! no name that looks like a credential, key, token or auth store is ever
//! answered, at any depth (`excluded`); symlinks are never served (they
//! are an escape hatch around the pinned roots). Every path is resolved
//! from its pinned root one component at a time with `O_NOFOLLOW`
//! (`openIn`), so no name below a root — swapped mid-session or not —
//! can point the daemon at a file outside it. The daemon must never
//! become a credential reader for anything that mounts it. Writes,
//! creates and setattrs answer EPERM.
//!
//! This module is the backend of `cloud9.fs.Server` (main.zig hands it to
//! `serve.Runner`). It declares `features = .{ .references = true }`: every
//! lookup result is a reference, so table entries below (the mirrored
//! files) are refcounted and freed when the last fid lets go. Node ids
//! pack (kind, root index, serial) in a u64, zmx-style: a mirrored file's
//! serial is its table slot and generation, so two walks of the same file
//! answer the same qid path while it is held.
const std = @import("std");
const cloud9 = @import("cloud9");
const fs = cloud9.fs;
const E = fs.E;
const Io = std.Io;
const linux = std.os.linux;
pub const active = @import("active.zig");

// ---- comptime bounds ---------------------------------------------------------

/// Longest relative path a mirrored file may carry (bytes below a root).
pub const rel_capacity: usize = 640;
/// Mirrored files remembered at once; each holds one reference per fid.
pub const path_capacity: usize = 4096;
comptime {
    if (path_capacity > 1 << 12) @compileError("path table slots must fit the 12 serial bits");
}
/// Largest frame the daemon negotiates; read and readdir staging buffers
/// are this big, so a single Rread can carry one full frame of bytes.
pub const msize: u32 = 32 * 1024;
/// Names one directory listing may stage (sorted for cursor stability).
pub const list_capacity: usize = 1024;
/// Bytes of name storage one listing may use (255 per name, packed).
pub const list_name_bytes: usize = 128 * 1024;
/// Longest base path a pinned root may carry.
pub const base_capacity: usize = 512;

pub const opts: fs.Options = .{
    .fid_capacity = 512,
    .slot_capacity = 8,
    .name_capacity = 255,
    .username_capacity = 28,
    .fid_index = true,
};

// ---- the tree skeleton ------------------------------------------------------

pub const Root = enum(u8) { claude, codex, omp, hermes, dsh };

/// Static nodes: the facts, the harness dirs and the union skills dir.
pub const Top = enum(u8) {
    root = 1,
    pid,
    uptime,
    claude,
    codex,
    omp,
    hermes,
    dsh,
    skills,
    active,
    readme,

    /// Directory entries of the root, in listing order.
    pub const listed = [_]Top{ .readme, .pid, .uptime, .claude, .codex, .omp, .hermes, .dsh, .skills, .active };

    pub fn fileName(t: Top) []const u8 {
        // The only name that is not its tag: a README announces itself in
        // the listing, and lowercase would bury it among the harness dirs.
        return if (t == .readme) "README" else @tagName(t);
    }

    pub fn dir(t: Top) bool {
        return switch (t) {
            .root, .claude, .codex, .omp, .hermes, .dsh, .skills, .active => true,
            .pid, .uptime, .readme => false,
        };
    }

    fn parent(t: Top) Top {
        _ = t;
        return .root; // the root is its own parent; every top hangs off it
    }

    /// The mirror a harness dir serves: its root and the relative path
    /// below it. The claude and codex dirs are *virtual* (their children
    /// are named mounts); omp, hermes and dsh mirror one subtree each.
    fn mirror(t: Top) ?Mount {
        return switch (t) {
            .omp => .{ .root = .omp, .rel = "agent" },
            .hermes => .{ .root = .hermes, .rel = "" },
            .dsh => .{ .root = .dsh, .rel = "" },
            else => null,
        };
    }
};

/// Where a mirrored subtree sits: `rel` below the root's pinned base path.
pub const Mount = struct {
    root: Root,
    rel: []const u8,
};

const NamedMount = struct {
    /// The name as it appears in its virtual directory.
    name: []const u8,
    owner: Top,
    mount: Mount,
};

/// The children of the virtual directories (claude, codex, skills). The
/// same target may appear twice (/claude/skills and /skills/claude): a
/// lookup of either hands out the same table entry, so both paths share
/// qid paths and identity.
const named_mounts = [_]NamedMount{
    .{ .name = "projects", .owner = .claude, .mount = .{ .root = .claude, .rel = "projects" } },
    .{ .name = "history", .owner = .claude, .mount = .{ .root = .claude, .rel = "history.jsonl" } },
    .{ .name = "skills", .owner = .claude, .mount = .{ .root = .claude, .rel = "skills" } },
    .{ .name = "sessions", .owner = .codex, .mount = .{ .root = .codex, .rel = "sessions" } },
    .{ .name = "session-index", .owner = .codex, .mount = .{ .root = .codex, .rel = "session_index.jsonl" } },
    .{ .name = "history", .owner = .codex, .mount = .{ .root = .codex, .rel = "history.jsonl" } },
    .{ .name = "claude", .owner = .skills, .mount = .{ .root = .claude, .rel = "skills" } },
    .{ .name = "codex", .owner = .skills, .mount = .{ .root = .codex, .rel = "skills" } },
    .{ .name = "omp", .owner = .skills, .mount = .{ .root = .omp, .rel = "skills" } },
};

fn mountNamed(owner: Top, name: []const u8) ?Mount {
    for (named_mounts) |m| {
        if (m.owner == owner and std.mem.eql(u8, m.name, name)) return m.mount;
    }
    return null;
}

/// The Top that owns the mount whose target is exactly (root, rel) — the
/// canonical parent a ".." walk answers. Falls back to the root's harness
/// dir for targets no named mount covers (deep paths, mirrors).
fn mountOwner(r: Root, rel_path: []const u8) Top {
    for (named_mounts) |m| {
        if (m.mount.root == r and std.mem.eql(u8, m.mount.rel, rel_path)) return m.owner;
    }
    return switch (r) {
        .claude => .claude,
        .codex => .codex,
        .omp => .omp,
        .hermes => .hermes,
        .dsh => .dsh,
    };
}

// ---- node ids and the path table ---------------------------------------------

pub const Kind = enum(u8) { top = 0, path = 1, active = 2 };

comptime {
    // The derived view indexes the same pinned roots the mirror does.
    for (std.enums.values(Root)) |r| {
        if (!std.mem.eql(u8, @tagName(r), @tagName(@as(active.Kind, @enumFromInt(@intFromEnum(r))))))
            @compileError("tree.Root and active.Kind must agree, index by index");
    }
}

/// A node under `/active`. Everything but a harness directory names a
/// slot of the live table and the generation it had when the id was
/// minted, so an id outlives its process only long enough to answer
/// ENOENT.
pub const AFile = enum(u8) {
    /// `/active/<harness>`
    harness_dir,
    /// `/active/<harness>/<pid>`
    entry,
    pid,
    ppid,
    started,
    cwd,
    name,
    title,
    session,
    model,
    via,
    zmx,
    status,
    transcript,
    /// `/active/<harness>/<pid>/agents`
    agents,
    /// `/active/<harness>/<pid>/agents/<name>`
    agent,
    agent_model,
    agent_transcript,

    /// The fields of one entry, in listing order. A field with no value
    /// is not listed and does not resolve.
    pub const entry_files = [_]AFile{
        .pid, .ppid, .started, .cwd, .name, .title,
        .session, .model, .via, .zmx, .status, .transcript,
    };
    pub const agent_files = [_]AFile{ .agent_model, .agent_transcript };

    pub fn fileName(f: AFile) []const u8 {
        return switch (f) {
            .agent_model => "model",
            .agent_transcript => "transcript",
            else => @tagName(f),
        };
    }
};

/// A resolved `/active` node.
pub const Act = struct {
    file: AFile,
    /// Only for `harness_dir`.
    kind: active.Kind = .claude,
    slot: u8 = 0,
    gen: u8 = 0,
    agent: u8 = 0,
};

pub fn activeNode(a: Act) u64 {
    const serial: u48 = switch (a.file) {
        .harness_dir => @intFromEnum(a.kind),
        else => @as(u48, a.slot) | (@as(u48, a.gen) << 8) | (@as(u48, a.agent) << 16),
    };
    return @bitCast(Node{
        .idx = @intFromEnum(a.file),
        .kind = @intFromEnum(Kind.active),
        .serial = serial,
    });
}

pub const Node = packed struct(u64) {
    /// A Top index (kind == .top) or a Root index (kind == .path).
    idx: u8 = 0,
    kind: u8 = 0,
    serial: u48 = 0,
};

pub fn topNode(t: Top) u64 {
    return @bitCast(Node{ .idx = @intFromEnum(t), .kind = @intFromEnum(Kind.top) });
}

pub const root: u64 = topNode(Top.root);

/// One remembered mirrored file: its root, its relative path, the hash
/// that short-circuits dedupe lookups, and its reference count (one per
/// fid holding it, handed out by lookup, paid back by release).
const Entry = struct {
    used: bool = false,
    root: Root = .claude,
    rel_buf: [rel_capacity]u8 = undefined,
    rel_len: u16 = 0,
    hash: u64 = 0,
    refs: u32 = 0,
    gen: u32 = 0,

    fn rel(e: *const Entry) []const u8 {
        return e.rel_buf[0..e.rel_len];
    }
};

fn serialOf(slot: u12, gen: u32) u48 {
    return (@as(u48, gen) << 12) | slot;
}

fn nodeOf(e: *const Entry, slot: u12) u64 {
    return @bitCast(Node{
        .idx = @intFromEnum(e.root),
        .kind = @intFromEnum(Kind.path),
        .serial = serialOf(slot, e.gen),
    });
}

// ---- the exclusions (the security boundary) -----------------------------------

fn containsFold(name: []const u8, needle: []const u8) bool {
    if (name.len < needle.len) return false;
    var i: usize = 0;
    while (i + needle.len <= name.len) : (i += 1) {
        if (std.ascii.eqlIgnoreCase(name[i .. i + needle.len], needle)) return true;
    }
    return false;
}

fn endsWithFold(name: []const u8, suffix: []const u8) bool {
    return name.len >= suffix.len and std.ascii.eqlIgnoreCase(name[name.len - suffix.len ..], suffix);
}

fn isOneOf(name: []const u8, comptime names: []const []const u8) bool {
    inline for (names) |n| if (std.ascii.eqlIgnoreCase(name, n)) return true;
    return false;
}

/// Absolute rule: a name that may hold a credential, key, token or auth
/// material is never served, at any depth, by lookup or readdir. The
/// substrings are folded (case-insensitive) and deliberately broad —
/// "auth" also hides "author-notes", the price of never guessing wrong.
/// When unsure, exclude and document (docs/DESIGN.md).
pub fn excluded(name: []const u8) bool {
    @setEvalBranchQuota(20000);
    if (name.len == 0) return true;
    for ([_][]const u8{ "credentials", "token", "auth", "secret" }) |needle| {
        if (containsFold(name, needle)) return true;
    }
    if (endsWithFold(name, ".key")) return true;
    if (endsWithFold(name, ".pem")) return true;
    if (endsWithFold(name, ".env")) return true;
    // Config and settings files of the other harnesses may embed API keys
    // (hermes config.yaml, omp config.yml, dsh settings.yaml). Claude
    // Code's settings.json is not in the tree at all: /claude serves only
    // projects/, skills/ and history.jsonl.
    if (isOneOf(name, &.{ "settings.json", "settings.yaml", "settings.local.json", "config.yml", "config.yaml", "config.toml", "models.yml", "models.yaml", ".ssh" })) return true;
    for ([_][]const u8{ "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519" }) |prefix| {
        if (name.len >= prefix.len and std.ascii.eqlIgnoreCase(name[0..prefix.len], prefix)) return true;
    }
    return false;
}

/// Every component of a relative path must pass `excluded`; used on the
/// comptime mount targets and the unit-test fixtures alike.
pub fn excludedPath(rel_path: []const u8) bool {
    @setEvalBranchQuota(4000);
    var it = std.mem.splitScalar(u8, rel_path, '/');
    while (it.next()) |comp| {
        if (excluded(comp)) return true;
    }
    return false;
}

// ---- the backend --------------------------------------------------------------

pub const Answer = struct {
    reply: fs.Reply,
    bytes: []const u8 = "",
};

fn fail(tag: u64, e: u16) Answer {
    return .{ .reply = fs.Reply.fail(tag, e) };
}

/// A refusal that says why. 9P2000 has no numeric error — error(5) is
/// `Rerror tag[2] ename[s]`, a string — and acme names its refusals in words
/// ("permission denied", "file does not exist", fsys.c). A server that only
/// answers bare errnos throws away the one channel the protocol gives it for
/// explaining itself, which matters most here: a move has seven different
/// reasons to say no, and EPERM tells the user none of them.
///
/// `errno` is still carried, because the reader may be a Linux mount rather
/// than a person: 9ns maps the *text* back to an errno by case-insensitive
/// substring (enameToErrno in 9ns/src/nine.zig, first match wins). So each
/// message below is worded to keep the phrase that carries its errno —
/// "not permitted" for EPERM, "invalid" for EINVAL, "exists" for EEXIST,
/// "no such" for ENOENT — and to avoid phrases that would silently retarget
/// it ("permission" and "denied" map to EACCES, "read-only" to EROFS, and
/// the bare substring "fid" to EBADF).
fn failWhy(tag: u64, e: u16, ename: []const u8) Answer {
    return .{ .reply = .{ .tag = tag, .status = .err, .errno = e, .ename = ename } };
}

/// The daemon's state. One instance serves every connection; `handle` is
/// called with `mutex` held (the serve handler in main.zig holds it across
/// handle and reply, because `bytes` point into the shared buffers).
pub const Harness = struct {
    pub const Req = fs.Req;
    pub const Reply = fs.Reply;
    pub const features: fs.Features = .{ .references = true };

    io: Io,
    pid: u32 = 0,
    started_sec: i64 = 0,
    /// The five pinned roots; a root without a base is unreachable.
    base_buf: [5][base_capacity]u8 = @splat(@splat(0)),
    base_len: [5]u16 = @splat(0),
    base_set: [5]bool = @splat(false),
    table: [path_capacity]Entry = @splat(.{}),
    mutex: Io.Mutex = .init,
    // Shared staging (guarded by `mutex`).
    data_buf: [msize]u8 = undefined,
    stage_buf: [msize]u8 = undefined,
    list_names: [list_name_bytes]u8 = undefined,
    list_dirs: [list_capacity]bool = undefined,
    list_offs: [list_capacity]u32 = undefined,

    // The derived view (`/active`). An empty `proc` base turns it off,
    // which is the default: a test must opt in to reading a process
    // tree, and never the live one.
    live: active.Table = .{},
    proc_buf: [base_capacity]u8 = @splat(0),
    proc_len: u16 = 0,
    home_buf: [base_capacity]u8 = @splat(0),
    home_len: u16 = 0,
    zmx_buf: [base_capacity]u8 = @splat(0),
    zmx_len: u16 = 0,
    runtime_buf: [base_capacity]u8 = @splat(0),
    runtime_len: u16 = 0,
    envp: ?cloud9.post.Env = null,
    self_pid: u32 = 0,
    btime: i64 = 0,
    allow_move: bool = false,
    act_text: [1024]u8 = undefined,
    act_name: [64]u8 = undefined,
    act_path: [active.path_capacity]u8 = undefined,

    pub const InitOptions = struct {
        io: Io,
        pid: u32,
        /// Base path of each root, or "" when the root is not pinned.
        bases: [5][]const u8,
        /// The proc filesystem `/active` reads. Empty — the default —
        /// leaves the derived view out of the tree entirely.
        proc: []const u8 = "",
        /// $HOME, for the harnesses' store-slug spellings.
        home: []const u8 = "",
        /// The zmx binary a move execs, resolved to an absolute path by
        /// the caller. Never client bytes.
        zmx: []const u8 = "zmx",
        /// $XDG_RUNTIME_DIR, where a move looks for the zmx session it
        /// is about to create.
        runtime: []const u8 = "",
        /// The daemon's own environment block, handed to the harness a
        /// move re-execs. Null leaves a moved agent with an empty one.
        envp: ?cloud9.post.Env = null,
        /// Whether writing `/active/<h>/<pid>/zmx` may move a session.
        allow_move: bool = false,
    };

    pub fn init(h: *Harness, o: InitOptions) void {
        h.* = .{ .io = o.io, .pid = o.pid, .started_sec = Io.Timestamp.now(o.io, .real).toSeconds() };
        if (o.proc.len > 0 and o.proc.len <= base_capacity) {
            @memcpy(h.proc_buf[0..o.proc.len], o.proc);
            h.proc_len = @intCast(o.proc.len);
            h.self_pid = o.pid;
            h.btime = active.bootTime(o.io, o.proc);
        }
        if (o.home.len <= base_capacity) {
            @memcpy(h.home_buf[0..o.home.len], o.home);
            h.home_len = @intCast(o.home.len);
        }
        if (o.zmx.len > 0 and o.zmx.len <= base_capacity) {
            @memcpy(h.zmx_buf[0..o.zmx.len], o.zmx);
            h.zmx_len = @intCast(o.zmx.len);
        }
        if (o.runtime.len <= base_capacity) {
            @memcpy(h.runtime_buf[0..o.runtime.len], o.runtime);
            h.runtime_len = @intCast(o.runtime.len);
        }
        h.allow_move = o.allow_move;
        h.envp = o.envp;
        inline for (0..5) |i| {
            const path = o.bases[i];
            h.base_set[i] = path.len > 0 and path.len <= base_capacity;
            if (h.base_set[i]) {
                @memcpy(h.base_buf[i][0..path.len], path);
                h.base_len[i] = @intCast(path.len);
            }
        }
    }

    pub fn base(h: *const Harness, r: Root) ?[]const u8 {
        if (!h.base_set[@intFromEnum(r)]) return null;
        return h.base_buf[@intFromEnum(r)][0..h.base_len[@intFromEnum(r)]];
    }

    // -- path table --

    fn hashOf(r: Root, rel_path: []const u8) u64 {
        var hh = std.hash.Wyhash.init(0x6861_726e_6573_7300); // "harness"
        hh.update(&.{@intFromEnum(r)});
        hh.update(rel_path);
        return hh.final();
    }

    /// Finds or creates the entry for (root, rel). `ref` says whether the
    /// caller hands out a reference (a lookup) or only names the file (a
    /// readdir record). Two walks of the same file find the same entry,
    /// so their node ids are equal; a freed entry's generation changes.
    fn entryFor(h: *Harness, r: Root, rel_path: []const u8, ref: bool) ?*Entry {
        if (rel_path.len == 0 or rel_path.len > rel_capacity) return null;
        const hash = hashOf(r, rel_path);
        var free: ?*Entry = null;
        for (&h.table) |*e| {
            if (!e.used) {
                if (free == null) free = e;
                continue;
            }
            if (e.hash == hash and e.root == r and e.rel_len == rel_path.len and
                std.mem.eql(u8, e.rel(), rel_path))
            {
                if (ref) e.refs += 1;
                return e;
            }
        }
        const e = free orelse return null;
        e.used = true;
        e.root = r;
        e.rel_len = @intCast(rel_path.len);
        @memcpy(e.rel_buf[0..rel_path.len], rel_path);
        e.hash = hash;
        e.refs = @intFromBool(ref);
        e.gen +%= 1;
        return e;
    }

    fn slotOf(h: *Harness, e: *Entry) u12 {
        const off = (@intFromPtr(e) - @intFromPtr(&h.table)) / @sizeOf(Entry);
        return @intCast(off);
    }

    /// The target a node names; a freed or forged serial answers null.
    fn resolve(h: *Harness, node: u64) ?Target {
        const n: Node = @bitCast(node);
        switch (std.enums.fromInt(Kind, n.kind) orelse return null) {
            .top => return .{ .top = std.enums.fromInt(Top, n.idx) orelse return null },
            .path => {
                const r = std.enums.fromInt(Root, n.idx) orelse return null;
                const slot: u12 = @truncate(n.serial);
                const e = &h.table[slot];
                if (!e.used or e.root != r) return null;
                if (serialOf(slot, e.gen) != n.serial) return null;
                return .{ .path = e };
            },
            .active => {
                const f = std.enums.fromInt(AFile, n.idx) orelse return null;
                if (f == .harness_dir) {
                    const k = std.enums.fromInt(active.Kind, @as(u8, @truncate(n.serial))) orelse return null;
                    return .{ .act = .{ .file = f, .kind = k } };
                }
                const slot: u8 = @truncate(n.serial);
                const gen: u8 = @truncate(n.serial >> 8);
                const agent: u8 = @truncate(n.serial >> 16);
                const l = h.live.at(slot, gen) orelse return null;
                return .{ .act = .{ .file = f, .kind = l.kind, .slot = slot, .gen = gen, .agent = agent } };
            },
        }
    }

    fn entryNode(h: *Harness, e: *Entry) u64 {
        return nodeOf(e, h.slotOf(e));
    }
};

pub const Target = union(enum) {
    top: Top,
    path: *Entry,
    act: Act,
};

// ---- attributes ---------------------------------------------------------------

/// Opens `<base(root)>/<rel>` without following a symlink at any step
/// below the base: every component is opened with `O_NOFOLLOW`, so a
/// name swapped for a symlink between the walk and the read fails
/// instead of reaching out of the root. Composing the whole path and
/// opening it in one call cannot do that — only the last component's
/// symlink is refused then, and every directory above it is followed
/// wherever it points. The base itself is configuration (`--root` or
/// $HOME), not client bytes, so it resolves normally. The caller owns
/// the descriptor.
fn openIn(h: *Harness, r: Root, rel_path: []const u8, final: linux.O) ?i32 {
    const b = h.base(r) orelse return null;
    if (rel_path.len > rel_capacity or b.len > base_capacity) return null;
    const walk: linux.O = .{ .PATH = true, .DIRECTORY = true, .CLOEXEC = true, .NOFOLLOW = true };

    var base_z: [base_capacity + 1]u8 = @splat(0);
    @memcpy(base_z[0..b.len], b);
    var top_flags = if (rel_path.len == 0) final else walk;
    top_flags.NOFOLLOW = false; // the pinned root may legitimately be a link
    top_flags.CLOEXEC = true;
    var fd = fdOf(linux.open(@ptrCast(&base_z), top_flags, 0)) orelse return null;
    if (rel_path.len == 0) return fd;

    var rest = rel_path;
    while (true) {
        const slash = std.mem.indexOfScalar(u8, rest, '/');
        const comp = if (slash) |i| rest[0..i] else rest;
        const last = slash == null;
        // Nothing below composes these; a component that could re-enter
        // the walk is refused rather than opened.
        if (comp.len == 0 or comp.len > 255 or
            std.mem.eql(u8, comp, ".") or std.mem.eql(u8, comp, ".."))
        {
            _ = linux.close(fd);
            return null;
        }
        var name_z: [256]u8 = @splat(0);
        @memcpy(name_z[0..comp.len], comp);
        var flags = if (last) final else walk;
        flags.NOFOLLOW = true;
        flags.CLOEXEC = true;
        const next = fdOf(linux.openat(fd, @ptrCast(&name_z), flags, 0));
        _ = linux.close(fd);
        fd = next orelse return null;
        if (last) return fd;
        rest = rest[comp.len + 1 ..];
    }
}

fn fdOf(rc: usize) ?i32 {
    if (linux.errno(rc) != .SUCCESS) return null;
    return @intCast(rc);
}

/// Stat of `<base(root)>/<rel>`, resolved the no-follow way. A symlink
/// is never served: it is the one escape hatch around the pinned roots.
/// `O_PATH` opens the name itself, so a fifo or device never blocks and
/// never has its open side effects run.
/// A stat plus the file's identity on disk.
const Stat = struct {
    st: Io.Dir.Stat,
    /// The qid path to report, or 0 when the kernel would not say.
    ///
    /// intro(5) is strict about what a qid path means: "The path is an
    /// integer unique among all files in the hierarchy. If a file is deleted
    /// and recreated with the same name in the same directory, the old and
    /// new path components of the qids should be different" — and two files
    /// are the same file if and only if their qids match. So the path has to
    /// be a property of the *file*, stable for as long as it exists.
    ///
    /// The backend's own node id cannot supply that: it is a slot in the path
    /// table, and a slot freed by its last release comes back with a new
    /// generation (the guard that stops a forged node id resolving). A client
    /// that walks, stats and clunks — `9p stat` does exactly this — saw a
    /// different qid path for the same unchanged file every single time, and
    /// by the protocol's own rule that means a different file.
    ///
    /// So this is u9fs's answer instead, from the same fstat the attr already
    /// needs:
    ///
    ///     memmove(p, &st->st_ino, ...); *(dev_t*)q ^= st->st_dev;  -- u9fs.c
    ///
    /// The device is mixed in because an inode number is only unique within
    /// its filesystem, and the five pinned roots need not share one. The
    /// engine keeps resolving requests by node id, which still recycles; only
    /// the qid the client sees is stabilised (fs.Attr.path exists for exactly
    /// this split, and the engine uses it for nothing else).
    qid_path: u64,
};

fn statIn(h: *Harness, r: Root, rel_path: []const u8) ?Stat {
    const fd = openIn(h, r, rel_path, .{ .PATH = true, .CLOEXEC = true }) orelse return null;
    const f: Io.File = .{ .handle = fd, .flags = .{ .nonblocking = false } };
    defer f.close(h.io);
    const st = f.stat(h.io) catch return null;
    if (st.kind == .sym_link) return null; // never served: an escape hatch
    return .{ .st = st, .qid_path = identityOf(fd) };
}

/// (dev, ino) of an open descriptor, folded into one integer. 0 when statx
/// declines to answer, which the caller reads as "fall back to the node id".
fn identityOf(fd: i32) u64 {
    var sx: linux.Statx = undefined;
    const want: linux.STATX = .{ .INO = true };
    const rc = linux.statx(fd, "", linux.AT.EMPTY_PATH, want, &sx);
    if (linux.errno(rc) != .SUCCESS or !sx.mask.INO) return 0;
    const dev = (@as(u64, sx.dev_major) << 32) | sx.dev_minor;
    // The inode carries the entropy, so it stays unshifted and the device is
    // folded over its top bits: two roots on one filesystem keep distinct
    // inodes, and the same inode on two filesystems stops colliding.
    return sx.ino ^ (dev *% 0x9E37_79B9_7F4A_7C15);
}

/// The qid version of a file on disk, the way u9fs derives it:
///
///     qid.vers = st->st_mtime ^ (st->st_size << 8);   -- u9fs.c
///
/// intro(5) makes the qid the server's identity for a file — "two files on
/// the same server hierarchy are the same if and only if their qids are the
/// same" — and the version the part that "is incremented every time the file
/// is modified". A server that leaves it 0 is telling every client that
/// nothing it serves ever changes, which is exactly wrong for this tree: its
/// whole point is transcripts that grow while you read them. The size shift
/// is what makes an append within the same second still change the version,
/// and a rewrite that keeps the size change it through the mtime.
fn qidVers(mtime_sec: i64, size: u64) u32 {
    return @truncate(@as(u64, @bitCast(mtime_sec)) ^ (size << 8));
}

/// The qid version of text this server derives rather than reads: there is no
/// mtime behind it, so the content itself is the only honest version.
fn textVers(text: []const u8) u32 {
    return @truncate(std.hash.Wyhash.hash(0, text));
}

fn statAttr(h: *Harness, e: *Entry) ?fs.Attr {
    const got = statIn(h, e.root, e.rel()) orelse return null;
    const st = got.st;
    const mtime = st.mtime.toSeconds();
    const size: u64 = if (st.kind == .directory) 0 else st.size;
    return .{
        .name = basename(e.rel()),
        .node = h.entryNode(e),
        .dir = st.kind == .directory,
        // stat(5): "Directories and most files representing devices have a
        // conventional length of 0."
        .size = size,
        .mode = if (st.kind == .directory) 0o555 else 0o444,
        .mtime = @truncate(@as(u64, @bitCast(mtime))),
        .version = qidVers(mtime, size),
        .path = if (got.qid_path != 0) got.qid_path else null,
    };
}

fn basename(rel_path: []const u8) []const u8 {
    if (std.mem.lastIndexOfScalar(u8, rel_path, '/')) |i| return rel_path[i + 1 ..];
    return rel_path;
}

/// Served as `/README`: what the tree is and how to read it. Static, so it
/// is the one "fact" that needs no buffer — `factText` returns it directly.
const readme_text =
    \\9agents - every coding agent's state on this machine, as files.
    \\Read-only: writes answer EPERM. Nothing is cached, so a transcript
    \\grows while you cat it and a new session appears as soon as its
    \\file lands.
    \\
    \\  README              this file
    \\  pid  uptime         this daemon's pid; seconds since it started
    \\  active/             what is running right now
    \\  claude/             projects/ history skills/
    \\  codex/              sessions/ session-index history
    \\  omp/ hermes/ dsh/   each harness's own directory, raw
    \\  skills/             claude/ codex/ omp/, in one place
    \\
    \\active/<harness>/<pid>/ holds pid ppid started cwd name title
    \\session via status transcript zmx.
    \\  session     its session id, empty when it did not resolve
    \\  via         how that id was found: registry, fd, dir or none
    \\  status      only harnesses that publish one have it
    \\  transcript  the live .jsonl; its mtime is the last activity
    \\  zmx         the zmx session it runs in, empty outside zmx
    \\
    \\  ls active/*/*                       what is running
    \\  cat active/claude/345104/session    what it is
    \\  tail -f active/claude/345104/transcript
    \\
    \\Credentials are excluded by name and never listed, at any depth;
    \\symlinks are never served. Writing a name into an agent's zmx file
    \\moves it into that zmx session, and only when the daemon was
    \\started with --allow-move; otherwise that write answers EPERM too.
    \\
;

/// A fact's text, rendered on demand. `buf` should be a small stack buffer.
fn factText(h: *Harness, fact: Top, buf: []u8) []const u8 {
    if (fact == .readme) return readme_text; // static: outlives any buffer
    var w = Io.Writer.fixed(buf);
    switch (fact) {
        .pid => w.print("{d}\n", .{h.pid}) catch {},
        .uptime => {
            const now = Io.Timestamp.now(h.io, .real).toSeconds();
            const up: u64 = if (now > h.started_sec) @intCast(now - h.started_sec) else 0;
            w.print("{d}\n", .{up}) catch {};
        },
        else => {},
    }
    return w.buffered();
}

var fact_buf: [64]u8 = undefined;

fn attrFor(h: *Harness, t: Target) ?fs.Attr {
    switch (t) {
        .top => |top| {
            switch (top) {
                .root => return .{ .name = "/", .node = root, .dir = true, .mode = 0o555 },
                .active => return .{ .name = "active", .node = topNode(.active), .dir = true, .mode = 0o555 },
                .pid, .uptime, .readme => return .{
                    .name = top.fileName(),
                    .node = topNode(top),
                    .size = factText(h, top, &fact_buf).len,
                    .mode = 0o444,
                },
                .claude, .codex, .skills => return .{
                    .name = top.fileName(),
                    .node = topNode(top),
                    .dir = true,
                    .mode = 0o555,
                },
                .omp, .hermes, .dsh => {
                    // The harness dir IS its mirror: stat the target.
                    const m = top.mirror().?;
                    const got = statIn(h, m.root, m.rel) orelse return null;
                    if (got.st.kind != .directory) return null;
                    return .{
                        .name = top.fileName(),
                        .node = topNode(top),
                        .dir = true,
                        .mode = 0o555,
                        .path = if (got.qid_path != 0) got.qid_path else null,
                    };
                },
            }
        },
        .path => |e| return statAttr(h, e),
        .act => |a| return activeAttr(h, a),
    }
}

/// Attr of the mount target as a table entry (fresh from disk, or null
/// when the target is missing, a symlink, or excluded by name).
fn attrOfMount(h: *Harness, r: Root, rel_path: []const u8) ?fs.Attr {
    const e = h.entryFor(r, rel_path, false) orelse return null;
    defer if (e.refs == 0) {
        e.used = false;
        e.gen +%= 1;
    };
    return statAttr(h, e);
}

// ---- /active: the derived view -------------------------------------------------

fn sourcesOf(h: *Harness) active.Sources {
    var roots: [5][]const u8 = @splat("");
    for (0..5) |i| {
        if (h.base_set[i]) roots[i] = h.base_buf[i][0..h.base_len[i]];
    }
    return .{
        .io = h.io,
        .proc = h.proc_buf[0..h.proc_len],
        .home = h.home_buf[0..h.home_len],
        .roots = roots,
        .self_pid = h.self_pid,
        .btime = h.btime,
    };
}

/// Rescans the process tree. Done on a listing of `/active` and on a
/// lookup that misses, which is what makes an agent visible the moment
/// it starts and gone the moment it exits.
fn rescan(h: *Harness) void {
    if (h.proc_len == 0) return;
    h.live.scan(sourcesOf(h));
}

fn hasLive(h: *Harness, k: active.Kind) bool {
    for (&h.live.slots) |*sl| {
        if (sl.used and sl.live.kind == k) return true;
    }
    return false;
}

/// `<text>\n` staged where an answer can point at it.
fn line(h: *Harness, text: []const u8) ?[]const u8 {
    return std.fmt.bufPrint(&h.act_text, "{s}\n", .{text}) catch null;
}

/// The value of a field file, or null when this agent has none — an
/// absent field is not listed and does not resolve, so the tree never
/// answers a blank where it does not know.
fn activeText(h: *Harness, a: Act) ?[]const u8 {
    const l = h.live.at(a.slot, a.gen) orelse return null;
    const src = sourcesOf(h);
    var scratch: [active.text_capacity]u8 = undefined;
    return switch (a.file) {
        .pid => std.fmt.bufPrint(&h.act_text, "{d}\n", .{l.pid}) catch null,
        .ppid => if (l.ppid == 0) null else std.fmt.bufPrint(&h.act_text, "{d}\n", .{l.ppid}) catch null,
        .started => if (l.started == 0) null else std.fmt.bufPrint(&h.act_text, "{d}\n", .{l.started}) catch null,
        .cwd => if (l.cwd.len == 0) null else line(h, l.cwd.slice()),
        .session => if (l.session.len == 0) null else line(h, l.session.slice()),
        .via => line(h, l.via.text()),
        .name => line(h, active.registryField(src, l, "name", &scratch) orelse return null),
        .status => line(h, active.registryField(src, l, "status", &scratch) orelse return null),
        .title => line(h, active.headField(h.io, l.kind, l.transcript.slice(), .title, &scratch) orelse return null),
        .model => line(h, active.headField(h.io, l.kind, l.transcript.slice(), .model, &scratch) orelse return null),
        .agent_model => blk: {
            const path = activePath(h, a) orelse break :blk null;
            break :blk line(h, active.headField(h.io, l.kind, path, .model, &scratch) orelse return null);
        },
        // `zmx` is always there, so it can always be written to; empty
        // means the agent runs outside zmx.
        .zmx => if (active.zmxOf(src, l.pid, &scratch)) |v| line(h, v) else h.act_text[0..0],
        else => null,
    };
}

/// The absolute path behind a transcript-shaped file.
fn activePath(h: *Harness, a: Act) ?[]const u8 {
    const l = h.live.at(a.slot, a.gen) orelse return null;
    switch (a.file) {
        .transcript => return if (l.transcript.len == 0) null else l.transcript.slice(),
        .agent_transcript, .agent_model => {
            var ag: active.Agents = .{};
            active.agentsOf(h.io, l, &ag);
            return active.agentPath(l, &ag, a.agent, &h.act_path);
        },
        else => return null,
    }
}

/// Opens an absolute path without following a symlink at the last
/// component. These paths are derived from a pinned root or from the
/// fd the harness itself holds, never from client bytes, but a name
/// swapped underneath must still fail rather than redirect.
fn openAbsNoFollow(path: []const u8) ?i32 {
    if (path.len == 0 or path.len >= active.path_capacity) return null;
    var z: [active.path_capacity]u8 = @splat(0);
    @memcpy(z[0..path.len], path);
    const rc = linux.open(@ptrCast(&z), .{
        .ACCMODE = .RDONLY,
        .NOFOLLOW = true,
        .CLOEXEC = true,
        .NONBLOCK = true,
    }, 0);
    if (linux.errno(rc) != .SUCCESS) return null;
    return @intCast(rc);
}

fn activeAttr(h: *Harness, a: Act) ?fs.Attr {
    switch (a.file) {
        .harness_dir => {
            if (!hasLive(h, a.kind)) return null;
            return .{ .name = a.kind.text(), .node = activeNode(a), .dir = true, .mode = 0o555 };
        },
        .entry => {
            const l = h.live.at(a.slot, a.gen) orelse return null;
            const nm = std.fmt.bufPrint(&h.act_name, "{d}", .{l.pid}) catch return null;
            return .{ .name = nm, .node = activeNode(a), .dir = true, .mode = 0o555 };
        },
        .agents => {
            const l = h.live.at(a.slot, a.gen) orelse return null;
            if (l.agent_dir.len == 0) return null;
            return .{ .name = "agents", .node = activeNode(a), .dir = true, .mode = 0o555 };
        },
        .agent => {
            const l = h.live.at(a.slot, a.gen) orelse return null;
            var ag: active.Agents = .{};
            active.agentsOf(h.io, l, &ag);
            if (a.agent >= ag.count) return null;
            const nm = ag.name(a.agent);
            @memcpy(h.act_name[0..nm.len], nm);
            return .{ .name = h.act_name[0..nm.len], .node = activeNode(a), .dir = true, .mode = 0o555 };
        },
        .transcript, .agent_transcript => {
            const path = activePath(h, a) orelse return null;
            const st = Io.Dir.statFile(.cwd(), h.io, path, .{ .follow_symlinks = false }) catch return null;
            if (st.kind != .file) return null;
            const mtime = st.mtime.toSeconds();
            return .{
                .name = a.file.fileName(),
                .node = activeNode(a),
                .size = st.size,
                .mode = 0o444,
                .mtime = @truncate(@as(u64, @bitCast(mtime))),
                .version = qidVers(mtime, st.size),
            };
        },
        else => {
            const text = activeText(h, a) orelse return null;
            // Only `zmx` is ever writable, and only when a move is allowed.
            const mode: u16 = if (a.file == .zmx and h.allow_move) 0o644 else 0o444;
            return .{
                .name = a.file.fileName(),
                .node = activeNode(a),
                .size = text.len,
                .mode = mode,
                // Derived, not read: `status` flipping busy->idle keeps its
                // size, so only the text can carry the change.
                .version = textVers(text),
            };
        },
    }
}

/// The slot holding `pid` for this harness, if any.
fn slotOfPid(h: *Harness, k: active.Kind, pid: u32) ?Act {
    for (&h.live.slots, 0..) |*sl, i| {
        if (!sl.used or sl.live.kind != k or sl.live.pid != pid) continue;
        return .{ .file = .entry, .kind = k, .slot = @intCast(i), .gen = sl.gen };
    }
    return null;
}

fn activeLookup(h: *Harness, req: fs.Req, a: Act, name: []const u8) Answer {
    switch (a.file) {
        .harness_dir => {
            const pid = std.fmt.parseInt(u32, name, 10) catch return fail(req.tag, E.NOENT);
            var found = slotOfPid(h, a.kind, pid);
            if (found == null) {
                rescan(h);
                found = slotOfPid(h, a.kind, pid);
            }
            const act = found orelse return fail(req.tag, E.NOENT);
            return activeReply(h, req, act, name);
        },
        .entry => {
            if (std.mem.eql(u8, name, "agents")) {
                return activeReply(h, req, .{ .file = .agents, .kind = a.kind, .slot = a.slot, .gen = a.gen }, name);
            }
            for (AFile.entry_files) |f| {
                if (!std.mem.eql(u8, f.fileName(), name)) continue;
                return activeReply(h, req, .{ .file = f, .kind = a.kind, .slot = a.slot, .gen = a.gen }, name);
            }
            return fail(req.tag, E.NOENT);
        },
        .agents => {
            const l = h.live.at(a.slot, a.gen) orelse return fail(req.tag, E.NOENT);
            var ag: active.Agents = .{};
            active.agentsOf(h.io, l, &ag);
            const i = ag.indexOf(name) orelse return fail(req.tag, E.NOENT);
            return activeReply(h, req, .{
                .file = .agent,
                .kind = a.kind,
                .slot = a.slot,
                .gen = a.gen,
                .agent = @intCast(i),
            }, name);
        },
        .agent => {
            for (AFile.agent_files) |f| {
                if (!std.mem.eql(u8, f.fileName(), name)) continue;
                return activeReply(h, req, .{
                    .file = f,
                    .kind = a.kind,
                    .slot = a.slot,
                    .gen = a.gen,
                    .agent = a.agent,
                }, name);
            }
            return fail(req.tag, E.NOENT);
        },
        else => return fail(req.tag, E.NOTDIR),
    }
}

fn activeReply(h: *Harness, req: fs.Req, a: Act, name: []const u8) Answer {
    const attr = activeAttr(h, a) orelse return fail(req.tag, E.NOENT);
    var with_name = attr;
    with_name.name = name;
    return .{ .reply = .{ .tag = req.tag, .attr = with_name } };
}

fn activeReaddir(h: *Harness, req: fs.Req, a: Act) Answer {
    var st: Staging = .{ .buf = &h.stage_buf, .skip = req.off };
    switch (a.file) {
        .harness_dir => {
            for (&h.live.slots, 0..) |*sl, i| {
                if (!sl.used or sl.live.kind != a.kind) continue;
                var num: [24]u8 = undefined;
                const nm = std.fmt.bufPrint(&num, "{d}", .{sl.live.pid}) catch continue;
                st.add(activeNode(.{
                    .file = .entry,
                    .kind = a.kind,
                    .slot = @intCast(i),
                    .gen = sl.gen,
                }), true, nm);
            }
        },
        .entry => {
            const l = h.live.at(a.slot, a.gen) orelse return fail(req.tag, E.NOENT);
            for (AFile.entry_files) |f| {
                const child: Act = .{ .file = f, .kind = a.kind, .slot = a.slot, .gen = a.gen };
                if (activeAttr(h, child) == null) continue; // no value: not listed
                st.add(activeNode(child), false, f.fileName());
            }
            if (l.agent_dir.len > 0) {
                st.add(activeNode(.{ .file = .agents, .kind = a.kind, .slot = a.slot, .gen = a.gen }), true, "agents");
            }
        },
        .agents => {
            const l = h.live.at(a.slot, a.gen) orelse return fail(req.tag, E.NOENT);
            var ag: active.Agents = .{};
            active.agentsOf(h.io, l, &ag);
            for (0..ag.count) |i| {
                st.add(activeNode(.{
                    .file = .agent,
                    .kind = a.kind,
                    .slot = a.slot,
                    .gen = a.gen,
                    .agent = @intCast(i),
                }), true, ag.name(i));
            }
        },
        .agent => {
            for (AFile.agent_files) |f| {
                const child: Act = .{ .file = f, .kind = a.kind, .slot = a.slot, .gen = a.gen, .agent = a.agent };
                if (activeAttr(h, child) == null) continue;
                st.add(activeNode(child), false, f.fileName());
            }
        },
        else => return fail(req.tag, E.NOTDIR),
    }
    return .{ .reply = .{ .tag = req.tag }, .bytes = h.stage_buf[0..st.len] };
}

fn activeRead(h: *Harness, req: fs.Req, a: Act) Answer {
    switch (a.file) {
        .harness_dir, .entry, .agents, .agent => return fail(req.tag, E.ISDIR),
        .transcript, .agent_transcript => {
            const path = activePath(h, a) orelse return fail(req.tag, E.NOENT);
            const fd = openAbsNoFollow(path) orelse return fail(req.tag, E.NOENT);
            const file: Io.File = .{ .handle = fd, .flags = .{ .nonblocking = false } };
            defer file.close(h.io);
            const st = file.stat(h.io) catch return fail(req.tag, E.IO);
            if (st.kind == .directory) return fail(req.tag, E.ISDIR);
            if (st.kind != .file) return fail(req.tag, E.PERM);
            _ = linux.fcntl(fd, linux.F.SETFL, 0);
            const want = @min(req.size, h.data_buf.len);
            const n = file.readPositionalAll(h.io, h.data_buf[0..want], req.off) catch
                return fail(req.tag, E.IO);
            return .{ .reply = .{ .tag = req.tag }, .bytes = h.data_buf[0..n] };
        },
        else => {
            const text = activeText(h, a) orelse return fail(req.tag, E.NOENT);
            return window(req, text);
        },
    }
}

// ---- the move: writing a zmx session name into an agent's `zmx` ----------------

/// How long a move waits, in 100ms ticks: for the agent to take the
/// hangup, then to die outright, then for the new zmx session to post.
const term_ticks: usize = 50;
const kill_ticks: usize = 30;
const post_ticks: usize = 100;

fn napOneTick(h: *Harness) void {
    h.io.sleep(.fromMilliseconds(100), .awake) catch {};
}

/// Is this name already a live zmx session? zmx posts each session into
/// the registry, so the registry is the answer — no process scanning.
fn zmxPosted(h: *Harness, name: []const u8) bool {
    if (h.runtime_len == 0) return false;
    var buf: [active.path_capacity]u8 = undefined;
    const path = std.fmt.bufPrint(&buf, "{s}/9p/zmx/{s}", .{ h.runtime_buf[0..h.runtime_len], name }) catch return true;
    return Io.Dir.statFile(.cwd(), h.io, path, .{ .follow_symlinks = true }) != error.FileNotFound;
}

fn procGone(h: *Harness, pid: u32) bool {
    var buf: [active.path_capacity]u8 = undefined;
    const path = std.fmt.bufPrint(&buf, "{s}/{d}", .{ h.proc_buf[0..h.proc_len], pid }) catch return false;
    _ = Io.Dir.statFile(.cwd(), h.io, path, .{ .follow_symlinks = true }) catch return true;
    return false;
}

/// SIGTERM, then SIGKILL, then give up. The agent's session was
/// resolved before this ran, so whatever happens it has somewhere to
/// come back to.
fn killAndWait(h: *Harness, pid: u32) bool {
    _ = linux.kill(@intCast(pid), .TERM);
    for (0..term_ticks) |_| {
        if (procGone(h, pid)) return true;
        napOneTick(h);
    }
    _ = linux.kill(@intCast(pid), .KILL);
    for (0..kill_ticks) |_| {
        if (procGone(h, pid)) return true;
        napOneTick(h);
    }
    return false;
}

/// `zmx run <name> -d <harness> <resume flag> <resume value>`, in the
/// agent's own directory. Every word but `<name>` is fixed by the
/// harness; `<name>` was checked against zmx's label charset before
/// anything was killed. No byte a client wrote reaches `exec` as a
/// command.
fn spawnZmx(h: *Harness, l: *const active.Live, name: []const u8, resume_value: []const u8) bool {
    if (h.zmx_len == 0) return false;
    const harness_argv0: []const u8 = @tagName(l.kind);
    const resume_flag: []const u8 = switch (l.kind) {
        .codex => "resume",
        else => "--resume",
    };

    // One buffer holds every NUL-terminated word; `argv` points into it.
    var words: [8 * active.path_capacity]u8 = undefined;
    var used: usize = 0;
    var argv: [9]?[*:0]const u8 = @splat(null);
    var n: usize = 0;
    const parts = [_][]const u8{
        h.zmx_buf[0..h.zmx_len], "run", name, "-d",
        harness_argv0,           resume_flag, resume_value,
    };
    for (parts) |w| {
        if (used + w.len + 1 > words.len or n + 1 >= argv.len) return false;
        @memcpy(words[used..][0..w.len], w);
        words[used + w.len] = 0;
        argv[n] = @ptrCast(&words[used]);
        n += 1;
        used += w.len + 1;
    }

    var cwd_z: [active.cwd_capacity + 1]u8 = @splat(0);
    if (l.cwd.len >= cwd_z.len) return false;
    @memcpy(cwd_z[0..l.cwd.len], l.cwd.slice());

    const rc = linux.fork();
    if (linux.errno(rc) != .SUCCESS) return false;
    if (rc == 0) {
        // The child: only async-signal-safe calls from here.
        _ = linux.chdir(@ptrCast(&cwd_z));
        const empty = [_:null]?[*:0]const u8{};
        const envp: cloud9.post.Env = h.envp orelse &empty;
        _ = linux.execve(argv[0].?, @ptrCast(&argv), envp);
        linux.exit(127);
    }
    // Reap the forked `zmx`, which returns as soon as the session is up.
    const child: i32 = @intCast(rc);
    var status: u32 = 0;
    for (0..post_ticks) |_| {
        const w = linux.waitpid(child, &status, 1); // WNOHANG
        if (w == @as(usize, @intCast(child))) break;
        napOneTick(h);
    }
    return true;
}

/// A move: kill the agent and bring it back inside a zmx session of the
/// name written. Refusals come before anything is destroyed.
fn moveToZmx(h: *Harness, req: fs.Req, a: Act) Answer {
    if (!h.allow_move) return failWhy(req.tag, E.PERM, "moves are not permitted: start 9agents with --allow-move");
    const name = std.mem.trim(u8, req.data, " \t\r\n");
    if (!active.legalZmxName(name)) return failWhy(req.tag, E.INVAL, "invalid zmx name: letters, digits, dot, dash and underscore only");

    const l = h.live.at(a.slot, a.gen) orelse return fail(req.tag, E.NOENT);
    // Nothing is killed that has nowhere to come back to.
    if (l.via == .none or l.session.len == 0) return failWhy(req.tag, E.PERM, "no session resolved: not permitted, there would be nothing to resume");
    if (l.cwd.len == 0) return failWhy(req.tag, E.PERM, "no working directory known for this agent: not permitted");
    const resume_value: []const u8 = switch (l.kind) {
        // omp resumes by the transcript it wrote, the others by id.
        .omp => l.transcript.slice(),
        .claude, .codex, .hermes => l.session.slice(),
        // dsh has no resume form worth guessing at.
        .dsh => return failWhy(req.tag, E.PERM, "dsh has no resume form: moving it is not permitted"),
    };
    if (resume_value.len == 0) return failWhy(req.tag, E.PERM, "nothing to resume from: not permitted");

    // Already there: setting a value it already has changes nothing.
    var have: [active.text_capacity]u8 = undefined;
    if (active.zmxOf(sourcesOf(h), l.pid, &have)) |current| {
        if (std.mem.eql(u8, current, name)) {
            return .{ .reply = .{ .tag = req.tag, .written = @intCast(req.data.len) } };
        }
    }
    if (zmxPosted(h, name)) return failWhy(req.tag, E.EXIST, "a live zmx session of that name already exists");
    // The slot could have gone stale between the scan and this write.
    if (!active.stillAlive(sourcesOf(h), l)) return failWhy(req.tag, E.NOENT, "the agent exited before the move began: no such process");

    // Everything below this line destroys something.
    var snapshot = l.*;
    if (!killAndWait(h, snapshot.pid)) return failWhy(req.tag, E.IO, "the agent did not exit when signalled; nothing was started");
    if (!spawnZmx(h, &snapshot, name, resume_value)) return failWhy(req.tag, E.IO, "could not start zmx; the agent has already been stopped");
    for (0..post_ticks) |_| {
        if (zmxPosted(h, name)) {
            rescan(h);
            return .{ .reply = .{ .tag = req.tag, .written = @intCast(req.data.len) } };
        }
        napOneTick(h);
    }
    rescan(h);
    return failWhy(req.tag, E.IO, "zmx did not post the session in time; the agent may still return");
}

// ---- dispatch ------------------------------------------------------------------

/// Answers one engine request. The caller holds `h.mutex` and replies
/// before letting go of it (answer bytes point into `h`).
pub fn handle(h: *Harness, req: fs.Req) Answer {
    const t = h.resolve(req.node) orelse return fail(req.tag, E.NOENT);
    return switch (req.op) {
        .lookup => lookup(h, req, t),
        .getattr => attrReply(h, req.tag, t),
        .setattr => setattrReq(h, req, t),
        .open => open(h, req, t),
        .release => release(h, req, t),
        .readdir => readdir(h, req, t),
        .read => read(h, req, t),
        .write => writeReq(h, req, t),
    };
}

/// Truncation is how a shell's `>` opens a file before writing it. The
/// `zmx` file has no length of its own — a write replaces the value —
/// so on the one writable file a zero-length truncate is a no-op
/// rather than a refusal. Everything else still answers EPERM.
fn setattrReq(h: *Harness, req: fs.Req, t: Target) Answer {
    switch (t) {
        .act => |a| if (a.file == .zmx and h.allow_move and req.truncate) {
            return .{ .reply = .{ .tag = req.tag } };
        },
        else => {},
    }
    return failWhy(req.tag, E.PERM, "9agents serves a view, not a store: writing is not permitted");
}

/// The tree answers EPERM to every write but one: a zmx session name
/// into a live agent's `zmx`, which moves it there.
fn writeReq(h: *Harness, req: fs.Req, t: Target) Answer {
    switch (t) {
        .act => |a| if (a.file == .zmx) return moveToZmx(h, req, a),
        else => {},
    }
    return failWhy(req.tag, E.PERM, "9agents serves a view, not a store: writing is not permitted");
}

fn attrReply(h: *Harness, tag: u64, t: Target) Answer {
    const a = attrFor(h, t) orelse return fail(tag, E.NOENT);
    return .{ .reply = .{ .tag = tag, .attr = a } };
}

/// A lookup's attr names the file as the client asked for it (the engine
/// keeps that name for the fid); refs for path targets were already taken
/// by `entryFor`.
fn lookupAttr(h: *Harness, req: fs.Req, t: Target, name: []const u8) Answer {
    const a = attrFor(h, t) orelse return fail(req.tag, E.NOENT);
    var with_name = a;
    with_name.name = name;
    return .{ .reply = .{ .tag = req.tag, .attr = with_name } };
}

fn lookup(h: *Harness, req: fs.Req, t: Target) Answer {
    const name = req.data;
    if (name.len == 0 or name.len > 255) return fail(req.tag, E.NOENT);
    if (std.mem.indexOfAny(u8, name, "/\x00") != null) return fail(req.tag, E.NOENT);

    if (std.mem.eql(u8, name, ".")) {
        // The engine asks for "." when cloning a fid; the reference is
        // paid for path targets here like any other lookup result.
        switch (t) {
            .top, .act => return attrReply(h, req.tag, t),
            .path => |e| {
                e.refs += 1;
                return lookupAttr(h, req, t, name);
            },
        }
    }
    if (std.mem.eql(u8, name, "..")) return lookupParent(h, req, t);

    switch (t) {
        .top => |top| switch (top) {
            .root => {
                const found: ?Top = blk: for (Top.listed) |e| {
                    if (std.mem.eql(u8, e.fileName(), name)) break :blk e;
                } else break :blk null;
                return attrReply(h, req.tag, .{ .top = found orelse return fail(req.tag, E.NOENT) });
            },
            .claude, .codex, .skills => {
                const m = mountNamed(top, name) orelse return fail(req.tag, E.NOENT);
                const e = h.entryFor(m.root, m.rel, true) orelse return fail(req.tag, E.NFILE);
                const a = statAttr(h, e) orelse {
                    unref(e);
                    return fail(req.tag, E.NOENT);
                };
                var with_name = a;
                with_name.name = name;
                return .{ .reply = .{ .tag = req.tag, .attr = with_name } };
            },
            .omp, .hermes, .dsh => {
                const m = top.mirror().?;
                return lookupBelow(h, req, m.root, m.rel, name);
            },
            .active => {
                const k = blk: for (std.enums.values(active.Kind)) |k| {
                    if (std.mem.eql(u8, k.text(), name)) break :blk k;
                } else return fail(req.tag, E.NOENT);
                if (!hasLive(h, k)) {
                    rescan(h);
                    if (!hasLive(h, k)) return fail(req.tag, E.NOENT);
                }
                return activeReply(h, req, .{ .file = .harness_dir, .kind = k }, name);
            },
            .pid, .uptime, .readme => return fail(req.tag, E.NOTDIR),
        },
        .path => |e| {
            const rel_path = e.rel();
            if (attrFor(h, t)) |a| {
                if (!a.dir) return fail(req.tag, E.NOTDIR);
            } else return fail(req.tag, E.NOENT);
            return lookupBelow(h, req, e.root, rel_path, name);
        },
        .act => |a| return activeLookup(h, req, a, name),
    }
}

/// A lookup of `name` in the directory (root, dir_rel): the child's rel
/// path is composed only from the remembered pair and the (single-segment,
/// engine-vetted) name.
fn lookupBelow(h: *Harness, req: fs.Req, r: Root, dir_rel: []const u8, name: []const u8) Answer {
    if (excluded(name)) return fail(req.tag, E.NOENT);
    var scratch: [rel_capacity + 256]u8 = undefined;
    const child_rel = joinRel(&scratch, dir_rel, name) orelse return fail(req.tag, E.NOENT);
    const e = h.entryFor(r, child_rel, true) orelse return fail(req.tag, E.NFILE);
    const a = statAttr(h, e) orelse {
        unref(e);
        return fail(req.tag, E.NOENT);
    };
    var with_name = a;
    with_name.name = name;
    return .{ .reply = .{ .tag = req.tag, .attr = with_name } };
}

fn joinRel(scratch: []u8, dir_rel: []const u8, name: []const u8) ?[]const u8 {
    if (dir_rel.len == 0) {
        if (name.len > scratch.len) return null;
        @memcpy(scratch[0..name.len], name);
        return scratch[0..name.len];
    }
    const total = dir_rel.len + 1 + name.len;
    if (total > scratch.len) return null;
    @memcpy(scratch[0..dir_rel.len], dir_rel);
    scratch[dir_rel.len] = '/';
    @memcpy(scratch[dir_rel.len + 1 .. total], name);
    return scratch[0..total];
}

fn lookupParent(h: *Harness, req: fs.Req, t: Target) Answer {
    const parent: Target = switch (t) {
        .top => |top| .{ .top = top.parent() },
        .path => |e| blk: {
            const rel_path = e.rel();
            if (std.mem.lastIndexOfScalar(u8, rel_path, '/')) |i| {
                const up = rel_path[0..i];
                const pe = h.entryFor(e.root, up, true) orelse return fail(req.tag, E.NFILE);
                break :blk .{ .path = pe };
            }
            break :blk .{ .top = mountOwner(e.root, rel_path) };
        },
        .act => |a| switch (a.file) {
            .harness_dir => .{ .top = .active },
            .entry => .{ .act = .{ .file = .harness_dir, .kind = a.kind } },
            .agents => .{ .act = .{ .file = .entry, .kind = a.kind, .slot = a.slot, .gen = a.gen } },
            .agent => .{ .act = .{ .file = .agents, .kind = a.kind, .slot = a.slot, .gen = a.gen } },
            .agent_model, .agent_transcript => .{ .act = .{
                .file = .agent,
                .kind = a.kind,
                .slot = a.slot,
                .gen = a.gen,
                .agent = a.agent,
            } },
            // Every other file hangs directly off its entry.
            else => .{ .act = .{ .file = .entry, .kind = a.kind, .slot = a.slot, .gen = a.gen } },
        },
    };
    return attrReply(h, req.tag, parent);
}

fn unref(e: *Entry) void {
    if (e.refs > 0) e.refs -= 1;
    if (e.refs == 0) {
        e.used = false;
        e.gen +%= 1;
    }
}

fn open(h: *Harness, req: fs.Req, t: Target) Answer {
    _ = attrFor(h, t) orelse return fail(req.tag, E.NOENT); // still there?
    // Read-only tree, with exactly one exception: the `zmx` file of a
    // live agent, and only when the daemon was started to allow moves.
    // Truncation is meaningless there (a write replaces the value), so
    // it is accepted rather than refused, which is what `>` needs.
    const writable = switch (t) {
        .act => |a| a.file == .zmx and h.allow_move,
        else => false,
    };
    const rw = req.omode & 3;
    if (!writable) {
        if (rw == cloud9.owrite or rw == cloud9.ordwr) return failWhy(req.tag, E.PERM, "9agents serves a view, not a store: writing is not permitted");
        if (req.omode & cloud9.otrunc != 0) return failWhy(req.tag, E.PERM, "truncation is not permitted here");
    }
    return .{ .reply = .{ .tag = req.tag, .handle = 1 } };
}

fn release(h: *Harness, req: fs.Req, t: Target) Answer {
    _ = h;
    switch (t) {
        .top, .act => {},
        .path => |e| unref(e),
    }
    return .{ .reply = .{ .tag = req.tag } };
}

// ---- reads ----------------------------------------------------------------------

fn read(h: *Harness, req: fs.Req, t: Target) Answer {
    switch (t) {
        .top => |top| switch (top) {
            .pid, .uptime, .readme => {
                const text = factText(h, top, &fact_buf);
                return window(req, text);
            },
            else => return fail(req.tag, E.ISDIR),
        },
        .act => |a| return activeRead(h, req, a),
        .path => |e| {
            // `O_NONBLOCK` so a fifo left in a harness root cannot park the
            // daemon in `open`; the kind check below refuses it anyway.
            const fd = openIn(h, e.root, e.rel(), .{
                .ACCMODE = .RDONLY,
                .NONBLOCK = true,
                .CLOEXEC = true,
            }) orelse return fail(req.tag, E.NOENT);
            const file: Io.File = .{ .handle = fd, .flags = .{ .nonblocking = false } };
            defer file.close(h.io);
            const st = file.stat(h.io) catch return fail(req.tag, E.IO);
            if (st.kind == .directory) return fail(req.tag, E.ISDIR);
            // Only regular files have bytes this tree promises to serve.
            if (st.kind != .file) return fail(req.tag, E.PERM);
            _ = linux.fcntl(fd, linux.F.SETFL, 0); // pread wants no O_NONBLOCK
            const want = @min(req.size, h.data_buf.len);
            const n = file.readPositionalAll(h.io, h.data_buf[0..want], req.off) catch
                return fail(req.tag, E.IO);
            return .{ .reply = .{ .tag = req.tag }, .bytes = h.data_buf[0..n] };
        },
    }
}

/// `text` windowed by the request's offset and size.
fn window(req: fs.Req, text: []const u8) Answer {
    const off: usize = @intCast(@min(req.off, text.len));
    const n = @min(text.len - off, req.size);
    return .{ .reply = .{ .tag = req.tag }, .bytes = text[off..][0..n] };
}

// ---- readdir --------------------------------------------------------------------

/// Directory records in the engine's shape: `node:u64le dir:u8 len:u8 name`.
const Staging = struct {
    buf: []u8,
    len: usize = 0,
    skip: u64,
    /// Set once a record did not fit. Everything after it is left for the
    /// next read: dropping one record and staging a shorter one behind it
    /// would lose that entry, because the client's next offset counts the
    /// records it received.
    full: bool = false,

    fn add(s: *Staging, node: u64, dir: bool, name: []const u8) void {
        if (s.full) return;
        if (s.skip > 0) {
            s.skip -= 1;
            return;
        }
        if (name.len == 0 or name.len > 255) return;
        if (s.len + 10 + name.len > s.buf.len) {
            s.full = true;
            return;
        }
        std.mem.writeInt(u64, s.buf[s.len..][0..8], node, .little);
        s.buf[s.len + 8] = @intFromBool(dir);
        s.buf[s.len + 9] = @intCast(name.len);
        @memcpy(s.buf[s.len + 10 ..][0..name.len], name);
        s.len += 10 + name.len;
    }
};

fn readdir(h: *Harness, req: fs.Req, t: Target) Answer {
    var st: Staging = .{ .buf = &h.stage_buf, .skip = req.off };
    switch (t) {
        .top => |top| switch (top) {
            .root => for (Top.listed) |e| st.add(topNode(e), e.dir(), e.fileName()),
            .claude, .codex, .skills => {
                for (named_mounts) |m| {
                    if (m.owner != top) continue;
                    // Only mounts whose target exists are listed (a harness
                    // without skills simply has no skills/ entry).
                    const a = attrOfMount(h, m.mount.root, m.mount.rel) orelse continue;
                    const e = h.entryFor(m.mount.root, m.mount.rel, false) orelse continue;
                    st.add(h.entryNode(e), a.dir, m.name);
                }
            },
            .pid, .uptime, .readme => return fail(req.tag, E.NOTDIR),
            .active => {
                rescan(h);
                for (std.enums.values(active.Kind)) |k| {
                    if (!hasLive(h, k)) continue;
                    st.add(activeNode(.{ .file = .harness_dir, .kind = k }), true, k.text());
                }
            },
            .omp, .hermes, .dsh => {
                const m = top.mirror().?;
                if (h.base(m.root) == null) return fail(req.tag, E.NOENT);
                switch (listDir(h, &st, m.root, m.rel)) {
                    .ok => {},
                    .gone => return fail(req.tag, E.NOENT),
                    .failed => return fail(req.tag, E.IO),
                    .overflow => return failWhy(req.tag, E.NFILE, "directory has more entries than this server can list at once"),
                }
            },
        },
        .path => |e| {
            if (attrFor(h, t)) |a| {
                if (!a.dir) return fail(req.tag, E.NOTDIR);
            } else return fail(req.tag, E.NOENT);
            switch (listDir(h, &st, e.root, e.rel())) {
                .ok => {},
                .gone => return fail(req.tag, E.NOENT),
                .failed => return fail(req.tag, E.IO),
                .overflow => return failWhy(req.tag, E.NFILE, "directory has more entries than this server can list at once"),
            }
        },
        .act => |a| return activeReaddir(h, req, a),
    }
    return .{ .reply = .{ .tag = req.tag }, .bytes = h.stage_buf[0..st.len] };
}

/// How a listing attempt ended. `overflow` is deliberate: a comptime cap
/// that would silently drop entries answers an error instead, because a
/// short listing is indistinguishable from a small directory.
const Listing = enum { ok, gone, failed, overflow };

/// Stages the contents of the directory (root, dir_rel): every name the
/// walker yields that survives the exclusions, sorted so a listing that
/// spans several reads stays consistent.
fn listDir(h: *Harness, st: *Staging, r: Root, dir_rel: []const u8) Listing {
    const fd = openIn(h, r, dir_rel, .{
        .ACCMODE = .RDONLY,
        .DIRECTORY = true,
        .CLOEXEC = true,
    }) orelse return .gone;
    const dir: Io.Dir = .{ .handle = fd };
    defer Io.Dir.close(dir, h.io);
    var read_buf: [Io.Dir.Iterator.reader_buffer_len]u8 align(@alignOf(usize)) = undefined;
    var reader = Io.Dir.Reader.init(dir, &read_buf);
    var names_len: usize = 0;
    var count: usize = 0;
    while (true) {
        const entry = (reader.next(h.io) catch return .failed) orelse break;
        if (excluded(entry.name)) continue;
        var kind = entry.kind;
        if (kind == .unknown or kind == .sym_link) {
            // The walker's word is not proof: stat without following.
            var child_buf: [rel_capacity + 256]u8 = undefined;
            const child_rel = joinRel(&child_buf, dir_rel, entry.name) orelse continue;
            const cst = statIn(h, r, child_rel) orelse continue;
            kind = cst.st.kind;
        }
        if (kind == .sym_link) continue; // never served
        // A cap reached is an error, never a short listing: a directory
        // that quietly loses entries is a wrong answer, and a caller
        // cannot tell it from a small directory.
        if (count == list_capacity or names_len + entry.name.len > h.list_names.len) return .overflow;
        @memcpy(h.list_names[names_len..][0..entry.name.len], entry.name);
        h.list_offs[count] = @intCast(names_len);
        h.list_dirs[count] = kind == .directory;
        names_len += entry.name.len;
        count += 1;
    }
    // Sort the (offset, length) pairs by name for cursor stability.
    const SortCtx = struct {
        names: []const u8,
        offs: []const u32,
        lens: [list_capacity]u32,

        fn lessThan(ctx: @This(), a: usize, b: usize) bool {
            return std.mem.order(u8, ctx.nameAt(a), ctx.nameAt(b)) == .lt;
        }
        fn nameAt(ctx: @This(), i: usize) []const u8 {
            const start = ctx.offs[i];
            return ctx.names[start..][0..ctx.lens[i]];
        }
    };
    var lens: [list_capacity]u32 = @splat(0);
    var order: [list_capacity]usize = @splat(0);
    {
        var end: usize = 0;
        for (0..count) |i| {
            end = if (i + 1 < count) h.list_offs[i + 1] else names_len;
            lens[i] = @intCast(end - h.list_offs[i]);
            order[i] = i;
        }
    }
    const ctx: SortCtx = .{ .names = h.list_names[0..names_len], .offs = &h.list_offs, .lens = lens };
    std.mem.sort(usize, order[0..count], ctx, SortCtx.lessThan);
    for (order[0..count]) |i| {
        const name = ctx.nameAt(i);
        var child_buf: [rel_capacity + 256]u8 = undefined;
        const child_rel = joinRel(&child_buf, dir_rel, name) orelse continue;
        const e = h.entryFor(r, child_rel, false) orelse return .overflow; // path table full
        st.add(h.entryNode(e), h.list_dirs[i], name);
    }
    return .ok;
}

// ---- unit tests -------------------------------------------------------------------

const testing = std.testing;

/// A rig with a fake HOME: every root under one temp dir, never the real
/// ~/.claude or any other live harness root.
const Rig = struct {
    dir: testing.TmpDir,
    /// Build a fixture process tree under <home>/proc and point
    /// `/active` at it. Off by default: a unit test must opt in to
    /// reading a process tree, and it is never the live one.
    with_proc: bool = false,
    /// The pid the daemon believes it is, for the ancestry exclusion.
    self_pid: u32 = 4242,
    zmx: []const u8 = "zmx",
    allow_move: bool = false,
    path_buf: [std.fs.max_path_bytes]u8 = undefined,
    home: []const u8 = undefined,
    h: *Harness = undefined,
    harness_mem: Harness = undefined,

    fn start(rig: *Rig) !void {
        const io = testing.io;
        rig.dir = testing.tmpDir(.{});
        errdefer rig.dir.cleanup();
        const len = try rig.dir.dir.realPath(io, &rig.path_buf);
        rig.home = try testing.allocator.dupe(u8, rig.path_buf[0..len]);
        var mk: [std.fs.max_path_bytes]u8 = undefined;
        // The five roots, pinned to the fake home.
        inline for ([_][]const u8{
            ".claude/projects/p1", ".claude/skills/revu",
            ".codex/sessions/2026/09/21",
            ".omp/agent",           ".hermes/logs",
            ".dsh/profiles",
        }) |sub| {
            try Io.Dir.cwd().createDirPath(io, try std.fmt.bufPrint(&mk, "{s}/{s}", .{ rig.home, sub }));
        }
        var base_buf: [5][std.fs.max_path_bytes]u8 = @splat(@splat(0));
        var bases: [5][]const u8 = @splat("");
        inline for (0..5) |i| {
            bases[i] = try std.fmt.bufPrint(&base_buf[i], "{s}/{s}", .{ rig.home, home_dirs[i] });
        }
        rig.harness_mem = undefined;
        var proc_buf: [std.fs.max_path_bytes]u8 = undefined;
        const proc_root: []const u8 = if (rig.with_proc)
            try std.fmt.bufPrint(&proc_buf, "{s}/proc", .{rig.home})
        else
            "";
        if (rig.with_proc) {
            try Io.Dir.cwd().createDirPath(io, proc_root);
            try rig.put("proc/stat", "cpu  1 2 3\nbtime 1000000\nprocesses 7\n");
        }
        rig.harness_mem.init(.{
            .io = io,
            .pid = rig.self_pid,
            .bases = bases,
            .proc = proc_root,
            .home = rig.home,
            .zmx = rig.zmx,
            .allow_move = rig.allow_move,
        });
        rig.h = &rig.harness_mem;
    }

    fn end(rig: *Rig) void {
        rig.dir.cleanup();
        testing.allocator.free(rig.home);
    }

    fn put(rig: *Rig, rel_path: []const u8, bytes: []const u8) !void {
        var buf: [std.fs.max_path_bytes]u8 = undefined;
        const path = try std.fmt.bufPrint(&buf, "{s}/{s}", .{ rig.home, rel_path });
        if (std.mem.lastIndexOfScalar(u8, rel_path, '/')) |i| {
            var dbuf: [std.fs.max_path_bytes]u8 = undefined;
            const dir_path = try std.fmt.bufPrint(&dbuf, "{s}/{s}", .{ rig.home, rel_path[0..i] });
            try Io.Dir.cwd().createDirPath(testing.io, dir_path);
        }
        var file = try Io.Dir.createFileAbsolute(testing.io, path, .{});
        defer file.close(testing.io);
        try file.writeStreamingAll(testing.io, bytes);
    }


    fn del(rig: *Rig, rel_path: []const u8) !void {
        var buf: [std.fs.max_path_bytes]u8 = undefined;
        const path = try std.fmt.bufPrint(&buf, "{s}/{s}", .{ rig.home, rel_path });
        try Io.Dir.deleteFileAbsolute(testing.io, path);
    }

    /// lookup of `name` in `dir_node`, answering the child's attr.
    fn lookupName(rig: *Rig, tag: u64, dir_node: u64, name: []const u8) Answer {
        return handle(rig.h, .{ .tag = tag, .op = .lookup, .node = dir_node, .data = name });
    }

    /// Writes one fake process into the fixture `/proc`: the `stat`
    /// line (with the start time in field 22, after a name that holds
    /// the spaces and parentheses a real one can), the NUL-separated
    /// `cmdline`, and a `cwd` symlink.
    fn fakeProc(rig: *Rig, o: struct {
        pid: u32,
        ppid: u32 = 1,
        comm: []const u8 = "x",
        starttime: u64 = 5000,
        argv: []const u8,
        cwd: []const u8 = "",
    }) !void {
        var rel: [128]u8 = undefined;
        var stat_text: [512]u8 = undefined;
        var w = Io.Writer.fixed(&stat_text);
        try w.print("{d} ({s}) S {d}", .{ o.pid, o.comm, o.ppid });
        for (5..22) |i| try w.print(" {d}", .{i});
        try w.print(" {d} 0 0\n", .{o.starttime});
        try rig.put(try std.fmt.bufPrint(&rel, "proc/{d}/stat", .{o.pid}), w.buffered());
        try rig.put(try std.fmt.bufPrint(&rel, "proc/{d}/cmdline", .{o.pid}), o.argv);

        const target = if (o.cwd.len > 0) o.cwd else rig.home;
        var link_buf: [std.fs.max_path_bytes]u8 = undefined;
        const link = try std.fmt.bufPrintZ(&link_buf, "{s}/proc/{d}/cwd", .{ rig.home, o.pid });
        Io.Dir.cwd().symLink(testing.io, target, link, .{}) catch {};
    }

    /// Removes a fake process, as an exit would.
    fn reapProc(rig: *Rig, pid: u32) !void {
        var buf: [std.fs.max_path_bytes]u8 = undefined;
        const dir_path = try std.fmt.bufPrint(&buf, "{s}/proc/{d}", .{ rig.home, pid });
        const d = try Io.Dir.openDirAbsolute(testing.io, dir_path, .{ .iterate = true });
        var rb: [Io.Dir.Iterator.reader_buffer_len]u8 align(@alignOf(usize)) = undefined;
        var it = Io.Dir.Reader.init(d, &rb);
        var names: [8][64]u8 = undefined;
        var lens: [8]usize = @splat(0);
        var n: usize = 0;
        while (n < names.len) {
            const e = (it.next(testing.io) catch break) orelse break;
            @memcpy(names[n][0..e.name.len], e.name);
            lens[n] = e.name.len;
            n += 1;
        }
        Io.Dir.close(d, testing.io);
        for (0..n) |i| {
            var one: [std.fs.max_path_bytes]u8 = undefined;
            const path = try std.fmt.bufPrint(&one, "{s}/{s}", .{ dir_path, names[i][0..lens[i]] });
            Io.Dir.deleteFileAbsolute(testing.io, path) catch {};
        }
        try Io.Dir.cwd().deleteDir(testing.io, dir_path);
    }
};

const home_dirs = [5][]const u8{ ".claude", ".codex", ".omp", ".hermes", ".dsh" };

fn expectNoent(a: Answer) !void {
    try testing.expect(a.reply.status == .err);
    try testing.expectEqual(E.NOENT, a.reply.errno);
}

fn expectEperm(a: Answer) !void {
    try testing.expect(a.reply.status == .err);
    try testing.expectEqual(E.PERM, a.reply.errno);
}

test "tree: facts at the root" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    const a = rig.lookupName(1, root, "pid");
    try testing.expect(a.reply.status == .ok);
    try testing.expect(a.reply.attr.dir == false);
    var read_a = handle(rig.h, .{ .tag = 2, .op = .read, .node = a.reply.attr.node, .off = 0, .size = 64 });
    try testing.expectEqualStrings("4242\n", read_a.bytes);
    read_a = handle(rig.h, .{ .tag = 3, .op = .read, .node = a.reply.attr.node, .off = 0, .size = 2 });
    try testing.expectEqualStrings("42", read_a.bytes);
    const up = rig.lookupName(4, root, "uptime");
    try testing.expect(up.reply.status == .ok);
    const up_read = handle(rig.h, .{ .tag = 5, .op = .read, .node = up.reply.attr.node, .off = 0, .size = 64 });
    try testing.expect(up_read.bytes.len > 0 and up_read.bytes[up_read.bytes.len - 1] == '\n');
    // The root lists the facts and the five harness dirs.
    const listing = handle(rig.h, .{ .tag = 6, .op = .readdir, .node = root, .off = 0, .size = msize });
    try testing.expect(listing.reply.status == .ok);
    for ([_][]const u8{ "README", "pid", "uptime", "claude", "codex", "omp", "hermes", "dsh", "skills" }) |name| {
        try testing.expect(stageHas(listing.bytes, name));
    }
}

test "tree: README is served at the root, whole and read-only" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();

    const rd = rig.lookupName(1, root, "README");
    try testing.expect(rd.reply.status == .ok);
    try testing.expect(!rd.reply.attr.dir);
    try testing.expectEqual(readme_text.len, rd.reply.attr.size);

    // Read it back whole and compare: a truncated or empty README would
    // otherwise pass every check above.
    const got = handle(rig.h, .{ .tag = 2, .op = .read, .node = rd.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(got.reply.status == .ok);
    try testing.expectEqualStrings(readme_text, got.bytes);

    // It is a file, and it is read-only like everything else here.
    const as_dir = handle(rig.h, .{ .tag = 3, .op = .readdir, .node = rd.reply.attr.node, .off = 0, .size = msize });
    try testing.expectEqual(E.NOTDIR, as_dir.reply.errno);
    const wr = handle(rig.h, .{ .tag = 4, .op = .write, .node = rd.reply.attr.node, .off = 0, .size = 1 });
    try testing.expectEqual(E.PERM, wr.reply.errno);
}

fn stageHas(staged: []const u8, name: []const u8) bool {
    var i: usize = 0;
    while (i + 10 <= staged.len) {
        const len: usize = staged[i + 9];
        const entry = staged[i + 10 ..][0..len];
        if (std.mem.eql(u8, entry, name)) return true;
        i += 10 + len;
    }
    return false;
}

test "tree: exclusions never serve a credentials-shaped name" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    // The fixture: a real transcript and a pile of credentials-shaped names
    // at several depths, including inside the mirrored subtrees.
    try rig.put(".claude/projects/p1/session-x.jsonl", "{\"a\":1}\n");
    try rig.put(".claude/projects/p1/.credentials.json", "STAY OUT\n");
    try rig.put(".claude/projects/p1/auth.json", "STAY OUT\n");
    try rig.put(".claude/projects/p1/settings.json", "STAY OUT\n");
    try rig.put(".claude/projects/p1/token.txt", "STAY OUT\n");
    try rig.put(".claude/projects/p1/api.key", "STAY OUT\n");
    try rig.put(".claude/projects/p1/models.yml", "STAY OUT\n");
    try rig.put(".claude/projects/p1/deep/.env", "STAY OUT\n");
    try rig.put(".claude/history.jsonl", "{\"h\":1}\n");
    try rig.put(".hermes/auth.json", "STAY OUT\n");
    try rig.put(".hermes/.env", "STAY OUT\n");
    try rig.put(".hermes/config.yaml", "STAY OUT\n");
    try rig.put(".hermes/logs/app.log", "log line\n");
    try rig.put(".dsh/.credentials.yaml", "STAY OUT\n");
    try rig.put(".dsh/settings.yaml", "STAY OUT\n");

    // /claude lists only its mounts; the credentials at ~/.claude root are
    // not in the tree at all (no mount serves them).
    const claude = handle(rig.h, .{ .tag = 1, .op = .readdir, .node = topNode(.claude), .off = 0, .size = msize });
    try testing.expect(claude.reply.status == .ok);
    for ([_][]const u8{ "projects", "history", "skills" }) |name| try testing.expect(stageHas(claude.bytes, name));
    try testing.expect(!stageHas(claude.bytes, "credentials"));

    // A project's listing shows the transcript and nothing else.
    const projects = rig.lookupName(2, topNode(.claude), "projects");
    try testing.expect(projects.reply.status == .ok);
    const p1 = rig.lookupName(3, projects.reply.attr.node, "p1");
    try testing.expect(p1.reply.status == .ok);
    const listed = handle(rig.h, .{ .tag = 4, .op = .readdir, .node = p1.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(listed.reply.status == .ok);
    try testing.expect(stageHas(listed.bytes, "session-x.jsonl"));
    for ([_][]const u8{ ".credentials.json", "auth.json", "settings.json", "token.txt", "api.key", "models.yml" }) |name| {
        try testing.expect(!stageHas(listed.bytes, name));
    }
    // The plain directory that holds a .env is served; the .env is not.
    try testing.expect(stageHas(listed.bytes, "deep"));

    // Every credentials-shaped name is unreachable by lookup too.
    for ([_][]const u8{ ".credentials.json", "auth.json", "settings.json", "token.txt", "api.key", "models.yml" }) |name| {
        try expectNoent(rig.lookupName(5, p1.reply.attr.node, name));
    }
    const deep = rig.lookupName(6, p1.reply.attr.node, "deep");
    try testing.expect(deep.reply.status == .ok);
    try expectNoent(rig.lookupName(7, deep.reply.attr.node, ".env"));

    // The fully mirrored roots hide theirs as well.
    const hermes = rig.lookupName(8, root, "hermes");
    try testing.expect(hermes.reply.status == .ok);
    const hlist = handle(rig.h, .{ .tag = 9, .op = .readdir, .node = hermes.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(stageHas(hlist.bytes, "logs"));
    for ([_][]const u8{ "auth.json", ".env", "config.yaml" }) |name| {
        try testing.expect(!stageHas(hlist.bytes, name));
        try expectNoent(rig.lookupName(10, hermes.reply.attr.node, name));
    }
    const dsh = rig.lookupName(11, root, "dsh");
    try testing.expect(dsh.reply.status == .ok);
    const dlist = handle(rig.h, .{ .tag = 12, .op = .readdir, .node = dsh.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(!stageHas(dlist.bytes, ".credentials.yaml"));
    try testing.expect(!stageHas(dlist.bytes, "settings.yaml"));
    try testing.expect(stageHas(dlist.bytes, "profiles"));

    // The exclusion predicate itself, spelled out.
    try testing.expect(excluded(".credentials.json"));
    try testing.expect(excluded("AUTH.JSON"));
    try testing.expect(excluded("session-token.bin"));
    try testing.expect(excluded("id_rsa_backup"));
    try testing.expect(excluded("prod.pem"));
    try testing.expect(excluded("config.yaml"));
    try testing.expect(!excluded("session-x.jsonl"));
    try testing.expect(!excluded("SKILL.md"));
    try testing.expect(!excluded("logs"));
}

test "tree: paths compose only from the pinned roots" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".claude/projects/p1/session-x.jsonl", "{}\n");
    // A slash, a NUL or an overlong name never reaches the filesystem.
    try expectNoent(rig.lookupName(1, topNode(.claude), "projects/../p1"));
    try expectNoent(rig.lookupName(2, topNode(.claude), "projects/\x00"));
    // A symlink inside a mirror is not served, whatever it points at.
    var buf: [std.fs.max_path_bytes]u8 = undefined;
    const link = try std.fmt.bufPrintZ(&buf, "{s}/.claude/projects/p1/escape", .{rig.home});
    try Io.Dir.cwd().symLink(testing.io, rig.home, link, .{});
    const projects = rig.lookupName(3, topNode(.claude), "projects");
    const p1 = rig.lookupName(4, projects.reply.attr.node, "p1");
    try expectNoent(rig.lookupName(5, p1.reply.attr.node, "escape"));
    // ".." from a mirrored file lands on its canonical parent, and walking
    // ".." repeatedly terminates at the root.
    const session = rig.lookupName(6, p1.reply.attr.node, "session-x.jsonl");
    try testing.expect(session.reply.status == .ok);
    var cur = session.reply.attr.node;
    var hops: usize = 0;
    while (hops < 8) : (hops += 1) {
        const up = rig.lookupName(7, cur, "..");
        try testing.expect(up.reply.status == .ok);
        if (up.reply.attr.node == root) break;
        cur = up.reply.attr.node;
    }
    try testing.expect(cur == root or hops < 8);
    // The facts refuse lookups with NOTDIR.
    try testing.expect(rig.lookupName(8, topNode(.pid), "x").reply.errno == E.NOTDIR);
}

test "tree: a file's qid path survives release, and its version tracks content" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".claude/projects/p1/session-x.jsonl", "{}\n");

    const projects = rig.lookupName(1, topNode(.claude), "projects");
    const dir = rig.lookupName(2, projects.reply.attr.node, "p1");
    const first = rig.lookupName(3, dir.reply.attr.node, "session-x.jsonl");
    try testing.expect(first.reply.status == .ok);
    const qid_path = first.reply.attr.path.?;
    const version = first.reply.attr.version;

    // Give every reference back, so the table slot is free to recycle.
    for ([_]u64{ first.reply.attr.node, dir.reply.attr.node, projects.reply.attr.node }) |n| {
        _ = handle(rig.h, .{ .tag = 4, .op = .release, .node = n });
    }

    // Walk to it again from scratch. intro(5): two files are the same file if
    // and only if their qids are the same — so the same unchanged file must
    // come back with the same qid path, whatever the node id does. Before the
    // qid path came from the file itself, the recycled slot's new generation
    // made this a different file on every walk.
    const p2 = rig.lookupName(5, topNode(.claude), "projects");
    const d2 = rig.lookupName(6, p2.reply.attr.node, "p1");
    const again = rig.lookupName(7, d2.reply.attr.node, "session-x.jsonl");
    try testing.expect(again.reply.status == .ok);
    try testing.expectEqual(qid_path, again.reply.attr.path.?);
    try testing.expectEqual(version, again.reply.attr.version);

    // Two different files never share a qid path.
    try rig.put(".claude/projects/p1/session-y.jsonl", "{}\n");
    const other = rig.lookupName(8, d2.reply.attr.node, "session-y.jsonl");
    try testing.expect(other.reply.attr.path.? != qid_path);

    // And a change to the content moves the version, which is what tells a
    // caching client the transcript it is holding has grown.
    try rig.put(".claude/projects/p1/session-x.jsonl", "{}\n{\"more\":1}\n");
    const grown = rig.lookupName(9, d2.reply.attr.node, "session-x.jsonl");
    try testing.expectEqual(qid_path, grown.reply.attr.path.?);
    try testing.expect(grown.reply.attr.version != version);
}

test "tree: node ids — same file equal, distinct files differ, ids recycle" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".claude/projects/p1/session-x.jsonl", "{}\n");
    try rig.put(".claude/projects/p1/session-y.jsonl", "{}\n");
    const projects = rig.lookupName(1, topNode(.claude), "projects");
    const a1 = rig.lookupName(2, projects.reply.attr.node, "p1");
    // Two walks of the same file: the same node id (the dedupe table).
    const x1 = rig.lookupName(3, a1.reply.attr.node, "session-x.jsonl");
    const x2 = rig.lookupName(4, a1.reply.attr.node, "session-x.jsonl");
    try testing.expect(x1.reply.status == .ok);
    try testing.expectEqual(x1.reply.attr.node, x2.reply.attr.node);
    const y1 = rig.lookupName(5, a1.reply.attr.node, "session-y.jsonl");
    try testing.expect(y1.reply.attr.node != x1.reply.attr.node);
    // The union skills view and the harness's own skills share identity.
    const via_harness = rig.lookupName(6, topNode(.claude), "skills");
    const via_union = rig.lookupName(7, topNode(.skills), "claude");
    try testing.expectEqual(via_harness.reply.attr.node, via_union.reply.attr.node);
    // References are paid back by release: both slots go, ids recycle.
    for ([_]u64{ x1.reply.attr.node, x2.reply.attr.node, y1.reply.attr.node, a1.reply.attr.node }) |n| {
        const rel = handle(rig.h, .{ .tag = 8, .op = .release, .node = n });
        try testing.expect(rel.reply.status == .ok);
    }
    const x3 = rig.lookupName(9, projects.reply.attr.node, "p1");
    const x4 = rig.lookupName(10, x3.reply.attr.node, "session-x.jsonl");
    // The entry was freed and re-created: a fresh generation, a new id.
    try testing.expect(x4.reply.attr.node != x1.reply.attr.node);
    // Node packing round-trips through the struct.
    const n: Node = .{ .idx = 3, .kind = 1, .serial = 0x1234_5678_9abc };
    const bits: u64 = @bitCast(n);
    const back: Node = @bitCast(bits);
    try testing.expect(back.idx == 3 and back.kind == 1 and back.serial == 0x1234_5678_9abc);
}

test "tree: a file that vanishes between lookup and read answers ENOENT" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".claude/projects/p1/session-x.jsonl", "{\"a\":1}\n");
    const projects = rig.lookupName(1, topNode(.claude), "projects");
    const p1 = rig.lookupName(2, projects.reply.attr.node, "p1");
    const session = rig.lookupName(3, p1.reply.attr.node, "session-x.jsonl");
    try testing.expect(session.reply.status == .ok);
    // The transcript reads back whole, fresh from disk.
    const whole = handle(rig.h, .{ .tag = 4, .op = .read, .node = session.reply.attr.node, .off = 0, .size = 1024 });
    try testing.expectEqualStrings("{\"a\":1}\n", whole.bytes);
    // It vanishes: lookup, getattr and read all answer ENOENT cleanly.
    try rig.del(".claude/projects/p1/session-x.jsonl");
    try expectNoent(rig.lookupName(5, p1.reply.attr.node, "session-x.jsonl"));
    const gone = handle(rig.h, .{ .tag = 6, .op = .getattr, .node = session.reply.attr.node });
    try expectNoent(gone);
    const read_gone = handle(rig.h, .{ .tag = 7, .op = .read, .node = session.reply.attr.node, .off = 0, .size = 64 });
    try expectNoent(read_gone);
}

test "tree: writes and setattrs answer EPERM" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".claude/projects/p1/session-x.jsonl", "{}\n");
    const projects = rig.lookupName(1, topNode(.claude), "projects");
    const p1 = rig.lookupName(2, projects.reply.attr.node, "p1");
    const session = rig.lookupName(3, p1.reply.attr.node, "session-x.jsonl");
    try testing.expect(session.reply.status == .ok);
    const write = handle(rig.h, .{ .tag = 4, .op = .write, .node = session.reply.attr.node, .data = "x" });
    try expectEperm(write);
    const set = handle(rig.h, .{ .tag = 5, .op = .setattr, .node = session.reply.attr.node, .set = .{ .mtime = true }, .mtime = 1 });
    try expectEperm(set);
    // An open for write is refused at open time.
    const wopen = handle(rig.h, .{ .tag = 6, .op = .open, .node = session.reply.attr.node, .omode = cloud9.owrite });
    try expectEperm(wopen);
    const ropen = handle(rig.h, .{ .tag = 7, .op = .open, .node = session.reply.attr.node, .omode = cloud9.oread });
    try testing.expect(ropen.reply.status == .ok);
}

test "tree: a transcript written while serving is visible at once" {
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".claude/projects/p1/session-x.jsonl", "{\"n\":1}\n");
    const projects = rig.lookupName(1, topNode(.claude), "projects");
    const p1 = rig.lookupName(2, projects.reply.attr.node, "p1");
    // The harness appends; the next read sees it — no cache in between.
    try rig.put(".claude/projects/p1/session-x.jsonl", "{\"n\":1}\n{\"n\":2}\n");
    const session = rig.lookupName(3, p1.reply.attr.node, "session-x.jsonl");
    const fresh = handle(rig.h, .{ .tag = 4, .op = .read, .node = session.reply.attr.node, .off = 0, .size = 1024 });
    try testing.expectEqualStrings("{\"n\":1}\n{\"n\":2}\n", fresh.bytes);
    // A brand-new session file appears on the next listing.
    try rig.put(".claude/projects/p1/session-new.jsonl", "{\"n\":9}\n");
    const listed = handle(rig.h, .{ .tag = 5, .op = .readdir, .node = p1.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(stageHas(listed.bytes, "session-new.jsonl"));
}

comptime {
    // Every static mount target must survive the exclusion rules; the
    // daemon's own skeleton may never be filtered out from under it.
    for (named_mounts) |m| {
        if (excludedPath(m.mount.rel)) @compileError("a 9agents mount target is excluded by name");
    }
}

fn stageCount(staged: []const u8) usize {
    var i: usize = 0;
    var n: usize = 0;
    while (i + 10 <= staged.len) : (n += 1) i += 10 + @as(usize, staged[i + 9]);
    return n;
}

test "tree: a file directly under a mirror root reads back" {
    // Regression: joining a child onto an empty relative path returned an
    // uncopied scratch slice, so every file at the top of a mirror root
    // (/hermes/<name>, /dsh/<name>) listed but resolved to garbage bytes.
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put(".hermes/note.txt", "hello-hermes\n");
    const listing = handle(rig.h, .{ .tag = 1, .op = .readdir, .node = topNode(.hermes), .off = 0, .size = msize });
    try testing.expect(stageHas(listing.bytes, "note.txt"));
    const note = rig.lookupName(2, topNode(.hermes), "note.txt");
    try testing.expect(note.reply.status == .ok);
    const bytes = handle(rig.h, .{ .tag = 3, .op = .read, .node = note.reply.attr.node, .off = 0, .size = 64 });
    try testing.expectEqualStrings("hello-hermes\n", bytes.bytes);
}

test "tree: a name swapped for a symlink under an open handle serves nothing" {
    // Regression: the read path composed the whole path and opened it in
    // one call, following symlinks. A name replaced between the walk and
    // the read handed the client bytes from outside every pinned root.
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    try rig.put("outside.txt", "OUTSIDE-THE-ROOTS\n"); // beside the roots, not in one
    try rig.put(".claude/projects/p1/swap.txt", "safe\n");
    const projects = rig.lookupName(1, topNode(.claude), "projects");
    const p1 = rig.lookupName(2, projects.reply.attr.node, "p1");
    const swap = rig.lookupName(3, p1.reply.attr.node, "swap.txt");
    try testing.expect(swap.reply.status == .ok);
    const opened = handle(rig.h, .{ .tag = 4, .op = .open, .node = swap.reply.attr.node, .omode = cloud9.oread });
    try testing.expect(opened.reply.status == .ok);
    // The file becomes a symlink out of the tree while the handle is open.
    var link_buf: [std.fs.max_path_bytes]u8 = undefined;
    var target_buf: [std.fs.max_path_bytes]u8 = undefined;
    const link = try std.fmt.bufPrintZ(&link_buf, "{s}/.claude/projects/p1/swap.txt", .{rig.home});
    const target = try std.fmt.bufPrint(&target_buf, "{s}/outside.txt", .{rig.home});
    try rig.del(".claude/projects/p1/swap.txt");
    try Io.Dir.cwd().symLink(testing.io, target, link, .{});
    const after = handle(rig.h, .{ .tag = 5, .op = .read, .node = swap.reply.attr.node, .off = 0, .size = 64 });
    try expectNoent(after);
    try testing.expectEqual(@as(usize, 0), after.bytes.len);
}

test "tree: a listing past the cap fails loudly instead of truncating" {
    // Regression: a directory with more entries (or longer names) than the
    // comptime caps was served short, and a short listing is
    // indistinguishable from a small directory.
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    var name_buf: [64]u8 = undefined;
    for (0..list_capacity + 1) |i| {
        try rig.put(try std.fmt.bufPrint(&name_buf, ".dsh/f{d:0>5}", .{i}), "");
    }
    const listed = handle(rig.h, .{ .tag = 1, .op = .readdir, .node = topNode(.dsh), .off = 0, .size = msize });
    try testing.expect(listed.reply.status == .err);
    try testing.expectEqual(E.NFILE, listed.reply.errno);
}

test "tree: a listing spanning several reads loses no entry" {
    // The staging buffer fills long before a big directory ends. Staging
    // must stop at the first record that does not fit: dropping it and
    // packing a shorter one behind it would lose that entry, because the
    // next read's offset counts the records already delivered.
    var rig: Rig = .{ .dir = undefined };
    try rig.start();
    defer rig.end();
    const count = 200;
    var name_buf: [320]u8 = undefined;
    for (0..count) |i| {
        const name = try std.fmt.bufPrint(&name_buf, ".dsh/{d:0>3}{s}", .{ i, "n" ** 200 });
        try rig.put(name, "");
    }
    var seen: [count]bool = @splat(false);
    var off: u64 = 0;
    var reads: usize = 0;
    while (reads < 16) : (reads += 1) {
        const page = handle(rig.h, .{ .tag = 1, .op = .readdir, .node = topNode(.dsh), .off = off, .size = msize });
        try testing.expect(page.reply.status == .ok);
        if (page.bytes.len == 0) break;
        var i: usize = 0;
        while (i + 10 <= page.bytes.len) {
            const len: usize = page.bytes[i + 9];
            const name = page.bytes[i + 10 ..][0..len];
            i += 10 + len;
            // The fixture root also holds `profiles`, created by the rig.
            const idx = std.fmt.parseInt(usize, name[0..@min(3, name.len)], 10) catch continue;
            try testing.expect(!seen[idx]); // never served twice
            seen[idx] = true;
        }
        off += stageCount(page.bytes);
    }
    try testing.expect(reads > 1); // the listing really did span several reads
    for (seen) |s| try testing.expect(s);
}

test {
    _ = active; // the derived view's own tests run with the tree's
}

// ---- /active: the derived view ------------------------------------------------

/// Walks `/active` down to one agent's directory, answering its node.
fn activeEntryNode(rig: *Rig, harness: []const u8, pid: []const u8) !u64 {
    const act = rig.lookupName(90, root, "active");
    try testing.expect(act.reply.status == .ok);
    // A listing is what rescans, so it comes before the walk.
    _ = handle(rig.h, .{ .tag = 91, .op = .readdir, .node = act.reply.attr.node, .off = 0, .size = msize });
    const h_dir = rig.lookupName(92, act.reply.attr.node, harness);
    try testing.expect(h_dir.reply.status == .ok);
    const entry = rig.lookupName(93, h_dir.reply.attr.node, pid);
    try testing.expect(entry.reply.status == .ok);
    return entry.reply.attr.node;
}

fn activeField(rig: *Rig, entry: u64, name: []const u8) ![]const u8 {
    const f = rig.lookupName(94, entry, name);
    try testing.expect(f.reply.status == .ok);
    const r = handle(rig.h, .{ .tag = 95, .op = .read, .node = f.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(r.reply.status == .ok);
    return r.bytes;
}

test "active: a fixture process tree lists by harness and by pid" {
    var rig: Rig = .{ .dir = undefined, .with_proc = true };
    try rig.start();
    defer rig.end();

    // A Claude Code session, resolved the way the harness publishes it.
    try rig.fakeProc(.{ .pid = 1001, .comm = "claude", .starttime = 5000, .argv = "claude\x00--print\x00" });
    var rec: [512]u8 = undefined;
    try rig.put(".claude/sessions/1001.json", try std.fmt.bufPrint(&rec,
        \\{{"pid":1001,"sessionId":"sess-abc","cwd":"{s}",
        \\ "name":"fixture-one","status":"busy","procStart":"5000"}}
    , .{rig.home}));
    var slug_buf: [512]u8 = undefined;
    const slug = active.slugOf(.claude, rig.home, rig.home, &slug_buf).?;
    var tr: [640]u8 = undefined;
    try rig.put(
        try std.fmt.bufPrint(&tr, ".claude/projects/{s}/sess-abc.jsonl", .{slug}),
        "{\"type\":\"summary\",\"aiTitle\":\"Fixture Title\"}\n",
    );

    const entry = try activeEntryNode(&rig, "claude", "1001");
    try testing.expectEqualStrings("1001\n", try activeField(&rig, entry, "pid"));
    try testing.expectEqualStrings("sess-abc\n", try activeField(&rig, entry, "session"));
    try testing.expectEqualStrings("registry\n", try activeField(&rig, entry, "via"));
    try testing.expectEqualStrings("fixture-one\n", try activeField(&rig, entry, "name"));
    try testing.expectEqualStrings("busy\n", try activeField(&rig, entry, "status"));
    try testing.expectEqualStrings("Fixture Title\n", try activeField(&rig, entry, "title"));
    // started is the boot time plus the process's own, in seconds.
    try testing.expectEqualStrings("1000050\n", try activeField(&rig, entry, "started"));
    // The transcript is served as the file it is, not as a field.
    const t = rig.lookupName(96, entry, "transcript");
    try testing.expect(t.reply.status == .ok);
    const bytes = handle(rig.h, .{ .tag = 97, .op = .read, .node = t.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(std.mem.indexOf(u8, bytes.bytes, "Fixture Title") != null);
    // A field this harness does not publish is absent, not blank.
    try expectNoent(rig.lookupName(98, entry, "model"));
}

test "active: a daemon or helper is never listed as an agent" {
    var rig: Rig = .{ .dir = undefined, .with_proc = true };
    try rig.start();
    defer rig.end();
    // The shapes actually running on this machine.
    try rig.fakeProc(.{ .pid = 1010, .comm = "python3", .argv = "python3\x00-m\x00hermes_cli.main\x00gateway\x00run\x00" });
    try rig.fakeProc(.{ .pid = 1011, .comm = "omp", .argv = "omp\x00__omp_worker_daemon_broker\x00" });
    try rig.fakeProc(.{ .pid = 1012, .comm = "claude", .argv = "claude\x00mcp-server\x00" });
    // ...and one real session, so an empty answer cannot pass by default.
    try rig.fakeProc(.{ .pid = 1013, .comm = "claude", .argv = "claude\x00" });

    const act = rig.lookupName(1, root, "active");
    const listing = handle(rig.h, .{ .tag = 2, .op = .readdir, .node = act.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(stageHas(listing.bytes, "claude"));
    try testing.expect(!stageHas(listing.bytes, "hermes"));
    try testing.expect(!stageHas(listing.bytes, "omp"));
    const claude = rig.lookupName(3, act.reply.attr.node, "claude");
    const pids = handle(rig.h, .{ .tag = 4, .op = .readdir, .node = claude.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(stageHas(pids.bytes, "1013"));
    try testing.expect(!stageHas(pids.bytes, "1012")); // the mcp server
}

test "active: a pid reused by another process stops resolving" {
    var rig: Rig = .{ .dir = undefined, .with_proc = true };
    try rig.start();
    defer rig.end();
    try rig.fakeProc(.{ .pid = 1020, .comm = "claude", .starttime = 5000, .argv = "claude\x00" });
    const entry = try activeEntryNode(&rig, "claude", "1020");
    try testing.expect(handle(rig.h, .{ .tag = 5, .op = .getattr, .node = entry }).reply.status == .ok);

    // The same pid, a different process: only the start time says so.
    try rig.fakeProc(.{ .pid = 1020, .comm = "claude", .starttime = 9999, .argv = "claude\x00" });
    const act = rig.lookupName(6, root, "active");
    _ = handle(rig.h, .{ .tag = 7, .op = .readdir, .node = act.reply.attr.node, .off = 0, .size = msize });
    try expectNoent(handle(rig.h, .{ .tag = 8, .op = .getattr, .node = entry }));
    // The pid is still there — as the new process, under a new node.
    const fresh = try activeEntryNode(&rig, "claude", "1020");
    try testing.expect(fresh != entry);
}

test "active: a process that exits leaves the tree" {
    var rig: Rig = .{ .dir = undefined, .with_proc = true };
    try rig.start();
    defer rig.end();
    try rig.fakeProc(.{ .pid = 1030, .comm = "claude", .argv = "claude\x00" });
    const entry = try activeEntryNode(&rig, "claude", "1030");
    try testing.expect(handle(rig.h, .{ .tag = 9, .op = .getattr, .node = entry }).reply.status == .ok);

    try rig.reapProc(1030);
    const act = rig.lookupName(10, root, "active");
    const listing = handle(rig.h, .{ .tag = 11, .op = .readdir, .node = act.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(!stageHas(listing.bytes, "claude"));
    try expectNoent(handle(rig.h, .{ .tag = 12, .op = .getattr, .node = entry }));
    try expectNoent(rig.lookupName(13, act.reply.attr.node, "claude"));
}

test "active: the daemon never lists the process tree it lives in" {
    // 1041 is the daemon, its parent 1040 is a harness: showing it would
    // let a client act on the tree serving it.
    var rig: Rig = .{ .dir = undefined, .with_proc = true, .self_pid = 1041 };
    try rig.start();
    defer rig.end();
    try rig.fakeProc(.{ .pid = 1040, .comm = "claude", .argv = "claude\x00" });
    try rig.fakeProc(.{ .pid = 1041, .comm = "9agents", .ppid = 1040, .argv = "9agents\x00" });
    try rig.fakeProc(.{ .pid = 1042, .comm = "claude", .argv = "claude\x00" });

    const act = rig.lookupName(14, root, "active");
    const claude = rig.lookupName(15, act.reply.attr.node, "claude");
    try testing.expect(claude.reply.status == .ok);
    const pids = handle(rig.h, .{ .tag = 16, .op = .readdir, .node = claude.reply.attr.node, .off = 0, .size = msize });
    try testing.expect(stageHas(pids.bytes, "1042")); // an unrelated session lists
    try testing.expect(!stageHas(pids.bytes, "1040")); // its own parent does not
}