@cello-protocol/daemon 0.0.176 → 0.0.178

package/dist/session-node-manager.js

@@ -193,6 +193,24 @@ export const REVIVAL_WINDOW_MS = 24 * 60 * 60 * 1000;
  * daemon left up for a week never applies it, and a long-lived daemon is the normal case.
  */
 export const REVIVAL_BOUND_SWEEP_MS = 60 * 60 * 1000;
+/** DOD-M12B-SESSION-SEED-1: per-relay deadline when a revived node asks for a circuit reservation.
+ *  Three seconds — a relay that has a slot answers well inside it, and one that does not never
+ *  answers at all (measured: 10,002ms and still waiting). */
+export const REVIVE_RESERVATION_TIMEOUT_MS = 3_000;
+/** How many relays a revival will ask before settling for a plain node. Two: the worst case is then
+ *  ~6s to a usable session, against a measured "never" for the unbounded form. */
+export const REVIVE_RESERVATION_CANDIDATES = 2;
+/**
+ * DOD-M12B-LEAF-TRIGGERS-FETCH-1 — how long the DIRECT path gets before we go and fetch content the
+ * relay has already told us about.
+ *
+ * Two seconds. The witness leaf and the plaintext are separate deliveries, and on a healthy session
+ * the direct content normally lands within milliseconds of the leaf — so fetching the instant a leaf
+ * arrives would put a relay round trip on the hot path of every message in every session, which is a
+ * self-inflicted load problem. Waiting forever is what cost 102 seconds. Two seconds is far above
+ * the healthy direct latency and far below anything a person would notice.
+ */
+export const LEAF_FETCH_GRACE_MS = 2_000;
 export class SessionNodeManager {
     #factory;
     #logger;
@@ -330,6 +348,17 @@ export class SessionNodeManager {
      * why restart is `RESTART-SEAL-1`'s case (resolve with a receipt) and not a revival case.
      */
     #sessionSeeds = new Map();
+    /** DOD-M12B-SESSION-SEED-1: see setRetryDrainHook — fired when a session is revived. */
+    #retryDrainHook = null;
+    /** DOD-M12B-LEAF-TRIGGERS-FETCH-1: content hashes this session has actually resolved — ingested,
+     *  held, or authored by us. A witnessed leaf whose hash is in here needs no fetch. */
+    #resolvedContent = new Map();
+    /** In-flight grace timers, keyed session+hash, so a redelivered leaf does not schedule a second
+     *  fetch for the same content — a slow relay must not be turned into a storm against itself. */
+    #leafFetchTimers = new Map();
+    /** Test seam: collapse the grace window so a test does not have to wait two real seconds. The
+     *  window itself is covered by its own case. */
+    #leafFetchGraceMs = LEAF_FETCH_GRACE_MS;
     #standingReceivers = new Map();
     #standingReceiverCreating = new Set();
     // M8B F14: agents that SHOULD have a standing receiver — marked by
@@ -2359,6 +2388,60 @@ export class SessionNodeManager {
      * 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).
      */
+    /**
+     * DOD-M12B-REVIVE-RELAY-1 — the relay witness leaf handler, shared by establishment and revival.
+     *
+     * Extracted because a REVIVED session must register the same handler. It was inline in
+     * `#connectSessionRelay`, so revival — which never called that at all — had no live inbound path:
+     * every message fell back to the five-minute mailbox poll, which is why a reconnected session took
+     * three minutes to deliver what a fresh one delivers in seconds, and why doorbells stopped firing.
+     *
+     * A revived session that behaves differently from a fresh one is the defect. This is one of the
+     * two halves of making them the same.
+     */
+    #relayLeafHandler(agentName, sessionId, correlationId) {
+        return (frame) => {
+            // The counterparty's witnessed leaf arrived with its canonical sequence. The
+            // plaintext is delivered separately over the direct content stream; this is the
+            // ordering/witness signal. Full canonical-sequence reconciliation against the
+            // local tree is MSG-001-3b (J-CONTENT).
+            this.#logger.info("session.relay.leaf.delivered", {
+                sessionId,
+                sequenceNumber: frame.sequence_number,
+                leafKind: frame.leaf_kind,
+                correlationId,
+            });
+            // DOD-MSG-4 (strict in-order): record the relay-witnessed canonical sequence for the
+            // counterparty's MSG leaves. The relay is the ordering authority; structure1_cbor =
+            // [1, content_hash(32), sender_pubkey, session_id, last_seen_seq, ts]. The relay sequence
+            // is 1-based and global per session; the daemon tree is 0-based — normalize with -1. Only
+            // COUNTERPARTY leaves (the ones B will ingest); our own echoed leaf already lands via the
+            // send path. The gate (ingestReceivedContent) reads this map to hold out-of-order arrivals.
+            if (!frame.authored_by_us && frame.leaf_kind !== LEAF_KIND_CTRL) {
+                try {
+                    const s1 = decode(frame.structure1_cbor);
+                    const contentHash = s1?.[1];
+                    if (contentHash instanceof Uint8Array && frame.sequence_number > 0) {
+                        this.recordWitnessedSequence(agentName, sessionId, Buffer.from(contentHash).toString("hex"), frame.sequence_number - 1);
+                    }
+                }
+                catch (err) {
+                    this.#logger.warn("session.relay.leaf.witness.decode.failed", {
+                        sessionId,
+                        error: err instanceof Error ? err.message : String(err),
+                        correlationId,
+                    });
+                }
+            }
+            // M7-UPGRADE-002: auto-acknowledge close. When the COUNTERPARTY's SEAL ctrl leaf (0x02)
+            // arrives and B has verified the content, B's OWN node auto-co-signs the responder SEAL
+            // leaf — no agent prompt — so the bilateral seal completes promptly instead of degrading
+            // to unilateral on a slow/busy/crashed agent. Never auto-ack our OWN echoed ctrl leaf.
+            if (frame.leaf_kind === LEAF_KIND_CTRL && !frame.authored_by_us) {
+                this.#maybeAutoAcknowledgeSeal(agentName, sessionId, correlationId);
+            }
+        };
+    }
     async #connectSessionRelay(sessionId, node, agentName, relay, correlationId) {
         try {
             // The session node's gater admits only the counterparty; the relay witness is a
@@ -2392,47 +2475,7 @@ export class SessionNodeManager {
                 this.#relayClients.set(clientKey, client);
             }
             const sessionIdHexForRelay = Buffer.from(relay.sessionIdBytes).toString("hex");
-            client.registerSession(sessionIdHexForRelay, node, (frame) => {
-                // The counterparty's witnessed leaf arrived with its canonical sequence. The
-                // plaintext is delivered separately over the direct content stream; this is the
-                // ordering/witness signal. Full canonical-sequence reconciliation against the
-                // local tree is MSG-001-3b (J-CONTENT).
-                this.#logger.info("session.relay.leaf.delivered", {
-                    sessionId,
-                    sequenceNumber: frame.sequence_number,
-                    leafKind: frame.leaf_kind,
-                    correlationId,
-                });
-                // DOD-MSG-4 (strict in-order): record the relay-witnessed canonical sequence for the
-                // counterparty's MSG leaves. The relay is the ordering authority; structure1_cbor =
-                // [1, content_hash(32), sender_pubkey, session_id, last_seen_seq, ts]. The relay sequence
-                // is 1-based and global per session; the daemon tree is 0-based — normalize with -1. Only
-                // COUNTERPARTY leaves (the ones B will ingest); our own echoed leaf already lands via the
-                // send path. The gate (ingestReceivedContent) reads this map to hold out-of-order arrivals.
-                if (!frame.authored_by_us && frame.leaf_kind !== LEAF_KIND_CTRL) {
-                    try {
-                        const s1 = decode(frame.structure1_cbor);
-                        const contentHash = s1?.[1];
-                        if (contentHash instanceof Uint8Array && frame.sequence_number > 0) {
-                            this.recordWitnessedSequence(agentName, sessionId, Buffer.from(contentHash).toString("hex"), frame.sequence_number - 1);
-                        }
-                    }
-                    catch (err) {
-                        this.#logger.warn("session.relay.leaf.witness.decode.failed", {
-                            sessionId,
-                            error: err instanceof Error ? err.message : String(err),
-                            correlationId,
-                        });
-                    }
-                }
-                // M7-UPGRADE-002: auto-acknowledge close. When the COUNTERPARTY's SEAL ctrl leaf (0x02)
-                // arrives and B has verified the content, B's OWN node auto-co-signs the responder SEAL
-                // leaf — no agent prompt — so the bilateral seal completes promptly instead of degrading
-                // to unilateral on a slow/busy/crashed agent. Never auto-ack our OWN echoed ctrl leaf.
-                if (frame.leaf_kind === LEAF_KIND_CTRL && !frame.authored_by_us) {
-                    this.#maybeAutoAcknowledgeSeal(agentName, sessionId, correlationId);
-                }
-            }, relay.assignment);
+            client.registerSession(sessionIdHexForRelay, node, this.#relayLeafHandler(agentName, sessionId, correlationId), relay.assignment);
             const entry = this.#activeNodes.get(this.#k(agentName, sessionId));
             if (entry) {
                 entry.relayClient = client;
@@ -2531,6 +2574,26 @@ export class SessionNodeManager {
         node.onPeerConnect((peerId) => {
             if (!isCounterparty(peerId))
                 return;
+            /**
+             * DOD-M12B-RESPONDER-ADDR-1 (review MEDIUM-4) — LEARN THE ADDRESS HERE, where it cannot race.
+             *
+             * The accept-time read was a race between two independent async chains: the responder accepts
+             * off a signaling frame, while the initiator dials only after its own `createSessionNode`. If
+             * accept looked before the dial landed it saw nothing, and the responder was back to holding
+             * no address — the state that made every reply after an interruption park forever.
+             *
+             * This fires exactly when the counterparty connects: on both sides, on the first connection,
+             * on every reconnect, and on a revived node too. It also REFRESHES, which the accept-time read
+             * never did — a counterparty that rebuilds its receiver would otherwise leave us dialling a
+             * dead address for the life of the session.
+             */
+            const observed = node
+                .getConnections()
+                .filter((c) => c.peerId === peerId && typeof c.remoteAddr === "string")
+                .map((c) => c.remoteAddr);
+            if (observed.length > 0) {
+                this.#counterpartyAddrs.set(key, [...new Set(observed)]);
+            }
             const prior = this.#sessionLiveness.get(key);
             this.#sessionLiveness.set(key, "alive");
             if (prior !== "alive") {
@@ -2849,6 +2912,51 @@ export class SessionNodeManager {
         // DAEMON-004: register the content stream handler for the inbound session.
         await this.#registerContentHandler(agentName, sessionId, node, counterpartyPubkey);
         // M7-SESSION-003 AC-004: act on the inbound session node's peer events too.
+        /**
+         * DOD-M12B-RESPONDER-ADDR-1 — LEARN THE INITIATOR'S ADDRESS, because we will need it and this is
+         * the only moment we have it.
+         *
+         * MEASURED LIVE 2026-08-18. After an interruption the responder's re-dial reported
+         * `session.transport.redial.unavailable` — *"this side holds no address for the counterparty, so
+         * every send parks until they re-establish"* — and every reply it tried to send failed. The
+         * initiator can always come back because it kept the addresses it dialled; the responder dialled
+         * nothing, so it kept nothing.
+         *
+         * In plain terms that meant: whoever ANSWERED a conversation could not restart it. Their replies
+         * went nowhere until the other side spoke first.
+         *
+         * The live connection has known the address all along — the responder is holding it right now,
+         * because the initiator just dialled in on it. `#counterpartyAddrs` is the same store the
+         * initiator fills from its signed relay assignment, and `#evictSessionCaches` hands both to the
+         * revival record on the way down, so this needs no separate lifetime.
+         */
+        const inboundAddrs = node
+            .getConnections()
+            .filter((c) => c.peerId === initiatorPeerId && typeof c.remoteAddr === "string")
+            .map((c) => c.remoteAddr);
+        if (inboundAddrs.length > 0) {
+            this.#counterpartyAddrs.set(this.#k(agentName, sessionId), [...new Set(inboundAddrs)]);
+            this.#logger.info("session.counterparty.addr.learned", {
+                agentName,
+                sessionId,
+                addrs: inboundAddrs.length,
+                source: "inbound_connection",
+                impact: "this side can now re-dial after an interruption instead of parking every reply",
+            });
+        }
+        else {
+            // NOT A WARNING. Review MEDIUM-4: accept runs off a signaling frame and the initiator dials
+            // separately, so "no connection yet" is the ordinary in-flight case — warning on it puts a
+            // signal on the normal path, which is how the one occurrence that matters gets buried. The
+            // race-free capture is in `#wireSessionLiveness`'s onPeerConnect, which fires when the dial
+            // actually lands; this read is only a fast path for when it already has.
+            this.#logger.debug("session.counterparty.addr.deferred", {
+                agentName,
+                sessionId,
+                initiatorPeerId,
+                impact: "no connection observed yet; the address is captured when the counterparty connects",
+            });
+        }
         this.#wireSessionLiveness(agentName, sessionId, node, counterpartyPubkey, correlationId, initiatorPeerId);
         // M7 DOD-SPINE-6 / MSG-001-3b: the receiver also connects to the relay witness so
         // the relay can deliver the initiator's witnessed leaves (leaf_deliver) to it.
@@ -3082,6 +3190,16 @@ export class SessionNodeManager {
         this.#heldRestored.delete(key);
         this.#heldReleased.delete(key);
         this.#diverged.delete(key);
+        // DOD-M12B-SESSION-SEED-1: HAND THEM TO THE REVIVAL RECORD BEFORE DROPPING THEM. This eviction
+        // runs on every teardown, including the interruption a revival is meant to undo — so clearing
+        // the addresses here is what left a revived session unable to dial anyone. The revival record
+        // has exactly the right lifetime for them: it dies when the session reaches a terminal status.
+        const survivingAddrs = this.#counterpartyAddrs.get(key);
+        if (survivingAddrs && survivingAddrs.length > 0) {
+            const identity = this.#sessionSeeds.get(key);
+            if (identity)
+                identity.counterpartyAddrs = [...survivingAddrs];
+        }
         this.#counterpartyAddrs.delete(key);
         this.#redialNotBefore.delete(key);
         this.#highWaterSeq.delete(key);
@@ -3272,9 +3390,38 @@ export class SessionNodeManager {
             .all(status);
     }
     /**
-     * DOD-M12B-RESTART-SEAL-1 — the sessions OUR OWN stop orphaned, and only those.
-     *
-     * `interrupted_by` is the whole safety argument. `'local'` means the boot sweep, the shutdown
+     * DOD-M12B-RESTART-SEAL-1 / DOD-M12B-PENDING-RESOLVE-1 — sessions that need a receipt and have
+     * nobody asking for one. TWO populations, one queue, each with its own safety argument.
+     *
+     * **(2) `seal_interrupted_pending` — a seal commitment nobody notarized.** Measured 2026-08-18 on
+     * the live store: 28 sessions, aged 0.3 to 12.8 days, one of them 14 messages long, 26 holding
+     * relay-witnessed seal leaves, and **not one with a sealed root**.
+     *
+     * **HALF OF THEM ARE NOT BILATERAL, and the first version of this comment claimed they were.**
+     * Measured split: 14 initiator rows, each carrying the counterparty's signed leaf — and 14
+     * responder rows with `counterparty_leaf = NULL`. A responder row is written by
+     * `inbound-seal-request.ts` from an UNSIGNED `seal_interrupted_request` frame, before its ack is
+     * even sent, so an ordinary send failure produces a one-sided pending row.
+     *
+     * So the licence is NOT "both parties signed". It is **somebody chose to end this**, on two
+     * branches: an initiator row carries the counterparty's signature, and a responder row exists
+     * because the counterparty sent a request to seal. And what makes the result VERIFIABLE is
+     * neither — it is that the directory rebuilds the tree from relay-witnessed leaves and checks
+     * their signatures, never consulting the commitment at all. The commitment is what makes it
+     * legitimate to ASK. (`close-session-handler.ts` states this in full; the first draft of this
+     * header contradicted it 200 lines away.) `PENDING-EXIT-1` built their exit and it works — but only when an operator runs
+     * `cello_close_session` on that session by hand, having somehow deduced they should. Nothing
+     * enumerated them, because both sweeps filtered `status = 'interrupted'`. An exit nobody is told
+     * about is not an exit.
+     *
+     * `interrupted_by` is deliberately NOT consulted for that population. It answers "did WE cause
+     * this, and may we therefore describe it" — and that is the wrong question once a seal was
+     * requested or signed. **SI-001 is not weakened:** it forbids notarizing *"a conversation nobody
+     * chose to end"*, and every row here was chosen to be ended by one side or the other. The only
+     * thing missing is the request to notarize it.
+     *
+     * **(1) `interrupted` — sessions our own stop orphaned, and only those.** Here `interrupted_by` is
+     * the whole safety argument. `'local'` means the boot sweep, the shutdown
      * sweep, or the operator's own kill switch ended this session — nobody else did, and it cannot be
      * resumed because the transport keypairs died with the process. Those are the ones the resolver
      * may seal on its own.
@@ -3303,9 +3450,23 @@ export class SessionNodeManager {
         // `restart_seal_gave_up_at IS NULL` — a session we have already exhausted. Without it a
         // machine restarting ~6 times a day re-runs five ceremonies against a hopeless session on
         // every boot, forever.
-        `SELECT s.session_id AS session_id, s.message_count AS message_count, a.agent_name AS agent_name
+        `SELECT s.session_id AS session_id, s.message_count AS message_count, a.agent_name AS agent_name,
+                s.status AS status
          FROM sessions s JOIN agents a ON a.agent_id = s.agent_id
-         WHERE s.status = 'interrupted' AND s.interrupted_by = 'local' AND a.state != 'retired'
+         WHERE a.state != 'retired'
+           AND (
+                 -- (1) OURS, and we can say so. SI-001 holds: an interrupted session with an
+                 -- unknown cause has no signatures behind it and must not be notarized.
+                 (s.status = 'interrupted' AND s.interrupted_by = 'local')
+                 -- (2) A seal commitment with nobody asking for it. review F5: the EXISTS is
+                 -- STRUCTURAL, not decoration. The header's licence is "a commitment was made", and
+                 -- a status check alone asserts that in prose while the query checks something
+                 -- else. Today status implies an artifact row by construction, which is exactly the
+                 -- kind of invariant that holds until someone adds a fourth writer.
+                 OR (s.status = 'seal_interrupted_pending'
+                     AND EXISTS (SELECT 1 FROM seal_interrupted_artifacts sa
+                                 WHERE sa.agent_id = s.agent_id AND sa.session_id = s.session_id))
+               )
            AND s.message_count > 0
            AND s.restart_seal_gave_up_at IS NULL
          ORDER BY s.updated_at ASC`)
@@ -3314,6 +3475,9 @@ export class SessionNodeManager {
             agentName: r.agent_name,
             sessionId: r.session_id,
             messageCount: r.message_count ?? 0,
+            // Carried so a give-up can say something TRUE about this session: the two populations need
+            // different words, and force-abandon is right for one and destructive for the other.
+            status: r.status === "seal_interrupted_pending" ? "seal_interrupted_pending" : "interrupted",
         }));
     }
     /**
@@ -5286,6 +5450,73 @@ export class SessionNodeManager {
         const hw = this.#highWaterSeq.get(key) ?? -1;
         if (sequenceNumber > hw)
             this.#highWaterSeq.set(key, sequenceNumber);
+        /**
+         * DOD-M12B-LEAF-TRIGGERS-FETCH-1 — A LEAF WE CANNOT READ IS A FETCH ORDER.
+         *
+         * MEASURED LIVE 2026-08-18: the relay delivered this leaf one second after the counterparty
+         * sent. We had the hash and the sequence, the bytes were parked at that same relay, and the
+         * plaintext arrived 102 seconds later on a background sweep. Nothing connected the two facts —
+         * this method recorded the sequence and stopped.
+         *
+         * The witness leaf and the plaintext are separate deliveries: the leaf comes over the relay, the
+         * bytes over the direct content stream. After an interruption the two session nodes have no
+         * direct connection, so the bytes go to the park instead and only a timer ever finds them.
+         *
+         * The grace window is what keeps this off the hot path. On a healthy session the direct content
+         * lands within milliseconds of its leaf, so fetching immediately would mean a relay round trip
+         * for every message in every session. We give the direct path its two seconds first.
+         */
+        this.#scheduleLeafFetchIfUnresolved(agentName, sessionId, contentHashHex);
+    }
+    /** DOD-M12B-LEAF-TRIGGERS-FETCH-1: this content is here — no fetch is owed for it, and any
+     *  pending one is cancelled. Called wherever content actually lands. */
+    #markContentResolved(agentName, sessionId, contentHashHex) {
+        const key = this.#k(agentName, sessionId);
+        let set = this.#resolvedContent.get(key);
+        if (!set) {
+            set = new Set();
+            this.#resolvedContent.set(key, set);
+        }
+        set.add(contentHashHex);
+        const timerKey = `${key}::${contentHashHex}`;
+        const t = this.#leafFetchTimers.get(timerKey);
+        if (t !== undefined) {
+            clearTimeout(t);
+            this.#leafFetchTimers.delete(timerKey);
+        }
+    }
+    #scheduleLeafFetchIfUnresolved(agentName, sessionId, contentHashHex) {
+        const key = this.#k(agentName, sessionId);
+        if (this.#resolvedContent.get(key)?.has(contentHashHex))
+            return;
+        const timerKey = `${key}::${contentHashHex}`;
+        // ONE fetch per content hash. The relay redelivers, and a redelivery carries the same sequence —
+        // scheduling per redelivery turns a slow relay into a storm against itself.
+        if (this.#leafFetchTimers.has(timerKey))
+            return;
+        const timer = setTimeout(() => {
+            this.#leafFetchTimers.delete(timerKey);
+            if (this.#resolvedContent.get(key)?.has(contentHashHex))
+                return; // the direct path won
+            if (this.#shuttingDown)
+                return;
+            this.#logger.info("session.content.leaf_unresolved.fetch", {
+                agentName,
+                sessionId,
+                contentHash: contentHashHex,
+                graceMs: this.#leafFetchGraceMs,
+                impact: "the relay told us this message exists and its plaintext never arrived directly — "
+                    + "fetching it now instead of waiting for the periodic sweep",
+            });
+            this.#fireParkedDrain(agentName, "witnessed_leaf_unresolved");
+        }, this.#leafFetchGraceMs);
+        timer.unref?.();
+        this.#leafFetchTimers.set(timerKey, timer);
+    }
+    /** DOD-M12B-LEAF-TRIGGERS-FETCH-1 test seams. */
+    setLeafFetchGraceMsForTest(ms) { this.#leafFetchGraceMs = ms; }
+    markContentPresentForTest(agentName, sessionId, contentHashHex) {
+        this.#markContentResolved(agentName, sessionId, contentHashHex);
     }
     /**
      * DOD-MSG-4: the relay's high-water canonical sequence for this session (largest witnessed leaf),
@@ -5625,6 +5856,11 @@ export class SessionNodeManager {
         // transcript. A later replay of the same hash is still caught by the dedup leaf-scan, which is
         // independent of the witness map.
         this.#witnessedSeq.get(recvKey)?.delete(contentHashHex);
+        // DOD-M12B-LEAF-TRIGGERS-FETCH-1: the bytes are here, so cancel any fetch the witness leaf
+        // scheduled. On a healthy session this is the branch that runs — the direct path beats the
+        // grace window and the relay is never asked, which is what keeps a fetch off the hot path of
+        // every message.
+        this.#markContentResolved(agentName, sessionId, contentHashHex);
         let buf = this.#receivedContent.get(recvKey);
         if (!buf) {
             buf = [];
@@ -7699,7 +7935,10 @@ export class SessionNodeManager {
         // overwrite that dropped a live seed un-zeroed would leave the one copy we are responsible for
         // in the heap with nothing tracking it.
         this.#sessionSeeds.get(key)?.seed.fill(0);
-        this.#sessionSeeds.set(key, { seed, counterpartyPeerId, counterpartyPubkey });
+        // `counterpartyAddrs` starts empty: at creation the signed assignment has not necessarily
+        // arrived yet. It is filled by `#evictSessionCaches` on the way down, which is the last moment
+        // the live addresses exist.
+        this.#sessionSeeds.set(key, { seed, counterpartyPeerId, counterpartyPubkey, counterpartyAddrs: [] });
     }
     /**
      * DOD-M12B-SESSION-SEED-1 — destroy a session's transport identity.
@@ -7726,6 +7965,213 @@ export class SessionNodeManager {
         this.#sessionSeeds.delete(key);
         this.#logger.debug("session.seed.destroyed", { agentName, sessionId });
     }
+    /**
+     * DOD-M12B-SESSION-SEED-1 — build a revived session node that is REACHABLE, without ever hanging.
+     *
+     * MEASURED 2026-08-18, live, three ways:
+     *   - handed 2 relay addrs at once, no deadline:  `start()` never completes (10,002ms and counting)
+     *   - handed none:                                `start()` in 1ms, but NOBODY can dial the node —
+     *                                                 the counterparty's re-dial fails
+     *                                                 `counterparty_dial_failed` and every message in
+     *                                                 both directions has to go the relay park route
+     *   - this:                                       one candidate at a time, each raced against its
+     *                                                 own deadline, plain node as the floor
+     *
+     * The middle option is what shipped for one test run and it made the session half-dead: revived,
+     * `active`, and unreachable. The first is what shipped before that and it hung. Neither is a
+     * choice between "fast" and "reliable" — the per-candidate race is how `#startReceiverNode` has
+     * always done it, and it is the shape that works in production every day.
+     *
+     * A FAILED CANDIDATE IS TORN DOWN AT SETTLEMENT. The first version awaited `stop()` immediately
+     * and claimed that made seed reuse safe; it did not — `libp2p.stop()` returns at once unless the
+     * node is `'started'`, and during the timeout window it is `'starting'` (review HIGH-3, verified
+     * against libp2p 3.3.2). The teardown is now chained onto the candidate's OWN start promise, so it
+     * runs whenever that settles, however late.
+     *
+     * A BRIEF OVERLAP IS THEREFORE POSSIBLE and is stated rather than denied: a candidate that grants
+     * at 4s comes up on this session's peer id and is stopped immediately after. What is guaranteed is
+     * that it dies, not that it never lives. The receiver path avoids even that by minting a seed per
+     * candidate; here the identity is fixed, which is the whole point of a revival, so that option
+     * does not exist.
+     *
+     * The floor is a plain node: a session that is usable over the relay park route beats no session.
+     */
+    async #buildRevivedNode(sessionId, gater, seed, candidateAddrs, agentName) {
+        for (const circuitAddr of candidateAddrs.slice(0, REVIVE_RESERVATION_CANDIDATES)) {
+            const candidate = await this.#factory.createNode({
+                sessionId,
+                connectionGater: gater,
+                nodeType: "session",
+                inboundReachable: true,
+                transportPrivateKey: seed,
+                circuitRelayListenAddrs: [circuitAddr],
+            });
+            // KEEP THE START PROMISE. Review HIGH-3: `libp2p.stop()` opens with
+            // `if (this.status !== 'started') return`, and during the whole timeout window the status is
+            // `'starting'` — so awaiting `stop()` on a timed-out candidate stopped nothing and waited for
+            // nothing. The abandoned `start()` stayed in flight, and if the relay answered late the node
+            // went live holding THIS SESSION'S peer id, sharing the gater (so it admits the counterparty)
+            // with no content handler registered, and with no reference left to stop it. Verified against
+            // libp2p 3.3.2 rather than assumed.
+            const startP = candidate.start();
+            let startError;
+            const started = await Promise.race([
+                startP.then(() => true),
+                new Promise((res) => setTimeout(() => res(false), REVIVE_RESERVATION_TIMEOUT_MS).unref?.()),
+            ]).catch((err) => { startError = err; return false; });
+            if (started && candidate.listenAddresses().some((a) => a.includes("/p2p-circuit"))) {
+                this.#logger.info("session.revive.reservation.granted", { agentName, sessionId });
+                return candidate;
+            }
+            // Started but granted nothing, or never started. Either way this node is not the one.
+            //
+            // Review MEDIUM-5: name WHICH of the three causes this was, the way `#startReceiverNode` does.
+            // "declined" alone stood for a relay that is full, a relay that is unreachable, and a relay
+            // that is merely slow — three different problems with three different responses, and the
+            // thrown error was discarded entirely.
+            const declineReason = started
+                ? "relay_granted_no_reservation"
+                : startError !== undefined
+                    ? "relay_unreachable"
+                    : "reservation_did_not_complete_in_time";
+            const isLast = circuitAddr === candidateAddrs.slice(0, REVIVE_RESERVATION_CANDIDATES).at(-1);
+            this.#logger.warn("session.revive.reservation.declined", {
+                agentName,
+                sessionId,
+                circuitAddr,
+                reason: declineReason,
+                ...(startError !== undefined ? { error: extractErrorMessage(startError) } : {}),
+                impact: isLast
+                    ? "no relay granted; the session comes up reachable only via the relay park route"
+                    : "trying the next relay",
+            });
+            // Teardown at SETTLEMENT, not now: a `stop()` issued while the node is still starting is a
+            // no-op (see above), so the only way to guarantee this node dies is to wait for its own start
+            // to finish first. Not awaited, so a hung start cannot hold the revival up — the point is that
+            // the teardown eventually happens, not that it happens before the next candidate.
+            void startP.then(() => candidate.stop().catch(() => { }), () => { });
+        }
+        // THE FLOOR. No reservation, so the counterparty cannot dial us directly — but their messages
+        // park at the relay and drain, which is how every message in the 2026-08-18 test arrived. A
+        // session usable one way beats a session that never comes back.
+        const plain = await this.#factory.createNode({
+            sessionId,
+            connectionGater: gater,
+            nodeType: "session",
+            inboundReachable: true,
+            transportPrivateKey: seed,
+        });
+        await plain.start();
+        if (candidateAddrs.length > 0) {
+            this.#logger.warn("session.revive.reservation.none", {
+                agentName,
+                sessionId,
+                candidates: candidateAddrs.length,
+                impact: "the revived session holds no circuit address — the counterparty cannot dial it, so "
+                    + "delivery in both directions depends on relay store-and-forward until it is rebuilt",
+            });
+        }
+        return plain;
+    }
+    /**
+     * 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.#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.#relayClients.get(clientKey);
+            if (!client) {
+                if (!this.#relayReceiptStore && this.#db)
+                    this.#relayReceiptStore = new RelayReceiptStore(this.#db, this.#logger);
+                if (!this.#sealLeafStore && this.#db)
+                    this.#sealLeafStore = new SessionSealLeafStore(this.#db, this.#logger);
+                client = this.#detachedRelayClientBuilder?.(agentName, ep.relayPeerId, [...ep.relayAddrs], {
+                    receiptStore: this.#relayReceiptStore ?? undefined,
+                    sealLeafStore: this.#sealLeafStore ?? undefined,
+                });
+                if (!client) {
+                    this.#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.#relayClients.set(clientKey, client);
+            }
+            client.registerSession(sessionId, node, this.#relayLeafHandler(agentName, sessionId, correlationId));
+            const entry = this.#activeNodes.get(this.#k(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.#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.#logger.warn("session.revive.relay.failed", {
+                agentName,
+                sessionId,
+                error: err instanceof Error ? err.message : String(err),
+                impact: "the session is back but without its witness — delivery falls back to the periodic poll",
+            });
+        }
+    }
     /**
      * DOD-M12B-SESSION-SEED-1 — bring an interrupted session back on the peer id it already has.
      *
@@ -7764,6 +8210,31 @@ export class SessionNodeManager {
                 guidance: `Session is '${record.status}'. A session that has ended cannot be revived; start a new one.`,
             };
         }
+        /**
+         * THE CAP APPLIES TO A REVIVAL TOO (review: parity gap). Establishment refuses at
+         * `MAX_SESSION_NODES` because each node is a real libp2p instance with listeners, connections
+         * and a relay reservation. A revival builds exactly the same thing, so letting it past the cap
+         * would let a daemon walk over the limit one reconnect at a time — and the limit exists to stop
+         * a machine being taken down by its own session count.
+         *
+         * Refused by name, so the caller can say something true: this is a local resource limit, not a
+         * problem with the session or the counterparty.
+         */
+        if (this.#activeNodes.size >= MAX_SESSION_NODES) {
+            this.#logger.warn("session.revive.cap.reached", {
+                agentName,
+                sessionId,
+                activeCount: this.#activeNodes.size,
+                maxCount: MAX_SESSION_NODES,
+                impact: "this session stays interrupted until another session ends and frees a node slot",
+            });
+            return {
+                ok: false,
+                reason: "session_node_cap_reached",
+                guidance: `This daemon already holds ${MAX_SESSION_NODES} active session nodes, so this session ` +
+                    "cannot be brought back yet. Close a session you have finished with and try again.",
+            };
+        }
         const identity = this.#sessionSeeds.get(key);
         if (identity === undefined) {
             // The honest case: the daemon restarted, so the keypair is genuinely gone. That is
@@ -7788,19 +8259,22 @@ export class SessionNodeManager {
         for (const relayPeerId of reservations.relayPeerIds)
             gater.setAllowedOutboundPeer(relayPeerId);
         let node;
+        const t0 = Date.now();
+        this.#logger.info("session.revive.node.building", {
+            agentName,
+            sessionId,
+            circuitAddrs: reservations.addrs.length,
+            relayPeerIds: reservations.relayPeerIds.length,
+        });
         try {
-            node = await this.#factory.createNode({
+            node = await this.#buildRevivedNode(sessionId, gater, identity.seed, reservations.addrs, agentName);
+            this.#logger.info("session.revive.node.started", {
+                agentName,
                 sessionId,
-                connectionGater: gater,
-                nodeType: "session",
-                transportPrivateKey: identity.seed,
-                // review HIGH-1: reachable, and holding a circuit reservation. A revived node that binds
-                // loopback preserves an identity nobody can dial — the counterparty's next message parks
-                // again and case B is only half delivered.
-                inboundReachable: true,
-                ...(reservations.addrs.length > 0 ? { circuitRelayListenAddrs: reservations.addrs } : {}),
+                startMs: Date.now() - t0,
+                listenAddrs: node.listenAddresses().length,
+                circuitListen: node.listenAddresses().filter((a) => a.includes("/p2p-circuit")).length,
             });
-            await node.start();
         }
         catch (err) {
             this.#logger.error("session.revive.node.failed", {
@@ -7818,7 +8292,38 @@ export class SessionNodeManager {
             probers: this.#autoNatProbers(),
         });
         autoNat.emitInitialResult();
+        // DOD-M12B-SESSION-SEED-1: give the re-dial its addresses back BEFORE the session goes active,
+        // so the first send after a revival has somewhere to go. Without this the send fails instantly
+        // on a connection that was never made, and — measured live — is lost rather than parked.
+        if (identity.counterpartyAddrs.length > 0) {
+            this.#counterpartyAddrs.set(key, [...identity.counterpartyAddrs]);
+        }
         const correlationId = randomUUID();
+        /**
+         * DOD-M12B-REVIVE-PARK-1 — RESTORE THE RELAY, or a revived session cannot park and every failed
+         * send is declared lost.
+         *
+         * This is the defect behind five identical live failures on 2026-08-18. `#parkContent` opens
+         * with `if (!hook || !entry || !entry.relayPeerId || !entry.relayAddrs) return "unconfigured"`,
+         * and a revived entry carried none of it — so the park was skipped and the send fell through to
+         * *"could NOT be queued for retry — it is lost. Send it again."* The relay was recorded on the
+         * session row the whole time, and store-and-forward would have delivered the message: the
+         * counterparty's own sends park through it successfully in the same minute.
+         *
+         * What it cost the operator: their reply was accepted, discarded, and they were told to retype
+         * it — which is how a transcript gets duplicates of a message that was never lost in the first
+         * place.
+         *
+         * Read from the row rather than carried in the revival record on purpose: the row is where the
+         * relay assignment is durable, and it is the same source `getPersistedRelayEndpoint` already
+         * serves the startup flush from — a path that exists precisely because in-memory entries are
+         * gone by then, which is exactly the situation a revival is in.
+         */
+        // ONE lookup, and ONE event for the absent case (review LOW-8). This used to read the endpoint
+        // here and again inside the relay reconnect, and both logged `session.revive.relay.absent` with
+        // different `impact` text — one event name standing for two meanings, fired twice for a single
+        // condition. `#reconnectRevivedSessionRelay` takes it as a parameter now.
+        const persistedRelay = this.getPersistedRelayEndpoint(agentName, sessionId);
         this.#activeNodes.set(key, {
             node,
             agentName,
@@ -7828,6 +8333,9 @@ export class SessionNodeManager {
             correlationId,
             counterpartySessionPeerId: identity.counterpartyPeerId,
             autoNat,
+            ...(persistedRelay
+                ? { relayPeerId: persistedRelay.relayPeerId, relayAddrs: persistedRelay.relayAddrs }
+                : {}),
         });
         await this.#registerContentHandler(agentName, sessionId, node, identity.counterpartyPubkey);
         /**
@@ -7841,6 +8349,9 @@ export class SessionNodeManager {
          * to trigger the next revival either.
          */
         this.#wireSessionLiveness(agentName, sessionId, node, identity.counterpartyPubkey, correlationId, identity.counterpartyPeerId);
+        // DOD-M12B-REVIVE-RELAY-1: the step revival skipped. Establishment connects the relay witness
+        // here; without it the session comes back with no live inbound path at all.
+        await this.#reconnectRevivedSessionRelay(agentName, sessionId, node, gater, correlationId, persistedRelay);
         // THE REVERSE EDGE. A transport event took this session out of `active` and nothing has ever
         // put one back. Written after the node is live and its handler registered, so the row never
         // claims `active` for a session that cannot yet receive.
@@ -7862,6 +8373,21 @@ export class SessionNodeManager {
                     "down rather than left live under an interrupted row. The daemon logged the cause.",
             };
         }
+        // The messages that failed while this session was down were queued on a promise of "retried on
+        // reconnect". This is that reconnect — fire it before anyone is told the session is back.
+        if (this.#retryDrainHook !== null) {
+            try {
+                this.#retryDrainHook(agentName, sessionId);
+            }
+            catch (err) {
+                this.#logger.warn("session.revive.retry_drain.failed", {
+                    agentName,
+                    sessionId,
+                    error: err instanceof Error ? err.message : String(err),
+                    impact: "messages queued while this session was down are still queued",
+                });
+            }
+        }
         const peerId = node.getPeerId();
         this.#logger.info("session.revived", {
             agentName,
@@ -7876,8 +8402,8 @@ export class SessionNodeManager {
     /**
      * DOD-M12B-SESSION-SEED-1 — the DEMAND edge: a send on an interrupted session revives it.
      *
-     * This is the only production caller of `reviveSessionNode`, and it is deliberately the send path
-     * rather than a timer. The `REDIAL-1` discipline and Andre's tenet say the same thing from two
+     * One of TWO production callers of `reviveSessionNode` — `reviveIfNeededForRead` is the other —
+     * and both are deliberately demand paths rather than timers. The `REDIAL-1` discipline and Andre's tenet say the same thing from two
      * directions: nothing may re-open on its own, because a background rebuilder would hold a dialable
      * endpoint open for a session nobody is using — the *"open connection a malicious agent can farm
      * for"*. The operator sending is the demand; there is no other trigger.
@@ -7970,11 +8496,45 @@ export class SessionNodeManager {
         this.#fireParkedDrain(agentName, "session_revived");
         return { ok: true };
     }
+    /** 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.#activeNodes.get(this.#k(agentName, sessionId));
+        if (!entry)
+            return null;
+        return {
+            ...(entry.relayPeerId !== undefined ? { relayPeerId: entry.relayPeerId } : {}),
+            ...(entry.relayAddrs !== undefined ? { relayAddrs: entry.relayAddrs } : {}),
+        };
+    }
+    /** DOD-M12B-SESSION-SEED-1 test seams: the counterparty addresses a re-dial depends on. Not
+     *  otherwise observable — they are set from a signed relay assignment that a fixture cannot mint. */
+    setCounterpartyAddrsForTest(agentName, sessionId, addrs) {
+        this.#counterpartyAddrs.set(this.#k(agentName, sessionId), [...addrs]);
+    }
+    getCounterpartyAddrsForTest(agentName, sessionId) {
+        return this.#counterpartyAddrs.get(this.#k(agentName, sessionId)) ?? [];
+    }
     /** DOD-M12B-SESSION-SEED-1 test seam: drop a seed WITHOUT zeroing or a status change — what a
      *  process restart does to it. The refusal that follows is the one an operator most needs named. */
     forgetSessionSeedForTest(agentName, sessionId) {
         this.#sessionSeeds.delete(this.#k(agentName, sessionId));
     }
+    /**
+     * DOD-M12B-SESSION-SEED-1 — drain the direct-resend queue when a session comes back.
+     *
+     * `retryQueue.drainSession` had NO production caller. The send path enqueues into it on a failed
+     * delivery and tells the operator the message will be "retried on reconnect", and nothing ever
+     * reconnected it — the row sat there until the session went terminal and was reaped. Measured
+     * live 2026-08-18: two of the operator's messages went in, and the response told them both were
+     * lost and to send again, which is how a transcript gets duplicates.
+     *
+     * A revival IS the reconnect that sentence promised. This is the hook that makes it true.
+     */
+    setRetryDrainHook(fn) {
+        this.#retryDrainHook = fn;
+    }
     /** DOD-M12B-SESSION-SEED-1 test seam: does this session still hold a revivable identity? */
     hasSessionSeedForTest(agentName, sessionId) {
         return this.#sessionSeeds.has(this.#k(agentName, sessionId));
@@ -8059,6 +8619,34 @@ export class SessionNodeManager {
     /** CC-5/F21: count of RECEIVED messages on a session — the "did the counterparty ever speak"
      *  signal the dead-half-open reaper uses (message_count also counts our own auto-"Dispatched." ack,
      *  so it is NOT a reliable half-open discriminator). Mirrors #getReceivedBytesTotal. */
+    /**
+     * DOD-M12B-REAP-HELD-1 — did the counterparty EVER establish? Counted from every place their
+     * messages can be, not just the one.
+     *
+     * OBSERVED LIVE 2026-08-18: the half-open reaper abandoned session `d28db475…` — twenty leaves in
+     * the chain and sixteen more frames verified and held, ten of them from the counterparty — while
+     * the restart-seal resolver was actively trying to notarize it. The receipt was forfeited.
+     *
+     * `countReceivedMessages` asks the TRANSCRIPT, and **held content never reaches the transcript**;
+     * it sits in `held_content` until it can join the chain. So the very condition that holds content
+     * — an interrupted session — is the condition that makes the counterparty's messages invisible,
+     * and a fully-established conversation reads identically to an offer nobody ever answered.
+     *
+     * `origin = 'received'` is load-bearing. Our OWN held frames prove nothing about them, and
+     * counting those would make every session we ever spoke into un-reapable — which is exactly the
+     * clutter the reaper exists to clear. D18 also depends on the zero case staying zero: reaping only
+     * genuinely 0-received ghosts is what stops a stranger whose first handshakes died from being
+     * locked out by the acceptance bound forever.
+     */
+    countEstablishedReceived(agentName, sessionId) {
+        if (!this.#db)
+            return 0;
+        const agentId = this.#requireAgentId(agentName);
+        const held = this.#db
+            .prepare("SELECT COUNT(*) AS n FROM held_content WHERE agent_id = ? AND session_id = ? AND origin = 'received'")
+            .get(agentId, sessionId);
+        return this.countReceivedMessages(agentName, sessionId) + (held?.n ?? 0);
+    }
     countReceivedMessages(agentName, sessionId) {
         if (!this.#db)
             return 0;