@cello-protocol/daemon 0.0.53 → 0.0.55

package/dist/session-node-manager.js

@@ -8,73 +8,26 @@
  *   2. Standing receiver node: pre-created, open gater, kept alive at all times.
  *      Handed to the first inbound session; immediately replaced.
  *   3. 32-node cap: enforced before any new node is created.
- *   4. Session status in SQLite: active → sealed (on close) or interrupted
+ *   4. Session status in the DB: active → sealed (on close) or interrupted
  *      (on graceful shutdown or SIGKILL-restart detection).
  *
- * Pseudocode (SPARC Phase P):
- *
- * initialize():
- *   1. Open SQLite (node:sqlite), create sessions table if not exists
- *   2. Detect interrupted sessions: SELECT * FROM sessions WHERE status='active'
- *      → batch-update to 'interrupted', log session.interrupted.detected for each
- *      (source: 'daemon_restart') — runs before IPC socket opens so no race
- *   3. Create standing receiver node (fresh libp2p, open gater, sentinel agentName)
- *   4. Start standing receiver, set standingReceiverReady=true
- *   5. Log session.node.created for the standing receiver
- *
- * createSessionNode(sessionId, agentName, counterpartyPubkey, counterpartyPeerId, correlationId):
- *   Pseudocode:
- *   1. Check activeNodes.size >= MAX_SESSION_NODES → log cap.reached, return error
- *   2. Create SessionConnectionGater(counterpartyPeerId) — restricted from birth
- *   3. nodeFactory.createNode({gater}) → fresh libp2p node
- *   4. node.start() — bind TCP ephemeral port
- *   5. Insert SQLite row status='active'
- *   6. Log session.node.created
- *   7. Add to activeNodes map
- *   8. Return {ok:true, peerId, addrs}
- *   On libp2p error: extract error.message (never ${error}), log create.failed, return error
- *
- * acceptSession(sessionId, agentName, counterpartyPubkey, initiatorPeerId, correlationId):
- *   Pseudocode:
- *   1. If !standingReceiverReady → return standing_receiver_unavailable
- *   2. Take standing receiver from slot (clear slot atomically)
- *   3. gater.setAllowedPeer(initiatorPeerId) ← BEFORE returning multiaddr (AC-015)
- *   4. Insert SQLite row status='active'
- *   5. Log session.node.created
- *   6. Add to activeNodes map
- *   7. Trigger async replacement of standing receiver (do NOT await)
- *   8. Return {ok:true, peerId, addrs}
- *
- * destroySessionNode(sessionId, reason):
- *   Pseudocode:
- *   1. Find node in activeNodes
- *   2. stop node
- *   3. Update SQLite status to sealed/interrupted/error
- *   4. Remove from activeNodes
- *   5. Log session.node.destroyed
- *
- * gracefulShutdown():
- *   Pseudocode:
- *   1. Get all activeNodes
- *   2. For each: update SQLite 'interrupted', log destroyed(reason:'interrupted')
- *   3. Stop all nodes
- *   4. Stop standing receiver
- *
- * getStatus(): { standingReceiverReady: boolean }
+ * Interrupted-session detection runs BEFORE the IPC socket opens, so a client cannot observe a
+ * stale 'active' row from a previous process.
  */
-// CELLO-M7-PERSIST-002 (DEC-1): the daemon DB is a SQLCipher database (whole-file AES-256 at rest).
-// `DaemonDatabase` is the thin varargs surface the daemon uses; `openEncryptedDatabase` opens with a
-// PRAGMA key and `resolveDbKey` manages the single plaintext key file (DEC-2). The whole-DB cipher
-// supersedes the old per-column transcript cipher (AC-010).
+// The daemon DB is SQLCipher (whole-file AES-256 at rest), never `node:sqlite`. `DaemonDatabase` is
+// the thin varargs surface; `openEncryptedDatabase` opens with a PRAGMA key and `resolveDbKey`
+// manages the single plaintext key file.
 import { openEncryptedDatabase, resolveDbKey, dbKeyPathFor, } from "./sqlcipher-db.js";
 import { migrateToEncryptedIfNeeded } from "./identity-migration.js";
 import { ensureIdentitySchema } from "./db-identity-store.js";
 import { migrateSessionTablesToAgentId } from "./agent-id-migration.js";
 import { TIER, normalizeTier, isKnownTierValue, tierBoundsFor, DEFAULT_TIER_BOUNDS, migrateContactsAddTierMetadata } from "./contacts-tier-migration.js";
+import { migrateCborBlobsToCanonical } from "./cbor-blob-migration.js";
 import { boundSettingKey, settableTierName, isValidSettingKey, awayTierSettingKey, AWAY_DEFAULT_KEY } from "./agent-settings-keys.js";
 import { randomUUID, createHash } from "node:crypto";
 import * as lp from "it-length-prefixed";
-import { decode, Encoder } from "cbor-x";
+import { decode } from "cbor-x";
+import { encodeCbor } from "@cello-protocol/protocol-types";
 import { MAX_SESSION_NODES, STANDING_RECEIVER_AGENT_NAME } from "./types.js";
 import { SessionConnectionGater } from "./session-connection-gater.js";
 import { SessionTree } from "./session-tree.js";
@@ -82,17 +35,16 @@ import { CELLO_CONTENT_PROTOCOL_ID, NodeAutoNatService } from "@cello-protocol/t
 import { verify } from "@cello-protocol/crypto";
 import { encodeSealPayload, MONIKER_RE, validateMoniker } from "@cello-protocol/protocol-types";
 import { decodeParkEnvelope, authenticateParkedEntry, pubkeyMatchesHex } from "./park-envelope.js";
-import { AgentRelayClient, LEAF_KIND_CTRL } from "./session-relay-client.js";
+import { isValidMultiaddr } from "@cello-protocol/transport";
+import { AgentRelayClient, LEAF_KIND_CTRL, extractErrorMessage } from "./session-relay-client.js";
 import { RelayReceiptStore } from "./relay-receipt-store.js";
 import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
 import { PassthroughGatewayClient, GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT, } from "@cello-protocol/gateway";
-const CBOR_ENC = new Encoder({ tagUint8Array: false });
 /** SEC-1 / review M4: cap on the refused-parked-entry memo (remote-fed → must be bounded). */
 const MAX_REFUSED_PARKED_ENTRIES = 512;
-// M8C-ABUSE-1 + DOD-TIER-2: persistence bounds. Formerly a binary "known contacts exempt entirely,
-// everyone else 3 sessions / 25 MB"; now TIER-GRADUATED via DEFAULT_TIER_BOUNDS (contacts-tier-
-// migration). The two consts below are kept for back-compat but DERIVE from the grid's UNKNOWN row —
-// the grid is the single source (DOD-TIER-2 AC4), so these can never drift from it.
+// Persistence bounds are TIER-GRADUATED via DEFAULT_TIER_BOUNDS (contacts-tier-migration). The two
+// consts below DERIVE from the grid's UNKNOWN row rather than restating it — the grid is the single
+// source (DOD-TIER-2 AC4), so these can never drift from it.
 /** Anti-drip-feed: cumulative RECEIVED bytes per session at the UNKNOWN tier (= the grid's UNKNOWN
  *  byte cap). Higher tiers get more (DEFAULT_TIER_BOUNDS); no tier is unbounded (INV-TIER-BOUND). */
 export const ABUSE_MAX_SESSION_RECEIVED_BYTES = DEFAULT_TIER_BOUNDS[TIER.UNKNOWN].maxBytesPerSession; // 25 MB
@@ -212,12 +164,11 @@ export class SessionNodeManager {
     // daemon.ts (depends on the notification dispatcher). Content-free by signature — carries only
     // agent / session / senderPubkey, NEVER the plaintext (INV-CONTENTFREE).
     #onContentArrived = null;
-    // CELLO-M7-MSG-001 (AC-001/AC-002/AC-003): the send is no longer fire-and-forget.
-    // After a content_frame is delivered over the direct session channel, the sender
-    // arms a TTF timer and waits for an unsigned, transport-authenticated `persisted`
-    // delivery ACK on the same /cello/content/1.0.0 protocol. A persisted ACK cancels
-    // the timer (content.delivery.acked); TTF expiry hands the content to the park
-    // backstop. Keyed sessionId → contentHashHex → entry.
+    // A send is NOT fire-and-forget. After a content_frame is delivered over the direct session
+    // channel, the sender arms a TTF timer and waits for an unsigned, transport-authenticated
+    // `persisted` delivery ACK on the same /cello/content/1.0.0 protocol. A persisted ACK cancels the
+    // timer (content.delivery.acked); TTF expiry hands the content to the park backstop.
+    // Keyed sessionId → contentHashHex → entry.
     #awaitingAck = new Map();
     // TTF (time-to-flush) for an un-acked content entry. Injectable so tests can drive
     // expiry deterministically; production default sits in the Part-4 proposed 10–30s band.
@@ -384,6 +335,14 @@ export class SessionNodeManager {
             // it to VERIFY the bilateral seal signature locally (the seal is signed by the initiator's
             // primary), not just accept it. NULL when this party initiated (it uses its own primary).
             "ALTER TABLE sessions ADD COLUMN counterparty_primary_pubkey TEXT",
+            // DOD-SESSION-NAME-1: the operator's own human-readable label for this session. LOCAL AND
+            // COSMETIC — it is never sent to the relay or directory, never in a wire frame, never in the
+            // transcript, never in the seal or a Merkle leaf, and the counterparty never sees it. It
+            // cannot influence protocol behaviour.
+            // NULL MEANS SOMETHING: a session closed through an agent usually carries a name, so an
+            // unnamed closed session is a hint it did not close cleanly. Never auto-generate a default —
+            // a fabricated name destroys that signal.
+            "ALTER TABLE sessions ADD COLUMN session_name TEXT",
         ]) {
             try {
                 this.#db.exec(ddl);
@@ -496,6 +455,14 @@ export class SessionNodeManager {
         // agent-id re-key above (it never needs to appear in that migration's pinned DDL) and BEFORE any
         // read below. Idempotent, no column DEFAULT, grandfathers existing contacts to WHITELISTED once.
         migrateContactsAddTierMetadata(this.#db, this.#logger);
+        // §1.1: normalize frost_commitments / frost_verifying_shares to ONE CBOR encoding. Registration
+        // wrote them with the shared encoder; the refresh path wrote them with cbor-x's bare `encode`,
+        // so an agent's share blobs changed format the first time it ran `cello_refresh_shares` and both
+        // formats are on disk. Both producers now use encodeCbor; this rewrites what is already stored.
+        // Idempotent (a canonical blob re-encodes to itself and is skipped) and per-row fail-safe (an
+        // undecodable share is LEFT ALONE, never dropped — losing key material is worse than an old
+        // encoding cbor-x still reads).
+        migrateCborBlobsToCanonical(this.#db, this.#logger);
         // M8C-TGDOOR-1: daemon-wide Telegram settings (bot token + allowlisted operator chat). A
         // NEW dedicated table — NOT folded into the parked M9-CFG-001 config store, because a bot
         // token has no sensible default (a required credential, unlike AWAY/TTL/CONTACT's real
@@ -625,7 +592,7 @@ export class SessionNodeManager {
     /**
      * DOD-LOG-1 / PERSIST-002 (AC-010): append one readable message to the durable transcript, keyed
      * by the canonical leaf `sequence` so it joins to the committed hash chain. The blob is stored as
-     * plaintext bytes — the whole DB is SQLCipher-encrypted at rest, so the per-column cipher is gone.
+     * plaintext bytes: the whole DB is SQLCipher-encrypted at rest, so there is no per-column cipher.
      * Idempotent on replay (INSERT OR IGNORE). Never throws into the caller's content path: a
      * transcript-write failure is logged, not fatal.
      */
@@ -763,7 +730,11 @@ export class SessionNodeManager {
            AND t.session_id = ?
            AND ${SessionNodeManager.#UNREAD_RECEIVED_WHERE}`)
             .get(this.#requireAgentId(agentName), sessionId);
-        return row ? row.unread_count : 0;
+        // Absent row → "I cannot count", which is NOT "you are caught up". Answer the same way the
+        // #db guard above does. Unreachable today (SELECT COUNT(*) with no GROUP BY always yields a
+        // row), but a fail-OPEN default inside a fail-CLOSED gate is a defect that only needs the query
+        // to change once. The two branches must never disagree about what "unknown" means.
+        return row ? row.unread_count : 1;
     }
     /** M8C-CONTACT-1: is this pubkey a known contact of this agent? */
     isContact(agentName, pubkey) {
@@ -2330,6 +2301,27 @@ export class SessionNodeManager {
         // agent_id scoped this lookup (~50 daemon call sites read `record.agent_name`).
         return row ? { ...row, agent_name: agentName } : null;
     }
+    /**
+     * DOD-SESSION-NAME-1: set (string) or clear (null) THIS agent's name for a session.
+     *
+     * Returns false when the (agent_id, session_id) row does not exist — i.e. the session is not this
+     * agent's — so the caller refuses with session_not_found rather than reporting a silent success on
+     * a write that landed nowhere. Same contract as setContactMoniker.
+     *
+     * Ownership is the ONLY scope: the composite key IS the ownership check, and status is deliberately
+     * not consulted. A sealed session can be named — naming one long after the fact is the point — and
+     * a name is a local column, so writing it cannot touch the seal, a Merkle leaf, or the wire.
+     *
+     * The caller validates (validateSessionName) before calling; this stores what it is given.
+     */
+    setSessionName(agentName, sessionId, sessionName) {
+        if (!this.#db)
+            throw new Error(`setSessionName('${agentName}'): database not initialized`);
+        const res = this.#db
+            .prepare("UPDATE sessions SET session_name = ? WHERE agent_id = ? AND session_id = ?")
+            .run(sessionName, this.#requireAgentId(agentName), sessionId);
+        return res.changes > 0;
+    }
     /**
      * MSG-2 startup-flush: the persisted relay endpoint for a session, or null if none was
      * recorded. Used by the crash-backstop flush, which runs at startup BEFORE the in-memory
@@ -2464,6 +2456,15 @@ export class SessionNodeManager {
         if (addrs.length === 0) {
             return { ok: false, reason: "no_counterparty_addrs", error: "the assignment carried no counterparty session addrs to dial" };
         }
+        // DOD-NAT-REACHABILITY-1: a /p2p-circuit counterparty address is dialed
+        // THROUGH its relay, so the gater must admit that relay peer OUTBOUND. The
+        // relay id is embedded in the address, which arrived inside the FROST-signed
+        // assignment — the same authorization rail as the assigned witness relay.
+        for (const addr of addrs) {
+            const viaRelay = addr.match(/\/p2p\/([^/]+)\/p2p-circuit/);
+            if (viaRelay)
+                entry.gater.setAllowedOutboundPeer(viaRelay[1]);
+        }
         let lastError = "";
         for (const addr of addrs) {
             try {
@@ -2476,8 +2477,11 @@ export class SessionNodeManager {
                 return { ok: true };
             }
             catch (err) {
-                // error.message extracted — never [object Object]; try the next addr.
-                lastError = err instanceof Error ? err.message : String(err);
+                // extractErrorMessage handles the transport's structured plain-object
+                // throws (dial() never throws Error instances) — the old
+                // `instanceof Error` idiom logged "[object Object]" on every dial
+                // failure; try the next addr.
+                lastError = extractErrorMessage(err);
             }
         }
         this.#logger.warn("session.transport.connect.failed", {
@@ -2489,10 +2493,9 @@ export class SessionNodeManager {
         return { ok: false, reason: "counterparty_dial_failed", error: lastError };
     }
     /**
-     * DAEMON-004: send content over the session node's direct P2P content stream.
-     * On a dead/missing stream this returns a NAMED, diagnosable failure — never a
-     * silent success and never a desync (closing the old silent fire-and-forget
-     * content catch in the retired in-process client send path).
+     * Send content over the session node's direct P2P content stream.
+     * On a dead/missing stream this returns a NAMED, diagnosable failure — never a silent success
+     * (which desyncs the two sides). Do not swallow a send error here.
      *
      * SCOPE / findings #3 + #4 — what this send path does and does NOT do today:
      *   - #4: it delivers the content over the direct /cello/content/1.0.0 P2P
@@ -2517,9 +2520,11 @@ export class SessionNodeManager {
         // canonical sequence from the hash whether or not the counterparty is reachable for direct
         // content. So an OFFLINE recipient still gets a sequence, and the parked content is later
         // recovered AT that sequence (DOD-MSG-4 recovery-not-desync). The relay only ever sees the
-        // hash (INV-3). Best-effort: a relay miss degrades to local-only sequencing. Previously this
-        // ran AFTER a successful direct send, so an offline recipient's content got NO sequence — the
-        // gap R1 closes.
+        // hash (INV-3). Best-effort: a relay miss degrades to local-only sequencing.
+        //
+        // This MUST run BEFORE the direct send, not after it: an offline recipient never completes a
+        // direct send, and sequencing after it would leave their content with no sequence at all.
+        //
         // DOD-MSG-4 (self-ordering content frame): the relay's committed ordering record for this leaf,
         // captured from the hash submit so it can be stamped into the content frame (and the parked
         // entry). Undefined if the relay is unreachable / an old relay — the receiver then falls back to
@@ -2569,7 +2574,7 @@ export class SessionNodeManager {
             // backstop. The correlationId rides in the frame so the receiver's
             // session.content.received shares ONE flow id with the sender.
             this.#trackAwaitingAck(agentName, sessionId, content, contentHash, correlationId, orderingS1, orderingS2);
-            const frame = CBOR_ENC.encode({
+            const frame = encodeCbor({
                 type: "content_frame",
                 session_id: sessionId,
                 content_hash: contentHash,
@@ -3010,14 +3015,15 @@ export class SessionNodeManager {
         const deliverContent = inboundVerdict.disposition === "redact" && inboundVerdict.content !== undefined
             ? inboundVerdict.content
             : content;
-        // B1 (review): screenInbound above is the ONLY suspension point in this method. Before M9 the
-        // dedup check (indexOfHash, above) and the leaf append (below) ran with no yield between them,
-        // so check-then-append was atomic under Node's single thread. The await reopened that window:
-        // two concurrent ingests of the SAME content hash — e.g. a direct retry and a park-recovery
-        // racing on reconnect — could BOTH pass the dedup check before either appends, producing two
-        // leaves for one hash (DOD-MSG-5 break → leafIndex≠canonicalSeq → root divergence). Re-check
-        // dedup now that we have resumed; everything from here to the append is synchronous (atomic),
-        // so the first to resume appends and the second sees its leaf and dedups.
+        // screenInbound above is the ONLY suspension point in this method, and it splits the dedup check
+        // (indexOfHash, above) from the leaf append (below). Across that await, two concurrent ingests of
+        // the SAME content hash — e.g. a direct retry and a park-recovery racing on reconnect — can BOTH
+        // pass the first dedup check before either appends, producing two leaves for one hash
+        // (DOD-MSG-5 break → leafIndex≠canonicalSeq → root divergence). So re-check dedup on resume.
+        // Everything from here to the append is synchronous (atomic under Node's single thread): the
+        // first to resume appends, and the second sees its leaf and dedups.
+        //
+        // Adding any further await between here and the append reopens the window.
         const dedupAfterScreen = this.getSessionTree(agentName, sessionId).indexOfHash(contentHashHex);
         if (dedupAfterScreen >= 0) {
             this.#logger.info("session.content.deduplicated", {
@@ -3115,6 +3121,37 @@ export class SessionNodeManager {
         const leafIndex = terminalBlock
             ? this.appendSessionLeaf(agentName, sessionId, "msg", contentHashHex, correlationId).leafIndex
             : this.#appendVerifiedContent(agentName, sessionId, deliverContent, contentHashHex, senderPubkey, correlationId).leafIndex;
+        // NO relay witness for this hash. We appended it anyway — refusing would make the relay a hard
+        // precondition for reading mail, so a relay outage would render the inbox unreadable, and the
+        // direct path and park backstop exist precisely to survive that. But this append is a WEAKER
+        // guarantee and must not masquerade as the stronger one: with a witness, the received content is
+        // checked against a hash the sender committed to a third party; without one, the only available
+        // hash rode in the same frame as the content, so the check is the sender's claim against the
+        // sender's own claim. Say so. A sender who simply never submits to the relay is otherwise
+        // indistinguishable from one the relay merely has not witnessed YET.
+        // The relay witness is an INDEPENDENT attestation: a (content_hash → sequence) binding derived
+        // from the sender's own signed leaf. Holding one, we check received content against a hash the
+        // sender committed to a THIRD PARTY. Holding none, the only hash available rode in the same frame
+        // as the content — the sender's claim checked against the sender's claim.
+        //
+        // Unwitnessed content is still ingested. Refusing it would make the relay a precondition for
+        // READING mail, so a relay outage would render the inbox unreadable — the redundancy the direct
+        // path and the park backstop exist to provide.
+        //
+        // Warn ONLY when a witness was EXPECTED. A session with no relay attached has no witness BY
+        // DESIGN, and warning on every message there would bury the one case that means something —
+        // a relay IS attached, so the sender's leaf should have been submitted and witnessed, and it
+        // was not. A signal that fires on the normal case is not a signal.
+        if (canonicalSeq === undefined && this.#activeNodes.get(key)?.relayClient) {
+            this.#logger.warn("session.content.unwitnessed", {
+                agentName,
+                sessionId,
+                leafIndex,
+                contentHash: contentHashHex,
+                correlationId,
+                guidance: "a relay is attached to this session but no witness bound this content hash — it was ingested with no independent commitment from the sender",
+            });
+        }
         // A just-appended leaf may unblock held out-of-order arrivals whose turn is now next.
         // appendedCount = this leaf + any held leaves released by it, so a caller (recover) can tally the
         // leaves ACTUALLY written, not just the directly-ingested one (review #3).
@@ -3380,7 +3417,7 @@ export class SessionNodeManager {
             return;
         try {
             const stream = await entry.node.newStream(entry.counterpartySessionPeerId, CELLO_CONTENT_PROTOCOL_ID);
-            const frame = CBOR_ENC.encode({
+            const frame = encodeCbor({
                 type: "content_delivery_ack",
                 session_id: sessionId,
                 content_hash: contentHash,
@@ -3486,12 +3523,11 @@ export class SessionNodeManager {
     /**
      * SEC-1 — THE ONLY WAY PARKED CONTENT ENTERS THE TRANSCRIPT.
      *
-     * Authentication and ingest are fused here on purpose. Before SEC-1 the recover loop in daemon.ts
-     * did `decode → (maybe verify ordering) → ingest`, where the verify step was OPTIONAL (skipped
-     * entirely when the attacker simply omitted the ordering record) and could not reject anything
-     * even when it ran — it gated ORDERING, not INGEST. Splitting the check from the write is what
-     * made the downgrade possible, so they no longer live apart: a caller cannot ingest parked content
-     * without passing the signature gate, because there is no other entry point.
+     * Authentication and ingest are FUSED here on purpose, and must stay fused. A caller cannot ingest
+     * parked content without passing the signature gate, because this is the only entry point. Exposing
+     * a separate `decode → ingest` path — with the signature check as its own optional step — is a
+     * downgrade attack: an attacker omits the thing that triggers the check, and the check never runs.
+     * A gate the caller can skip by leaving a field out is not a gate.
      *
      * FAILS CLOSED. No signature / bad signature / signer is not this session's counterparty / no
      * session at all → REFUSED, nothing is appended, nothing is written, and the caller MUST NOT
@@ -3848,6 +3884,131 @@ export class SessionNodeManager {
             this.#standingReceiverCreating.delete(agentName);
         }
     }
+    /**
+     * DOD-NAT-REACHABILITY-1 (Phase 2): relay endpoints the DIRECTORY handed this
+     * agent at signaling-auth time — the freshest, health-filtered view of the
+     * relay pool, and the only source a FRESH agent (no session history) has.
+     */
+    #directoryRelayEndpoints = new Map();
+    /**
+     * DOD-NAT-REACHABILITY-1 (Phase 2): accept the directory's relay-pool endpoints
+     * for an agent (arrives with signaling_auth_ok, i.e. on every connect AND every
+     * reconnect). If the agent's standing receiver is up but holds NO reservation —
+     * the agent-online ensure raced ahead of auth_ok, or every relay was down at
+     * create time — rebuild it now so the agent becomes dialable without waiting
+     * for a session handoff that (being unreachable) would never come.
+     */
+    setDirectoryRelayEndpoints(agentName, endpoints) {
+        this.#directoryRelayEndpoints.set(agentName, endpoints);
+        if (endpoints.length === 0 || this.#shuttingDown)
+            return;
+        const sr = this.#standingReceivers.get(agentName);
+        if (!sr)
+            return; // not ensured yet — the coming ensure reads the map
+        if (sr.node.listenAddresses().some((a) => a.includes("/p2p-circuit")))
+            return; // already reserved
+        this.#logger.info("session.standing_receiver.reservation.rebuild", {
+            agentName,
+            relayPeerIds: endpoints.map((e) => e.relayPeerId),
+        });
+        void this.#rebuildStandingReceiver(agentName);
+    }
+    /**
+     * Replace an agent's reservation-less standing receiver with one that reserves.
+     *
+     * Deliberately NOT removeStandingReceiverForAgent()+ensureStandingReceiverForAgent():
+     * the public remove CLEARS #agentsWantingReceiver, so a cello_stop_agent landing in
+     * the window while node.stop() is awaited would find no map entry and no creating
+     * marker, leave no tombstone, and the re-ensure would then RESURRECT a receiver for
+     * an agent that asked to go dark — accepting inbound sessions for an offline agent.
+     * Here the want-flag is left intact and re-checked after the stop: a concurrent stop
+     * clears it, and the rebuild correctly no-ops.
+     */
+    async #rebuildStandingReceiver(agentName) {
+        try {
+            const sr = this.#standingReceivers.get(agentName);
+            if (sr) {
+                this.#standingReceivers.delete(agentName);
+                try {
+                    sr.autoNat.stop();
+                    await sr.node.stop();
+                }
+                catch (err) {
+                    this.#logger.warn("session.standing_receiver.teardown.failed", {
+                        agentName,
+                        error: extractErrorMessage(err),
+                    });
+                }
+            }
+            // The agent may have gone offline while we were stopping the old node. Its
+            // want-flag is the authority — never resurrect a receiver it disowned.
+            if (!this.#agentsWantingReceiver.has(agentName) || this.#shuttingDown)
+                return;
+            await this.#ensureStandingReceiver(agentName);
+        }
+        catch (err) {
+            this.#logger.warn("session.standing_receiver.reservation.rebuild.failed", {
+                agentName,
+                error: extractErrorMessage(err),
+            });
+        }
+    }
+    /**
+     * DOD-NAT-REACHABILITY-1: circuit-relay listen addresses for an agent's known
+     * relays, so its standing receiver takes reservations and becomes dialable
+     * behind NAT. Sources, merged and deduped by relay peer id: the directory's
+     * auth-time relay pool (freshest — first), then the persisted relay endpoints
+     * of past sessions (getAgentRelayEndpoints — covers a directory that predates
+     * the auth_ok extension).
+     */
+    #reservationCircuitAddrs(agentName) {
+        let persisted;
+        try {
+            persisted = this.getAgentRelayEndpoints(agentName);
+        }
+        catch (err) {
+            // No DB / unknown agent — persisted source unavailable. The directory
+            // source may still serve; reachability degrades only if both are empty.
+            // Logged (not swallowed): a genuine DB failure must be distinguishable
+            // from "fresh agent, no history" in the reachability trail.
+            this.#logger.debug("session.standing_receiver.persisted_relays.unavailable", {
+                agentName,
+                error: extractErrorMessage(err),
+            });
+            persisted = [];
+        }
+        const merged = new Map();
+        for (const ep of [...(this.#directoryRelayEndpoints.get(agentName) ?? []), ...persisted]) {
+            if (!merged.has(ep.relayPeerId))
+                merged.set(ep.relayPeerId, ep);
+        }
+        const addrs = [];
+        const relayPeerIds = [];
+        for (const ep of merged.values()) {
+            const base = ep.relayAddrs[0];
+            if (!base)
+                continue;
+            const candidate = base.includes("/p2p/")
+                ? `${base}/p2p-circuit`
+                : `${base}/p2p/${ep.relayPeerId}/p2p-circuit`;
+            // These addresses are built from DIRECTORY-supplied endpoints — data from off
+            // this machine. A malformed one throws inside libp2p node construction, which
+            // would take the standing receiver down entirely and leave the agent deaf to
+            // ALL inbound (worse than the defect this fixes). A bad endpoint must cost one
+            // relay, never the receiver.
+            if (!isValidMultiaddr(candidate)) {
+                this.#logger.warn("session.standing_receiver.relay_endpoint.invalid", {
+                    agentName,
+                    relayPeerId: ep.relayPeerId,
+                    addr: candidate,
+                });
+                continue;
+            }
+            addrs.push(candidate);
+            relayPeerIds.push(ep.relayPeerId);
+        }
+        return { addrs, relayPeerIds };
+    }
     /** One standing-receiver create attempt (extracted for the M8B F14 retry loop). */
     async #tryCreateStandingReceiver(agentName, correlationId) {
         const sessionId = `standing_receiver_${randomUUID()}`;
@@ -3856,13 +4017,29 @@ export class SessionNodeManager {
             allowedPeerId: null, // open — counterparty unknown at creation time
             logger: this.#logger,
         });
+        // DOD-NAT-REACHABILITY-1: reserve with the agent's known relays. The relay
+        // peers are allowed OUTBOUND on the gater up front, so reservation refreshes
+        // keep working after the receiver is claimed and setAllowedPeer() narrows
+        // the inbound gate to the session counterparty.
+        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: "standing_receiver" });
+            node = await this.#factory.createNode({
+                sessionId,
+                connectionGater: gater,
+                nodeType: "standing_receiver",
+                ...(reservations.addrs.length > 0 ? { circuitRelayListenAddrs: reservations.addrs } : {}),
+            });
             await node.start();
         }
         catch (err) {
-            const error = err instanceof Error ? err.message : String(err);
+            // extractErrorMessage, NOT String(err): the transport throws structured
+            // plain objects ({ reason, message }), and String() destroys both into
+            // "[object Object]" — the loud failure must carry its cause.
+            const error = extractErrorMessage(err);
             this.#logger.error("session.node.create.failed", {
                 sessionId,
                 agentName: `${STANDING_RECEIVER_AGENT_NAME}:${agentName}`,
@@ -3908,6 +4085,25 @@ export class SessionNodeManager {
             sessionPeerId: node.getPeerId(),
             correlationId,
         });
+        // DOD-NAT-REACHABILITY-1 observability: how reachable did this receiver come
+        // up? circuitAddrs === 0 with reservations requested means every relay
+        // refused/was unreachable — the agent is deaf to NAT'd initiators (public
+        // ones can still connect directly). That must be LOUD, not a quiet shrug.
+        const circuitAddrs = node.listenAddresses().filter((a) => a.includes("/p2p-circuit")).length;
+        this.#logger.info("session.standing_receiver.reachability", {
+            agentName,
+            circuitAddrs,
+            reservationsRequested: reservations.addrs.length,
+            correlationId,
+        });
+        if (reservations.addrs.length > 0 && circuitAddrs === 0) {
+            this.#logger.warn("session.standing_receiver.reservation.none", {
+                agentName,
+                reservationsRequested: reservations.addrs.length,
+                relayPeerIds: reservations.relayPeerIds,
+                correlationId,
+            });
+        }
         return { outcome: "installed" };
     }
     /**
@@ -3923,6 +4119,10 @@ export class SessionNodeManager {
     async removeStandingReceiverForAgent(agentName) {
         // M8B F14: the agent no longer wants a receiver — disarm the teardown re-arm.
         this.#agentsWantingReceiver.delete(agentName);
+        // The directory hands these out at signaling-auth time, so a re-started agent
+        // gets a fresh set on its next connect — holding the old ones would keep a
+        // retired agent's relay list alive for the daemon's lifetime.
+        this.#directoryRelayEndpoints.delete(agentName);
         const sr = this.#standingReceivers.get(agentName);
         if (!sr) {
             // L1: an #ensureStandingReceiver for this agent may be in flight (parked on start(), so no