@cello-protocol/daemon 0.0.182 → 0.0.184

package/dist/session-relay-client.js

@@ -32,6 +32,7 @@ import { createHash } from "node:crypto";
 import * as lp from "it-length-prefixed";
 import { decode } from "cbor-x";
 import { encodeCbor, decodeSealPayload } from "@cello-protocol/protocol-types";
+import { verify } from "@cello-protocol/crypto";
 import { evaluateRelayAck } from "./relay-receipt-store.js";
 export const RELAY_PROTOCOL_ID = "/cello/relay/1.0.0";
 export const RELAY_AUTH_DOMAIN = "CELLO-RELAY-AUTH-v1";
@@ -72,6 +73,97 @@ export const TERMINAL_RELAY_REFUSALS = new Set([
 export function isTerminalRelayRefusal(reason) {
     return reason !== undefined && TERMINAL_RELAY_REFUSALS.has(reason);
 }
+/**
+ * DOD-M15-RELAYSLOTS-1 — **WHICH REFUSALS JUSTIFY TRYING A DIFFERENT RELAY.**
+ *
+ * We run several relays, so "move on to the next one" is always available — which is exactly why it
+ * needs a rule. Moving on from a problem that every relay will have turns one client-side fault into
+ * what looks like a fleet-wide outage, and the operator then goes looking for a broken relay.
+ *
+ * ENUMERATED, never pattern-matched, for the same reason `TERMINAL_RELAY_REFUSALS` is: a substring
+ * rule would silently absorb a future reason nobody has considered.
+ */
+const RELAY_SIDE_REFUSALS = new Set([
+    /**
+     * The relay holds no directory public key, so it can verify nothing and is refusing everyone.
+     * That is this relay being misconfigured, not us being wrong — another relay is the right move,
+     * and it is the whole reason we run more than one.
+     */
+    "online_token_no_directory_key",
+]);
+/**
+ * Classify a relay's auth refusal: what to tell the operator, and whether another relay would help.
+ *
+ * Everything not in `RELAY_SIDE_REFUSALS` defaults to "do not try another", and that default is the
+ * safe direction. A token problem reproduces identically on every relay in the fleet, so retrying
+ * around the fleet spends real time turning a client fault into an apparent outage — and a slot cap
+ * IS satisfiable elsewhere, but spreading to another relay papers over sessions that leaked and
+ * brings the same wall back on the next one.
+ */
+export function classifyRelayAuthRefusal(reason, extra = {}) {
+    const tryAnotherRelay = RELAY_SIDE_REFUSALS.has(reason);
+    let advice;
+    switch (reason) {
+        case "online_token_required":
+            advice = "This agent has no online token from a directory yet. It is issued when a directory " +
+                "marks the agent online, so this usually clears itself on the next directory connection. If " +
+                "it persists, the agent is not reaching any directory — check that first, not the relay.";
+            break;
+        case "online_token_expired":
+            advice = "The online token has expired and is refreshed on the next directory connection. If " +
+                "it keeps expiring, this machine's clock or its directory connection is the thing to look at.";
+            break;
+        case "online_token_signature_invalid":
+        case "online_token_malformed":
+        case "online_token_lifetime_too_long":
+            advice = "This relay would not accept the token this agent was issued. Most often the relay " +
+                "and the directory are not in the same consortium — check which directories this relay is " +
+                "configured to trust.";
+            break;
+        case "online_token_pubkey_mismatch":
+            advice = "The token names a different key from the one this agent signed with. That is an " +
+                "identity mix-up on this machine, not a relay problem.";
+            break;
+        case "online_token_no_directory_key":
+            advice = "This relay holds no directory public key, so it cannot verify anyone and is " +
+                "refusing every agent. Its operator needs to configure one; another relay will work now.";
+            break;
+        case "slot_cap_exceeded":
+            advice = extra.slotsHeld !== undefined && extra.slotCap !== undefined
+                ? `This agent already holds ${String(extra.slotsHeld)} of a maximum ${String(extra.slotCap)} ` +
+                    "reservations on this relay, and none is idle enough to reclaim. That is almost always " +
+                    "sessions that were never closed — close some and this clears. Moving to another relay " +
+                    "would work now and hit the same wall there."
+                : "This agent already holds the most reservations one agent may hold on this relay. That is " +
+                    "almost always sessions that were never closed — close some and this clears.";
+            break;
+        case "session_tuple_cap_exceeded":
+            advice = extra.slotsHeld !== undefined && extra.slotCap !== undefined
+                ? `You already have ${String(extra.slotsHeld)} conversations open with this counterparty, ` +
+                    `which is the maximum of ${String(extra.slotCap)} this relay allows between one pair of ` +
+                    "agents. Close some and try again — this is almost always conversations that were never " +
+                    "closed rather than ones anybody is still using."
+                : "You already have the maximum number of concurrent conversations open with this " +
+                    "counterparty. Close some and try again.";
+            break;
+        case "rate_limited":
+            advice = extra.retryAfterMs !== undefined
+                ? `This relay is throttling this agent; it clears on its own in about ${String(Math.ceil(extra.retryAfterMs / 1000))}s.`
+                : "This relay is throttling this agent; it clears on its own after the throttle window.";
+            break;
+        default:
+            advice = "This agent could not authenticate to this relay, so it cannot hold a reservation " +
+                "here and is reachable only over a direct connection.";
+    }
+    return {
+        reason,
+        advice,
+        tryAnotherRelay,
+        ...(extra.slotsHeld !== undefined ? { slotsHeld: extra.slotsHeld } : {}),
+        ...(extra.slotCap !== undefined ? { slotCap: extra.slotCap } : {}),
+        ...(extra.retryAfterMs !== undefined ? { retryAfterMs: extra.retryAfterMs } : {}),
+    };
+}
 export const LEAF_KIND_MSG = 0x00;
 /** Control leaf (SEAL etc.) — two distinct-sender ctrl leaves trigger directory notarization. */
 export const LEAF_KIND_CTRL = 0x02;
@@ -100,6 +192,19 @@ export function buildRelayAuthPayload(nonce, pubkey) {
 export function encodeStructure1(contentHash, senderPubkey, sessionId, lastSeenSeq, timestamp) {
     return encodeCbor([1, contentHash, senderPubkey, sessionId, lastSeenSeq, timestamp]);
 }
+/**
+ * Rebuild the bytes a relay signs when it reports a witnessed forgery.
+ *
+ * ⚠️ **MIRRORED CODEC** — `packages/relay/src/leaf-witness.ts` `buildWitnessAlertTbs` in
+ * trustless-cello is the other half and the two MUST stay in sync. Both call `encodeCbor` from
+ * `@cello-protocol/protocol-types` rather than configuring an encoder, so the only thing that can
+ * drift is the field list, and both list it in one place.
+ */
+const RELAY_WITNESS_DOMAIN = "CELLO-RELAY-WITNESS-v1";
+function buildWitnessAlertTbs(sessionId, reason, observedAt, submitterIsCounterparty) {
+    const body = encodeCbor([RELAY_WITNESS_DOMAIN, sessionId, reason, observedAt, submitterIsCounterparty]);
+    return new Uint8Array(createHash("sha256").update(body).digest());
+}
 /**
  * Extract a real message from a thrown value. libp2p / cross-package errors are not
  * always `instanceof Error` in this realm (multi-version split), so fall back to a
@@ -167,6 +272,22 @@ export class AgentRelayClient {
     #logger;
     #receiptStore;
     #sealLeafStore;
+    /** DOD-M15-RELAYSLOTS-1 — read fresh at every auth. See `AgentRelayClientOpts.onlineToken`. */
+    #onlineToken;
+    /** DOD-M15-CORROBORATE-1 — where a relay's witness alert goes. See the opt of the same name. */
+    #onWitnessAlert;
+    /** DOD-M15-CORROBORATE-1 review F7 — where an UNREADABLE witness alert goes. */
+    #onWitnessUnreadable;
+    /**
+     * DOD-M15-RELAYSLOTS-1: the last refusal this relay gave us, classified. Kept because a log line
+     * reaches neither the operator asking why their agent is unreachable nor the code deciding
+     * whether a different relay would do any better.
+     */
+    #lastAuthRefusal = null;
+    /** The last classified auth refusal from this relay, or null if the last attempt succeeded. */
+    getLastAuthRefusal() {
+        return this.#lastAuthRefusal;
+    }
     #stream = null;
     #connecting = null;
     #closed = false;
@@ -182,6 +303,13 @@ export class AgentRelayClient {
     // The sender-signed structure1_cbor of the in-flight submit, paired with its ack so the
     // SubmitResult can carry it (the ack itself only returns the relay's structure2_cbor).
     #pendingStructure1 = null;
+    /**
+     * DOD-M15-SEALWIRE-1 bullet 5 (sent half) — OUR signature over the in-flight `#pendingStructure1`,
+     * paired with its ack for the same reason that one is: the ack returns the relay's record, never
+     * ours. Cleared wherever `#pendingStructure1` is cleared; the two must never drift apart, because
+     * a signature paired with the WRONG signed bytes is worse than no signature at all.
+     */
+    #pendingSignature = null;
     // The in-flight submit's leaf kind (0x00 msg / 0x02 ctrl), paired with its ack so
     // #captureReceipt can persist it alongside the Structure2/Structure1 carry bytes for the unilateral seal.
     #pendingLeafKind = null;
@@ -205,6 +333,9 @@ export class AgentRelayClient {
         this.#logger = opts.logger;
         this.#receiptStore = opts.receiptStore;
         this.#sealLeafStore = opts.sealLeafStore;
+        this.#onlineToken = opts.onlineToken;
+        this.#onWitnessAlert = opts.onWitnessAlert;
+        this.#onWitnessUnreadable = opts.onWitnessUnreadable;
     }
     /** The agent's K_local public key as hex — the responder identity for auto-acknowledge. */
     get senderPubkeyHex() {
@@ -236,6 +367,29 @@ export class AgentRelayClient {
                 .then(() => undefined, () => undefined);
         }
     }
+    /**
+     * DOD-M15-RELAYAUTH-1 review H1 — **present the assignment and WAIT for the relay to say it
+     * recorded it.**
+     *
+     * `registerSession` above presents eagerly and forgets: the record is queued onto the submit chain
+     * and nobody can observe when it lands. That is correct for the witness relay, where the only
+     * requirement is "before the first submit". It is NOT sufficient for the relay that GATES A DIAL,
+     * because there the record is a precondition of an action we are about to take on another thread
+     * of the protocol — and losing that race denies a legitimate dial (review H1).
+     *
+     * Chained on `#submitChain` exactly like `#doSubmit`, so it cannot interleave with a submit on the
+     * same stream. Idempotent by construction: `#doRecord` returns `true` immediately once the session
+     * is recorded, so calling this straight after `registerSession` waits for the record that call
+     * already queued rather than sending a second one.
+     *
+     * Returns whether the relay recorded it. NEVER throws — a caller must be free to proceed on false
+     * (a dial that might be denied still beats no dial at all).
+     */
+    async recordAssignmentAndWait(node, sessionIdHex) {
+        const run = this.#submitChain.then(() => this.#doRecord(node, sessionIdHex));
+        this.#submitChain = run.then(() => undefined, () => undefined);
+        return run.catch(() => false);
+    }
     /**
      * Present the directory-signed assignment to the relay. Idempotent
      * (no-op once `recorded`, or when the session has no assignment — direct/persisted/legacy sessions).
@@ -327,12 +481,25 @@ export class AgentRelayClient {
     hasSessions() {
         return this.#sessions.size > 0;
     }
+    /**
+     * Is THIS session already registered on this client?
+     *
+     * DOD-M15-RELAYLEAK-1 (review MEDIUM-5). The detached seal transport releases its registration
+     * when the submit finishes, and "did I register it, or did I find it already there?" is the
+     * difference between releasing my own and **pulling a live one out from under a concurrent
+     * caller** — which closes the client that caller is mid-`submitLeaf` on. `hasSessions()` cannot
+     * answer it: it is a count, and by then the id is in the set either way.
+     */
+    hasSession(sessionIdHex) {
+        return this.#sessions.has(sessionIdHex);
+    }
     /** Settle the one outstanding submit (if any) exactly once. */
     #settlePending(r) {
         const resolve = this.#pendingAck;
         this.#pendingAck = null;
         this.#pendingAckSessionHex = null;
         this.#pendingStructure1 = null;
+        this.#pendingSignature = null;
         this.#pendingLeafKind = null;
         if (resolve)
             resolve(r);
@@ -472,6 +639,8 @@ export class AgentRelayClient {
             const s2 = frame["structure2_cbor"];
             const structure2Cbor = s2 instanceof Uint8Array ? s2 : undefined;
             const structure1Cbor = this.#pendingStructure1 ?? undefined;
+            // Captured with structure1Cbor and BEFORE #settlePending clears both — see #pendingSignature.
+            const senderSignature = this.#pendingSignature ?? undefined;
             // Verify the relay's signed ordering record and durably store the receipt BEFORE
             // settling (which clears #pendingStructure1, the source of the content hash + session id). A
             // signed-but-INVALID ACK rejects the submit so the send does not settle ok on an unverified sequence.
@@ -479,7 +648,7 @@ export class AgentRelayClient {
             this.#settlePending(rejectSubmit
                 ? { ok: false, reason: "relay_ack_signature_invalid" }
                 : seq >= 0
-                    ? { ok: true, sequence_number: seq, structure1_cbor: structure1Cbor, structure2_cbor: structure2Cbor }
+                    ? { ok: true, sequence_number: seq, structure1_cbor: structure1Cbor, structure2_cbor: structure2Cbor, sender_signature: senderSignature }
                     : { ok: false, reason: "relay_ack_malformed" });
         }
         else if (type === "hash_submit_error") {
@@ -487,7 +656,16 @@ export class AgentRelayClient {
             // Carry the relay's `detail` through — see `SubmitResult`. Reading the class and discarding
             // what happened is how a refusal arrives as a bare code with no cause attached to it.
             const detail = typeof frame["detail"] === "string" ? frame["detail"] : undefined;
-            this.#settlePending({ ok: false, reason, ...(detail ? { detail } : {}) });
+            // DOD-M15-RELAYABUSE-1: the relay knows when its window clears and says so. Carried, not
+            // dropped — `#doSubmit` waits it out and resubmits, so a throttle never reaches the operator.
+            const rawRetry = frame["retry_after_ms"];
+            const retry_after_ms = typeof rawRetry === "number" && Number.isFinite(rawRetry) && rawRetry > 0 ? rawRetry : undefined;
+            this.#settlePending({
+                ok: false,
+                reason,
+                ...(detail ? { detail } : {}),
+                ...(retry_after_ms !== undefined ? { retry_after_ms } : {}),
+            });
         }
         else if (type === "assignment_ok") {
             // The relay verified + recorded our client-presented assignment.
@@ -499,7 +677,23 @@ export class AgentRelayClient {
         else if (type === "assignment_invalid") {
             // The relay rejected the assignment (e.g. directory_signature_invalid — not signed by any
             // consortium directory). Fail LOUD: the session has no relay witness until this is resolved.
-            this.#logger.warn("session.relay.assignment.invalid", { relayPeerId: this.#relayPeerId, reason: typeof frame["reason"] === "string" ? frame["reason"] : "unknown" });
+            const reason = typeof frame["reason"] === "string" ? frame["reason"] : "unknown";
+            this.#logger.warn("session.relay.assignment.invalid", { relayPeerId: this.#relayPeerId, reason });
+            /**
+             * DOD-M15-RELAYSLOTS-1 review M2 — **the tuple cap has to reach the operator too.**
+             *
+             * Clause 7 says EVERY refusal reaches them with a cause and an affordance, and this one was
+             * arriving as `assignment_invalid` in a log. It is also the refusal most likely to hit a real
+             * person, for the reason the order itself gives: nobody knows what sessions they have open, so
+             * whoever hits it believes they have none. Routed through the same classifier and onto the
+             * same surface as every other relay refusal.
+             */
+            const concurrent = typeof frame["concurrent_sessions"] === "number" ? frame["concurrent_sessions"] : undefined;
+            const cap = typeof frame["session_cap"] === "number" ? frame["session_cap"] : undefined;
+            this.#lastAuthRefusal = classifyRelayAuthRefusal(reason, {
+                ...(concurrent !== undefined ? { slotsHeld: concurrent } : {}),
+                ...(cap !== undefined ? { slotCap: cap } : {}),
+            });
             const r = this.#pendingRecord;
             this.#pendingRecord = null;
             if (r)
@@ -559,6 +753,161 @@ export class AgentRelayClient {
                 });
             }
         }
+        else if (type === "session_witness_alert") {
+            /**
+             * DOD-M15-CORROBORATE-1 — **the relay is telling us what it saw, and this is where it lands.**
+             *
+             * A relay is not trusted to send a well-formed frame any more than a peer is, so every field
+             * is checked before anything is reported. A frame that does not decode is a MISBEHAVING OR
+             * SKEWED RELAY, not an alert: reporting it as one would let a broken build manufacture
+             * accusations against a counterparty who did nothing. It is logged loudly and goes no further.
+             */
+            const sid = frame["session_id"];
+            const rawRelayId = frame["relay_id"];
+            const observedAt = frame["observed_at"];
+            const submitterIsCounterparty = frame["submitter_is_counterparty"];
+            const sidBytes = sid instanceof Uint8Array || Buffer.isBuffer(sid) ? toU8(sid) : new Uint8Array();
+            const wellFormed = sidBytes.length === 16
+                && frame["reason"] === "leaf_signed_by_neither_participant"
+                && typeof observedAt === "number" && Number.isFinite(observedAt)
+                && typeof submitterIsCounterparty === "boolean"
+                && (rawRelayId === undefined || typeof rawRelayId === "string");
+            const unreadable = (why) => {
+                this.#logger.error("session.relay.witness.malformed", {
+                    relayPeerId: this.#relayPeerId,
+                    why,
+                    impact: "this relay sent a witness alert this build cannot read, so NOTHING has been " +
+                        "reported to the operator about it. Treat it as a relay fault or a version skew, not " +
+                        "as evidence about either participant.",
+                });
+                /**
+                 * Review F7 — **and it reaches a surface, not only this file.** If a version skew makes
+                 * every relay's alert unreadable, the witness layer is silently dead and the operator would
+                 * have no way to find that out. Deliberately carries NO session and NO party: it says a
+                 * relay sent something we could not read, and claims nothing about anyone.
+                 */
+                this.#onWitnessUnreadable?.(this.#relayPeerId, why);
+            };
+            if (!wellFormed) {
+                unreadable("field_shape");
+                return;
+            }
+            const sessionIdHex = Buffer.from(sidBytes).toString("hex");
+            /**
+             * ⚠️ **IT MUST BE A SESSION THIS CLIENT ACTUALLY HOLDS ON THIS RELAY** — review F2.
+             *
+             * `wellFormed` checks shape and shape only. Without this, any relay we are authenticated to
+             * could push alerts naming arbitrary session ids — including conversations carried by a
+             * DIFFERENT relay — and they would land in the operator's inbox as statements of fact about
+             * a counterparty. Combined with a bounded notice list that is the cheap mute: flood
+             * fabrications until the real one is gone.
+             */
+            if (!this.#sessions.has(sessionIdHex)) {
+                /**
+                 * ⚠️ **REFUSED AS AN ALERT, BUT NOT BINNED IN SILENCE** — fallback-finder HIGH 1.
+                 *
+                 * It cannot be reported as an observation about a conversation: a relay naming a session we
+                 * do not hold is exactly the fabrication the check above exists to stop, and rendering it
+                 * would put a claim about a counterparty in front of an operator on a stranger's say-so.
+                 *
+                 * But dropping it entirely was worse than it looked, because the relay's own copy is GONE by
+                 * then: its queue is keyed by PUBKEY and `drainWitnessAlerts` splices, so it hands over
+                 * everything it held for this agent the moment any client authenticates. The detached seal
+                 * client registers exactly ONE session and then authenticates — so a restart-then-seal on
+                 * one conversation destroyed a held alert about a different one, at both ends, and the
+                 * operator's inbox looked clean.
+                 *
+                 * So it goes to the same neutral surface a version skew does: something arrived that this
+                 * daemon could not place. No session, no party, no claim.
+                 */
+                this.#logger.error("session.relay.witness.unknown_session", {
+                    relayPeerId: this.#relayPeerId,
+                    session: sessionIdHex,
+                    impact: "not rendered as an observation — this relay named a session this client is not " +
+                        "holding. Reported to the operator as an unplaceable witness report, never as a claim " +
+                        "about a counterparty.",
+                });
+                this.#onWitnessUnreadable?.(this.#relayPeerId, "session_not_held_here");
+                return;
+            }
+            /**
+             * A DECLARED IDENTITY MUST BE PROVEN — review F3. `relay_id` is the hex of the key that signs
+             * every `hash_submit_ack`, so the same check that verifies a receipt verifies this. Missing,
+             * malformed and mismatched take ONE path: omitting the proof is the cheapest way to dodge it.
+             */
+            const rawSig = frame["witness_signature"];
+            const sigBytes = rawSig instanceof Uint8Array || Buffer.isBuffer(rawSig) ? toU8(rawSig) : null;
+            let verifiable = false;
+            if (typeof rawRelayId === "string") {
+                if (!/^[0-9a-fA-F]{64}$/.test(rawRelayId)) {
+                    unreadable("relay_id_not_a_pubkey");
+                    return;
+                }
+                if (!sigBytes || sigBytes.length !== 64) {
+                    unreadable("declared_relay_id_without_signature");
+                    return;
+                }
+                const tbs = buildWitnessAlertTbs(sidBytes, "leaf_signed_by_neither_participant", observedAt, submitterIsCounterparty);
+                if (!verify(new Uint8Array(Buffer.from(rawRelayId, "hex")), tbs, sigBytes)) {
+                    unreadable("witness_signature_invalid");
+                    return;
+                }
+                verifiable = true;
+            }
+            const alert = {
+                sessionIdHex,
+                reason: "leaf_signed_by_neither_participant",
+                relayId: typeof rawRelayId === "string" ? rawRelayId : null,
+                observedAt,
+                submitterIsCounterparty,
+                witnessPeerId: this.#relayPeerId,
+                verifiable,
+            };
+            // BOTH halves, per Invariant 2: the log is the durable forensic record, and the callback is
+            // the half that actually reaches a person.
+            this.#logger.error("session.relay.witness.alert", {
+                relayPeerId: this.#relayPeerId,
+                session: alert.sessionIdHex,
+                relayId: alert.relayId ?? "(unnamed)",
+                submitterIsCounterparty: alert.submitterIsCounterparty,
+                verifiable: alert.verifiable,
+                observation: "one relay refused a leaf on this session because it verified against neither participant key",
+                impact: "nothing was added to the conversation record. This is ONE relay's observation and " +
+                    "establishes only that it saw and refused that submission — not who sent it.",
+            });
+            if (this.#onWitnessAlert)
+                this.#onWitnessAlert(alert);
+        }
+        else if (type === "relay_slot_reclaimed") {
+            /**
+             * DOD-M15-RELAYSLOTS-1 clause 8 — **the reaped party is told, and this is where it lands.**
+             *
+             * The relay reclaimed this agent's circuit reservation to free capacity. Without a branch
+             * here the frame fell off the end of this chain and was discarded in silence, which is the
+             * trap the order records in its own words: a refusal that only reaches the relay's log does
+             * not exist. From the agent's side the reservation simply stops working.
+             *
+             * Recorded as a refusal so it reaches `cello_status` through the same surface as every other
+             * relay refusal, with the same shape: a cause, and what to do about it.
+             */
+            const idleMs = typeof frame["idle_ms"] === "number" ? frame["idle_ms"] : undefined;
+            const detail = typeof frame["detail"] === "string" ? frame["detail"] : undefined;
+            this.#lastAuthRefusal = {
+                reason: "slot_reclaimed",
+                advice: detail ?? "This relay reclaimed your circuit reservation to free capacity because it " +
+                    "had carried no traffic for a long time. Your agent stays online and rebuilds its receiver " +
+                    "automatically; a new session will take a fresh reservation.",
+                // Not the relay's fault and not ours — it was under pressure and we were the quietest. The
+                // client rebuilds against the same pool, so there is nothing to fail over from.
+                tryAnotherRelay: false,
+            };
+            this.#logger.warn("session.relay.slot_reclaimed", {
+                relayPeerId: this.#relayPeerId,
+                ...(idleMs !== undefined ? { idleHours: Math.round(idleMs / 3_600_000) } : {}),
+                impact: "this relay reclaimed our circuit reservation to free capacity. Until a receiver is " +
+                    "rebuilt, this agent is reachable only over a direct connection.",
+            });
+        }
         // session_interrupted / content_park_notify are out of scope here — session interruption
         // is handled by the session node manager's dedicated relay-stream watcher.
     }
@@ -570,6 +919,61 @@ export class AgentRelayClient {
     async connect(node) {
         return this.#ensureConnected(node);
     }
+    /**
+     * DOD-M15-RELAYAUTH-1 review HIGH-1 — prove key possession FROM THIS NODE, on its own stream.
+     *
+     * ⚠️ **`connect()` CANNOT be used for this, and using it was the defect.** `#ensureConnected`
+     * returns `true` the moment `#stream` is non-null, and `#stream` belongs to whichever node
+     * connected FIRST. An agent legitimately runs several nodes against one relay — the node promoted
+     * into a live session, plus the replacement standing receiver built behind it — and they share
+     * one `AgentRelayClient` because the cache is keyed `${agent}::${relay}`. So calling `connect()`
+     * from the replacement receiver short-circuited on the session node's stream, sent nothing, and
+     * the relay never saw that receiver's transport identity: it revoked the reservation ~15s later,
+     * the watchdog rebuilt, and the agent churned on a ~45s loop holding no usable circuit address
+     * for as long as the conversation lasted. Any future "reuse the existing connection" optimisation
+     * here reintroduces exactly that.
+     *
+     * So this always opens its own short-lived stream from `node`, and marks it
+     * `purpose: "reservation"` so the relay proves possession WITHOUT rebinding the agent's delivery
+     * stream (which would steal the live session's inbound leaves — see the relay-side dispatch).
+     */
+    async proveReservation(node) {
+        if (this.#closed)
+            return false;
+        for (const addr of this.#relayAddrs) {
+            try {
+                await node.dial(addr);
+                break;
+            }
+            catch { /* try the next address */ }
+        }
+        let stream;
+        try {
+            stream = await node.newStream(this.#relayPeerId, RELAY_PROTOCOL_ID);
+        }
+        catch (err) {
+            this.#logger.warn("session.relay.reservation_proof.failed", {
+                relayPeerId: this.#relayPeerId, reason: "stream", error: extractErrorMessage(err),
+            });
+            return false;
+        }
+        try {
+            const iter = lp.decode(stream)[Symbol.asyncIterator]();
+            const ok = await this.#authenticate(stream, iter, "reservation");
+            this.#logger.info("session.relay.reservation_proof.result", {
+                relayPeerId: this.#relayPeerId,
+                nodePeerId: node.getPeerId(),
+                ok,
+                // DOD-M15-RELAYSLOTS-1: name the cause here too. `ok: false` alone sent people looking at
+                // the transport for what is usually a token or a cap.
+                ...(ok ? {} : { refusalReason: this.#lastAuthRefusal?.reason ?? "no_relay_verdict" }),
+            });
+            return ok;
+        }
+        finally {
+            await stream.close().catch(() => { });
+        }
+    }
     /** Ensure an authenticated stream exists, (re)dialing from `node` if needed. */
     async #ensureConnected(node) {
         if (this.#closed)
@@ -622,7 +1026,7 @@ export class AgentRelayClient {
         this.#startReader(stream, iter);
         return true;
     }
-    async #authenticate(stream, iter) {
+    async #authenticate(stream, iter, purpose) {
         const challengeRes = await nextWithTimeout(iter, RELAY_AUTH_TIMEOUT_MS);
         if (challengeRes.done || challengeRes.value === undefined) {
             this.#logger.warn("session.relay.auth.failed", { relayPeerId: this.#relayPeerId, reason: "no_challenge" });
@@ -646,8 +1050,37 @@ export class AgentRelayClient {
             return false;
         }
         const authSig = await this.#keyProvider.sign(buildRelayAuthPayload(nonce, this.#senderPubkey));
+        /**
+         * DOD-M15-RELAYSLOTS-1: read the token NOW, not at construction — it is reissued on every
+         * signaling reconnect and the one this client was built with is usually already gone.
+         *
+         * When there is none we send the auth anyway. Declining to try would replace a named refusal
+         * from the relay (`online_token_required`, which says what is wrong and what to do) with
+         * silence on both sides — and silence is what an operator reads as "the product is broken".
+         */
+        const onlineToken = this.#onlineToken?.();
+        if (!onlineToken) {
+            this.#logger.warn("session.relay.auth.no_online_token", {
+                relayPeerId: this.#relayPeerId,
+                impact: "authenticating without the directory's online token. The relay will refuse this and " +
+                    "will not let this node keep a circuit reservation, so the agent is reachable by nobody " +
+                    "over this relay. The usual cause is that no directory connection has been established " +
+                    "yet; the next signaling connect issues a token and the receiver re-authenticates.",
+            });
+        }
         try {
-            stream.send(lp.encode.single(encodeCbor({ type: "relay_auth_response", pubkey: this.#senderPubkey, signature: authSig })));
+            stream.send(lp.encode.single(encodeCbor({
+                type: "relay_auth_response",
+                pubkey: this.#senderPubkey,
+                signature: authSig,
+                // DOD-M15-RELAYAUTH-1: absent for the ordinary session auth (which also registers this
+                // stream as the agent's delivery target). `"reservation"` proves possession from THIS
+                // node's transport identity and nothing more — see proveReservation().
+                ...(purpose ? { purpose } : {}),
+                // DOD-M15-RELAYSLOTS-1: opaque bytes from the directory, forwarded verbatim. The client
+                // never parses them — a format it does not read is a format it cannot get wrong.
+                ...(onlineToken ? { online_token: onlineToken } : {}),
+            })));
         }
         catch (err) {
             this.#logger.warn("session.relay.auth.failed", { relayPeerId: this.#relayPeerId, reason: "response_send", error: extractErrorMessage(err) });
@@ -667,12 +1100,50 @@ export class AgentRelayClient {
             return false;
         }
         if (ackFrame["type"] !== "relay_auth_ok") {
+            /**
+             * DOD-M15-RELAYABUSE-1 review F2 — **THE RELAY SAYS WHY, AND WE USED TO THROW IT AWAY.**
+             *
+             * `relay_auth_failed` carries a `reason` — `rate_limited`, `signature_invalid`, `nonce_expired`,
+             * `nonce_reused`, `nonce_unknown` — and, when throttled, a `retry_after_ms`. This branch
+             * collapsed all of them into the single word `auth_rejected`, so a throttled agent looked
+             * exactly like a bad signature, which looked exactly like a dead relay. That is precisely the
+             * distinction the order that added those refusals set out to create, undone at the last hop.
+             *
+             * The difference matters to whoever is looking: `rate_limited` clears by itself and says when;
+             * `signature_invalid` never clears and means a key or clock problem; a nonce failure means the
+             * handshake raced and an immediate retry is the right move. One label for all three sends
+             * someone to look for a broken relay in all three cases.
+             */
+            const relayReason = typeof ackFrame["reason"] === "string" ? ackFrame["reason"] : undefined;
+            const retryAfterMs = typeof ackFrame["retry_after_ms"] === "number" ? ackFrame["retry_after_ms"] : undefined;
+            /**
+             * DOD-M15-RELAYSLOTS-1: keep the refusal, do not merely log it.
+             *
+             * Everything below writes an excellent warn line into a file nobody opens. The operator who
+             * runs `cello_use_agent` and finds their agent unreachable never sees it, and the daemon
+             * deciding whether another relay would help cannot read it either. So the classified refusal
+             * — reason, what to do about it, and whether to fail over — is stored where both can reach it.
+             */
+            const slotsHeld = typeof ackFrame["slots_held"] === "number" ? ackFrame["slots_held"] : undefined;
+            const slotCap = typeof ackFrame["slot_cap"] === "number" ? ackFrame["slot_cap"] : undefined;
+            this.#lastAuthRefusal = classifyRelayAuthRefusal(ackFrame["type"] === "relay_auth_failed" ? (relayReason ?? "auth_rejected") : "unexpected_frame", {
+                ...(slotsHeld !== undefined ? { slotsHeld } : {}),
+                ...(slotCap !== undefined ? { slotCap } : {}),
+                ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            });
             this.#logger.warn("session.relay.auth.failed", {
                 relayPeerId: this.#relayPeerId,
-                reason: ackFrame["type"] === "relay_auth_failed" ? "auth_rejected" : "unexpected_frame",
+                reason: ackFrame["type"] === "relay_auth_failed" ? (relayReason ?? "auth_rejected") : "unexpected_frame",
+                ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+                impact: relayReason === "rate_limited"
+                    ? "this relay is throttling us; it clears on its own after the stated window, and until it does this agent cannot reserve or witness here"
+                    : "this agent could not authenticate to this relay, so it cannot witness leaves or hold a reservation here",
             });
             return false;
         }
+        // DOD-M15-RELAYSLOTS-1: a success clears the stored refusal, so a stale one is never reported
+        // as the current state of a relay that has since started admitting us.
+        this.#lastAuthRefusal = null;
         return true;
     }
     #startReader(stream, iter) {
@@ -906,6 +1377,21 @@ export class AgentRelayClient {
      * and returned as-is — retrying those would be pointless traffic masking a real state.
      */
     static #SESSION_NOT_FOUND_ATTEMPTS = 3;
+    /**
+     * DOD-M15-RELAYABUSE-1 review F1: how many times a throttled submit waits out the relay's stated
+     * window before the refusal is surfaced. Three, because the window is a fixed sliding minute —
+     * two waits clear any ordinary burst, and a third failure means something other than this
+     * sender's own volume is going on, which the operator should hear about.
+     */
+    static #RATE_LIMITED_ATTEMPTS = 3;
+    /** Used only when the relay names no window (an older relay, or a malformed value). */
+    static #RATE_LIMITED_FALLBACK_MS = 5_000;
+    /**
+     * Ceiling on a single wait, so a relay reporting an implausible window cannot park a send
+     * indefinitely — a hostile or misconfigured relay must not be able to stall a sender by
+     * answering `retry_after_ms: 3600000`. Past this the send fails and says so.
+     */
+    static #RATE_LIMITED_MAX_WAIT_MS = 65_000;
     async #doSubmit(node, sessionId, contentHash, leafKind, contentBytes) {
         const sessionIdHex = Buffer.from(sessionId).toString("hex");
         // Snapshotted BEFORE the first attempt, and it is the whole safety of this loop.
@@ -945,6 +1431,51 @@ export class AgentRelayClient {
             });
             result = await this.#doSubmitOnce(node, sessionId, contentHash, leafKind, contentBytes);
         }
+        /**
+         * DOD-M15-RELAYABUSE-1 review F1 — **A THROTTLE IS BACK-PRESSURE, NOT AN ERROR.** (Andre,
+         * 2026-08-31: retry on the relay's own timing; surface only if the retry also fails.)
+         *
+         * Without this the relay's `rate_limited` fell into the caller's catch-all: one log line, and
+         * `cello_send` returned `{ok:true, delivered:true}` for a message the relay had refused to
+         * witness — on the parked path telling the operator it was *"sealed, witnessed and on its way"*.
+         * The leaf went out unwitnessed with no sequence number, and the seal later covered a transcript
+         * missing it.
+         *
+         * This is the ONE refusal that is safely retryable and self-clearing, and the relay tells us
+         * exactly when. So we wait it out here, where the wait is invisible, rather than handing the
+         * agent an error for a condition that resolves in under a minute. Bounded: if the window is
+         * absent or implausible we fall back to a fixed wait, and after
+         * `#RATE_LIMITED_ATTEMPTS` the refusal is returned and the caller surfaces it — Option 2 as
+         * the fallback, not the first move.
+         */
+        for (let attempt = 1; attempt < _a.#RATE_LIMITED_ATTEMPTS
+            && !result.ok
+            && result.reason === "rate_limited"
+            && !this.#closed; attempt++) {
+            const waitMs = Math.min(result.retry_after_ms !== undefined ? result.retry_after_ms : _a.#RATE_LIMITED_FALLBACK_MS, _a.#RATE_LIMITED_MAX_WAIT_MS);
+            this.#logger.info("session.relay.submit.throttled", {
+                relayPeerId: this.#relayPeerId,
+                sessionShort: sessionIdHex.slice(0, 16),
+                attempt,
+                waitMs,
+                retryAfterMsFromRelay: result.retry_after_ms,
+                impact: "the relay is throttling this sender; waiting out its stated window and resubmitting — the message is NOT lost and the operator is not told, because this clears on its own",
+            });
+            await new Promise((r) => setTimeout(r, waitMs));
+            if (this.#closed)
+                break;
+            result = await this.#doSubmitOnce(node, sessionId, contentHash, leafKind, contentBytes);
+        }
+        if (!result.ok && result.reason === "rate_limited") {
+            // Option 2, the fallback: it did not clear within our budget, so the caller must hear it
+            // rather than be told the message was witnessed.
+            this.#logger.warn("session.relay.submit.throttle_persisted", {
+                relayPeerId: this.#relayPeerId,
+                sessionShort: sessionIdHex.slice(0, 16),
+                attempts: _a.#RATE_LIMITED_ATTEMPTS,
+                impact: "this message was NOT witnessed by the relay — it has no sequence number and will not appear in the notarized record",
+            });
+        }
         // The relay lost a session we had successfully recorded — sealed, idle-swept, or restarted.
         // Report THAT, rather than letting the caller read a bare `session_not_found` that reads like
         // the first-message race. Never re-present here: recreating it is the resurrection above.
@@ -1041,6 +1572,7 @@ export class AgentRelayClient {
         // Remember this submit's sender-signed structure1_cbor so its ack can return the full
         // ordering record (the ack itself carries only the relay's structure2_cbor).
         this.#pendingStructure1 = structure1;
+        this.#pendingSignature = signature;
         this.#pendingLeafKind = leafKind;
         try {
             stream.send(lp.encode.single(frame));
@@ -1050,6 +1582,7 @@ export class AgentRelayClient {
                 this.#pendingAck = null;
                 this.#pendingAckSessionHex = null;
                 this.#pendingStructure1 = null;
+                this.#pendingSignature = null;
                 this.#pendingLeafKind = null;
             }
             this.#logger.warn("session.relay.submit.send.failed", { relayPeerId: this.#relayPeerId, error: extractErrorMessage(err) });
@@ -1072,6 +1605,7 @@ export class AgentRelayClient {
                 this.#pendingAck = null;
                 this.#pendingAckSessionHex = null;
                 this.#pendingStructure1 = null;
+                this.#pendingSignature = null;
                 this.#pendingLeafKind = null;
             }
         }