@cello-protocol/daemon 0.0.174 → 0.0.176

package/dist/session-node-manager.js

@@ -26,7 +26,7 @@ import { TIER, normalizeTier, isKnownTierValue, tierBoundsFor, DEFAULT_TIER_BOUN
 import { migrateCborBlobsToCanonical } from "./cbor-blob-migration.js";
 import { ensureTrustSignalSchema } from "./trust-signal-store.js";
 import { boundSettingKey, settableTierName, isValidSettingKey, awayTierSettingKey, AWAY_DEFAULT_KEY } from "./agent-settings-keys.js";
-import { randomUUID, createHash } from "node:crypto";
+import { randomUUID, createHash, randomBytes } from "node:crypto";
 import * as lp from "it-length-prefixed";
 import { decode } from "cbor-x";
 import { encodeCbor } from "@cello-protocol/protocol-types";
@@ -173,6 +173,26 @@ export const ABUSE_MAX_UNKNOWN_SESSIONS_GLOBAL = 50;
  * the leak the old destructive read was accidentally preventing.
  */
 const RECEIVED_BUFFER_CAP = 32;
+/**
+ * DOD-M12B-REVIVAL-BOUND-1 — how long an interrupted session stays revivable before it is closed.
+ *
+ * 24 hours. The bound exists because of Andre's 2026-08-18 tenet — *"leave nothing open that is no
+ * longer needed"* — and its value is set by the case it must not break: a laptop closed for the
+ * night. A window shorter than a night's sleep would abandon exactly the sessions case A/B exist to
+ * rescue, which is why this is not zero and not an hour.
+ *
+ * It is deliberately a plain constant and not a setting. A per-operator knob here is a knob that
+ * turns the guarantee off, and the guarantee is the security property, not a preference.
+ */
+export const REVIVAL_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * DOD-M12B-REVIVAL-BOUND-1 — how often the revival bound is applied.
+ *
+ * Hourly. The window is 24 hours, so the worst-case overshoot is ~4% of the bound, and the pass is
+ * one DB walk with no network in it. Boot-only was the first build and it is not a bound at all: a
+ * 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;
 export class SessionNodeManager {
     #factory;
     #logger;
@@ -287,6 +307,29 @@ export class SessionNodeManager {
     // `hasReservation`: this receiver came up holding a /p2p-circuit address. The
     // watchdog uses it to tell "lost its reservation" (must recover) apart from
     // "never had one" (already degraded, and already loud) — see #reservationWatchdogTick.
+    /**
+     * DOD-M12B-SESSION-SEED-1 — session id → the transport seed its node identity derives from.
+     *
+     * **DELIBERATELY NOT ON `ActiveSessionEntry`.** That entry is deleted the instant a session is
+     * interrupted (`markInterruptedWithDetails` and `destroySessionNode` both do it), which is exactly
+     * the moment the seed becomes necessary — storing it there would destroy it precisely when the
+     * session needs to come back. It has to outlive the NODE without outliving the SESSION.
+     *
+     * Andre's 2026-08-18 tenet is the lifetime rule: *"it should be possible to revive that session on
+     * those peer IDs. But after that, those peer IDs and that peer connection needs to be shut down."*
+     * So this map is cleared in the same step that writes a terminal status (`#updateSessionStatus`),
+     * not on a later sweep — and the bytes are zeroed before the reference is dropped, because a seed
+     * that stays readable in the heap is exactly the "left open" the tenet forbids.
+     *
+     * It holds the counterparty's session peer id alongside the seed, and not for convenience: that
+     * value lives ONLY on `ActiveSessionEntry` and is destroyed with it on interruption, so without a
+     * copy here we could rebuild our own identity and still not know who to let back in. Both halves
+     * of the revival have the same lifetime, so they are destroyed in one step.
+     *
+     * In memory only, never persisted. A daemon restart genuinely destroys these identities, which is
+     * why restart is `RESTART-SEAL-1`'s case (resolve with a receipt) and not a revival case.
+     */
+    #sessionSeeds = new Map();
     #standingReceivers = new Map();
     #standingReceiverCreating = new Set();
     // M8B F14: agents that SHOULD have a standing receiver — marked by
@@ -2176,6 +2219,9 @@ export class SessionNodeManager {
         let node;
         let gater;
         let autoNat;
+        // DOD-M12B-SESSION-SEED-1: whichever branch below runs, the session ends up owning a seed.
+        // Promotion inherits the receiver's; a freshly-built node mints its own.
+        let seed;
         if (reuseStandingReceiver) {
             const sr = this.#standingReceivers.get(agentName);
             if (!sr) {
@@ -2189,7 +2235,7 @@ export class SessionNodeManager {
                     guidance: "The standing receiver node is initializing (completes within 200ms). Retry the session in a moment.",
                 };
             }
-            ({ node, gater, autoNat } = sr);
+            ({ node, gater, autoNat, seed } = sr);
             gater.setAllowedPeer(counterpartyPeerId);
             // Hand this agent's standing receiver off to this session; a replacement is spun up below.
             this.#standingReceivers.delete(agentName);
@@ -2201,7 +2247,8 @@ export class SessionNodeManager {
                 logger: this.#logger,
             });
             try {
-                node = await this.#factory.createNode({ sessionId, connectionGater: gater, nodeType: "session" });
+                seed = randomBytes(32);
+                node = await this.#factory.createNode({ sessionId, connectionGater: gater, nodeType: "session", transportPrivateKey: seed });
                 await node.start();
             }
             catch (err) {
@@ -2262,7 +2309,7 @@ export class SessionNodeManager {
         // Log observability event (session.node.created)
         //
         // `counterpartySessionPeerId` IS LOGGED because it is recorded here ONCE and never refreshed,
-        // while a standing receiver is rebuilt with a fresh libp2p keypair on every signaling reconnect
+        // while a standing receiver is rebuilt with a fresh libp2p keypair on a lost relay reservation
         // and every lost reservation. If the peer rebuilds between advertising its endpoint and this
         // handoff, we record an identity that no longer exists — and since `newStream` never dials, it
         // only ever looks for an ALREADY-OPEN connection filed under exactly this string, so every send
@@ -2288,6 +2335,7 @@ export class SessionNodeManager {
             counterpartySessionPeerId: counterpartyPeerId,
             autoNat,
         });
+        this.#rememberSessionSeed(agentName, sessionId, seed, counterpartyPeerId, counterpartyPubkey);
         // DAEMON-004: register the content stream handler so inbound content_frames
         // are cross-checked, appended to the daemon-owned tree, and buffered.
         await this.#registerContentHandler(agentName, sessionId, node, counterpartyPubkey);
@@ -2736,7 +2784,7 @@ export class SessionNodeManager {
                     "Close an existing session before starting a new one.",
             };
         }
-        const { node, gater, autoNat } = inboundSr;
+        const { node, gater, autoNat, seed } = inboundSr;
         // AC-015: update gater BEFORE retrieving multiaddr / returning to caller
         gater.setAllowedPeer(initiatorPeerId);
         const peerId = node.getPeerId();
@@ -2747,6 +2795,11 @@ export class SessionNodeManager {
         // pointed at this initiator.
         if (!this.#insertSessionRow(sessionId, agentName, counterpartyPubkey, "active")) {
             this.#standingReceivers.delete(agentName);
+            // DOD-M12B-SESSION-SEED-1 (review F8): this abort happens BEFORE `#rememberSessionSeed`, so
+            // the identity is not being handed to a session — it is being discarded, and is zeroed like
+            // any other discard. (The two PROMOTION sites deliberately do not zero: there the same bytes
+            // become the session's.)
+            inboundSr.seed.fill(0);
             try {
                 await node.stop();
             }
@@ -2792,6 +2845,7 @@ export class SessionNodeManager {
             counterpartySessionPeerId: initiatorPeerId,
             autoNat,
         });
+        this.#rememberSessionSeed(agentName, sessionId, seed, initiatorPeerId, counterpartyPubkey);
         // 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.
@@ -3150,6 +3204,13 @@ export class SessionNodeManager {
         // plaintext must not survive shutdown in memory).
         this.#trees.clear();
         this.#receivedContent.clear();
+        // DOD-M12B-SESSION-SEED-1 (review F5): transport identities are key material and belong in the
+        // same sentence as the plaintext above. Shutdown marks every active row `interrupted` by direct
+        // SQL, so no `#updateSessionStatus` destroy fires for them — without this, every live session's
+        // seed survives the shutdown in memory for as long as the process lingers.
+        for (const identity of this.#sessionSeeds.values())
+            identity.seed.fill(0);
+        this.#sessionSeeds.clear();
         // Stop ALL per-agent standing receivers (DOD-LOOP-1). In PARALLEL and BOUNDED: this was a
         // sequential await per agent with no deadline, so five agents meant five chances for one stuck
         // libp2p teardown to hold the exit — and it sits between the operator being told the daemon is
@@ -3168,6 +3229,10 @@ export class SessionNodeManager {
                 });
             }
         })), "standing_receivers", this.#standingReceivers.size);
+        // Same reason: a receiver's seed is the identity it has already advertised in
+        // `session_offer_accept` for any session it is mid-handshake on.
+        for (const sr of this.#standingReceivers.values())
+            sr.seed.fill(0);
         this.#standingReceivers.clear();
         this.#srReservationRetry.clear();
         this.#srLastRejectionReason.clear();
@@ -3251,6 +3316,211 @@ export class SessionNodeManager {
             messageCount: r.message_count ?? 0,
         }));
     }
+    /**
+     * DOD-M12B-REVIVAL-BOUND-1 — interrupted sessions that can no longer be revived, and must close.
+     *
+     * Andre, 2026-08-18: *"after that, those peer IDs and that peer connection needs to be shut down.
+     * It is an open connection that a malicious agent can farm for."* The tenet is **leave nothing
+     * open that is no longer needed**, and the threat model is a daemon that has been reprogrammed —
+     * so the guarantee has to hold on the side that is not the attacker.
+     *
+     * WHAT IS OPEN. `ingestReceivedContent` refuses `sealed`, `seal_interrupted_pending` and
+     * `abandoned`, but deliberately ACCEPTS `interrupted` — that acceptance is the only reason
+     * recovery can work. Nothing else ever leaves `interrupted`, so it means accepts FOREVER.
+     *
+     * **THIS IS THE BACKSTOP, NOT THE COMPLEMENT.** The seal path gets first refusal on every
+     * local-cause session, because a session whose ending we can describe truthfully earns a
+     * notarized receipt. But "the seal path owns it" is not the same as "the seal path will finish
+     * it", and two populations fall through the gap between those:
+     *
+     *   - **The resolver gave up.** `markRestartSealGaveUp` writes only `restart_seal_gave_up_at`;
+     *     the status stays `interrupted`, and `listRestartOrphanedSessions` then excludes the row by
+     *     `restart_seal_gave_up_at IS NULL` so it is never retried. `TERMINAL_SEAL_REFUSALS` has ten
+     *     entries and the measured figure is that 59% of seals that start never finish, so this is
+     *     the common case, not a corner.
+     *   - **Zero-message local sessions.** The resolver requires `message_count > 0` — a dead
+     *     handshake is not worth a ceremony. It is still an open write surface.
+     *
+     * Excluding those left them permanently interrupted and permanently writable, which is the exact
+     * condition this line exists to end. And the population is about to become the majority: no row
+     * has ever carried `interrupted_by = 'local'` yet, and from the next shutdown onward every
+     * shutdown-orphaned session will. So the sweep takes a local-cause session once the seal path
+     * has either declined it or exhausted it — never before.
+     *
+     * **THE CLOCK MUST BE ONE THE COUNTERPARTY CANNOT MOVE.** The obvious fallback for a row with no
+     * `interrupted_at` is `updated_at` — and it is exactly wrong. `ingestReceivedContent` accepts
+     * content into an `interrupted` session (that acceptance is this whole line's premise), and a
+     * successful ingest runs `UPDATE sessions SET message_count = ?, updated_at = <now>`. So
+     * `updated_at` is a clock the reprogrammed peer holds: one message every 24 hours and the session
+     * never expires, forever. The fallback would have handed the attacker the off switch for the
+     * control built to stop them.
+     *
+     * Instead the missing timestamps are STAMPED ONCE, by `#stampMissingInterruptedAt` immediately
+     * before this query runs, and this query reads `interrupted_at` and nothing else. The stamp is
+     * written under `WHERE interrupted_at IS NULL`, so it is monotone — set once, never moved, by us
+     * and not by a peer. A legacy row therefore gets its full window starting from the first sweep
+     * that sees it, which is later than the true interruption but is the only bound that is sound.
+     *
+     * Same retired-agent INNER JOIN as the sibling query: a retired agent's rows are kept for
+     * accountability, are not resumable, and are not writable either.
+     *
+     * **THE TIME ARITHMETIC IS LOAD-BEARING, AND BOTH OBVIOUS FORMS OF IT ARE WRONG.** These two
+     * columns do not hold the same kind of value:
+     *
+     *   `interrupted_at`  TEXT,    an ISO-8601 string — `new Date(now).toISOString()`.
+     *   `updated_at`      INTEGER, epoch milliseconds.
+     *
+     * There are FOUR writers of `status = 'interrupted'`, not three. The fourth is
+     * `destroySessionNode` → `#updateSessionStatus(…, "interrupted", "local")`, which historically
+     * wrote `interrupted_by` and **no timestamp at all** — and it is the path that produced the two
+     * rows in Entry 41. It now stamps `interrupted_at` like the others, so NULL is a legacy state
+     * rather than one production keeps creating.
+     *
+     * So a bare `interrupted_at <= ?` against a numeric bound is **always false** — the column has
+     * TEXT affinity and the bound parameter has none, so SQLite applies TEXT affinity to the
+     * parameter and compares them as STRINGS (`'2026-08-18T05:32:04.183Z' <= 1755000000000` → 0).
+     * The query silently returns nothing forever and reads as "nothing has expired yet". And
+     * `CAST(interrupted_at AS
+     * INTEGER)` is worse than useless: SQLite casts by taking the leading digits, so
+     * `'2026-08-18T05:32:04Z'` becomes **2026**, which is older than any epoch bound. That form
+     * abandons every interrupted session on the next boot, immediately, whatever its age. It was
+     * written, and `session-001`/`cello-list-sessions` failed on it in the gate.
+     *
+     * `strftime('%s', …) * 1000` parses the ISO string properly and returns NULL for anything it
+     * cannot parse — so a malformed or differently-formatted value falls through the COALESCE to
+     * `updated_at` rather than being read as the year 2026.
+     */
+    listExpiredUnrevivableSessions(nowMs, windowMs) {
+        if (!this.#db) {
+            // ABSENT IS NOT FINE. An empty array here is indistinguishable from "the store is clean",
+            // which is the state this line exists to end — so the one boot where the sweep could not
+            // read the store must not look like the boots where it read it and found nothing.
+            this.#logger.error("session.revival_bound.enumerate.failed", {
+                error: "db not initialized",
+                impact: "no interrupted session was checked against the revival window this boot; any that "
+                    + "have expired are still accepting content",
+            });
+            return [];
+        }
+        const rows = this.#db
+            .prepare(`SELECT s.session_id AS session_id, s.interrupted_by AS cause, a.agent_name AS agent_name
+         FROM sessions s JOIN agents a ON a.agent_id = s.agent_id
+         WHERE s.status = 'interrupted' AND a.state != 'retired'
+           AND (COALESCE(s.interrupted_by, '') != 'local'
+                OR s.restart_seal_gave_up_at IS NOT NULL
+                OR s.message_count = 0)
+           AND CAST(strftime('%s', s.interrupted_at) AS INTEGER) * 1000 <= ?
+         ORDER BY CAST(strftime('%s', s.interrupted_at) AS INTEGER) * 1000 ASC`)
+            .all(nowMs - windowMs);
+        return rows.map((r) => ({ agentName: r.agent_name, sessionId: r.session_id, cause: r.cause }));
+    }
+    /**
+     * DOD-M12B-REVIVAL-BOUND-1 — give every timestamp-less interrupted session a clock, once.
+     *
+     * A row with `interrupted_at IS NULL` has no bound that can be evaluated, and skipping such rows
+     * would exempt the oldest sessions in the store from the control permanently — the same "open
+     * forever" failure wearing a different NULL. The two rows measured in Entry 41 are exactly this
+     * shape, written by a `destroySessionNode` path that set the cause and no timestamp.
+     *
+     * **`WHERE interrupted_at IS NULL` is the security property, not an optimisation.** It makes the
+     * stamp write-once: this can run on every sweep forever and a row's clock still cannot be moved
+     * after the first one. That is what disqualifies `updated_at`, which a peer moves with every
+     * message it sends into the still-accepting session.
+     *
+     * The cost is honest and bounded: a legacy row's window starts at the first sweep that sees it
+     * rather than at its true interruption, so it survives up to one window longer than it should.
+     * A late close is recoverable; a clock the counterparty winds is not.
+     *
+     * @returns how many rows were stamped.
+     */
+    #stampMissingInterruptedAt(nowMs) {
+        if (!this.#db)
+            return 0;
+        try {
+            const res = this.#db
+                .prepare("UPDATE sessions SET interrupted_at = ? WHERE status = 'interrupted' AND interrupted_at IS NULL")
+                .run(new Date(nowMs).toISOString());
+            const stamped = Number(res?.changes ?? 0);
+            if (stamped > 0) {
+                this.#logger.info("session.revival_bound.clock.stamped", {
+                    stamped,
+                    impact: "these sessions had no interruption timestamp; their revival window starts now",
+                });
+            }
+            return stamped;
+        }
+        catch (err) {
+            this.#logger.error("session.revival_bound.clock.stamp.failed", {
+                error: err instanceof Error ? err.message : String(err),
+                impact: "sessions with no interruption timestamp cannot be evaluated and stay open",
+            });
+            return 0;
+        }
+    }
+    /**
+     * DOD-M12B-REVIVAL-BOUND-1 — close every session the revival window has expired.
+     *
+     * `abandonSession` is the right instrument and already exists: it flips the status FIRST and
+     * synchronously, annexes held content so the operator does not lose mail that has nowhere to go,
+     * and retires the node. It notarizes nothing, which is the point — we are closing a door, not
+     * asserting how it came to be open.
+     *
+     * One session's failure must not strand the rest, so each is caught and logged; the sweep runs at
+     * boot beside the restart-seal resolver and a throw there would take the daemon with it.
+     *
+     * @returns how many sessions actually flipped — not how many were attempted.
+     */
+    async closeExpiredUnrevivableSessions(nowMs, windowMs) {
+        // Stamp FIRST. A row with no clock cannot be evaluated by the query below, and this is the only
+        // thing that gives it one. Running it before every sweep is safe because the write is scoped to
+        // rows that have no timestamp yet.
+        this.#stampMissingInterruptedAt(nowMs);
+        const expired = this.listExpiredUnrevivableSessions(nowMs, windowMs);
+        let closed = 0;
+        for (const s of expired) {
+            try {
+                if (await this.abandonSession(s.agentName, s.sessionId)) {
+                    closed += 1;
+                    this.#logger.info("session.revival_bound.closed", {
+                        agentName: s.agentName,
+                        sessionId: s.sessionId,
+                        // The cause we could NOT establish is the reason this ends without a receipt — log it
+                        // so an operator asking "why no certificate?" gets the answer here.
+                        interruptedBy: s.cause ?? "unknown",
+                        windowMs,
+                        // NAME THE FORFEIT. Until this sweep ran, `cello_close_session` (without `force`) still
+                        // accepted this session — it takes `status IN ('active','interrupted')` — so the
+                        // operator could have come back days later and obtained a real seal. `abandoned` is in
+                        // TERMINAL_SEAL_REFUSALS, so after this they cannot. That is a deliberate trade (SI-001
+                        // forbids auto-sealing a session nobody chose to end) and it costs something real, so
+                        // it is stated rather than left implicit in a WHERE clause.
+                        forfeited: "a seal was still obtainable by hand until now; it is not after this",
+                    });
+                }
+            }
+            catch (err) {
+                this.#logger.warn("session.revival_bound.close.failed", {
+                    agentName: s.agentName,
+                    sessionId: s.sessionId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        // UNCONDITIONAL. A sweep that found nothing and a sweep that never really ran must not produce
+        // the same silence — this line is the only proof the control executed at all.
+        this.#logger.info("session.revival_bound.sweep", { expired: expired.length, closed, windowMs });
+        if (closed !== expired.length) {
+            // Not arithmetic for the reader to do: a session the security control failed to close is one
+            // that is still interrupted and still accepting content.
+            this.#logger.warn("session.revival_bound.sweep.incomplete", {
+                expired: expired.length,
+                closed,
+                failed: expired.length - closed,
+                impact: "these sessions are still interrupted and still accept content from any peer that dials them",
+            });
+        }
+        return closed;
+    }
     /**
      * DOD-M12B-RESTART-SEAL-1 — record that automatic sealing has exhausted this session.
      *
@@ -3562,7 +3832,18 @@ export class SessionNodeManager {
         const result = this.#db
             .prepare("UPDATE sessions SET status = 'seal_interrupted_pending', updated_at = ? WHERE agent_id = ? AND session_id = ? AND status IN ('active', 'interrupted')")
             .run(now, this.#requireAgentId(opts.agentName), opts.sessionId);
-        return Number(result.changes) > 0;
+        const landed = Number(result.changes) > 0;
+        if (landed) {
+            // DOD-M12B-SESSION-SEED-1 (review F3): `seal_interrupted_pending` is NOT a state revival
+            // exists for, and the first build's comment wrongly grouped it with `interrupted`.
+            // `ingestReceivedContent` refuses it outright, and BOTH sweeps that could otherwise close a
+            // session — `listRestartOrphanedSessions` and `listExpiredUnrevivableSessions` — filter
+            // `status = 'interrupted'`, so a pending-seal session is unrevivable AND unswept. Keeping its
+            // identity meant holding it until the process exited. Entry 42's own measurement is that 59%
+            // of seals that start never finish, so that is the common path, not a corner.
+            this.#destroySessionSeed(opts.agentName, opts.sessionId);
+        }
+        return landed;
     }
     /**
      * M7-SESSION-001 (H-1): read back the persisted bilateral commitment artifacts
@@ -4112,9 +4393,12 @@ export class SessionNodeManager {
             // like a protocol mystery for a night.
             //
             // `counterpartySessionPeerId` is the load-bearing field. It is recorded ONCE at session
-            // establishment and never refreshed, while a standing receiver is rebuilt with a fresh keypair
-            // on every signaling reconnect — so if the two ever cross, every send goes one-way forever and
-            // nothing says so. With this line that becomes a single grep instead of a night.
+            // establishment and never refreshed. (CORRECTED 2026-08-18: this used to say a standing
+            // receiver is rebuilt "on every signaling reconnect" — it is not. `ensureStandingReceiverForAgent`
+            // no-ops on a healthy receiver; the only rebuild triggers are a LOST RELAY RESERVATION and the
+            // one-shot upgrade when relay endpoints first arrive.) If the two ever cross, every send goes
+            // one-way forever and nothing says so. With this line that becomes a single grep instead of a
+            // night.
             this.#logger.warn("session.content.direct.send.failed", {
                 agentName,
                 sessionId,
@@ -6882,6 +7166,22 @@ export class SessionNodeManager {
             const sr = this.#standingReceivers.get(agentName);
             if (sr) {
                 this.#standingReceivers.delete(agentName);
+                /**
+                 * DOD-M12B-SESSION-SEED-1 (review F8): drop it zeroed, like every other seed.
+                 *
+                 * (review F7, DECIDED AGAINST — deliberately NOT reusing this seed for the replacement.)
+                 * Reuse is attractive: this receiver's peer id may already be inside a `session_offer_accept`
+                 * the counterparty is acting on, and a rebuild in that window is the documented "we record
+                 * an identity that no longer exists… every send in this direction parks forever" defect. But
+                 * a preserved identity would have to be handed to the candidate loop in
+                 * `#startReceiverNode`, whose rejected candidates are stopped WITHOUT awaiting `start()` —
+                 * so two nodes could be briefly live on one advertised peer id, which is review F1, a HIGH,
+                 * and the reason each candidate now mints its own. Fixing F7 properly means bounding and
+                 * awaiting the loser's teardown first, and an unawaited stop is precisely what the current
+                 * code chose to avoid a stuck libp2p teardown blocking receiver creation. Filed as
+                 * follow-on work rather than trading a MEDIUM fix for a HIGH regression.
+                 */
+                sr.seed.fill(0);
                 try {
                     sr.autoNat.stop();
                     await sr.node.stop();
@@ -7166,11 +7466,25 @@ export class SessionNodeManager {
      */
     async #startReceiverNode(agentName, sessionId, gater, candidateCircuitAddrs, correlationId) {
         for (const circuitAddr of candidateCircuitAddrs) {
+            // DOD-M12B-SESSION-SEED-1: A SEED PER CANDIDATE, NOT ONE FOR THE LOOP.
+            //
+            // A rejected candidate is stopped with an unawaited `void …then(() => candidate.stop())`
+            // while its `start()` may still be in flight, so two candidate nodes can briefly be live at
+            // once. Sharing one seed would give both the SAME peer id — and the loser would then be a
+            // second live node under the identity we advertise in `session_offer_accept`, sharing this
+            // gater (so it admits dials) with no content handler registered. Inbound arriving there goes
+            // nowhere, and it is an open endpoint under our advertised id: the "connection a malicious
+            // agent can farm for" the tenet names. Before seeds existed the loser had its own random key
+            // and was harmless; introducing a shared seed is what would have made it dangerous.
+            //
+            // Nothing reads the seed before the winner is installed, so per-candidate costs nothing.
+            const candidateSeed = randomBytes(32);
             const candidate = await this.#factory.createNode({
                 sessionId,
                 connectionGater: gater,
                 nodeType: "standing_receiver",
                 circuitRelayListenAddrs: [circuitAddr],
+                transportPrivateKey: candidateSeed,
             });
             let timer;
             const timedOut = Symbol("reservation_timeout");
@@ -7196,7 +7510,7 @@ export class SessionNodeManager {
             // completes the handshake and simply grants nothing, leaving a node that looks
             // started and is reachable by nobody.
             if (outcome === "started" && candidate.listenAddresses().some((a) => a.includes("/p2p-circuit"))) {
-                return candidate;
+                return { node: candidate, seed: candidateSeed };
             }
             const rejectionReason = outcome === "started"
                 ? "relay_granted_no_reservation"
@@ -7217,13 +7531,15 @@ export class SessionNodeManager {
                 .then(() => candidate.stop())
                 .catch(() => { });
         }
+        const plainSeed = randomBytes(32);
         const plain = await this.#factory.createNode({
             sessionId,
             connectionGater: gater,
             nodeType: "standing_receiver",
+            transportPrivateKey: plainSeed,
         });
         await plain.start();
-        return plain;
+        return { node: plain, seed: plainSeed };
     }
     /** One standing-receiver create attempt (extracted for the M8B F14 retry loop). */
     async #tryCreateStandingReceiver(agentName, correlationId) {
@@ -7242,8 +7558,21 @@ export class SessionNodeManager {
             gater.setAllowedOutboundPeer(relayPeerId);
         }
         let node;
+        /**
+         * DOD-M12B-SESSION-SEED-1 — the transport identity of the receiver that actually survived.
+         *
+         * Minted per CANDIDATE inside `#startReceiverNode` and returned with the winner, not minted
+         * here: a rejected candidate is stopped without awaiting its `start()`, so two candidates can
+         * be briefly live, and one shared seed would put both on the same advertised peer id.
+         *
+         * FRESH EVERY TIME, which is the privacy property rather than an implementation detail. A
+         * receiver serves at most one session (it is promoted into the session at handoff and replaced),
+         * so no identifier is ever shared between two sessions and the 2026-04-11 rationale —
+         * unlinkability of an agent's sessions to a passive observer — survives intact.
+         */
+        let seed;
         try {
-            node = await this.#startReceiverNode(agentName, sessionId, gater, reservations.addrs, correlationId);
+            ({ node, seed } = await this.#startReceiverNode(agentName, sessionId, gater, reservations.addrs, correlationId));
         }
         catch (err) {
             // extractErrorMessage, NOT String(err): the transport throws structured
@@ -7314,6 +7643,7 @@ export class SessionNodeManager {
             node,
             gater,
             autoNat,
+            seed,
             hasReservation: circuitAddrs > 0,
             ...(reservedRelayPeerId !== undefined ? { relayPeerId: reservedRelayPeerId } : {}),
         });
@@ -7355,6 +7685,303 @@ export class SessionNodeManager {
      * M8B F14: also called from the inbound accept path (ensure on demand). Marks the agent as
      * WANTING a receiver, which arms the teardown re-arm in destroySessionNode/retireSessionNode.
      */
+    /**
+     * DOD-M12B-SESSION-SEED-1 test seam: the seed the agent's current standing receiver holds.
+     *
+     * The property under test — "the receiver built behind a promoted one never reuses its seed" — is
+     * about an identity that by design never leaves the process, so there is no observable surface for
+     * it short of a live two-node dial. Reading it here is the narrowest way to pin it.
+     */
+    /** DOD-M12B-SESSION-SEED-1: record the identity this session must be able to return at. */
+    #rememberSessionSeed(agentName, sessionId, seed, counterpartyPeerId, counterpartyPubkey) {
+        const key = this.#k(agentName, sessionId);
+        // Defensive: unreachable today because `insertSessionRow` PK-conflicts on a repeat, but an
+        // 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 });
+    }
+    /**
+     * DOD-M12B-SESSION-SEED-1 — destroy a session's transport identity.
+     *
+     * Called from `#updateSessionStatus` on a terminal status, in the SAME step that writes it, so
+     * there is no window in which a session is closed on paper and still revivable in memory.
+     *
+     * **WHAT THE ZERO-FILL DOES AND DOES NOT DO** — checked against the derivation, not assumed.
+     * `createNode` hands the buffer to `generateKeyPairFromSeed`, and `@libp2p/crypto` COPIES it
+     * (`uint8arrayConcat([seed, publicKeyRaw])`, then `Uint8Array.from`). Two consequences:
+     *   - zeroing after the node has started is SAFE — the running node holds its own copy;
+     *   - it does NOT erase the key from the heap. An identical usable copy is the first 32 bytes of
+     *     `privateKey.raw` on the node object until that node is dropped.
+     * So this removes OUR long-lived copy — the one that would otherwise sit in a map for the life of
+     * the process, decoupled from any node — and that is worth doing. It is not a heap scrub, and
+     * the DoD already says the bound rather than secrecy is the control.
+     */
+    #destroySessionSeed(agentName, sessionId) {
+        const key = this.#k(agentName, sessionId);
+        const identity = this.#sessionSeeds.get(key);
+        if (identity === undefined)
+            return;
+        identity.seed.fill(0);
+        this.#sessionSeeds.delete(key);
+        this.#logger.debug("session.seed.destroyed", { agentName, sessionId });
+    }
+    /**
+     * DOD-M12B-SESSION-SEED-1 — bring an interrupted session back on the peer id it already has.
+     *
+     * THE DEFECT THIS CLOSES. `markInterruptedWithDetails` and `destroySessionNode` stop the node and
+     * delete it from `#activeNodes`, and until now **nothing anywhere recreated one**. A laptop-close
+     * session stayed stuck even though both processes were alive and both keypairs were still in
+     * memory — the trace on 2026-08-17 found no missing transport capability, just a missing edge.
+     *
+     * TWO THINGS HAVE TO HAPPEN, and doing only one leaves the session exactly as stuck:
+     *   1. the NODE comes back, at the same peer id, or the counterparty can never dial us again;
+     *   2. the STATUS comes back to `active`, or every send still refuses with `session_not_active`.
+     *
+     * **DEMAND-DRIVEN ONLY.** Nothing calls this on a timer. That is the `REDIAL-1` discipline and it
+     * is also Andre's tenet — a background rebuilder would hold a dialable endpoint open for a session
+     * nobody is using, which is the "open connection a malicious agent can farm for" in as many words.
+     *
+     * **TERMINAL IS TERMINAL.** A sealed or abandoned session had its seed zeroed in the same step
+     * that wrote its status, so there is nothing to come back on. This refuses by name rather than
+     * minting a fresh identity — a revival that quietly mints would hand one session a second peer id
+     * and break the invariant while appearing to work.
+     *
+     * Idempotent: a session that already has a live node returns ok without building a second one.
+     */
+    async reviveSessionNode(agentName, sessionId) {
+        const key = this.#k(agentName, sessionId);
+        const live = this.#activeNodes.get(key);
+        if (live)
+            return { ok: true, peerId: live.node.getPeerId() };
+        const record = this.getSessionRecord(agentName, sessionId);
+        if (!record)
+            return { ok: false, reason: "session_not_found" };
+        if (record.status === "sealed" || record.status === "abandoned" || record.status === "seal_interrupted_pending") {
+            return {
+                ok: false,
+                reason: "session_terminal",
+                guidance: `Session is '${record.status}'. A session that has ended cannot be revived; start a new one.`,
+            };
+        }
+        const identity = this.#sessionSeeds.get(key);
+        if (identity === undefined) {
+            // The honest case: the daemon restarted, so the keypair is genuinely gone. That is
+            // RESTART-SEAL-1's territory (resolve with a receipt), not a revival — and saying so is the
+            // difference between an operator waiting for a reconnect that cannot happen and one closing
+            // the session.
+            return {
+                ok: false,
+                reason: "session_identity_lost",
+                guidance: "This session's transport identity did not survive a daemon restart, so it cannot be " +
+                    "revived. It will be sealed automatically, or you can close it now to get its receipt.",
+            };
+        }
+        const gater = new SessionConnectionGater({
+            sessionId,
+            allowedPeerId: identity.counterpartyPeerId,
+            logger: this.#logger,
+        });
+        // The relay peers must be allowed OUTBOUND before the node starts, or the reservation the line
+        // below depends on is refused by our own gater — the same ordering the receiver builder uses.
+        const reservations = this.#reservationCircuitAddrs(agentName);
+        for (const relayPeerId of reservations.relayPeerIds)
+            gater.setAllowedOutboundPeer(relayPeerId);
+        let node;
+        try {
+            node = await this.#factory.createNode({
+                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 } : {}),
+            });
+            await node.start();
+        }
+        catch (err) {
+            this.#logger.error("session.revive.node.failed", {
+                agentName,
+                sessionId,
+                error: err instanceof Error ? err.message : String(err),
+                impact: "the session stays interrupted; the next send will attempt this again",
+            });
+            return { ok: false, reason: "session_node_creation_failed" };
+        }
+        const autoNat = new NodeAutoNatService({
+            node,
+            logger: this.#logger,
+            nodeType: "session",
+            probers: this.#autoNatProbers(),
+        });
+        autoNat.emitInitialResult();
+        const correlationId = randomUUID();
+        this.#activeNodes.set(key, {
+            node,
+            agentName,
+            sessionId,
+            counterpartyPubkey: identity.counterpartyPubkey,
+            gater,
+            correlationId,
+            counterpartySessionPeerId: identity.counterpartyPeerId,
+            autoNat,
+        });
+        await this.#registerContentHandler(agentName, sessionId, node, identity.counterpartyPubkey);
+        /**
+         * review HIGH-2 — REWIRE LIVENESS, or this session can never be interrupted again.
+         *
+         * Both creation paths call this; the first build of the revival did not. Without it the revived
+         * session is pinned `active`: a later disconnect fires no transition, no `session_state_changed`
+         * reaches the MCP client, and the receive surface renders unknown liveness as healthy-and-quiet.
+         * So the SECOND laptop close would leave the operator staring at a session that reports fine and
+         * is dead — this milestone's founding defect, one revival later, and with no status change left
+         * to trigger the next revival either.
+         */
+        this.#wireSessionLiveness(agentName, sessionId, node, identity.counterpartyPubkey, correlationId, identity.counterpartyPeerId);
+        // 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.
+        //
+        // review MEDIUM-3: the result is CHECKED. `#updateSessionStatus` returns false when the write
+        // matched no row or the DB errored — and reporting revival ok on a row that still says
+        // `interrupted` leaves a live, talking session where REVIVAL-BOUND-1's sweep can seal or abandon
+        // it. Failing here means tearing the node back down rather than running in that split state.
+        if (!this.#updateSessionStatus(agentName, sessionId, "active")) {
+            this.#activeNodes.delete(key);
+            try {
+                await node.stop();
+            }
+            catch { /* best-effort: the status write already failed and is logged with its cause */ }
+            return {
+                ok: false,
+                reason: "session_status_write_failed",
+                guidance: "The session node was rebuilt but its status could not be written, so it was torn back " +
+                    "down rather than left live under an interrupted row. The daemon logged the cause.",
+            };
+        }
+        const peerId = node.getPeerId();
+        this.#logger.info("session.revived", {
+            agentName,
+            sessionId,
+            peerId,
+            // The whole claim of this line, in the log: the id did not change, so the counterparty's
+            // stored dial target is still correct and they do not need to be told anything.
+            identityPreserved: true,
+        });
+        return { ok: true, peerId };
+    }
+    /**
+     * 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
+     * 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.
+     *
+     * A no-op for the normal case. An `active` session with a live node returns immediately without
+     * touching it — this sits on the hot path of every send, and replacing a healthy node would be
+     * churn that changes the peer id for no reason.
+     */
+    async reviveIfNeededForSend(agentName, sessionId) {
+        const record = this.getSessionRecord(agentName, sessionId);
+        if (!record)
+            return { ok: false, reason: "session_not_found" };
+        // The overwhelmingly common case: nothing to do, and no node was disturbed to find that out.
+        if (record.status === "active" && this.#activeNodes.has(this.#k(agentName, sessionId)))
+            return { ok: true };
+        const revived = await this.reviveSessionNode(agentName, sessionId);
+        if (!revived.ok) {
+            this.#logger.info("session.revive.declined", {
+                agentName,
+                sessionId,
+                previousStatus: record.status,
+                trigger: "send",
+                reason: revived.reason,
+            });
+            return revived;
+        }
+        this.#logger.info("session.revived.on_demand", {
+            agentName,
+            sessionId,
+            previousStatus: record.status,
+            trigger: "send",
+        });
+        return { ok: true };
+    }
+    /**
+     * DOD-M12B-SESSION-SEED-1 (case B) — the INBOUND half of the demand edge.
+     *
+     * `reviveIfNeededForSend` covers the operator waking first. Case B's triggers are symmetric — a
+     * wifi hop, a relay restart, a directory node cycling — so half the time the COUNTERPARTY wakes
+     * first. They send; we have no node yet, because revival is demand-driven and we have demanded
+     * nothing. Their content parks at the relay, which is the backstop working as designed.
+     *
+     * Then the operator comes back and READS, and until now that told them nothing: the receive
+     * handler reads the transcript and never gates on status, so it happily reports what is already
+     * stored while messages sit parked, waiting for a node that will not exist until the operator
+     * happens to SEND. An operator who only reads was stuck forever with a surface that looked fine.
+     *
+     * **WHY A READ MAY TRIGGER THIS AND AN INBOUND DIAL MAY NOT.** Andre's tenet is about what a
+     * REMOTE party can cause: *"an open connection that a malicious agent can farm for."* Reviving
+     * because a peer dialled us would hand that lever straight to the peer — a stranger could keep our
+     * endpoints open indefinitely by poking dead sessions. A read is the OPERATOR asking, on their own
+     * machine, for their own session: the same class of demand as a send, and the class the tenet
+     * allows. That distinction is the whole reason this is a separate entry point rather than a
+     * revival triggered from the inbound handler.
+     */
+    async reviveIfNeededForRead(agentName, sessionId) {
+        const record = this.getSessionRecord(agentName, sessionId);
+        if (!record)
+            return { ok: false, reason: "session_not_found" };
+        if (record.status === "active" && this.#activeNodes.has(this.#k(agentName, sessionId)))
+            return { ok: true };
+        // Reading the transcript of an ended session is normal and must keep working — the CALLER does
+        // not treat this refusal as an error, it just reads what is stored. What must not happen is the
+        // read bringing the session back: the receipt is issued and the identity is gone.
+        const revived = await this.reviveSessionNode(agentName, sessionId);
+        if (!revived.ok) {
+            // review MEDIUM-4: the absence of a success line was the only signal that a session could not
+            // come back. `session_identity_lost` is the one an operator most needs, and it was generated
+            // and destroyed one stack frame later with nothing written down.
+            this.#logger.info("session.revive.declined", {
+                agentName,
+                sessionId,
+                previousStatus: record.status,
+                trigger: "read",
+                reason: revived.reason,
+            });
+            return revived;
+        }
+        this.#logger.info("session.revived.on_demand", {
+            agentName,
+            sessionId,
+            previousStatus: record.status,
+            trigger: "read",
+        });
+        // Fetch what is waiting NOW. Review MEDIUM-5 corrected the claim this used to make: the drain
+        // runs off the AGENT's standing receiver, not the session node, and the 5-minute backstop would
+        // have delivered this content anyway. So this is an accelerator, not a rescue — worth having,
+        // and worth describing accurately. (The send path deliberately does not fire one: the same
+        // backstop covers it, at a cost of at most one interval.)
+        this.#fireParkedDrain(agentName, "session_revived");
+        return { ok: true };
+    }
+    /** 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 test seam: does this session still hold a revivable identity? */
+    hasSessionSeedForTest(agentName, sessionId) {
+        return this.#sessionSeeds.has(this.#k(agentName, sessionId));
+    }
+    getStandingReceiverSeedForTest(agentName) {
+        return this.#standingReceivers.get(agentName)?.seed;
+    }
     async ensureStandingReceiverForAgent(agentName) {
         this.#agentsWantingReceiver.add(agentName);
         this.#startReservationWatchdog();
@@ -7385,7 +8012,11 @@ export class SessionNodeManager {
                 this.#standingReceiverRemoving.add(agentName);
             return;
         }
+        const removed = this.#standingReceivers.get(agentName);
         this.#standingReceivers.delete(agentName);
+        // DOD-M12B-SESSION-SEED-1 (review F8): the operator took this agent offline — its advertised
+        // identity is not needed any more, and the tenet's rule is that nothing unneeded stays live.
+        removed?.seed.fill(0);
         // Best-effort teardown, but NOT silent: a standing receiver that failed to stop keeps a libp2p
         // node live on the network. For a removal/retire (a revocation-class action) that must be visible,
         // so the caller and the operator can see the leak rather than trust a false "torn down". autoNat is
@@ -7522,6 +8153,26 @@ export class SessionNodeManager {
     interruptedBy) {
         if (!this.#db)
             return false;
+        /**
+         * DOD-M12B-SESSION-SEED-1 (review F2) — the identity dies on terminal INTENT, not on a
+         * successful UPDATE.
+         *
+         * The first build destroyed the seed only after the write landed. `#requireAgentId` THROWS for
+         * a retired agent, so every terminal write for a revoked agent's sessions fell into the catch
+         * and kept its transport identity for the life of the process — an identity whose agent has
+         * just been revoked in the directory, held with nothing reporting it, and REVIVAL-BOUND-1's
+         * sweep excludes retired agents so nothing else closed it either. The same held for a
+         * `session.status.write.missed` and for any DB error.
+         *
+         * Coupling a security teardown to a database write is backwards: the write can fail, and the
+         * failure is exactly when we least want a live key lying around. So it runs FIRST and
+         * unconditionally, and if the write then fails the session is one we can no longer revive —
+         * which is the safe direction, and is reported loudly below rather than inferred from the
+         * absence of a debug line.
+         */
+        if (status === "sealed" || status === "abandoned") {
+            this.#destroySessionSeed(agentName, sessionId);
+        }
         // THE TERMINAL GUARD LIVES HERE, not in one wrapper, because there are three writers of
         // "sealed": markSealed, destroySessionNode, and retireSession on the witnessed-submit path.
         // Guarding only the wrapper asserts the invariant in a test while two other paths still break
@@ -7557,10 +8208,22 @@ export class SessionNodeManager {
         const now = Date.now();
         try {
             const res = this.#db
-                .prepare(interruptedBy === undefined
-                ? "UPDATE sessions SET status = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?"
-                : "UPDATE sessions SET status = ?, updated_at = ?, interrupted_by = 'local' WHERE agent_id = ? AND session_id = ?")
-                .run(status, now, this.#requireAgentId(agentName), sessionId);
+                .prepare(
+            // DOD-M12B-REVIVAL-BOUND-1: this is the FOURTH writer of `status = 'interrupted'`, and
+            // until now the only one that wrote no `interrupted_at`. That is where Entry 41's two
+            // timestamp-less rows came from, and a row with no timestamp has no revival bound that
+            // can be evaluated. `COALESCE` matches the three sibling producers: the FIRST
+            // interruption is the clock, so re-entering the status cannot push the deadline out.
+            status === "interrupted"
+                ? (interruptedBy === undefined
+                    ? "UPDATE sessions SET status = ?, updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?) WHERE agent_id = ? AND session_id = ?"
+                    : "UPDATE sessions SET status = ?, updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?), interrupted_by = 'local' WHERE agent_id = ? AND session_id = ?")
+                : (interruptedBy === undefined
+                    ? "UPDATE sessions SET status = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?"
+                    : "UPDATE sessions SET status = ?, updated_at = ?, interrupted_by = 'local' WHERE agent_id = ? AND session_id = ?"))
+                .run(...(status === "interrupted"
+                ? [status, now, new Date(now).toISOString(), this.#requireAgentId(agentName), sessionId]
+                : [status, now, this.#requireAgentId(agentName), sessionId]));
             // "Did not throw" is NOT "landed". An UPDATE whose WHERE matches no row — a wrong agent_id, a
             // session_id with no row — succeeds silently and changes nothing. Reporting that as a written
             // status flip is what let a disposition hook delete a live session's content, so the row count
@@ -7571,7 +8234,11 @@ export class SessionNodeManager {
                     sessionId,
                     status,
                     agentName,
-                    impact: "no session row matched — the status was NOT changed and no disposition was run",
+                    impact: (status === "sealed" || status === "abandoned")
+                        ? "no session row matched — the status was NOT changed and no disposition was run, AND "
+                            + "this session's transport identity has already been destroyed, so it can no longer "
+                            + "be revived even though its row still says it is open"
+                        : "no session row matched — the status was NOT changed and no disposition was run",
                 });
                 return false;
             }