@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/session-relay.js

@@ -0,0 +1,1636 @@
+/**
+ * CELLO Daemon — THE BLIND WITNESS, AND STAYING REACHABLE THROUGH IT
+ *
+ * Split out of `session-node-manager.ts`. A relay countersigns the ORDER of a conversation and is
+ * given only hashes, never plaintext — so what lives here is everything about talking to one:
+ * connecting a session to its witness, proving key possession to it, holding a circuit reservation
+ * open so a counterparty behind a NAT can still reach us, watching that reservation decay and
+ * renewing it, quarantining a relay that misbehaves, and detaching cleanly when a session ends.
+ *
+ * **Moved verbatim, comments included.**
+ *
+ * ⚠️ **A RELAY IS NOT TRUSTED, AND THE CODE HERE IS WHERE THAT IS ENFORCED.** It authenticates to
+ * us as much as we authenticate to it; it is quarantined rather than believed when it misbehaves;
+ * and the one thing it must never learn — the operator's own address — is why the circuit-dial
+ * authorisation below is narrow rather than convenient. Anything added here that widens what a
+ * relay can see or do is a protocol change, not a refactor.
+ */
+import { randomUUID } from "node:crypto";
+import * as lp from "it-length-prefixed";
+import { decode } from "cbor-x";
+import { isValidMultiaddr } from "@cello-protocol/transport";
+import { contentHashFor } from "./wire-content-hash.js";
+import { extractErrorMessage } from "./error-message.js";
+import { RelayReceiptStore } from "./relay-receipt-store.js";
+import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
+import { AgentRelayClient } from "./session-relay-client.js";
+import { mergeRelayEndpoints } from "./relay-endpoints.js";
+import { RELAY_QUARANTINE_MS, SR_RESERVATION_MAX_RETRIES, heldRelayIdsOf, relayPeerIdOf, } from "./session-node-types.js";
+export class SessionRelay {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /** A getter so the moved queries still read `this.#db` and narrow exactly as they did. */
+    get #db() {
+        return this.#ctx.db();
+    }
+    /**
+     * DOD-M15-RELAYAUTH-1: authenticate a fresh standing receiver to its reservation relay over the
+     * CELLO relay protocol — proof of K_local key possession, not a session. Reuses the SAME
+     * `#relayClients` cache `connectSessionRelay`/`#resolveSealTransport` read from, keyed
+     * identically (`${agentName}::${relayPeerId}`), so a session created moments later on this same
+     * relay finds an already-authenticated client instead of dialing and authenticating twice.
+     *
+     * The manager holds no K_local (M12-P15's own rationale for `#detachedRelayClientBuilder`) —
+     * without a builder wired (a narrow startup race, or a test harness that never wires one), this
+     * is a no-op and the relay's own grace-window revoke is the backstop, not a defect in this path.
+     */
+    async authenticateStandingReceiver(agentName, node, relayPeerId, heldCircuitAddr, correlationId) {
+        const clientKey = `${agentName}::${relayPeerId}`;
+        let client = this.#ctx.relayClients.get(clientKey);
+        if (!client) {
+            if (!this.#ctx.relayReceiptStore && this.#db)
+                this.#ctx.relayReceiptStore = new RelayReceiptStore(this.#db, this.#ctx.logger);
+            if (!this.#ctx.sealLeafStore && this.#db)
+                this.#ctx.sealLeafStore = new SessionSealLeafStore(this.#db, this.#ctx.logger);
+            /**
+             * ⚠️ SPLIT, NOT AN ANCHORED STRIP. The held address is
+             * `/ip4/…/tcp/…/p2p/<relay>/p2p-circuit/p2p/<self>` — the `/p2p-circuit` marker is in the
+             * MIDDLE, not at the end, so a `/\/p2p-circuit$/` replace matches nothing and silently
+             * hands the relay client a circuit address as its DIAL address. Measured, not assumed:
+             * that first version failed this file's own test because the client could not dial.
+             */
+            const baseRelayAddr = heldCircuitAddr.split("/p2p-circuit")[0] ?? heldCircuitAddr;
+            client = this.#ctx.detachedRelayClientBuilder?.(agentName, relayPeerId, [baseRelayAddr], {
+                receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                ownChainStore: this.#ctx.ownChainStore ?? undefined,
+                // DOD-M15-RELAYSLOTS-1: read at each auth, never snapshotted — the token expires hourly.
+                onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+            });
+            if (!client) {
+                /**
+                 * Review M5: this was a `debug` line, and it is not a debug-level event.
+                 *
+                 * If no builder is wired we return without proving key possession, the relay revokes this
+                 * receiver's reservation about fifteen seconds later, and the agent stops being reachable
+                 * from behind NAT — while reporting itself perfectly healthy. Calling that "a narrow startup
+                 * race" in a comment concedes it happens in production, and a system that is unreachable
+                 * must not be quieter about it than a system that is merely slow.
+                 */
+                this.#ctx.logger.warn("session.standing_receiver.relay_auth.no_builder", {
+                    agentName,
+                    relayPeerId,
+                    correlationId,
+                    impact: "this receiver cannot prove key possession, so the relay will revoke its reservation and " +
+                        "the agent becomes unreachable from behind NAT — nobody can start a session with it — " +
+                        "even though it still reports itself online.",
+                });
+                return;
+            }
+            this.#ctx.relayClients.set(clientKey, client);
+        }
+        /**
+         * ⚠️ `proveReservation`, NOT `connect`. Review HIGH-1: `connect()` short-circuits on the
+         * client's cached stream, which belongs to whichever node connected FIRST — so every
+         * REPLACEMENT standing receiver (the one built behind each new session) sent nothing, the relay
+         * never saw its transport identity, and its reservation was revoked ~15s later. The agent then
+         * churned reserve→revoke→rebuild for the life of the conversation, holding no usable circuit
+         * address, so while you were talking to one person nobody else could reach you.
+         *
+         * `proveReservation` always opens its own stream from THIS node, and marks it so the relay
+         * proves possession without rebinding the agent's delivery target away from the live session.
+         */
+        const proven = await client.proveReservation(node);
+        /**
+         * DOD-M15-RELAYSLOTS-1: keep the relay's refusal where the OPERATOR can reach it.
+         *
+         * The log line below is a good log line and it is not an answer to "why is my agent
+         * unreachable?" — nobody opens the file. The relay now refuses for reasons a person can act on
+         * (no token yet, too many sessions still open, this relay is misconfigured), each with its own
+         * next step, and every one of them is useless if it stops at a log.
+         */
+        if (!proven) {
+            const refusal = client.getLastAuthRefusal();
+            /**
+             * Review L2: the `else` is not symmetry for its own sake. `proveReservation` also fails for
+             * transport reasons, which leave `getLastAuthRefusal()` null — and without this branch the
+             * PREVIOUS refusal stayed in the map, so `cello_status` went on showing a cause and an
+             * affordance for something that was no longer what was wrong.
+             */
+            if (refusal)
+                this.#ctx.srRelayRefusal.set(agentName, { ...this.#ctx.withDirectoryCause(agentName, refusal), relayPeerId });
+            else
+                this.#ctx.srRelayRefusal.delete(agentName);
+            /**
+             * DOD-M15-RELAYSLOTS-1 clause 9 — **ACT on the classification, do not merely record it.**
+             * A relay-side fault means a different relay will work now, so quarantine this one and
+             * rebuild the receiver against the rest of the pool. Everything else stays put: a token
+             * problem reproduces on every relay, and walking the fleet would turn one client fault into
+             * what looks like a fleet-wide outage.
+             */
+            if (refusal?.tryAnotherRelay && !this.#ctx.shuttingDown) {
+                /**
+                 * ⚠️ **THE QUARANTINE ACTS; THE REBUILD USED TO AND NO LONGER CAN — 056-SLOTDEAD.**
+                 *
+                 * This used to `rebuildStandingReceiver` so the new node would reserve against the rest of
+                 * the pool. A rebuilt receiver reserves NOTHING now (055-ONDEMAND), so the rebuild bought
+                 * nothing and cost the agent its transport identity. The quarantine is the half that still
+                 * does the work: the next offer reserves against the pool minus this relay.
+                 */
+                this.#quarantineRelay(agentName, relayPeerId, refusal.reason);
+            }
+        }
+        else {
+            this.#ctx.srRelayRefusal.delete(agentName);
+        }
+        this.#ctx.logger.info("session.standing_receiver.relay_auth.result", {
+            agentName,
+            relayPeerId,
+            // The node that actually proved itself — without this, HIGH-1 was invisible in the logs: the
+            // line said `connected: true` for a receiver that had sent nothing.
+            nodePeerId: node.getPeerId(),
+            proven,
+            ...(proven ? {} : {
+                refusalReason: client.getLastAuthRefusal()?.reason ?? "no_relay_verdict",
+                tryAnotherRelay: client.getLastAuthRefusal()?.tryAnotherRelay ?? false,
+            }),
+            correlationId,
+        });
+    }
+    /**
+     * RELAYSIG-1: the durably-stored, signature-verified relay ordering-record receipts for an agent
+     * (optionally a single session). Empty when no receipts have been recorded yet. Read-only.
+     */
+    getRelayReceipts(agentPubkeyHex, sessionIdHex) {
+        if (!this.#ctx.relayReceiptStore && this.#db) {
+            this.#ctx.relayReceiptStore = new RelayReceiptStore(this.#db, this.#ctx.logger);
+        }
+        return this.#ctx.relayReceiptStore?.getAll(agentPubkeyHex, sessionIdHex) ?? [];
+    }
+    /**
+     * DOD-M15-REFUSEDEVIDENCE-1 — retain a message refused OUTSIDE `ingestReceivedContent`
+     * (`session-content-ingest.ts`).
+     *
+     * Review F6. The park drain terminally-blocks a message that arrived for an already-committed
+     * session, then confirm-deletes the relay copy — the one other route in the tree that discarded
+     * refused content, and the highest-suspicion combination in the product: hostile bytes aimed at a
+     * conversation somebody has already sealed. Shipped guidance now tells every operator that
+     * refused messages are kept, so this is made true rather than the promise narrowed.
+     *
+     * A thin delegate, not a second implementation: the bound, the dedup, the sequence allocation and
+     * the logging are the ones every other refusal uses.
+     */
+    quarantineRefusedInbound(agentName, sessionId, reason, content, contentHashHex, senderPubkeyHex, correlationId) {
+        return this.#ctx.refusals.quarantineRefusedContent(agentName, sessionId, reason, content, contentHashHex, {
+            senderPubkeyHex, correlationId,
+        });
+    }
+    /** The metadata half of a framed quarantine read — everything known ABOUT the message, none of it
+     *  taken from the message. Split out so the framing module never touches the database. */
+    quarantineFrameMeta(agentName, sessionId, rec) {
+        return {
+            reason: rec.reason,
+            senderPubkeyHex: rec.senderPubkeyHex,
+            senderLabel: rec.senderPubkeyHex === null ? null : this.#ctx.records.getContactMoniker(agentName, rec.senderPubkeyHex),
+            // `attribution` is the column that exists to answer exactly this, so it is read rather than
+            // inferred from `sender_sig` being non-null — a stored signature that was never checked
+            // against the sender's key would otherwise be reported as VERIFIED.
+            signature: rec.attribution === "verified_signature" ? "VERIFIED" : "NOT SIGNED",
+            sessionId,
+            position: rec.sequence,
+            arrivedAtMs: rec.createdAt,
+            /**
+             * The hash OF THE RETAINED BYTES, recomputed here — not the hash the sender committed to.
+             *
+             * On the highest-value case in the whole unit those two differ ON PURPOSE:
+             * `content_hash_mismatch` means the sender's committed hash does not describe these bytes.
+             * Printing their claim over our bytes would label the payload with a hash it does not have,
+             * which is the one thing a reader would use this line to check.
+             */
+            contentHashHex: Buffer.from(contentHashFor(rec.content, { alg: "sha256", salt: null })).toString("hex"),
+        };
+    }
+    /**
+     * The current standing receiver node's session-transport coordinates (peer id +
+     * listen multiaddrs), or null if it is not ready. These are the addresses a local
+     * SessionNegotiator advertises as this node's counterparty endpoint so the initiator
+     * can dial it, and the value an inbound session_assignment carries in its
+     * counterparty_session_* fields. Read-only — does NOT consume the standing receiver
+     * (unlike acceptSession, which hands it off).
+     */
+    /**
+     * 032-RELAYSPREAD — would this receiver ADMIT an inbound dial from this relay?
+     *
+     * The gater's inbound carve-out is the security-sensitive half of the spread: only relays whose
+     * own reservation is confirmed held earn it, so a directory that merely NAMES a relay cannot dial
+     * in behind the gate. Nothing could observe that from outside the manager, and the review found
+     * the consequence: substituting the CANDIDATE list for the held list at the `setReservedRelayPeers`
+     * call kept every test in the unit green while shipping exactly that hole. A guard whose wiring
+     * cannot be observed is a guard nothing can test.
+     *
+     * Reads the live gater rather than a copy, so it cannot drift from what the gate actually does.
+     */
+    isRelayCarvedOutInbound(agentName, relayPeerId) {
+        return this.#ctx.standingReceivers.get(agentName)?.gater.holdsInboundCarveOut(relayPeerId) ?? false;
+    }
+    /**
+     * M7 DOD-SPINE-6 / MSG-001-3b: connect a session node to the relay witness and
+     * store the client on the active entry. Best-effort: a connect/auth failure logs
+     * and leaves relayClient undefined — the session is NOT destroyed and the direct
+     * content path keeps working (the relay-park/recovery path is MSG-001-3b's domain).
+     *
+     * ⚠️ THIS BLOCK SPENT TWO MILESTONES ABOVE THE WRONG METHOD. It sat stacked on top of
+     * `relayLeafHandler`'s own docblock, so the file showed two descriptions in a row and the first
+     * one described a method further down the page. The content split then carried it verbatim into
+     * `session-content-ingest.ts`, where `connectSessionRelay` does not exist at all and the
+     * misattribution could no longer be worked out from context. Returned to the method it describes.
+     */
+    async connectSessionRelay(sessionId, node, agentName, relay, correlationId) {
+        try {
+            // The session node's gater admits only the counterparty; the relay witness is a
+            // third peer. Permit it OUTBOUND so the dial isn't denied — inbound stays
+            // counterparty-only (INV-5). The relay peer id comes from the signed assignment.
+            this.#ctx.activeNodes.get(this.#ctx.sessionKey(agentName, sessionId))?.gater.setAllowedOutboundPeer(relay.relayPeerId);
+            // One relay client per (AGENT, RELAY NODE). The relay keys by agent pubkey, so the
+            // collision H1 addresses is per relay; CELLO is federated, so a different session for
+            // the same agent may be assigned a DIFFERENT relay — that needs its own client.
+            const clientKey = `${agentName}::${relay.relayPeerId}`;
+            let client = this.#ctx.relayClients.get(clientKey);
+            if (!client) {
+                // RELAYSIG-1: one shared receipt store (keyed by agent_pubkey, so a single instance serves all
+                // agents + relays). Lazy — the encrypted DB is open by the time sessions are active.
+                if (!this.#ctx.relayReceiptStore && this.#db) {
+                    this.#ctx.relayReceiptStore = new RelayReceiptStore(this.#db, this.#ctx.logger);
+                }
+                // FED-OPTIONB-SEAL-001: one shared seal-leaf log (keyed by agent_pubkey), same lazy lifecycle.
+                if (!this.#ctx.sealLeafStore && this.#db)
+                    this.#ctx.sealLeafStore = new SessionSealLeafStore(this.#db, this.#ctx.logger);
+                if (!this.#ctx.sealLeafStore)
+                    this.#ctx.logger.error("session.relay.stores_absent", { agentName, sessionId, correlationId, impact: "no leaf record: this session cannot resume after a restart and keeps no seal evidence" });
+                client = new AgentRelayClient({
+                    relayPeerId: relay.relayPeerId,
+                    relayAddrs: relay.relayAddrs,
+                    keyProvider: relay.keyProvider,
+                    senderPubkey: relay.senderPubkey,
+                    logger: this.#ctx.logger,
+                    receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                    sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                    ownChainStore: this.#ctx.ownChainStore ?? undefined, // absent = own leaves not durably chained
+                    // DOD-M15-RELAYSLOTS-1: read at each auth, never snapshotted — the token expires hourly.
+                    onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+                    // DOD-M15-CORROBORATE-1: a relay's witness alert reaches the operator's inbox from here.
+                    // The DETACHED clients get the same callback from the builder in daemon.ts.
+                    onWitnessAlert: (alert) => { this.#ctx.witness.recordRelayWitnessAlert(agentName, alert); },
+                    onWitnessUnreadable: (relayPeerId, why) => { this.#ctx.records.recordRelayWitnessUnreadable(agentName, relayPeerId, why); },
+                });
+                this.#ctx.relayClients.set(clientKey, client);
+            }
+            const sessionIdHexForRelay = Buffer.from(relay.sessionIdBytes).toString("hex");
+            /**
+             * ⚠️ THE GENESIS IS WRITTEN BEFORE THE REGISTRATION, NOT AFTER — review F10.
+             *
+             * `#leafRecords.sessionGenesisPrevRoot` reads the entry's assignment first and the column second,
+             * and BOTH were still unset at this line: the entry's assignment is set below and the column
+             * is written below that. So the argument was always `undefined` here on a first attach, and
+             * the seed only survived because `registerSession` falls back to deriving one from the
+             * assignment it is handed. That is a dead argument standing next to a live fallback, which
+             * reads as deliberate and is the shape a later edit removes the wrong half of.
+             */
+            const entry = this.#ctx.activeNodes.get(this.#ctx.sessionKey(agentName, sessionId));
+            if (entry)
+                entry.relayAssignment = relay.assignment;
+            if (relay.assignment)
+                this.#ctx.leafRecords.persistGenesisPrevRoot(agentName, sessionId, relay.assignment);
+            client.registerSession(sessionIdHexForRelay, node, this.#ctx.contentIn.relayLeafHandler(agentName, sessionId, correlationId), relay.assignment, this.#ctx.leafRecords.sessionGenesisPrevRoot(agentName, sessionId), this.#ctx.leafRecords.sessionRelayAnchor(agentName, sessionId));
+            if (entry) {
+                entry.relayClient = client;
+                entry.relaySessionIdBytes = relay.sessionIdBytes;
+                entry.relayClientKey = clientKey;
+                // DOD-M15-AWAYSCOPE-1: the session just gained a relay, so tell it where this agent stands.
+                // The three attendance transitions fan out over sessions that already exist; this is the
+                // other direction — a session that arrives DURING an away stretch, which is exactly the
+                // case the order is about and the one the transitions cannot see.
+                client.announceAttendance(node, relay.sessionIdBytes, this.#ctx.currentAttendance(agentName));
+                // 2b: remember the relay endpoint so the content-park backstop deposits to the SAME relay.
+                entry.relayPeerId = relay.relayPeerId;
+                entry.relayAddrs = relay.relayAddrs;
+                // Review H1: the dial path needs the credential in hand, not just the endpoint.
+                // (Set above, before `registerSession`, so the genesis lookup it does has something to
+                // find — see the note there.)
+                // MSG-2 startup-flush: also PERSIST it, so a restart's crash-backstop flush (which runs
+                // before the in-memory entry exists) can deposit un-acked content to the same relay.
+                try {
+                    this.#db
+                        ?.prepare("UPDATE sessions SET relay_peer_id = ?, relay_addrs = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+                        .run(relay.relayPeerId, JSON.stringify(relay.relayAddrs), Date.now(), this.#ctx.requireAgentId(agentName), sessionId);
+                }
+                catch (err) {
+                    this.#ctx.logger.warn("session.relay.endpoint.persist.failed", {
+                        sessionId,
+                        error: extractErrorMessage(err),
+                    });
+                }
+            }
+            else {
+                // The session was torn down while we were wiring — undo the registration.
+                client.unregisterSession(sessionIdHexForRelay);
+                if (!client.hasSessions() && this.#ctx.relayClients.get(clientKey) === client) {
+                    client.close();
+                    this.#ctx.relayClients.delete(clientKey);
+                }
+                return;
+            }
+            // Proactively connect so the relay has this agent's stream to deliver leaves to
+            // (the RECEIVER must be connected before the counterparty submits). Best-effort.
+            await client.connect(node);
+            // DOD-M15-RELAYAUTH-1 review HIGH-2 — see below. Best-effort and non-blocking: a session must
+            // never fail to come up because a SECOND relay could not be told about it.
+            //
+            // Review M1: `.catch()` is not decoration. This is an unawaited promise, so a throw it does not
+            // handle is an unhandled rejection — and this file already carries a comment elsewhere about an
+            // absent `await` that became a remote process kill. The method's own try/catch does not cover
+            // its prologue, so the catch here is the only thing standing between a torn-down node and the
+            // daemon dying.
+            void this.#presentAssignmentToReservationRelay(agentName, node, relay, sessionIdHexForRelay, correlationId, entry)
+                .catch((err) => {
+                this.#ctx.logger.warn("session.relay.assignment.reservation_relay_failed", {
+                    agentName,
+                    sessionId: sessionIdHexForRelay.slice(0, 16),
+                    error: extractErrorMessage(err),
+                    impact: "inbound relayed dials to this node may be refused by its reservation relay; the session still works over the direct path and the park backstop",
+                    correlationId,
+                });
+            });
+        }
+        catch (err) {
+            this.#ctx.logger.warn("session.relay.connect.error", {
+                sessionId,
+                error: extractErrorMessage(err),
+                correlationId,
+            });
+        }
+    }
+    /**
+     * DOD-M15-RELAYAUTH-1 review HIGH-2 — **THE RELAY THAT GATES THE DIAL IS NOT ALWAYS THE RELAY
+     * THAT HOLDS THE ASSIGNMENT, AND THE GATE DENIES WHEN THEY DIFFER.**
+     *
+     * Two relays are in play for one session, chosen by unrelated rules:
+     *   - the WITNESS relay, `assignment.relay_endpoint`, picked by the directory. Both parties
+     *     present `client_record_assignment` to it and to nowhere else.
+     *   - the RESERVATION relay, whichever one this node's circuit address is held on — the first
+     *     candidate that granted when it was a standing receiver.
+     *
+     * The counterparty dials our CIRCUIT address, so it is the RESERVATION relay whose gater is asked
+     * `denyOutboundRelayedConnection(them, us)`. With no assignment recorded there it finds no binding
+     * and refuses a completely legitimate dial. Two relays run in production and the client's own
+     * logs show the fall-through to the second candidate is frequent, so this is the ordinary case,
+     * not a corner: the session still opens, but every message falls to the store-and-forward park
+     * path, and the only trace is a denial on a relay nobody is tailing.
+     *
+     * So the node that will be DIALLED presents the same assignment to the relay that will be asked
+     * to allow it. Safe by construction: the assignment is self-authenticating (a per-node directory
+     * signature the relay verifies against its consortium set), so presenting it more widely grants
+     * nothing that forging it would not already require. No directory change, no new frame.
+     */
+    async #presentAssignmentToReservationRelay(agentName, node, relay, sessionIdHex, correlationId, entry) {
+        // Review M1: the prologue below lives INSIDE the try. `listenAddresses()` on a node torn down
+        // while we were wiring is exactly the case handled 30 lines above at the caller, and out here it
+        // would have escaped both this method's catch and (before the caller's `.catch`) the process.
+        let reservationRelayPeerId;
+        try {
+            if (!relay.assignment)
+                return; // direct/legacy/persisted-reconnect: nothing to present anywhere
+            const heldCircuitAddr = node.listenAddresses().find((a) => a.includes("/p2p-circuit"));
+            if (!heldCircuitAddr)
+                return; // no reservation held → nobody will gate a dial to us
+            reservationRelayPeerId = /\/p2p\/([^/]+)\/p2p-circuit/.exec(heldCircuitAddr)?.[1];
+            if (!reservationRelayPeerId || reservationRelayPeerId === relay.relayPeerId)
+                return; // same relay — already recorded
+            const clientKey = `${agentName}::${reservationRelayPeerId}`;
+            let client = this.#ctx.relayClients.get(clientKey);
+            if (!client) {
+                if (!this.#ctx.relayReceiptStore && this.#db)
+                    this.#ctx.relayReceiptStore = new RelayReceiptStore(this.#db, this.#ctx.logger);
+                if (!this.#ctx.sealLeafStore && this.#db)
+                    this.#ctx.sealLeafStore = new SessionSealLeafStore(this.#db, this.#ctx.logger);
+                // Split on the marker, not an anchored strip: the held address is
+                // `…/p2p/<relay>/p2p-circuit/p2p/<self>`, so the marker is in the MIDDLE.
+                const baseRelayAddr = heldCircuitAddr.split("/p2p-circuit")[0] ?? heldCircuitAddr;
+                client = this.#ctx.detachedRelayClientBuilder?.(agentName, reservationRelayPeerId, [baseRelayAddr], {
+                    receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                    sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                    // DOD-M15-RELAYSLOTS-1: read at each auth, never snapshotted — the token expires hourly.
+                    onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+                });
+                if (!client)
+                    return;
+                this.#ctx.relayClients.set(clientKey, client);
+                // Review M4: record the key so teardown releases this client too — `relayClientKey` names
+                // only the witness relay, so before this the client and its session registration leaked.
+                if (entry)
+                    entry.extraRelayClientKeys = [...(entry.extraRelayClientKeys ?? []), clientKey];
+            }
+            // registerSession presents the assignment eagerly (see its own comment). No leaf handler: this
+            // relay is not witnessing the session, it only needs the binding that authorizes the dial.
+            // 033-ACKEMIT: no genesis is passed and none is needed. This client is not witnessing the
+            // session — it never submits — and `registerSession` derives a seed from the assignment
+            // anyway. Reaching into the session record for one — or for the ANCHOR (069-ORDERPROOF), which
+            // is why none is passed — reaches with the RELAY session id, not the key it is stored under.
+            client.registerSession(sessionIdHex, node, undefined, relay.assignment, undefined, undefined);
+            this.#ctx.logger.info("session.relay.assignment.presented_to_reservation_relay", {
+                agentName,
+                sessionId: sessionIdHex.slice(0, 16),
+                witnessRelayPeerId: relay.relayPeerId,
+                reservationRelayPeerId,
+                impact: "the relay that will be asked to allow inbound circuit dials to this node now holds the assignment authorizing them",
+                correlationId,
+            });
+        }
+        catch (err) {
+            this.#ctx.logger.warn("session.relay.assignment.reservation_relay_failed", {
+                agentName,
+                sessionId: sessionIdHex.slice(0, 16),
+                reservationRelayPeerId,
+                error: extractErrorMessage(err),
+                impact: "inbound relayed dials to this node may be refused by its reservation relay; the session still works over the direct path and the park backstop",
+                correlationId,
+            });
+        }
+    }
+    /**
+     * M7 DOD-SPINE-6 / MSG-001-3b: detach a session from its (agent, relay) client and
+     * close the client when it has no remaining sessions. Idempotent and identity-guarded:
+     * the map delete only fires if the map still holds THIS client (a racing teardown of a
+     * sibling session must not close a freshly-created replacement client for the same key).
+     */
+    detachSessionRelay(entry) {
+        const client = entry.relayClient;
+        const key = entry.relayClientKey;
+        if (!entry.relaySessionIdBytes)
+            return;
+        const sidHex = Buffer.from(entry.relaySessionIdBytes).toString("hex");
+        /**
+         * Review M4: release the EXTRA relay clients first — the ones opened to relays that gate circuit
+         * dials. `relayClientKey` above names only the witness relay, so these were registered and never
+         * unregistered: an authenticated relay stream and a `#sessions` entry leaked per session, and
+         * relay-side the dial-through binding they hold is then cleared only by the idle timer, which is
+         * now 24h. Runs before the early return below so it happens even for a session that never got a
+         * witness client.
+         */
+        for (const extraKey of entry.extraRelayClientKeys ?? []) {
+            const extra = this.#ctx.relayClients.get(extraKey);
+            if (!extra)
+                continue;
+            extra.unregisterSession(sidHex);
+            if (!extra.hasSessions()) {
+                extra.close();
+                this.#ctx.relayClients.delete(extraKey);
+            }
+        }
+        entry.extraRelayClientKeys = undefined;
+        if (!client)
+            return;
+        // Idempotent: clear the entry's reference so a second teardown of the same entry no-ops.
+        entry.relayClient = undefined;
+        client.unregisterSession(sidHex);
+        if (!client.hasSessions() && key && this.#ctx.relayClients.get(key) === client) {
+            client.close();
+            this.#ctx.relayClients.delete(key);
+        }
+    }
+    /**
+     * DOD-M15-RELAYAUTH-1 review H1 — **THE GATE WAS DENYING THE LEGITIMATE DIAL, AND USUALLY.**
+     *
+     * With the gater installed, a relay refuses a circuit dial unless it already holds a
+     * directory-signed assignment naming both transport peer ids. Both parties get that assignment
+     * from the directory independently, and until this method existed, each only presented it to
+     * relays IT had chosen — so whether a dial was allowed came down to which of two independent
+     * network races finished first:
+     *
+     *   1. WE connect to the witness relay, then dial the counterparty's circuit address. ~2 RTT.
+     *   2. THEY connect to their witness relay, then — unawaited, on a fresh dial + auth + record —
+     *      tell their RESERVATION relay about the session. ~3–4 RTT.
+     *
+     * Nothing sequenced (1) against (2), and (1) is shorter, so we usually arrived first and were
+     * refused. The session still opened and reported `transportMode: "relay"`, so the failure was
+     * invisible: every message for the life of that conversation quietly took the store-and-forward
+     * park path, and the only trace was a denial logged on a third machine nobody tails.
+     *
+     * The fix is to stop racing. Whoever is about to dial presents the assignment to the relay that
+     * will gate that dial, and WAITS for the relay to confirm it recorded it. The ordering becomes
+     * local to one thread of execution, so there is nothing left to lose.
+     *
+     * Safe by construction: we are a participant the assignment names, so the relay's own participant
+     * check passes; and the assignment is self-authenticating (a directory signature the relay
+     * verifies against its consortium set), so presenting it more widely grants nothing that forging
+     * it would not already require.
+     *
+     * Best-effort by design — a relay we cannot reach must not stop us from dialling. If the record
+     * fails we dial anyway: a dial that might be refused is strictly better than no dial.
+     */
+    async authorizeCircuitDialsToCounterparty(agentName, sessionId, entry, addrs) {
+        const assignment = entry.relayAssignment;
+        if (!assignment || !entry.relaySessionIdBytes)
+            return; // direct/legacy/persisted: no credential to present
+        const sessionIdHex = Buffer.from(entry.relaySessionIdBytes).toString("hex");
+        // One presentation per distinct relay, not per address: a counterparty commonly advertises
+        // several circuit addresses on the SAME relay.
+        const seen = new Set();
+        for (const addr of addrs) {
+            const relayPeerId = /\/p2p\/([^/]+)\/p2p-circuit/.exec(addr)?.[1];
+            if (!relayPeerId || seen.has(relayPeerId))
+                continue;
+            seen.add(relayPeerId);
+            // The witness relay already has it — registerSession presented it when the session was wired.
+            if (relayPeerId === entry.relayPeerId)
+                continue;
+            const baseRelayAddr = addr.split("/p2p-circuit")[0] ?? addr;
+            try {
+                const clientKey = `${agentName}::${relayPeerId}`;
+                let client = this.#ctx.relayClients.get(clientKey);
+                if (!client) {
+                    if (!this.#ctx.relayReceiptStore && this.#db)
+                        this.#ctx.relayReceiptStore = new RelayReceiptStore(this.#db, this.#ctx.logger);
+                    if (!this.#ctx.sealLeafStore && this.#db)
+                        this.#ctx.sealLeafStore = new SessionSealLeafStore(this.#db, this.#ctx.logger);
+                    client = this.#ctx.detachedRelayClientBuilder?.(agentName, relayPeerId, [baseRelayAddr], {
+                        receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                        sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                        // DOD-M15-RELAYSLOTS-1: read at each auth, never snapshotted — the token expires hourly.
+                        onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+                    });
+                    if (!client) {
+                        this.#ctx.logger.warn("session.transport.dial_authorization.no_builder", {
+                            sessionId,
+                            relayPeerId,
+                            impact: "cannot present the assignment to the relay that gates this dial; if the counterparty has not presented it either, the dial will be refused and every message will fall to the park path",
+                            correlationId: entry.correlationId,
+                        });
+                        continue;
+                    }
+                    this.#ctx.relayClients.set(clientKey, client);
+                    // Review M4: remember it so teardown releases it — this is a SECOND client for the
+                    // session, and detach only knows about the witness one.
+                    entry.extraRelayClientKeys = [...(entry.extraRelayClientKeys ?? []), clientKey];
+                }
+                // No leaf handler: this relay is not witnessing the session, it only needs the binding.
+                client.registerSession(sessionIdHex, entry.node, undefined, assignment, this.#ctx.leafRecords.sessionGenesisPrevRoot(agentName, sessionId), this.#ctx.leafRecords.sessionRelayAnchor(agentName, sessionId));
+                const recorded = await client.recordAssignmentAndWait(entry.node, sessionIdHex);
+                if (recorded) {
+                    this.#ctx.logger.info("session.transport.dial_authorized", {
+                        sessionId,
+                        relayPeerId,
+                        impact: "the relay that gates this circuit dial now holds the assignment authorizing it",
+                        correlationId: entry.correlationId,
+                    });
+                }
+                else {
+                    this.#ctx.logger.warn("session.transport.dial_authorization.not_recorded", {
+                        sessionId,
+                        relayPeerId,
+                        impact: "the relay did not confirm the assignment; the dial below may be refused and messages would fall to the park path",
+                        correlationId: entry.correlationId,
+                    });
+                }
+            }
+            catch (err) {
+                this.#ctx.logger.warn("session.transport.dial_authorization.failed", {
+                    sessionId,
+                    relayPeerId,
+                    error: extractErrorMessage(err),
+                    impact: "could not tell the relay that gates this dial about the session; the dial is attempted anyway",
+                    correlationId: entry.correlationId,
+                });
+            }
+        }
+    }
+    /**
+     * TEST-ONLY (M8C-INBOX-1 reviewer F1): buffer a received message + persist its transcript row,
+     * exactly as the real inbound path (appendVerifiedContent, in `session-content-ingest.ts`) does,
+     * WITHOUT standing up a session
+     * tree — so a test can drive a live cello_receive that advances the read watermark (the N3
+     * "delivery marks read" coupling). Only reachable via the CELLO_ENV=test IPC hook.
+     */
+    /** CELLO_ENV=test only: patch a relay client and session-id bytes onto an existing active node entry
+     *  so submitSealLeaf succeeds without a real relay handshake (used by the oneshot relay-path test). */
+    patchRelayClientForTest(agentName, sessionId, relayClient, relaySessionIdBytes, 
+    /**
+     * 069-ORDERPROOF: the session's assignment ANCHOR — the relay key the directory named, which
+     * every relay ordering attestation is verified against. Production puts it on the node entry
+     * when the session is created with a relay; a fixture that built its node without one supplies
+     * it here, or every submit is refused for want of an anchor and the fixture measures that
+     * refusal instead of whatever it was written for.
+     */
+    assignment) {
+        const entry = this.#ctx.activeNodes.get(this.#ctx.sessionKey(agentName, sessionId));
+        if (!entry)
+            throw new Error(`patchRelayClientForTest: no active node for (${agentName}, ${sessionId})`);
+        entry.relayClient = relayClient;
+        entry.relaySessionIdBytes = relaySessionIdBytes;
+        /**
+         * ⚠️ REGISTER THE SESSION TOO — the seam must leave the state production leaves.
+         *
+         * A relay client that has never been told about a session holds no starting point for it, and
+         * since `DOD-M15-SELFCHAIN-1` every submit on such a session is refused: there is nothing for
+         * the chain links to anchor to. Production always registers, because attaching a relay is what
+         * registration IS. A seam that attached the client and skipped the registration left fixtures
+         * exercising a refusal path, and the failure surfaced as "the seal never happened" in a test
+         * about away-mode replies.
+         */
+        relayClient.registerSession(Buffer.from(relaySessionIdBytes).toString("hex"), entry.node, undefined, entry.relayAssignment ?? assignment, this.#ctx.leafRecords.sessionGenesisPrevRoot(agentName, sessionId), this.#ctx.leafRecords.sessionRelayAnchor(agentName, sessionId) ?? assignment?.relayPubkeyHex);
+    }
+    /**
+     * M7-SESSION-001 AC-004/AC-005: Register a relay stream for an active session.
+     * Starts a background reader that watches for session_interrupted frames and
+     * stream close events. Both detection paths call markInterruptedWithDetails().
+     *
+     * The reader runs for the lifetime of the relay stream. If the stream closes
+     * without delivering a session_interrupted frame (AC-005 / 'stream_close' path),
+     * the session is still marked interrupted.
+     *
+     * @param sessionId The hex session ID
+     * @param stream The relay stream to monitor
+     * @param messageCount Number of message leaves at the time of registration
+     *   (used as the count at interruption — best effort since exact count at frame
+     *   receipt may differ, but this is the value available at stream setup time)
+     */
+    registerRelayStream(agentName, sessionId, stream, messageCount = 0) {
+        void this.#watchRelayStream(agentName, sessionId, stream, messageCount);
+    }
+    /**
+     * Background relay stream watcher.
+     * Pseudocode:
+     *   1. Create LP-framed iterator over the stream
+     *   2. For each frame:
+     *      a. If type === 'session_interrupted':
+     *         - Record receivedInterruptFrame = true
+     *         - Call markInterruptedWithDetails(sessionId, messageCount, 'relay_frame')
+     *         - Break (no more frames expected)
+     *   3. On stream close (loop ends normally or with error):
+     *      a. If !receivedInterruptFrame:
+     *         - Call markInterruptedWithDetails(sessionId, messageCount, 'stream_close')
+     */
+    async #watchRelayStream(agentName, sessionId, stream, messageCount) {
+        let receivedInterruptFrame = false;
+        // CELLO-M7-TRANSPORT-001: cast the stream input to lp.decode. Adding the
+        // @libp2p/autonat service (interface@3.2.2 / uint8arraylist v2) to the
+        // transport package surfaced a benign mixed-version split between the Stream
+        // type (now v2) and it-length-prefixed's expected Uint8ArrayList (v3). The two
+        // are structurally identical at runtime — this is a build-time-only artifact.
+        const lpSource = stream;
+        const source = lp.decode(lpSource)[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                let result;
+                try {
+                    result = await source.next();
+                }
+                catch {
+                    // Stream error (e.g. stream aborted) — treat as stream close
+                    break;
+                }
+                if (result.done || result.value === undefined)
+                    break;
+                let frame;
+                try {
+                    const bytes = result.value instanceof Uint8Array ? result.value
+                        : Buffer.isBuffer(result.value) ? new Uint8Array(result.value)
+                            : result.value.slice();
+                    frame = decode(bytes);
+                }
+                catch {
+                    continue;
+                }
+                if (frame["type"] === "session_interrupted") {
+                    // H-3 SECURITY: this stream is registered (bound) to a specific
+                    // sessionId. A malicious or buggy relay could put a DIFFERENT session_id
+                    // in the frame body to target a session this stream is not authorized
+                    // for (cross-session targeting). Never trust the frame's id: if the frame
+                    // names a different session, reject it and keep watching the bound one.
+                    const frameSessionId = typeof frame["session_id"] === "string"
+                        ? frame["session_id"]
+                        : (frame["session_id"] instanceof Uint8Array
+                            ? Buffer.from(frame["session_id"]).toString("hex")
+                            : null);
+                    if (frameSessionId !== null && frameSessionId !== sessionId) {
+                        this.#ctx.logger.warn("session.interrupt.frame.session_mismatch", {
+                            boundSessionId: sessionId,
+                            frameSessionId,
+                            reason: "cross_session_frame_rejected",
+                        });
+                        continue; // ignore the hostile/mismatched frame; keep reading
+                    }
+                    receivedInterruptFrame = true;
+                    // Always mark the BOUND sessionId — never the id carried in the frame.
+                    await this.#ctx.markInterruptedWithDetails(agentName, sessionId, messageCount, "relay_frame");
+                    break; // No more relay frames expected after session_interrupted
+                }
+            }
+        }
+        catch {
+            // Stream read loop ended — fall through to stream_close check
+        }
+        // AC-005: stream closed without a session_interrupted frame
+        if (!receivedInterruptFrame) {
+            // Only mark interrupted if this session is still active in SQLite
+            const record = this.#ctx.queries.getSessionRecord(agentName, sessionId);
+            if (record && record.status === "active") {
+                await this.#ctx.markInterruptedWithDetails(agentName, sessionId, messageCount, "stream_close");
+            }
+        }
+    }
+    /**
+     * DOD-NAT-REACHABILITY-1 (Phase 2): accept the directory's relay-pool endpoints
+     * for an agent (arrives with signaling_auth_ok, i.e. on every connect AND every
+     * reconnect). If the agent's standing receiver is up but holds NO reservation —
+     * the agent-online ensure raced ahead of auth_ok, or every relay was down at
+     * create time — rebuild it now so the agent becomes dialable without waiting
+     * for a session handoff that (being unreachable) would never come.
+     */
+    setDirectoryRelayEndpoints(agentName, endpoints) {
+        // DOD-M12B-RESERVATION-RETRY-1: a DIFFERENT relay pool re-arms the retry budget; the same one
+        // does not. This fires on every signaling connect AND reconnect, so clearing unconditionally
+        // would reset the bound on a short grid and defeat the whole point of having one. But once the
+        // budget is spent, `getStandingReceiverReachability` reports `unreachable` for the rest of the
+        // online episode — including while this path is actively re-attempting against relays we have
+        // never tried. A new relay is new information; a repeat of the same list is not.
+        const previous = this.#ctx.directoryRelayEndpoints.get(agentName);
+        const poolChanged = previous === undefined ||
+            previous.length !== endpoints.length ||
+            endpoints.some((e, i) => e.relayPeerId !== previous[i]?.relayPeerId);
+        this.#ctx.directoryRelayEndpoints.set(agentName, endpoints);
+        if (poolChanged) {
+            this.#ctx.srReservationRetry.delete(agentName);
+            this.#ctx.srLastRejectionReason.delete(agentName);
+        }
+        /**
+         * ⚠️ **ENDPOINTS ARRIVING NO LONGER REBUILD THE RECEIVER — 055-ONDEMAND.**
+         *
+         * This used to rebuild so the new node could reserve with the relays that had just been
+         * announced, because reservations were fixed at node creation and acquired at login. Neither is
+         * true now: nothing is reserved at login, and a running node can take one on demand.
+         *
+         * So a rebuild here would buy nothing and cost something real. The receiver it replaces may be
+         * holding the circuit a LIVE SESSION's counterparty was told to dial — throwing that away in
+         * response to a routine directory announcement would drop the route silently, at both ends.
+         *
+         * The endpoints are still recorded above, which is all they were ever needed for: they are the
+         * candidate list an offer reserves against.
+         */
+    }
+    /**
+     * Is this agent currently skipping this relay? The observable half of the failover decision — a
+     * test that asserts only on the classifier's boolean proves nothing about what the daemon does.
+     */
+    isRelayQuarantined(agentName, relayPeerId) {
+        return this.#relayQuarantineFor(agentName).has(relayPeerId);
+    }
+    /** Live quarantine entries for an agent, expired ones swept on read. */
+    #relayQuarantineFor(agentName) {
+        const byRelay = this.#ctx.relayQuarantine.get(agentName);
+        if (!byRelay)
+            return new Set();
+        const now = Date.now();
+        for (const [relayPeerId, expiresAt] of byRelay) {
+            if (now >= expiresAt)
+                byRelay.delete(relayPeerId);
+        }
+        if (byRelay.size === 0)
+            this.#ctx.relayQuarantine.delete(agentName);
+        return new Set(byRelay.keys());
+    }
+    /**
+     * Skip this relay for this agent for a while. Called only for refusals the classifier marks
+     * `tryAnotherRelay` — a fault of the relay's, not one that would follow us to the next one.
+     */
+    #quarantineRelay(agentName, relayPeerId, reason) {
+        let byRelay = this.#ctx.relayQuarantine.get(agentName);
+        if (!byRelay) {
+            byRelay = new Map();
+            this.#ctx.relayQuarantine.set(agentName, byRelay);
+        }
+        byRelay.set(relayPeerId, Date.now() + RELAY_QUARANTINE_MS);
+        this.#ctx.logger.warn("session.standing_receiver.relay_quarantined", {
+            agentName,
+            relayPeerId,
+            reason,
+            forMs: RELAY_QUARANTINE_MS,
+            impact: "this relay refused this agent for a fault of its own, so the agent will ask a " +
+                "different relay for its reservation until the quarantine lapses. Its inbound reachability " +
+                "is restored by moving, not by waiting for someone to fix that relay.",
+        });
+    }
+    reservationCircuitAddrs(agentName) {
+        let persisted;
+        try {
+            persisted = this.#ctx.queries.getAgentRelayEndpoints(agentName);
+        }
+        catch (err) {
+            // No DB / unknown agent — persisted source unavailable. The directory
+            // source may still serve; reachability degrades only if both are empty.
+            // Logged (not swallowed): a genuine DB failure must be distinguishable
+            // from "fresh agent, no history" in the reachability trail.
+            this.#ctx.logger.debug("session.standing_receiver.persisted_relays.unavailable", {
+                agentName,
+                error: extractErrorMessage(err),
+            });
+            persisted = [];
+        }
+        const merged = new Map(mergeRelayEndpoints(this.#ctx.directoryRelayEndpoints.get(agentName), persisted).map((ep) => [ep.relayPeerId, ep]));
+        /**
+         * DOD-M15-RELAYSLOTS-1 — **THE FAILOVER.** Skip relays that refused this agent for a fault of
+         * their own (today: a relay holding no directory public key, which can verify nobody and is
+         * refusing everyone). We run several relays precisely so one being broken is survivable.
+         *
+         * ⚠️ NEVER TO THE POINT OF HAVING NO RELAY AT ALL. If the quarantine would empty the candidate
+         * list it is ignored wholesale: a relay that refuses is strictly better than no relay, because
+         * the refusal at least has a cause the operator can read, while an agent with no candidates is
+         * simply unreachable with nothing to show for it. This is the same "refusing too eagerly is the
+         * failure mode" rule, applied to the client's own choice of where to ask.
+         */
+        const quarantined = this.#relayQuarantineFor(agentName);
+        const eligible = [...merged.values()].filter((ep) => !quarantined.has(ep.relayPeerId));
+        const usable = eligible.length > 0 ? eligible : [...merged.values()];
+        if (eligible.length === 0 && quarantined.size > 0 && merged.size > 0) {
+            this.#ctx.logger.warn("session.standing_receiver.relay_quarantine.ignored", {
+                agentName,
+                quarantined: [...quarantined],
+                impact: "every known relay has refused this agent for a relay-side fault, so the quarantine " +
+                    "is being ignored and they are all being tried again. A relay that refuses with a cause " +
+                    "is better than no relay at all — but if this persists, every relay this agent knows " +
+                    "about is misconfigured, and that is the thing to look at.",
+            });
+        }
+        const addrs = [];
+        const relayPeerIds = [];
+        for (const ep of usable) {
+            const base = ep.relayAddrs[0];
+            if (!base)
+                continue;
+            const candidate = base.includes("/p2p/")
+                ? `${base}/p2p-circuit`
+                : `${base}/p2p/${ep.relayPeerId}/p2p-circuit`;
+            // These addresses are built from DIRECTORY-supplied endpoints — data from off
+            // this machine. A malformed one throws inside libp2p node construction, which
+            // would take the standing receiver down entirely and leave the agent deaf to
+            // ALL inbound (worse than the defect this fixes). A bad endpoint must cost one
+            // relay, never the receiver.
+            if (!isValidMultiaddr(candidate)) {
+                this.#ctx.logger.warn("session.standing_receiver.relay_endpoint.invalid", {
+                    agentName,
+                    relayPeerId: ep.relayPeerId,
+                    addr: candidate,
+                });
+                continue;
+            }
+            addrs.push(candidate);
+            relayPeerIds.push(ep.relayPeerId);
+        }
+        return { addrs, relayPeerIds };
+    }
+    /**
+     * DOD-NAT-REACHABILITY-1: notice when a standing receiver has SILENTLY LOST its
+     * reservation, and get it another one.
+     *
+     * libp2p refreshes a circuit reservation before it expires. If the relay has died,
+     * that refresh fails and the /p2p-circuit address simply DISAPPEARS from the node's
+     * addresses. Nothing throws. The receiver is still up, still directly dialable, and
+     * still looks perfectly healthy — but no NAT'd peer can reach the agent any more.
+     * That is precisely the silent-loss-of-inbound failure this whole story exists to
+     * kill, so it cannot be left to chance: we watch for it and re-pick a relay.
+     *
+     * ⚠️ 056-SLOTDEAD: this paragraph used to end "Only receivers that HAD a reservation are watched.
+     * One that never got one is already degraded and already loud (reservation.none /
+     * reservation.timeout); rebuilding it on a timer would just thrash against relays we know are
+     * refusing." Every clause of that is now false — an idle receiver holds nothing BY DESIGN so
+     * "degraded" is the normal state, `reservation.none` is not emitted at build any more, and
+     * nothing rebuilds. What is watched is a receiver whose recorded set has shrunk, and what
+     * happens is a re-take in place for a LIVE session, never a rebuild.
+     */
+    /**
+     * DOD-M12B-RESERVATION-RETRY-1 / 055-ONDEMAND — is a re-attempt due, and claim it if so.
+     *
+     * ⚠️ **TWO DOC BLOCKS DESCRIBING `#retryReservationIfDue` USED TO SIT HERE — 056-SLOTDEAD, review
+     * F7.** That function is deleted. One of them said "the rebuild is the re-attempt … which is why
+     * it stays", so a reader following the comment landed on this function and concluded a rebuild
+     * ladder was still running. There is no rebuild anywhere in this file.
+     *
+     * What this does: a live session that lost its circuit re-takes it IN PLACE, on the node that
+     * already has the session, and this owns whether it is allowed to try yet. ONE ladder — a
+     * reservation is scarce, the relay holds it for its full TTL even after the client disconnects,
+     * and this file's own warning is that churning attempts across a fleet is how a relay is
+     * exhausted.
+     */
+    #retryDue(agentName) {
+        const now = Date.now();
+        const state = this.#ctx.srReservationRetry.get(agentName)
+            ?? { attempts: 0, nextAt: now + this.#ctx.srReservationRetryMs, correlationId: randomUUID() };
+        const lastReason = this.#ctx.srLastRejectionReason.get(agentName);
+        if (lastReason !== undefined)
+            state.lastReason = lastReason;
+        if (!this.#ctx.srReservationRetry.has(agentName)) {
+            // First sighting — schedule, do not fire. Something just tried.
+            this.#ctx.srReservationRetry.set(agentName, state);
+            return false;
+        }
+        if (now < state.nextAt)
+            return false;
+        if (state.attempts >= SR_RESERVATION_MAX_RETRIES) {
+            if (state.attempts === SR_RESERVATION_MAX_RETRIES) {
+                state.attempts += 1; // report once
+                this.#ctx.srReservationRetry.set(agentName, state);
+                this.#ctx.logger.error("session.standing_receiver.reservation.gave_up", {
+                    agentName,
+                    attempts: SR_RESERVATION_MAX_RETRIES,
+                    correlationId: state.correlationId,
+                    // WHY, not just the consequence. Three different problems reach this one message and they
+                    // need three different responses: `relay_granted_no_reservation` is relay CAPACITY (and a
+                    // trustless-cello problem), `relay_unreachable` is the NETWORK, and
+                    // `reservation_did_not_complete_in_time` is LATENCY.
+                    ...(state.lastReason !== undefined ? { lastRejectionReason: state.lastReason } : {}),
+                    /**
+                     * ⚠️ **THESE TWO CAME BACK — 056-SLOTDEAD, review F9.** The deleted emitter of this SAME
+                     * event name carried them; the surviving one did not, so the fields quietly vanished from
+                     * an operator's view while the event kept appearing.
+                     *
+                     * "No relay would grant" and "there was no relay to ask" are different facts that lead to
+                     * different places — the first at relay capacity, the second at this agent's directory
+                     * connection. Without them they are the same sentence.
+                     *
+                     * `hadRelayToAsk` reads the directory pool alone; `relaysOffered` is the merged,
+                     * quarantine-filtered candidate list the re-take actually walks. Two populations, so two
+                     * names — the mis-naming that made `reservationsRequested` unreadable is the reason this
+                     * note exists.
+                     */
+                    hadRelayToAsk: (this.#ctx.directoryRelayEndpoints.get(agentName)?.length ?? 0) > 0,
+                    relaysOffered: this.reservationCircuitAddrs(agentName).addrs.length,
+                    impact: "a live session lost the circuit its counterparty dials, and no relay would give " +
+                        "it back inside the retry budget. Messages still reach this agent through the relay's " +
+                        "store-and-forward; a direct dial to it will not connect until the session is rebuilt.",
+                });
+            }
+            return false;
+        }
+        state.attempts += 1;
+        // Doubling, floored at the configured interval. 056-SLOTDEAD: this said "the same shape the
+        // rebuild ladder uses" — there is no rebuild ladder any more, this IS the ladder. The reason is
+        // unchanged: a fixed short interval is what exhausts a relay.
+        state.nextAt = now + this.#ctx.srReservationRetryMs * Math.pow(2, state.attempts - 1);
+        this.#ctx.srReservationRetry.set(agentName, state);
+        this.#ctx.logger.info("session.standing_receiver.reservation.retry", {
+            agentName, attempts: state.attempts, correlationId: state.correlationId,
+        });
+        return true;
+    }
+    async #reservationWatchdogTick() {
+        if (this.#ctx.shuttingDown)
+            return;
+        for (const [agentName, sr] of this.#ctx.standingReceivers) {
+            if (!this.#ctx.agentsWantingReceiver.has(agentName))
+                continue; // agent went offline
+            // DOD-M12B-RESERVATION-RETRY-1 — NEVER HAD ONE IS NOT "NOTHING TO DO".
+            //
+            // This used to `continue` unconditionally, on the grounds that a receiver with no reservation
+            // is "already degraded and already loud". Measured over 17 days: `reservation.none` fired 481
+            // times and `relay.rejected` 2,215 — every one of the latter `relay_granted_no_reservation`,
+            // a relay out of slots completing the handshake and granting nothing. Nothing ever acted on
+            // the noise, and each of those receivers is a plain TCP node with no circuit address: behind
+            // NAT, dialable by NOBODY, for its whole life. That is the silent loss of inbound this file
+            // says three lines below it exists to kill.
+            //
+            // A relay out of slots at boot may have one minutes later, so re-attempt — on a BACKOFF and
+            // BOUNDED, never on this 30-second grid. A reservation is scarce: the relay holds it for its
+            // full TTL even after the client disconnects, and churning attempts across a fleet is how a
+            // relay is exhausted (`#startReceiverNode` records that hazard).
+            if (sr.relayPeerIds.length === 0) {
+                /**
+                 * ⚠️ **AN IDLE AGENT HOLDING NOTHING IS THE DESIGN NOW, NOT A DEGRADATION — 055-ONDEMAND.**
+                 *
+                 * Everything above this line was written when a receiver reserved at login and holding zero
+                 * meant an agent dialable by nobody for its whole life. A reservation is taken at OFFER time
+                 * now and given back at the seal, so zero is the correct steady state for an agent nobody is
+                 * calling — and retrying here would have every idle agent in the fleet asking relays for
+                 * slots the design says it must not hold. That is the exact churn the note below warns
+                 * about, pointed at the whole fleet instead of one receiver.
+                 *
+                 * The retry still matters for an agent that HAS a live session and lost the circuit that
+                 * session depends on, which is what the condition now says.
+                 */
+                const liveSessions = [...this.#ctx.activeNodes.values()].filter((e) => e.agentName === agentName);
+                if (liveSessions.length === 0) {
+                    /**
+                     * ⚠️ **AN AGENT WITH NO SESSION HAS NOTHING TO RETRY, SO IT MUST NOT LOOK LIKE IT DOES —
+                     * `DOD-M15-IDLERETRY-1`, second half.**
+                     *
+                     * 061 stopped the ladder being OPENED for a session that needs nothing. It did not clear
+                     * one that was legitimately opened and is now moot. A ladder exists to get a LIVE session
+                     * its circuit back; when that session ends there is nothing left to get, and the entry is
+                     * the only thing `getStandingReceiverReachability` consults — so a perfectly idle agent
+                     * went on reporting `retrying`, and eventually `unreachable`, until the daemon restarted.
+                     *
+                     * Observed on the shipped 0.0.217 build: an agent with no live session at all, reading
+                     * `retrying`. That can only happen through a stale entry, which is what sent this back for
+                     * a second pass.
+                     *
+                     * Cleared HERE rather than at teardown on purpose: this is the one place that already
+                     * knows, every tick, that an agent holds nothing and wants nothing. A teardown hook would
+                     * be a second thing to keep in step with session lifecycle, and the whole class of defect
+                     * in this file is two things drifting apart.
+                     */
+                    this.#ctx.srReservationRetry.delete(agentName);
+                    this.#ctx.srLastRejectionReason.delete(agentName);
+                    continue;
+                }
+                /**
+                 * ⚠️ **RE-TAKE THE SESSION'S CIRCUIT — REBUILDING THE RECEIVER NO LONGER DOES IT.**
+                 *
+                 * `#retryReservationIfDue` rebuilds the receiver, and a rebuilt receiver reserves NOTHING
+                 * (055-ONDEMAND). So on its own the retry ladder became a no-op by construction: a relay
+                 * that flapped mid-session would leave that session permanently un-dialable while the
+                 * ladder churned receivers to no effect.
+                 *
+                 * The circuit a live session needs is the one its ASSIGNMENT named, which is persisted with
+                 * the session — so ask for that one back, rather than rebuilding and hoping.
+                 */
+                /**
+                 * ⚠️ **ON THE SAME BUDGET AND BACKOFF AS THE LADDER IT REPLACES.** A reservation is scarce:
+                 * the relay holds it for its full TTL even after the client disconnects, and this file's own
+                 * warning is that churning attempts across a fleet is how a relay is exhausted. Asking on
+                 * every 30-second tick would be exactly that churn, wearing a new name — measured here as 52
+                 * asks where the budget allows 37.
+                 */
+                /**
+                 * ⚠️ **WHAT ACTUALLY NEEDS A CIRCUIT, DECIDED BEFORE THE BUDGET IS TOUCHED —
+                 * `DOD-M15-IDLERETRY-1`.**
+                 *
+                 * `#retryDue` was called FIRST, and it does not merely answer a question: on an agent it has
+                 * not seen before it WRITES a retry entry and returns false. So simply having a live session
+                 * while holding no circuit was enough to open a retry ladder — and for the INITIATOR of a
+                 * call that state is permanent and wrong, because an initiator DIALS OUT and never needs to
+                 * be dialable (055-ONDEMAND narrowed the reservation to the party being dialed, deliberately).
+                 *
+                 * Two things followed, and both were measured live on 2026-09-11 rather than reasoned:
+                 *   - `cello_status` reported `retrying` for a healthy agent from its first call onward,
+                 *     cleared only by a daemon restart — the same "a broken agent looks like a fine one"
+                 *     defect 060-READY had just fixed, in a case it did not cover;
+                 *   - worse, it is not cosmetic. Held past the retry interval, both agents emitted a real
+                 *     `session.standing_receiver.reservation.retry` — the daemon asking relays for slots on
+                 *     behalf of sessions that need none. That is churn against the scarce resource this
+                 *     whole story exists to conserve.
+                 *
+                 * So the question "is there anything to re-take?" is answered from the SESSION NODES first.
+                 * A session that already holds its circuit, or has no relay endpoint recorded, needs
+                 * nothing. If none needs anything, this tick is a no-op and must leave no trace.
+                 */
+                const needRetake = liveSessions.filter((entry) => {
+                    const ep = this.#ctx.queries.getPersistedRelayEndpoint(agentName, entry.sessionId);
+                    if (!ep || ep.relayAddrs.length === 0)
+                        return false;
+                    /**
+                     * ⚠️ `heldRelayIdsOf`, NOT a substring test — the same distinction 056-SLOTDEAD had to
+                     * make one layer up. A circuit address that does not NAME its relay cannot be dialled
+                     * through, so a session announcing one holds nothing usable and DOES need a re-take.
+                     * A substring test counts it as held and leaves that session silently unreachable.
+                     */
+                    return heldRelayIdsOf(entry.node).length === 0;
+                });
+                if (needRetake.length === 0)
+                    continue;
+                if (!this.#retryDue(agentName))
+                    continue;
+                /**
+                 * ⚠️ **ON THE SESSION'S OWN NODE, NOT THE IDLE RECEIVER — and the first version got this
+                 * wrong in a way that was worse than doing nothing.**
+                 *
+                 * It called the take path, which reserves on `standingReceivers.get(agentName).node`. That
+                 * is the fresh receiver built after the promotion — a DIFFERENT peer id from the one the
+                 * counterparty was told to dial. So the circuit it obtained helped no one, and it made an
+                 * IDLE receiver hold a relay slot, which is the exact thing this unit exists to stop. It
+                 * also set `relayPeerIds` non-empty, hiding the real loss from every later tick.
+                 */
+                let retook = false;
+                for (const entry of needRetake) {
+                    const ep = this.#ctx.queries.getPersistedRelayEndpoint(agentName, entry.sessionId);
+                    const base = ep.relayAddrs[0];
+                    const circuitAddr = base.includes(`/p2p/${ep.relayPeerId}`) ? `${base}/p2p-circuit` : `${base}/p2p/${ep.relayPeerId}/p2p-circuit`;
+                    if (await this.#ctx.retakeReservationOn(agentName, entry.node, circuitAddr, entry.correlationId))
+                        retook = true;
+                }
+                if (retook)
+                    continue;
+                // …unless one has arrived since. Review F4, same class as the recompute below: the
+                // slow-start path installs a receiver before every circuit has bound, so "held nothing at
+                // install" is not the same fact as "holds nothing now". Adopting it here is what stops the
+                // retry ladder rebuilding a receiver that is already reachable.
+                const arrived = heldRelayIdsOf(sr.node)
+                    .filter((id) => sr.node.getConnections().some((c) => c.peerId === id && c.status === "open"));
+                if (arrived.length === 0) {
+                    /**
+                     * ⚠️ **`#retryReservationIfDue` WAS CALLED HERE AND COULD NEVER DO ANYTHING — 056-SLOTDEAD.**
+                     *
+                     * It guards on `now < state.nextAt`, and `#retryDue` above advances that same state on
+                     * this very tick, so the second call always returned immediately. Reachable, referenced,
+                     * and inert — the shape a reference scan cannot find.
+                     *
+                     * *(The first version of this order claimed it DOUBLE-ADVANCED the budget and triggered a
+                     * useless rebuild. That was wrong, and it was wrong because it was reasoned rather than
+                     * run. It was a no-op.)*
+                     *
+                     * Nothing replaces it: `#retryDue` owns the budget and the re-take above owns the work.
+                     */
+                    continue;
+                }
+                sr.relayPeerIds = arrived;
+                sr.gater.setReservedRelayPeers(arrived);
+                this.#ctx.logger.info("session.standing_receiver.reservation.gained", {
+                    agentName,
+                    relayPeerIds: arrived,
+                    reservationsHeld: arrived.length,
+                });
+            }
+            // It has at least one — any earlier retry budget, and the reason the last attempt failed, are
+            // stale.
+            this.#ctx.srReservationRetry.delete(agentName);
+            this.#ctx.srLastRejectionReason.delete(agentName);
+            // Watch the CONNECTION to the relay, not the circuit address.
+            //
+            // Killing the relay does NOT make the /p2p-circuit address disappear: libp2p
+            // keeps the listen address until the reservation's own refresh, up to two hours
+            // away. Watching the address would therefore miss a dead relay for hours — the
+            // agent would advertise a circuit address that routes through a relay that no
+            // longer exists, which is exactly the silent unreachability we are hunting. The
+            // live connection to the relay is the honest signal: no connection, no relay,
+            // no reservation.
+            //
+            // AND IT MUST BE OPEN. `getConnections()` returns libp2p's registry, which keeps a connection
+            // listed while it is closing and after its muxer has died — the state the whole M12 Tier P5
+            // investigation turned on. Without the status check a registered corpse reads as "still
+            // connected", the rebuild never fires, and the agent silently stops being reachable while
+            // this loop reports it healthy. The comment above claimed liveness; only this tests it.
+            // 032-RELAYSPREAD — PER RELAY, and the health question is now a COUNT.
+            //
+            // This used to evaluate one peer id and rebuild the entire standing receiver when it went
+            // false. With a pool of one that was the only thing it could do; with a pool of three it is
+            // the churn engine — every relay is another watchdog subject, and a full rebuild per loss
+            // multiplies the 30-second grid by the size of the pool while throwing away reservations that
+            // are perfectly healthy.
+            /**
+             * RECOMPUTED FROM THE NODE, never filtered down from the stored list. Review F4: filtering
+             * `sr.relayPeerIds` makes it SHRINK-ONLY, and a list that can only shrink cannot see a
+             * circuit arrive. Three things went wrong with that, and the first one happens routinely:
+             *   - the slow-start path installs the receiver before every circuit has bound, so a relay
+             *     that binds four seconds later was invisible to this watchdog and absent from the
+             *     gater's carve-out set FOREVER — its AutoNAT probe reply refused by our own gate;
+             *   - shrinking to zero then rebuilt a receiver that was announcing live circuits, which is
+             *     the exact defect this unit is against;
+             *   - anything that ever restores a circuit could not be counted.
+             * Reading the node's own addresses costs the same and has none of that.
+             */
+            const open = sr.node.getConnections().filter((c) => c.status === "open").map((c) => c.peerId);
+            const stillHeld = heldRelayIdsOf(sr.node).filter((id) => open.includes(id));
+            const lost = sr.relayPeerIds.filter((id) => !stillHeld.includes(id));
+            const gained = stillHeld.filter((id) => !sr.relayPeerIds.includes(id));
+            sr.relayPeerIds = stillHeld;
+            if (gained.length > 0) {
+                // A circuit this receiver did not have at install. Said out loud because it is the visible
+                // half of the slow-start case, and because it is the moment that relay earns its inbound
+                // carve-out — a silent widening of the gate is not something to do without a line.
+                this.#ctx.logger.info("session.standing_receiver.reservation.gained", {
+                    agentName,
+                    relayPeerIds: gained,
+                    reservationsHeld: stillHeld.length,
+                });
+            }
+            if (lost.length === 0) {
+                // Nothing lost. The gater still gets the current set, because `gained` may have widened it.
+                if (gained.length > 0)
+                    sr.gater.setReservedRelayPeers(stillHeld);
+                continue;
+            }
+            // REVOKE FIRST. A relay whose reservation is gone must lose its inbound carve-out in the same
+            // breath as the loss is noticed, or the gater's bound quietly becomes "granted one once".
+            sr.gater.setReservedRelayPeers(stillHeld);
+            for (const relayPeerId of lost) {
+                // DOD-RELAY-KEEPALIVE-1 (review F4): carry the CAUSE, not just the exit point.
+                // `relay_connection_gone` says where this was noticed — a poll of getConnections() — by
+                // which time the abort reason that actually killed the link is long discarded. The relay
+                // client for this (agent, relay) pair kept the error that ended its reader; that is the
+                // nearest thing to an upstream cause available here, and its absence is how 2,061 of these
+                // went untraced.
+                /**
+                 * ⚠️ **A DIAGNOSTIC MUST NOT BE ABLE TO KILL THE WATCHDOG TICK.** This is optional-chained on
+                 * the map lookup but the METHOD was called unguarded, so a client without it threw — an
+                 * unhandled rejection inside the tick, which takes the rest of the sweep with it. Surfaced
+                 * when 055-ONDEMAND made this branch reachable in more cases. The cause line is worth
+                 * having; it is not worth the loss detection it rides on.
+                 */
+                const client = this.#ctx.relayClients.get(`${agentName}::${relayPeerId}`);
+                const upstreamReason = typeof client?.getLastReaderError === "function" ? client.getLastReaderError() : null;
+                this.#ctx.logger.warn("session.standing_receiver.reservation.lost", {
+                    agentName,
+                    relayPeerId,
+                    reason: open.includes(relayPeerId) ? "circuit_address_vanished" : "relay_connection_gone",
+                    ...(upstreamReason ? { upstreamReason } : {}),
+                    reservationsHeld: stillHeld.length,
+                    /**
+                     * The line an operator reads, and the two cases are not the same event at all.
+                     *
+                     * ⚠️ **THE ZERO CASE PROMISED A REPAIR THAT NO LONGER HAPPENS — 056-SLOTDEAD, review F3.**
+                     * It ended "The receiver is being rebuilt against the rest of the pool", which was true
+                     * when this branch rebuilt. Nothing rebuilds now. An operator reading the old line would
+                     * wait for a recovery that was never coming, and the only thing that WOULD have told them
+                     * otherwise is a `zero_held` line at debug level they are not reading. Both branches now
+                     * say what actually happens next and who owns it.
+                     */
+                    impact: stillHeld.length > 0
+                        ? "this agent still holds " + stillHeld.length + " other circuit reservation(s), so it "
+                            + "stays dialable from behind NAT. Losing one relay costs this agent nothing it can feel."
+                        : "this agent now holds NO circuit reservation. If it has no live session that is the "
+                            + "normal idle state and costs nothing — a slot is taken when someone calls. If it "
+                            + "DOES have a live session, that session's counterparty can no longer dial it, and "
+                            + "the re-take above is what gets it back, on a bounded budget. Nothing rebuilds the "
+                            + "receiver any more, so do not wait for one.",
+                });
+            }
+            /**
+             * ⚠️ **DRAIN ON THE LOSS ITSELF — 056-SLOTDEAD.** This used to happen one step downstream, as
+             * a side effect of the rebuild below: lose every reservation → rebuild → the new receiver
+             * reports ready → drain. Deleting the rebuild would have deleted the drain with it, leaving
+             * content the counterparty parked to sit until the periodic backstop. The loss is the cause
+             * and always was; the rebuild was only where it happened to be noticed.
+             */
+            this.#ctx.park.fireParkedDrain(agentName, "reservation_lost");
+            if (stillHeld.length === 0) {
+                /**
+                 * ⚠️ **THIS REBUILT THE RECEIVER ON A JUSTIFICATION THAT STOPPED BEING TRUE IN UNIT 1, AND
+                 * UNDER ON-DEMAND IT DESTROYS AN IN-FLIGHT OFFER'S RESERVATION — 056-SLOTDEAD.**
+                 *
+                 * It read: *"only a new node can take a new reservation, because a circuit listener is fixed
+                 * at node creation."* `listenOnCircuit` removed that constraint (`DOD-M15-RELAYPROVE-ORDER-1`),
+                 * and a rebuilt receiver now reserves nothing at all.
+                 *
+                 * The state it fires in is the dangerous one: between an offer taking a reservation and the
+                 * session being created, the receiver holds exactly one circuit. Lose the connection in that
+                 * window and this rebuilt the node — discarding the slot the offer just took, after the
+                 * accept may already have advertised it. **Observed**, not reasoned: a fixture that reported
+                 * no relay connection drove this path and the test caught the rebuild.
+                 *
+                 * Nothing replaces it here. An idle agent holding zero is the design; a LIVE session that
+                 * lost its circuit is re-taken on its own node by the branch above, on a bounded budget.
+                 */
+                this.#ctx.logger.debug("session.standing_receiver.reservation.zero_held", {
+                    agentName,
+                    impact: "this agent holds no circuit. If it has no live session that is the idle steady " +
+                        "state; if it does, the re-take above owns getting it back.",
+                });
+                continue;
+            }
+        }
+    }
+    /** Start the reservation watchdog (idempotent). Stopped by gracefulShutdown. */
+    startReservationWatchdog() {
+        if (this.#ctx.reservationWatchdog !== null)
+            return;
+        // Arm the backstop clock from the START of watching, not from the epoch — otherwise the first
+        // tick always fires a sweep on top of the install drain that just ran.
+        this.#ctx.park.armBackstopClock(Date.now());
+        this.#ctx.reservationWatchdog = setInterval(() => {
+            try {
+                void this.#reservationWatchdogTick();
+                this.#ctx.park.parkedDrainBackstopTick(Date.now());
+            }
+            catch (err) {
+                this.#ctx.logger.warn("session.standing_receiver.watchdog.failed", { error: extractErrorMessage(err) });
+            }
+        }, this.#ctx.srWatchdogIntervalMs);
+        // Never hold the process open on account of the watchdog.
+        this.#ctx.reservationWatchdog.unref?.();
+    }
+    /**
+     * Start the standing receiver's libp2p node, holding a circuit-relay reservation
+     * if one can be had — and WITHOUT one if it cannot.
+     *
+     * THE INVARIANT, learned live: **standing-receiver creation must NEVER be gated on
+     * a relay.** libp2p's circuit listener awaits a live connection to its relay before
+     * start() resolves, and it does not time out. A relay that does not answer parks
+     * start() forever: no created event, no failure, no retry, no alarm — the agent
+     * simply has no receiver and is deaf to ALL inbound, including the direct path that
+     * worked before reservations existed. Strictly worse than the NAT defect this whole
+     * line exists to fix. So every attempt is raced against a deadline, and failure
+     * ALWAYS falls through to a plain TCP receiver.
+     *
+     * ONE relay, tried on the REAL node — not a probe.
+     *
+     * A relay reservation is a scarce resource: the relay holds it for its full TTL
+     * even after the client disconnects, and it has a finite number of slots. An
+     * earlier design probed each relay on a throwaway node and then reserved AGAIN on
+     * the receiver — burning TWO slots per agent to get one, and leaving the throwaway's
+     * slot pinned for hours. That is how a fleet exhausts a relay. Here the receiver
+     * itself makes the attempt: if the relay grants the reservation, we KEEP that node.
+     * One slot per agent, which is the true cost.
+     *
+     * Candidates are tried in order (directory pool first). The first that actually
+     * grants a reservation wins; the rest are never touched.
+     */
+    /**
+     * DOD-M15-RELAYSLOTS-1 — tell the relay this transport identity belongs to a registered agent, so
+     * the reservation it just refused is granted on the next attempt.
+     *
+     * Returns `"proven"` on success, or the shape of the failure so the candidate loop can act on it.
+     * It never throws: throwing would turn one unreachable relay into a failure to build a receiver
+     * at all.
+     *
+     * ─── Why this returns a verdict instead of a boolean ──────────────────────────────────────────
+     *
+     * Review HIGH-1/HIGH-2. Putting the reservation behind a proof MOVED THE FIRST REFUSAL onto this
+     * path. `authenticateStandingReceiver` does everything right with a refusal — records it where
+     * `cello_status` can read it, and quarantines a relay whose fault is its own — but it runs only
+     * on a receiver that ALREADY HAS a reservation, so under the new gate a total failure never
+     * reaches it. This method was logging `proven: false` and returning.
+     *
+     * What that cost the operator: an expired token, or an agent at its slot cap, refused by every
+     * relay in the pool. `cello_status` shows an agent that is online and reachable by nobody, with
+     * no cause anywhere the person will look — while the relay had computed the cause, the count, and
+     * the next step, and put them on the wire. And `slot_cap_exceeded` is classified
+     * `tryAnotherRelay: false` precisely so the client STOPS walking the fleet; without the verdict,
+     * the loop walked it anyway, turning one client-side fault into what reads as a fleet outage.
+     */
+    /**
+     * 055-ONDEMAND — **tell the relay this agent has finished with its slot.**
+     *
+     * The only thing that actually frees one: closing a circuit listener sends the relay nothing, and
+     * the relay reclaims on its own only at the reservation TTL (two hours) or under reaper pressure.
+     * Best-effort by design — an undelivered release costs a slot until that TTL, and must never fail
+     * the seal that triggered it.
+     */
+    async tellRelayReleased(agentName, relayPeerId, node, correlationId) {
+        /**
+         * ⚠️ **THE NODE IS THE SOURCE OF TRUTH FOR WHERE THIS RELAY IS — review MEDIUM-6.**
+         *
+         * The first version looked the relay up in `directoryRelayEndpoints`. But the reservation was
+         * taken on the relay the OFFER named, whose addresses came off that frame; if the directory's
+         * last announcement does not contain it — a pool relay dropped from the roster, a stale
+         * announcement — the release warns `no_endpoint` and the slot is held to its TTL. The node
+         * announces the circuit it actually holds, so derive the address from that and fall back to the
+         * directory list only when there is nothing to derive from.
+         */
+        const fromNode = node.listenAddresses()
+            .filter((a) => a.split("/").includes("p2p-circuit") && a.includes(`/p2p/${relayPeerId}/`))
+            .map((a) => a.split("/p2p-circuit")[0])
+            .filter((a) => a.length > 0);
+        const ep = this.#ctx.directoryRelayEndpoints.get(agentName)?.find((e) => e.relayPeerId === relayPeerId);
+        const relayAddrs = fromNode.length > 0 ? [...new Set(fromNode)] : (ep ? [...ep.relayAddrs] : []);
+        if (relayAddrs.length === 0) {
+            this.#ctx.logger.warn("session.relay.reservation_release.no_endpoint", {
+                agentName, relayPeerId, correlationId,
+                impact: "no address is known for this relay, so it cannot be told the slot is free and " +
+                    "holds it until the reservation TTL expires.",
+            });
+            return;
+        }
+        let client;
+        try {
+            client = this.#ctx.detachedRelayClientBuilder?.(agentName, relayPeerId, relayAddrs, {
+                receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+            });
+            if (!client)
+                return;
+            await client.releaseReservation(node);
+        }
+        catch (err) {
+            this.#ctx.logger.warn("session.relay.reservation_release.failed", {
+                agentName, relayPeerId, correlationId,
+                error: extractErrorMessage(err),
+                impact: "the relay holds this slot until its TTL expires.",
+            });
+        }
+        finally {
+            client?.close();
+        }
+    }
+    async proveToRelay(agentName, circuitAddr, node, correlationId, 
+    /**
+     * Whether this proof is the STANDING RECEIVER's, and may therefore write the surface
+     * `cello_status` reads as "your standing receiver was refused".
+     *
+     * A revival proves itself too, and its refusal is real — but it is not evidence about the
+     * receiver. A receiver that proved thirty seconds ago and holds a slot, plus a revival refused
+     * with `slot_cap_exceeded`, would otherwise have `cello_status` report a front door as refused
+     * while it is open. The refusal is still logged and still steers the candidate loop; what it
+     * does not do is claim to be about something it did not measure.
+     */
+    surfaceAsReceiverRefusal) {
+        const relayPeerId = relayPeerIdOf(circuitAddr);
+        const baseRelayAddr = circuitAddr.split("/p2p-circuit")[0];
+        if (!relayPeerId || !baseRelayAddr) {
+            this.#ctx.logger.warn("session.standing_receiver.prove.address_unreadable", {
+                agentName,
+                circuitAddr,
+                correlationId,
+                impact: "this candidate's circuit address does not name a relay peer, so there is nothing " +
+                    "to prove to and its reservation will stay refused. Skipped silently before — which made " +
+                    "a malformed address look identical to a relay that simply said no.",
+            });
+            return "unavailable";
+        }
+        /**
+         * Declared out here so the `finally` can close it. Scoped inside the `try` before, so a throw
+         * from `proveReservation` skipped the close and left the stream and its pending settles behind.
+         */
+        let client;
+        try {
+            client = this.#ctx.detachedRelayClientBuilder?.(agentName, relayPeerId, [baseRelayAddr], {
+                receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+            });
+            if (!client) {
+                this.#ctx.logger.warn("session.standing_receiver.prove.no_builder", {
+                    agentName,
+                    relayPeerId,
+                    correlationId,
+                    impact: "no relay client could be built, so this receiver cannot prove itself and the " +
+                        "relay will refuse its reservation again. The agent is reachable only over a direct " +
+                        "connection until this is wired.",
+                });
+                return "unavailable";
+            }
+            const proven = await client.proveReservation(node);
+            if (proven) {
+                if (surfaceAsReceiverRefusal)
+                    this.#ctx.srRelayRefusal.delete(agentName);
+                this.#ctx.logger.info("session.standing_receiver.prove.result", {
+                    agentName, relayPeerId, peerId: node.getPeerId(), proven: true, correlationId,
+                });
+                return "proven";
+            }
+            // ⚠️ A NULL REFUSAL IS A TRANSPORT FAILURE, NOT A VERDICT (review HIGH-1): set only on a
+            // refusal ON THE MERITS, so the `else` clears a stale one `cello_status` would misreport, and
+            // the RETURN below says `unavailable` — the caller decides whether to ask on it.
+            const refusal = client.getLastAuthRefusal();
+            if (surfaceAsReceiverRefusal) {
+                if (refusal) {
+                    this.#ctx.srRelayRefusal.set(agentName, { ...this.#ctx.withDirectoryCause(agentName, refusal), relayPeerId });
+                }
+                else {
+                    this.#ctx.srRelayRefusal.delete(agentName);
+                }
+            }
+            this.#ctx.logger.warn("session.standing_receiver.prove.result", {
+                agentName,
+                relayPeerId,
+                peerId: node.getPeerId(),
+                proven: false,
+                refusalReason: refusal?.reason ?? "no_relay_verdict",
+                tryAnotherRelay: refusal?.tryAnotherRelay ?? true,
+                correlationId,
+                impact: refusal?.advice ??
+                    "the relay said nothing about why, which is what a transport failure mid-handshake looks " +
+                        "like. No verdict was reached, so the reservation is still asked for.",
+            });
+            if (refusal && !refusal.tryAnotherRelay)
+                return "refused_this_agent";
+            if (refusal?.tryAnotherRelay && !this.#ctx.shuttingDown) {
+                this.#quarantineRelay(agentName, relayPeerId, refusal.reason);
+            }
+            if (!refusal)
+                return "unavailable"; // no verdict — see the refusal note above.
+            return "refused_try_another_relay";
+        }
+        catch (err) {
+            this.#ctx.logger.warn("session.standing_receiver.prove.failed", {
+                agentName,
+                correlationId,
+                error: extractErrorMessage(err),
+                impact: "this receiver could not prove itself, so its retry will be refused and the " +
+                    "candidate loop will try the next relay.",
+            });
+            return "unavailable";
+        }
+        finally {
+            client?.close();
+        }
+    }
+    /**
+     * DOD-M12B-REVIVE-RELAY-1 — reconnect the session's relay WITNESS, which revival never did.
+     *
+     * THE FIRST-PRINCIPLES DEFECT, and the one that explains every symptom chased separately before
+     * it. Establishment does five things: build the node, register the content handler, wire liveness,
+     * **connect the relay**, and dial the counterparty. Revival did the first three. A revived session
+     * was therefore not a session — it looked live, reported `active`, and had no live inbound path at
+     * all.
+     *
+     * MEASURED 2026-08-18 with two real agents: a message on a reconnected session took **three
+     * minutes**, against seconds on a fresh one, because only the five-minute mailbox backstop ever
+     * found it. Doorbells stopped firing for the same reason — the relay stream is what rings them.
+     * And `#parkContent` refuses without `entry.relayClient`, so sends could not park either.
+     *
+     * NO ASSIGNMENT IS PRESENTED, and that is by design rather than omission: `RelayConnectParams`
+     * documents the reconnect mode itself — *"absent … on the restart/persisted reconnect path (the
+     * relay already recorded the session at first establishment) — the client then just reconnects
+     * without re-recording."* A revival is exactly that path.
+     *
+     * Best-effort and non-fatal: a session that comes back without its witness is still better than
+     * one that does not come back, and the failure is named rather than silent.
+     */
+    async reconnectRevivedSessionRelay(agentName, sessionId, node, gater, correlationId, ep) {
+        if (!ep) {
+            this.#ctx.logger.warn("session.revive.relay.absent", {
+                agentName,
+                sessionId,
+                impact: "no relay is recorded for this session, so it comes back with no live inbound path — "
+                    + "messages arrive only on the periodic mailbox poll, and a failed send cannot park and is "
+                    + "reported lost",
+            });
+            return;
+        }
+        try {
+            // The gater admits only the counterparty inbound; the relay is a third peer and must be
+            // permitted OUTBOUND or our own gate refuses the dial (INV-5 keeps inbound counterparty-only).
+            gater.setAllowedOutboundPeer(ep.relayPeerId);
+            const clientKey = `${agentName}::${ep.relayPeerId}`;
+            let client = this.#ctx.relayClients.get(clientKey);
+            if (!client) {
+                if (!this.#ctx.relayReceiptStore && this.#db)
+                    this.#ctx.relayReceiptStore = new RelayReceiptStore(this.#db, this.#ctx.logger);
+                if (!this.#ctx.sealLeafStore && this.#db)
+                    this.#ctx.sealLeafStore = new SessionSealLeafStore(this.#db, this.#ctx.logger);
+                client = this.#ctx.detachedRelayClientBuilder?.(agentName, ep.relayPeerId, [...ep.relayAddrs], {
+                    receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                    sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                    // DOD-M15-RELAYSLOTS-1: read at each auth, never snapshotted — the token expires hourly.
+                    onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+                });
+                if (!client) {
+                    this.#ctx.logger.warn("session.revive.relay.builder_absent", {
+                        agentName,
+                        sessionId,
+                        impact: "no relay client could be built, so this revived session has no live inbound path",
+                    });
+                    return;
+                }
+                this.#ctx.relayClients.set(clientKey, client);
+            }
+            // 033-ACKEMIT: a revived session re-registers with no assignment in hand, so the genesis comes
+            // from the entry that was just restored above.
+            // 069-ORDERPROOF: a revived session re-registers with no assignment, so the anchor comes from
+            // the session row — the reason it is stored there at all.
+            client.registerSession(sessionId, node, this.#ctx.contentIn.relayLeafHandler(agentName, sessionId, correlationId), undefined, this.#ctx.leafRecords.sessionGenesisPrevRoot(agentName, sessionId), this.#ctx.leafRecords.sessionRelayAnchor(agentName, sessionId));
+            const entry = this.#ctx.activeNodes.get(this.#ctx.sessionKey(agentName, sessionId));
+            if (entry) {
+                entry.relayClient = client;
+                entry.relaySessionIdBytes = Uint8Array.from(Buffer.from(sessionId, "hex"));
+                entry.relayClientKey = clientKey;
+            }
+            /**
+             * THE STEP THIS METHOD IS NAMED AFTER, and the first version did not take it (review HIGH-2).
+             *
+             * `registerSession` files a handler in a Map. It opens nothing — no dial, no auth, no reader
+             * loop. `connectSessionRelay` ends with exactly this line and the reconnect ended without it,
+             * so a revived session registered a handler on a client whose stream was `null` and then
+             * logged that its live inbound path was back. It was not: the counterparty's leaves queued at
+             * the relay, no doorbell fired, and delivery fell back to the five-minute mailbox poll — the
+             * three-minutes-versus-seconds symptom the whole unit exists to remove.
+             *
+             * Worse, the client is usually BRAND NEW here: `markInterruptedWithDetails` closes and drops
+             * the client for the last session on a relay, so a single-session agent always lands in the
+             * build branch above with a fresh, unconnected client.
+             *
+             * `#ensureConnected` is idempotent, so this also repairs the cached-but-dead-stream case.
+             */
+            await client.connect(node);
+            this.#ctx.logger.info("session.revive.relay.connected", {
+                agentName,
+                sessionId,
+                relayPeerId: ep.relayPeerId,
+                impact: "the revived session has its live inbound path back — messages arrive promptly "
+                    + "instead of waiting for the periodic mailbox poll",
+            });
+        }
+        catch (err) {
+            this.#ctx.logger.warn("session.revive.relay.failed", {
+                agentName,
+                sessionId,
+                error: extractErrorMessage(err),
+                impact: "the session is back but without its witness — delivery falls back to the periodic poll",
+            });
+        }
+    }
+    /** DOD-M12B-REVIVE-PARK-1 test seam: the relay the live entry will park to. Not otherwise
+     *  observable — `#activeNodes` is private and the park's own refusal is silent about which of its
+     *  four preconditions was missing. */
+    getSessionRelayForTest(agentName, sessionId) {
+        const entry = this.#ctx.activeNodes.get(this.#ctx.sessionKey(agentName, sessionId));
+        if (!entry)
+            return null;
+        return {
+            ...(entry.relayPeerId !== undefined ? { relayPeerId: entry.relayPeerId } : {}),
+            ...(entry.relayAddrs !== undefined ? { relayAddrs: entry.relayAddrs } : {}),
+        };
+    }
+}
+//# sourceMappingURL=session-relay.js.map