baychat 0.14.0 → 0.15.0

package/dist/relay/daemon.js

@@ -40,7 +40,9 @@ const path = __importStar(require("path"));
 const config_1 = require("../config");
 const runtime_binary_1 = require("../runtime-binary");
 const adapters_1 = require("./adapters");
+const parent_watch_1 = require("./parent-watch");
 const queue_1 = require("./queue");
+const held_1 = require("./held");
 const registry_1 = require("./registry");
 const mailbox_1 = require("./mailbox");
 const mailbox_watcher_1 = require("./mailbox-watcher");
@@ -82,6 +84,46 @@ class RelayDaemon {
     discoveryReasons = new Map();
     discovery;
     spawnHeadless;
+    isAlive;
+    /**
+     * Sessions with a headless turn running right now — the one-session lease.
+     *
+     * `SessionQueue` serialises `deliver()` calls, which is NOT the same thing: a
+     * headless turn is awaited inside one of those calls, and a second delivery
+     * arriving after it resolves would happily start another. Two headless agents
+     * under one name is the same fault as the attach/headless clone, reached by a
+     * different door.
+     *
+     * HONEST LIMIT: this can stop a new headless STARTING. It cannot un-run one
+     * already in flight, so it does not make a duplicate impossible — it makes the
+     * daemon stop creating them.
+     */
+    headlessInFlight = new Set();
+    /**
+     * Batches held for a session that is ALIVE but between wakes.
+     *
+     * 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 not
+     * undeliverable — it is EARLY. Timing out and recording it pending threw away
+     * two of the owner's own messages on 2026-08-31 while the agent was busy
+     * answering the one before them, which reads to a user as the relay stopping.
+     *
+     * Held here and flushed the instant the session attaches again.
+     *
+     * KEYED BY CONVERSATION as well as session. A session is in several rooms, and
+     * a wake frame carries ONE conversation id — so merging every held batch under
+     * the first one tells the agent that messages from room B came from room A, and
+     * sends it to re-read the wrong room. Rooms are held apart and flushed apart.
+     *
+     * PERSISTED, and that is not a detail. While this was a plain Map a daemon
+     * restart lost every held message, and the poll cursor had already moved past
+     * them, so the server never sent them again — gone, with `relay status`
+     * reporting nothing at all. See `held.ts`.
+     */
+    held = new held_1.HeldStore();
+    /** Beyond this a session is not "busy", it is broken; stop growing and report. */
+    static MAX_HELD = 200;
+    reattachGraceMs;
     resolveBinary;
     runTurn;
     /**
@@ -132,6 +174,8 @@ class RelayDaemon {
         }));
         this.discovery = opts.discovery ?? {};
         this.spawnHeadless = opts.spawnHeadless ?? adapters_1.runHeadless;
+        this.isAlive = opts.isAlive ?? parent_watch_1.processIsAlive;
+        this.reattachGraceMs = opts.reattachGraceMs ?? 4000;
         this.resolveBinary = opts.resolveBinary ?? ((name) => (0, runtime_binary_1.resolveRuntimeBinary)(name, (0, runtime_binary_1.currentBinaryEnv)()));
         this.runTurn = opts.runTurn;
         this.queue = new queue_1.SessionQueue((session, batch) => this.deliver(session, batch), (session, err) => {
@@ -153,6 +197,10 @@ class RelayDaemon {
         }
         const auth = { baseUrl: device.baseUrl, token: device.token };
         this.registry.load();
+        // Held messages outlive the process that held them. Loaded before the socket
+        // opens, so a session that re-arms in the first moments of a new daemon is
+        // handed what the previous one was holding rather than a clean slate.
+        this.held.load();
         const sockPath = (0, socket_1.socketPath)();
         if (await (0, socket_1.probeSocket)(sockPath)) {
             throw new Error(`a relay is already listening on ${sockPath} — run \`baychat relay status\``);
@@ -239,6 +287,59 @@ class RelayDaemon {
         // could never have matched anything.
         this.queue.push(sessionName, { ...message, conversationId });
     }
+    /**
+     * Hand a freshly attached session everything held while it was mid-turn.
+     *
+     * Sent as ONE wake: the messages arrived while the agent was busy and are read
+     * together, in order, the way a person returning to a chat reads them. Waking
+     * once per held message would spend a turn on each and let the agent answer the
+     * first three not knowing the fourth exists.
+     */
+    async flushHeld(session, sock) {
+        const rooms = this.held.roomsFor(session);
+        if (rooms.length === 0)
+            return;
+        for (const room of rooms) {
+            try {
+                // ACKNOWLEDGED, not fired and forgotten. A hand-over into a socket that
+                // has already died would otherwise clear the hold AND record `woken` —
+                // destroying the only copy of the messages and filing them as
+                // delivered, which is worse than never having held them.
+                await (0, socket_1.writeFrameAck)(sock, { type: "wake", conversationId: room.conversationId, messages: room.messages });
+            }
+            catch (err) {
+                // KEEP IT. This store is the only copy: dropping it because the handoff
+                // failed turns "held" into "lost", which is the failure it exists to
+                // prevent. The next attach gets it instead.
+                this.log(`could not hand ${room.messages.length} held message(s) for ${session} over: ${errText(err)}`);
+                return;
+            }
+            // Removed only once it is actually on the wire, and only for THIS room —
+            // a failure on the second room must not discard the first's receipt or the
+            // third's contents.
+            this.held.clearRoom(session, room.conversationId);
+            this.record({ kind: "woken", via: "attach", session }, session, room.messages);
+            this.log(`delivered ${room.messages.length} held message(s) to ${session} in ${room.conversationId} on re-attach`);
+        }
+    }
+    /**
+     * Wait for a session to re-arm its socket, up to `graceMs`.
+     *
+     * Polled rather than event-driven on purpose: the attach path already evicts
+     * a previous holder and re-registers, so the socket map is the single source
+     * of truth, and subscribing to it would mean a second one to keep in step.
+     */
+    async waitForReattach(session, graceMs) {
+        const deadline = Date.now() + graceMs;
+        for (;;) {
+            const sock = this.attached.get(session);
+            if (sock && !sock.destroyed)
+                return sock;
+            if (Date.now() >= deadline)
+                return undefined;
+            await new Promise((r) => setTimeout(r, 10));
+        }
+    }
     /**
      * Deliver one coalesced batch to one session. Runs under the queue's
      * per-session lock, so an attach wake and a headless resume can never be in
@@ -272,12 +373,53 @@ class RelayDaemon {
         }
         const sock = this.attached.get(session);
         if (sock && !sock.destroyed) {
-            // Live session: hand it the batch and let the harness re-invoke it. The
-            // attach client exits after one wake, which is what makes this a wake
-            // rather than a stream — and why the socket is dropped here.
-            (0, socket_1.writeFrame)(sock, { type: "wake", conversationId: batch[0].conversationId, messages: batch });
-            this.record({ kind: "woken", via: "attach", session }, session, batch);
-            return;
+            // AN OPEN SOCKET IS NOT A LIVE SESSION.
+            //
+            // `watchParent` used to guarantee that by making an orphaned attach exit
+            // with its launcher. Without it — and a `Stop` hook has to detach, so it
+            // cannot rely on ppid — an orphan keeps its socket open, the daemon reads
+            // "socket open" as "session alive", and the wake is written into a corpse
+            // and recorded `woken via attach`. A destroyed message, filed as delivered.
+            // Two orphans were measured doing exactly that on 2026-08-30.
+            //
+            // `ownerPid` answers the same question `watchParent` did, from the other
+            // side and without depending on the attach's own process tree: rung 3.5
+            // uses it to refuse to clone a LIVING session, and this uses it to refuse
+            // to deliver into a DEAD one. Absent (an old registration, or a platform
+            // with no readable process table) means unknown, and unknown must not cost
+            // a live session its delivery — so only a definite "dead" declines.
+            if (target.ownerPid !== undefined && !this.isAlive(target.ownerPid)) {
+                this.log(`socket for ${session} is orphaned — owner ${target.ownerPid} is gone; not delivering into it`);
+                this.attached.delete(session);
+                this.registry.setAttached(session, false);
+                sock.destroy();
+                // Fall through: the session really is gone, which is what the rungs
+                // below are for.
+            }
+            else {
+                // Live session: hand it the batch and let the harness re-invoke it. The
+                // attach client exits after one wake, which is what makes this a wake
+                // rather than a stream — and why the socket is dropped here.
+                //
+                // AWAITED. `sock.write()` buffers and returns, so an EPIPE from a peer
+                // that died between the liveness check and this line used to arrive
+                // after `record` had already filed the batch as `woken` — a lost message
+                // reported as delivered. A write that does not complete is not a
+                // delivery, and the rungs below exist for exactly this case.
+                try {
+                    await (0, socket_1.writeFrameAck)(sock, { type: "wake", conversationId: batch[0].conversationId, messages: batch });
+                    this.record({ kind: "woken", via: "attach", session }, session, batch);
+                    return;
+                }
+                catch (err) {
+                    this.log(`attach socket for ${session} took no frame: ${errText(err)} — falling through`);
+                    this.attached.delete(session);
+                    this.registry.setAttached(session, false);
+                    sock.destroy();
+                    // Fall through: nothing was delivered, so this must not shadow a rung
+                    // that could still reach the session.
+                }
+            }
         }
         const adapter = (0, adapters_1.adapterFor)(target.runtime);
         // ORDERED ABOVE THE FIFO, deliberately.
@@ -372,6 +514,58 @@ class RelayDaemon {
             this.mailboxes.delete(session);
             this.registry.setAttached(session, false);
         }
+        // RUNG 3.5: NEVER CLONE A LIVING SESSION.
+        //
+        // A socket attach exits by design on every wake, so a healthy session is
+        // briefly unreachable between wakes — and to every rung above, that is
+        // indistinguishable from a session that has gone. On 2026-08-31 a message
+        // landed in that gap and the ladder spawned a headless twin of a session
+        // that was alive and re-arming: two agents on one name, both authorised to
+        // answer, both able to act. The twin behaved impeccably and still committed
+        // and pushed under an identity that already had an occupant.
+        //
+        // `ownerPid` is the session itself, so it survives the gap that `pid` and
+        // the socket do not. Alive means "wait for it", never "replace it".
+        //
+        // SKIPPED after a mailbox fell through, and that exception is load-bearing:
+        // ENXIO has already PROVEN no reader there, and a sandboxed agent records a
+        // namespaced pid that reads alive forever (spec §13) — so applying this to
+        // fifo sessions would permanently shadow the one rung that can still reach
+        // them, which is the 2026-08-31 00:04 regression in a new costume.
+        if (!mailbox && target.ownerPid !== undefined && this.isAlive(target.ownerPid)) {
+            const rearmed = await this.waitForReattach(session, this.reattachGraceMs);
+            if (rearmed) {
+                try {
+                    await (0, socket_1.writeFrameAck)(rearmed, { type: "wake", conversationId: batch[0].conversationId, messages: batch });
+                    this.record({ kind: "woken", via: "attach", session }, session, batch);
+                    return;
+                }
+                catch (err) {
+                    // The socket appeared and then went. Do NOT record a delivery, and do
+                    // not fall to headless either — the session's process is still alive,
+                    // so this is the held case arriving by a different door.
+                    this.log(`re-armed socket for ${session} took no frame: ${errText(err)} — holding instead`);
+                }
+            }
+            // HELD, not pending. The session's process is still there — it is mid-turn,
+            // which is the normal state of a working agent, not a failure. Recording
+            // this pending threw the message away and told the user their relay had
+            // stopped; spawning a headless one instead is the clone bug. The third
+            // option is the correct one: keep it and hand it over when it re-arms.
+            const conversationId = batch[0].conversationId;
+            const total = this.held.countFor(session);
+            if (total + batch.length > RelayDaemon.MAX_HELD) {
+                this.record({
+                    kind: "pending",
+                    session,
+                    reason: `session process ${target.ownerPid} is alive but has not re-attached, and ${total} message(s) are already held — not holding more`,
+                }, session, batch);
+                return;
+            }
+            this.held.add(session, conversationId, batch);
+            this.log(`holding ${batch.length} message(s) for ${session} in ${conversationId} until it re-attaches (${this.held.countFor(session)} held)`);
+            return;
+        }
         const resolved = await this.resolveResume(target);
         const check = adapter.canResume(resolved);
         if (!check.ok) {
@@ -414,48 +608,110 @@ class RelayDaemon {
             }
             executable = binary.path;
         }
-        // A runtime with a richer transport than "spawn a command" gets to use it.
-        // Only a transport that could not be used AT ALL falls through to the spawn:
-        // a failure that is a real answer about this session — an id that names no
-        // thread, a turn the runtime refused — would say exactly the same thing
-        // again down the older path, more slowly and less clearly.
-        const richTransport = this.runTurn
-            ? (input) => this.runTurn({ runtime: target.runtime, ...input })
-            : adapter.runTurn?.bind(adapter);
-        if (richTransport) {
-            const outcome = await richTransport({ binaryPath: executable, target: resolved, prompt });
-            if (outcome.kind === "completed") {
-                this.record({ kind: "woken", via: "headless", session, exitCode: 0 }, session, batch);
-                return;
+        // THE LEASE — around the WHOLE headless phase, rich transport included.
+        //
+        // `SessionQueue` already serialises `deliver()`, so this is NOT what stops
+        // a second headless turn under normal flow; it is the guard for the paths
+        // that do not go through the queue, and the place the invariant is stated
+        // rather than assumed. It sits ABOVE `richTransport` because Codex's real
+        // headless turn runs there — a lease that wrapped only the plain spawn left
+        // the primary path uncovered, which is worse than none: it reads as
+        // protection while protecting the branch least likely to be taken.
+        //
+        // WHAT IT DOES NOT DO, deliberately. An attach arriving mid-turn is still
+        // accepted and only logged. Declining it would make a session with a HUMAN
+        // sitting at it unreachable in order to protect a spawned proxy, which is a
+        // worse failure than the overlap: the person gets silence and no way to see
+        // why. So this is mutual exclusion between headless turns, and observability
+        // for attach-vs-headless. Claiming more than that is what the review caught.
+        if (this.headlessInFlight.has(session)) {
+            this.record({ kind: "pending", session, reason: "a headless turn is already running for this session — refusing to start a second" }, session, batch);
+            return;
+        }
+        this.headlessInFlight.add(session);
+        // DELIBERATELY NOT AWAITED.
+        //
+        // `deliver()` runs under `SessionQueue`'s per-session lock, and a headless
+        // turn takes MINUTES. Awaiting it here holds that lock for the whole turn,
+        // so every later message for this session parks in the queue: not delivered,
+        // not recorded pending, not logged. Measured 2026-08-31 — three messages
+        // from the room vanished exactly this way while a twin ran, and the only
+        // reason anyone noticed was the human asking whether the agent was alive.
+        //
+        // Released here, the lease still stops a SECOND headless turn starting, and
+        // the message that would have started it is now recorded pending with a
+        // reason a person can read. Silence becomes a visible refusal.
+        void this.runHeadlessTurn({ session, batch, target, adapter, resolved, executable, prompt, args, file })
+            .catch((err) => {
+            // Nothing awaits this promise any more, so an escaping rejection would
+            // be an unhandled one — which can take the whole daemon down and with it
+            // every other session. A turn that threw also did not answer anybody, so
+            // the honest record is pending.
+            const reason = err instanceof Error ? err.message : String(err);
+            this.log(`headless turn for ${session} threw: ${reason}`);
+            this.record({ kind: "pending", session, reason: `headless turn threw: ${reason}` }, session, batch);
+        })
+            .finally(() => {
+            this.headlessInFlight.delete(session);
+        });
+    }
+    /**
+     * The headless turn itself, outside the delivery lock.
+     *
+     * Split from `deliver()` for one reason: its duration must not decide whether
+     * OTHER messages for this session are handled. Everything it records — woken,
+     * or pending with a reason — happens whenever the turn actually ends.
+     */
+    async runHeadlessTurn(ctx) {
+        const { session, batch, target, adapter, resolved, executable, prompt, args, file } = ctx;
+        try {
+            // A runtime with a richer transport than "spawn a command" gets to use it.
+            // Only a transport that could not be used AT ALL falls through to the spawn:
+            // a failure that is a real answer about this session — an id that names no
+            // thread, a turn the runtime refused — would say exactly the same thing
+            // again down the older path, more slowly and less clearly.
+            const richTransport = this.runTurn
+                ? (input) => this.runTurn({ runtime: target.runtime, ...input })
+                : adapter.runTurn?.bind(adapter);
+            if (richTransport) {
+                const outcome = await richTransport({ binaryPath: executable, target: resolved, prompt });
+                if (outcome.kind === "completed") {
+                    this.record({ kind: "woken", via: "headless", session, exitCode: 0 }, session, batch);
+                    return;
+                }
+                if (!outcome.transportUnusable) {
+                    this.record({ kind: "pending", session, reason: outcome.reason }, session, batch);
+                    return;
+                }
+                this.log(`${target.runtime}: falling back to a plain spawn — ${outcome.reason}`);
             }
-            if (!outcome.transportUnusable) {
-                this.record({ kind: "pending", session, reason: outcome.reason }, session, batch);
+            // A Windows .cmd needs its interpreter named explicitly, whatever produced
+            // the path — resolution or the session's own runtimeBin — so the decision
+            // lives here, after both, rather than inside either. Never a shell: these
+            // args carry the wake prompt, and therefore other people's message text.
+            const plan = (0, runtime_binary_1.spawnPlanFor)(executable, process.platform);
+            // The session's own directory when we know it: `cwd` is only where the
+            // attach process ran, and `codex exec` refuses to start outside a trusted
+            // directory at all.
+            const { exitCode, stderr } = await this.spawnHeadless(plan.file, [...plan.prefixArgs, ...args], {
+                cwd: resolved.resumeCwd ?? resolved.cwd,
+            });
+            if (exitCode !== 0) {
+                // The binary ran and the turn still failed, so what we resolved may be
+                // stale — a half-finished upgrade, a runtime removed since. Drop it and
+                // prove it again next time rather than trusting it for the process's life.
+                this.binaries.delete(file);
+                // A non-zero headless turn did not necessarily reply. Recording it as
+                // delivered would claim an answer we cannot evidence.
+                this.record({ kind: "pending", session, reason: `headless ${target.runtime} exited ${exitCode}: ${stderr.slice(0, 200)}` }, session, batch);
                 return;
             }
-            this.log(`${target.runtime}: falling back to a plain spawn — ${outcome.reason}`);
+            this.record({ kind: "woken", via: "headless", session, exitCode }, session, batch);
         }
-        // A Windows .cmd needs its interpreter named explicitly, whatever produced
-        // the path — resolution or the session's own runtimeBin — so the decision
-        // lives here, after both, rather than inside either. Never a shell: these
-        // args carry the wake prompt, and therefore other people's message text.
-        const plan = (0, runtime_binary_1.spawnPlanFor)(executable, process.platform);
-        // The session's own directory when we know it: `cwd` is only where the
-        // attach process ran, and `codex exec` refuses to start outside a trusted
-        // directory at all.
-        const { exitCode, stderr } = await this.spawnHeadless(plan.file, [...plan.prefixArgs, ...args], {
-            cwd: resolved.resumeCwd ?? resolved.cwd,
-        });
-        if (exitCode !== 0) {
-            // The binary ran and the turn still failed, so what we resolved may be
-            // stale — a half-finished upgrade, a runtime removed since. Drop it and
-            // prove it again next time rather than trusting it for the process's life.
-            this.binaries.delete(file);
-            // A non-zero headless turn did not necessarily reply. Recording it as
-            // delivered would claim an answer we cannot evidence.
-            this.record({ kind: "pending", session, reason: `headless ${target.runtime} exited ${exitCode}: ${stderr.slice(0, 200)}` }, session, batch);
-            return;
+        finally {
+            // Nothing to release here — the lease is cleared by the caller's
+            // `.finally`, which owns it for exactly as long as this turn runs.
         }
-        this.record({ kind: "woken", via: "headless", session, exitCode }, session, batch);
     }
     /**
      * The proven executable for a runtime, resolved at most once per process
@@ -512,6 +768,13 @@ class RelayDaemon {
     record(outcome, session, batch) {
         if (outcome.kind === "woken") {
             this.delivered += batch.length;
+            // The one witness `relay status` may treat as proof that a session is
+            // reachable again. A headless turn only counts when it exited cleanly: a
+            // spawn that ran and failed delivered nothing, and recording it would
+            // clear the very failure it just repeated.
+            if (outcome.via !== "headless" || outcome.exitCode === 0) {
+                this.registry.markDelivered(session, new Date().toISOString());
+            }
             this.log(`woke ${session} via ${outcome.via} with ${batch.length} message(s)`);
             return;
         }
@@ -547,11 +810,20 @@ class RelayDaemon {
                     resumeCwd: frame.resumeCwd,
                     cwd: frame.cwd,
                     runtimeBin: frame.runtimeBin,
+                    ownerPid: frame.ownerPid,
                 });
                 // A session that names itself supersedes anything discovery guessed
                 // for it, so drop the throttle and let the next wake use the new id.
                 if (frame.resumeId)
                     this.discoveryReasons.delete(frame.session);
+                // OVERLAP, AND WE CANNOT PREVENT IT — only report it. A headless turn
+                // already running was spawned because this session looked gone; it is
+                // mid-turn now, and the daemon will not kill a model that may be part
+                // way through writing something. Two agents briefly hold this name.
+                // Said out loud because the alternative is that nobody ever knows.
+                if (this.headlessInFlight.has(frame.session)) {
+                    this.log(`WARNING: ${frame.session} attached while a headless turn for it is still running — two agents hold this session name until that turn ends`);
+                }
                 // EVICT THE PREVIOUS HOLDER. A session name has exactly one listener,
                 // and `set` alone would leave the old socket open and its process
                 // running — which is how two orphaned attaches came to be stacked on
@@ -566,6 +838,7 @@ class RelayDaemon {
                 this.registry.setAttached(frame.session, true);
                 (0, socket_1.writeFrame)(sock, { type: "attached", session: frame.session });
                 this.log(`attached: ${frame.session} (${frame.runtime})`);
+                void this.flushHeld(frame.session, sock);
                 return;
             }
             if (frame.type === "status") {
@@ -607,6 +880,7 @@ class RelayDaemon {
             delivered: this.delivered,
             sessions,
             pending: this.pending,
+            held: this.held.summary(),
             lastError: this.lastError,
         };
     }

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.js

@@ -185,6 +185,7 @@ function registrationToTarget(reg) {
         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.