baychat 0.13.1 → 0.15.0

package/dist/relay/held.js

@@ -0,0 +1,184 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeldStore = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+const FILE = "relay-held.json";
+function heldPath() {
+    return path.join((0, config_1.configDir)(), FILE);
+}
+/**
+ * Messages held for a session that is alive but mid-turn, PERSISTED.
+ *
+ * A socket attach exits on every wake and the turn it triggers runs for minutes
+ * before the session re-arms. A message arriving in that window is early, not
+ * undeliverable, so the daemon holds it. That much already worked — in memory.
+ *
+ * In memory was not enough, and the gap was specific: a daemon restart lost
+ * every held message, and because the poll cursor had already advanced past
+ * them the server never sent them again. They were not pending, not delivered,
+ * and not anywhere. `relay status` showed nothing at all, so the only symptom
+ * was a person on a phone whose message was never answered — the exact reading
+ * of "the relay stopped" that holding was introduced to prevent.
+ *
+ * So the store is a file, and it is in `relay status`. Held is a THIRD state,
+ * neither delivered nor failed, and it has to be visible as itself: printing it
+ * as pending would make a working agent look broken, and printing nothing is
+ * what we just came from.
+ *
+ * ⚠️ THIS FILE CONTAINS MESSAGE TEXT IN PLAINTEXT. Everything else the relay
+ * persists is metadata — session names, resume ids, positions. This is chat
+ * content, sitting on disk on the user's own machine for as long as their agent
+ * takes to finish a turn. Mode 0600, in the same private config dir as the
+ * device credential, and deliberately emptied the moment a batch is handed
+ * over. That is the price of not losing messages, and it is worth naming rather
+ * than discovering.
+ */
+class HeldStore {
+    filePath;
+    /** session → conversationId → room. */
+    rooms = new Map();
+    constructor(filePath = heldPath()) {
+        this.filePath = filePath;
+    }
+    load() {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+        }
+        catch {
+            // Missing or corrupt. An empty store is the correct reading: it means the
+            // daemon holds nothing, which is true, rather than crashing a relay on
+            // startup over messages it cannot recover anyway.
+            return;
+        }
+        if (!raw || typeof raw !== "object")
+            return;
+        for (const [session, bySession] of Object.entries(raw)) {
+            if (!bySession || typeof bySession !== "object")
+                continue;
+            const rooms = new Map();
+            for (const [conversationId, value] of Object.entries(bySession)) {
+                const room = value;
+                if (!room || !Array.isArray(room.messages) || room.messages.length === 0)
+                    continue;
+                rooms.set(conversationId, {
+                    conversationId,
+                    heldAt: typeof room.heldAt === "string" ? room.heldAt : new Date().toISOString(),
+                    messages: room.messages,
+                });
+            }
+            if (rooms.size > 0)
+                this.rooms.set(session, rooms);
+        }
+    }
+    save() {
+        const out = {};
+        for (const [session, rooms] of this.rooms) {
+            if (rooms.size === 0)
+                continue;
+            out[session] = Object.fromEntries(rooms);
+        }
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            if (Object.keys(out).length === 0) {
+                // Nothing held: remove the file rather than leaving `{}` behind, so the
+                // plaintext does not outlive the hold by a single byte more than it
+                // must.
+                fs.rmSync(this.filePath, { force: true });
+                return;
+            }
+            fs.writeFileSync(this.filePath, JSON.stringify(out, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // Losing durability is not losing the hold: the in-memory copy still
+            // serves this process, which is exactly the behaviour we had before.
+        }
+    }
+    /**
+     * Hold a batch for one room.
+     *
+     * De-duplicated by message id: a cursor re-baseline (409 recovery re-reads
+     * from a watermark) can legitimately replay an event, and a room must not
+     * show the agent the same line twice when it finally re-arms.
+     */
+    add(session, conversationId, messages) {
+        const rooms = this.rooms.get(session) ?? new Map();
+        const room = rooms.get(conversationId) ?? { conversationId, heldAt: new Date().toISOString(), messages: [] };
+        for (const m of messages) {
+            if (!room.messages.some((held) => held.id === m.id))
+                room.messages.push(m);
+        }
+        rooms.set(conversationId, room);
+        this.rooms.set(session, rooms);
+        this.save();
+    }
+    /** Every room held for a session, oldest hold first. */
+    roomsFor(session) {
+        const rooms = this.rooms.get(session);
+        if (!rooms)
+            return [];
+        return [...rooms.values()].sort((a, b) => Date.parse(a.heldAt) - Date.parse(b.heldAt));
+    }
+    /** Drop one room's hold — called only once its messages are on the wire. */
+    clearRoom(session, conversationId) {
+        const rooms = this.rooms.get(session);
+        if (!rooms || !rooms.delete(conversationId))
+            return;
+        if (rooms.size === 0)
+            this.rooms.delete(session);
+        this.save();
+    }
+    /** How many messages are held for one session, across all its rooms. */
+    countFor(session) {
+        let n = 0;
+        for (const room of this.rooms.get(session)?.values() ?? [])
+            n += room.messages.length;
+        return n;
+    }
+    /** What `relay status` prints. Content is deliberately NOT included. */
+    summary() {
+        const out = [];
+        for (const [session, rooms] of this.rooms) {
+            for (const room of rooms.values()) {
+                out.push({ session, conversationId: room.conversationId, count: room.messages.length, heldAt: room.heldAt });
+            }
+        }
+        return out.sort((a, b) => Date.parse(a.heldAt) - Date.parse(b.heldAt));
+    }
+}
+exports.HeldStore = HeldStore;

package/dist/relay/mailbox-watcher.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailboxWatcher = void 0;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const mailbox_1 = require("./mailbox");
+const parent_watch_1 = require("./parent-watch");
+/**
+ * Watch the mailbox root for sessions arming and dying.
+ *
+ * `fs.watch` AND a periodic sweep, not one or the other. `fs.watch` gives
+ * instant pickup but is unreliable across filesystems — notably a tmpfs
+ * directory the agent created moments earlier — and a sweep alone would add
+ * seconds to every arming. The sweep is also the only thing that can notice a
+ * registration whose process has since died, because nothing on disk changes
+ * when a process exits and there is no event to watch for.
+ */
+class MailboxWatcher {
+    opts;
+    seen = new Map();
+    isAlive;
+    sweepMs;
+    watcher;
+    timer;
+    constructor(opts) {
+        this.opts = opts;
+        this.isAlive = opts.isAlive ?? parent_watch_1.processIsAlive;
+        this.sweepMs = opts.sweepMs ?? 2_000;
+    }
+    start() {
+        fs.mkdirSync(this.opts.root, { recursive: true, mode: 0o700 });
+        try {
+            this.watcher = fs.watch(this.opts.root, { recursive: true }, () => this.sweep());
+        }
+        catch {
+            // Not every platform or filesystem supports recursive watching. The sweep
+            // below is the floor, so this degrades to slower pickup, never to none.
+        }
+        this.timer = setInterval(() => this.sweep(), this.sweepMs);
+        this.timer.unref();
+        this.sweep();
+    }
+    stop() {
+        this.watcher?.close();
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    sweep() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.opts.root, { withFileTypes: true });
+        }
+        catch {
+            return; // No root yet: nothing has armed. Not a fault.
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = path.join(this.opts.root, entry.name);
+            const reg = (0, mailbox_1.readRegistration)(dir);
+            if (!reg)
+                continue;
+            if (!this.isAlive(reg.pid)) {
+                this.seen.delete(reg.session);
+                fs.rmSync(dir, { recursive: true, force: true });
+                this.opts.onDrop(reg.session, `mailbox process ${reg.pid} is no longer running`);
+                continue;
+            }
+            // Identity is the registration's CONTENT, not its timestamp.
+            //
+            // `registeredAt` has millisecond resolution, so two armings inside one
+            // millisecond share a timestamp — which in a test is a flake and in
+            // production is a re-arm that goes unannounced. Hashing the content is
+            // exact: anything the daemon would act on differently is a different hash,
+            // and a byte-identical rewrite is one the daemon already has right.
+            const stamp = crypto.createHash("sha256").update(JSON.stringify(reg)).digest("hex");
+            if (this.seen.get(reg.session) === stamp)
+                continue;
+            this.seen.set(reg.session, stamp);
+            this.opts.onRegister(reg);
+        }
+    }
+}
+exports.MailboxWatcher = MailboxWatcher;

package/dist/relay/mailbox.js

@@ -0,0 +1,320 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAKE_FIFO = exports.REGISTER_FILE = void 0;
+exports.resolveMailboxRoot = resolveMailboxRoot;
+exports.mailboxRootCandidates = mailboxRootCandidates;
+exports.pickUsableMailboxDir = pickUsableMailboxDir;
+exports.sanitizeSessionDir = sanitizeSessionDir;
+exports.sessionMailboxDir = sessionMailboxDir;
+exports.writeRegistration = writeRegistration;
+exports.readRegistration = readRegistration;
+exports.registrationToTarget = registrationToTarget;
+exports.createWakeFifo = createWakeFifo;
+exports.ensureWakeFifo = ensureWakeFifo;
+exports.wakeFifoPath = wakeFifoPath;
+exports.awaitWakeFifo = awaitWakeFifo;
+exports.writeWake = writeWake;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Where a sandboxed agent and the relay meet on disk.
+ *
+ * THE AGENT CHOOSES, NOT THE DAEMON. Only the agent's own process knows what its
+ * sandbox permits: on 2026-08-30 a Codex shell could create files under /tmp but
+ * was refused `connect()` on a socket beside them, and `/run/user/1000` was
+ * granted as a writable root while the socket in it stayed unreachable. This is
+ * the same rule `SessionTarget.runtimeBin` already follows — the session
+ * identifies its own environment and the daemon does not guess for it.
+ *
+ * Order: an explicit override, then XDG_RUNTIME_DIR (user-private 0700 tmpfs,
+ * cleared on logout, so nothing outlives the session), then a uid-scoped
+ * directory under TMPDIR. The uid is in the tmp name because /tmp is shared: two
+ * users must never resolve to one root, and the 0700 mode the caller creates it
+ * with is what keeps either out of the other's.
+ */
+function resolveMailboxRoot(env = process.env, uid = process.getuid?.() ?? 0) {
+    return mailboxRootCandidates(env, uid)[0];
+}
+/**
+ * Every root worth trying, best first.
+ *
+ * There is more than one because PREFERRING a root is not the same as being
+ * able to USE it. Measured 2026-08-30: inside bubblewrap, `/run/user/1000` is
+ * statable — the relay socket in it can be stat'ed and refused at `connect()` —
+ * but `mkdir` under it fails ENOENT. An agent that resolved one root and
+ * assumed it would work gave up there instead of trying `/tmp`, which the same
+ * sandbox creates files in happily.
+ *
+ * The daemon watches all of these, because it cannot know which one the agent
+ * turned out to be able to use.
+ */
+function mailboxRootCandidates(env = process.env, uid = process.getuid?.() ?? 0) {
+    // An explicit override is EXCLUSIVE, not merely first. "Use this directory"
+    // is what someone setting it means, and treating it as a preference left both
+    // the daemon and `doctor` still reading the machine's real mailbox roots —
+    // which made the tests non-hermetic and, worse, let a leftover mailbox for a
+    // session of the same name hijack a delivery meant for another root.
+    if (env.BAYCHAT_MAILBOX_DIR)
+        return [env.BAYCHAT_MAILBOX_DIR];
+    const roots = [];
+    if (env.XDG_RUNTIME_DIR)
+        roots.push(path.join(env.XDG_RUNTIME_DIR, "baychat-mailbox"));
+    roots.push(path.join(env.TMPDIR ?? os.tmpdir(), `baychat-mailbox-${uid}`));
+    return [...new Set(roots)];
+}
+/**
+ * The first root this process can actually create — PROVED, not assumed.
+ *
+ * This is the agent's half of "the session identifies its own environment": it
+ * finds out by doing, because nothing else on the machine can tell it what its
+ * sandbox permits.
+ */
+function pickUsableMailboxDir(session, env = process.env, uid = process.getuid?.() ?? 0, mkdir = (dir) => fs.mkdirSync(dir, { recursive: true, mode: 0o700 })) {
+    const failures = [];
+    for (const root of mailboxRootCandidates(env, uid)) {
+        // The SESSION directory, not the root. Measured 2026-08-30: the root often
+        // already exists because the unsandboxed daemon created it, so probing the
+        // root succeeds as a no-op and the real refusal only surfaces one level
+        // down — where the agent had already committed to a root it cannot use.
+        // Prove the exact directory you are about to write into.
+        const dir = sessionMailboxDir(root, session);
+        try {
+            mkdir(dir);
+            return dir;
+        }
+        catch (err) {
+            failures.push(`${dir} (${err.message})`);
+        }
+    }
+    throw new Error(`no usable mailbox directory — tried ${failures.join(", ")}`);
+}
+/**
+ * A session name is user input; it must never become a path traversal.
+ *
+ * Characters outside the safe set are COLLAPSED rather than dropped: dropping
+ * would let "a/b" and "ab" resolve to one directory, so two sessions would share
+ * a mailbox and each would take the other's wakes.
+ */
+function sanitizeSessionDir(name) {
+    return name.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+function sessionMailboxDir(root, session) {
+    return path.join(root, sanitizeSessionDir(session));
+}
+exports.REGISTER_FILE = "register.json";
+exports.WAKE_FIFO = "wake.fifo";
+function writeRegistration(dir, reg) {
+    // 0600: this file names the session's resume id, which is the handle for
+    // "continue that conversation". It is not public inside a shared /tmp.
+    fs.writeFileSync(path.join(dir, exports.REGISTER_FILE), JSON.stringify(reg, null, 2), { mode: 0o600 });
+}
+/**
+ * Read a registration, or `undefined` for anything we cannot fully trust.
+ *
+ * Never throws. The daemon watches this directory while the agent writes into
+ * it, so a truncated or half-flushed file is an ordinary event, not a fault —
+ * and the sweep behind the watcher picks it up a moment later anyway.
+ */
+function readRegistration(dir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(dir, exports.REGISTER_FILE), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const reg = parsed;
+    if (typeof reg.session !== "string" || typeof reg.runtime !== "string")
+        return undefined;
+    if (typeof reg.fifo !== "string" || typeof reg.pid !== "number")
+        return undefined;
+    if (typeof reg.registeredAt !== "string")
+        return undefined;
+    return reg;
+}
+/** The registry cares about a SessionTarget, whichever channel described it. */
+function registrationToTarget(reg) {
+    return {
+        name: reg.session,
+        runtime: reg.runtime,
+        resumeId: reg.resumeId,
+        resumeSource: reg.resumeSource,
+        resumeEvidence: reg.resumeEvidence,
+        resumeCwd: reg.resumeCwd,
+        cwd: reg.cwd,
+        runtimeBin: reg.runtimeBin,
+        ownerPid: reg.ownerPid,
+        // Persisted, so a LATER headless resume still knows this session is
+        // sandboxed and must be told to re-arm in the foreground. `status()`
+        // recomputes the live rung for display; this is the remembered one.
+        transport: "fifo",
+    };
+}
+/**
+ * Create this session's wake FIFO, replacing any previous one.
+ *
+ * Replacing rather than reusing is deliberate: a FIFO left behind by a crashed
+ * attach has no reader, and a stale reader from a previous arming could
+ * otherwise steal this session's next wake. A fresh inode makes both impossible.
+ *
+ * `mkfifo(1)` rather than a binding: Node has no `mkfifo`, and a sandboxed agent
+ * has been shown to run it (2026-08-30, `mkfifo -m 600` under bubblewrap).
+ */
+function createWakeFifo(dir) {
+    const fifo = path.join(dir, exports.WAKE_FIFO);
+    fs.rmSync(fifo, { force: true });
+    (0, child_process_1.execFileSync)("mkfifo", ["-m", "600", fifo]);
+    return fifo;
+}
+/**
+ * Make sure a wake FIFO exists at this path — WITHOUT disturbing one that does.
+ *
+ * This is the daemon's entry point, and it is deliberately not `createWakeFifo`.
+ * That function unlinks and recreates, which was right when the AGENT owned the
+ * FIFO (a stale one from a crashed attach has no reader, and a fresh inode stops
+ * an old reader stealing the next wake). Once the daemon took ownership the risk
+ * inverted: an agent may be blocked on this FIFO right now, and unlinking it
+ * leaves that reader waiting forever on an inode nothing can reach while the
+ * daemon writes to a new one where nobody is.
+ *
+ * Measured 2026-08-30 23:54: Codex registered twice nine seconds apart, the
+ * second registration recreated the FIFO, and the next message was recorded
+ * `pending` with a live reader sitting on the orphaned inode. Same shape as the
+ * orphaned attach sockets earlier that evening — a wake sent somewhere nobody
+ * is listening.
+ *
+ * A path that exists but is NOT a FIFO is replaced: nothing can be blocked on a
+ * regular file, so there is no reader to orphan, and a wake written into one
+ * would be silently lost.
+ */
+function ensureWakeFifo(dir) {
+    const fifo = path.join(dir, exports.WAKE_FIFO);
+    try {
+        if (fs.statSync(fifo).isFIFO())
+            return fifo;
+    }
+    catch {
+        /* not there — create it below */
+    }
+    return createWakeFifo(dir);
+}
+/** Where this session's FIFO will live, without creating it. */
+function wakeFifoPath(dir) {
+    return path.join(dir, exports.WAKE_FIFO);
+}
+/**
+ * Wait for the daemon to create this session's FIFO.
+ *
+ * THE DAEMON CREATES IT, NOT THE AGENT. Node has no `mkfifo` binding, so making
+ * one means spawning `mkfifo(1)` — and spawning a helper binary is precisely
+ * what a sandbox restricts. Measured 2026-08-30: inside bubblewrap the agent
+ * could create its directory and write its registration, then died with
+ * `spawnSync mkfifo EPERM`.
+ *
+ * So the privileged step moved to the side that has the privilege. The agent
+ * declares the path it wants in `register.json`; the daemon, which is not
+ * sandboxed, creates the FIFO there; the agent waits for it to appear. Nothing
+ * the agent must do is now anything but opening and reading a file.
+ */
+async function awaitWakeFifo(fifo, timeoutMs = 30_000, pollMs = 100) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            if (fs.statSync(fifo).isFIFO())
+                return;
+        }
+        catch {
+            /* not there yet */
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`the relay did not create ${fifo} within ${Math.round(timeoutMs / 1000)}s — it may not be watching this mailbox root. Run \`baychat doctor\`.`);
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+/**
+ * Hand one wake to a blocked reader, or say why we could not — NEVER block.
+ *
+ * `O_NONBLOCK` on a write-only FIFO open fails with ENXIO when no reader has it
+ * open. That is not an error condition: it is the honest answer "this session
+ * registered, but it is not waiting right now", and it must become `pending`
+ * rather than `delivered`.
+ *
+ * A completed write is the one piece of real evidence this transport has that a
+ * message was TAKEN rather than merely sent — which is more than either of the
+ * other two rungs can offer.
+ */
+function writeWake(fifoPath, payload) {
+    let stat;
+    try {
+        stat = fs.statSync(fifoPath);
+    }
+    catch {
+        return { ok: false, reason: `no mailbox FIFO at ${fifoPath}` };
+    }
+    if (!stat.isFIFO())
+        return { ok: false, reason: `${fifoPath} is not a FIFO — refusing to write a wake into it` };
+    let fd;
+    try {
+        fd = fs.openSync(fifoPath, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENXIO")
+            return { ok: false, reason: "session registered a mailbox but is not waiting on it right now" };
+        return { ok: false, reason: `could not open ${fifoPath}: ${code ?? "unknown error"}` };
+    }
+    try {
+        fs.writeSync(fd, payload);
+        return { ok: true };
+    }
+    catch (err) {
+        // The reader went away mid-write. Nothing was taken; say so.
+        return { ok: false, reason: `reader left mid-wake: ${err.code ?? "write failed"}` };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}