@cello-protocol/daemon 0.0.181 → 0.0.183

package/dist/session-relay-client.js

@@ -31,7 +31,7 @@ var _a;
 import { createHash } from "node:crypto";
 import * as lp from "it-length-prefixed";
 import { decode } from "cbor-x";
-import { encodeCbor } from "@cello-protocol/protocol-types";
+import { encodeCbor, decodeSealPayload } from "@cello-protocol/protocol-types";
 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";
@@ -51,11 +51,118 @@ export const RELAY_AUTH_DOMAIN = "CELLO-RELAY-AUTH-v1";
  * ENUMERATED, never pattern-matched. A substring rule like `reason.includes("sealed")` would absorb
  * a future reason nobody has considered — which is the same collapse in a new coat.
  */
-export const TERMINAL_RELAY_REFUSALS = new Set(["session_sealed", "session_not_found"]);
+export const TERMINAL_RELAY_REFUSALS = new Set([
+    "session_sealed",
+    "session_not_found",
+    /**
+     * `DOD-M15-TERMINAL-REASON-1` split `session_sealed` into named causes, and this set is one of
+     * THREE places keyed on the old literal — a rename on the relay silently made a terminal refusal
+     * non-terminal here, which is the 68-minute defect above reopened by a string change.
+     *
+     * `seal_refused`: a directory READ the seal and rejected it. Terminal in the strongest sense —
+     * there is no later, and no retry can change a merits verdict.
+     *
+     * `seal_in_progress` is deliberately ABSENT. A seal in flight may still succeed, and after
+     * `DOD-M15-TRANSPORT-TERMINAL-1` the session can return to `active` — treating it as terminal
+     * would retire a conversation that is about to seal normally.
+     */
+    "seal_refused",
+]);
 /** True when the relay has ended this session and no later submit can succeed. */
 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;
@@ -151,6 +258,18 @@ export class AgentRelayClient {
     #logger;
     #receiptStore;
     #sealLeafStore;
+    /** DOD-M15-RELAYSLOTS-1 — read fresh at every auth. See `AgentRelayClientOpts.onlineToken`. */
+    #onlineToken;
+    /**
+     * 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;
@@ -166,6 +285,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;
@@ -189,6 +315,7 @@ export class AgentRelayClient {
         this.#logger = opts.logger;
         this.#receiptStore = opts.receiptStore;
         this.#sealLeafStore = opts.sealLeafStore;
+        this.#onlineToken = opts.onlineToken;
     }
     /** The agent's K_local public key as hex — the responder identity for auto-acknowledge. */
     get senderPubkeyHex() {
@@ -220,6 +347,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).
@@ -311,12 +461,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);
@@ -456,6 +619,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.
@@ -463,12 +628,24 @@ 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") {
             const reason = typeof frame["reason"] === "string" ? frame["reason"] : "relay_rejected";
-            this.#settlePending({ ok: false, reason });
+            // 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;
+            // 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.
@@ -480,7 +657,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)
@@ -540,6 +733,36 @@ export class AgentRelayClient {
                 });
             }
         }
+        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.
     }
@@ -551,6 +774,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)
@@ -603,7 +881,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" });
@@ -627,8 +905,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) });
@@ -648,12 +955,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) {
@@ -729,18 +1074,132 @@ export class AgentRelayClient {
      * `final_message` and from `answered` — guards that could never fire while this method hardcoded
      * MSG for every caller. See `document-leaf-kind-on-the-wire.test.ts` for what that cost.
      */
-    async submitMessageHash(node, sessionId, contentHash, leafKind = LEAF_KIND_MSG) {
-        return this.submitLeaf(node, sessionId, contentHash, leafKind);
+    async submitMessageHash(node, sessionId, contentHash, 
+    /**
+     * REQUIRED — `DOD-M15-SEALWIRE-1` B2b-1 pass-2 F3. This default was the last one on the path,
+     * and it is the reason a test passing `undefined` for `leafKind` looked correct: the value was
+     * silently rebuilt as MESSAGE one hop below the parameter the fix had just made required. Its
+     * one production caller always passes explicitly, so the default was dead and misleading.
+     */
+    leafKind) {
+        /**
+         * `null`, and it is now IMPOSSIBLE to omit — see `submitLeaf`'s note on why the parameter is
+         * required. A message leaf's content belongs to the operator and never reaches the relay.
+         */
+        return this.submitLeaf(node, sessionId, contentHash, leafKind, null);
     }
     /**
      * Submit a leaf hash of a given kind (0x00 message / 0x02 control) to the relay. The SEAL
      * ctrl leaf rides this path: two distinct-sender ctrl leaves in the relay's
      * log trigger the directory's FROST notarization (relay `#maybeProcessSeal`).
+     *
+     * ─── `contentBytes` — `DOD-M15-SEALWIRE-1` bullets 3+4, THE SENDER LEG ───────────────────────
+     *
+     * The SEAL leaf's own payload, carried alongside its hash. Without it the directory holds a
+     * SHA-256 pre-image and nothing else, so the client's SIGNED `final_root` — the one value in the
+     * whole seal that the relay cannot produce — is unrecoverable, and every root check the directory
+     * can make compares the relay against itself.
+     *
+     * ⚠️ THIS PARAMETER PUTS LEAF CONTENT ON THE RELAY, AND THE RELAY IS THE PARTY THIS PROTOCOL
+     * EXISTS TO KEEP CONTENT AWAY FROM (INV-3: a forwarding relay sees ciphertext).
+     *
+     * It is safe for a SEAL ctrl leaf and for nothing else. The payload is `[session_id, final_root,
+     * close_timestamp, "PENDING"]` and the relay already knows all four — it assigned the session,
+     * built the tree the root comes from, and stamped the leaf. Nothing is disclosed. That reasoning
+     * stops dead at the next leaf kind: a `msg` leaf's content is the operator's plaintext and a `doc`
+     * leaf's is their document.
+     *
+     * So both directions are REFUSED rather than tidied, and refused HERE rather than at the relay:
+     *
+     *   - content on a non-ctrl leaf → the relay would refuse the whole frame, but only after the
+     *     operator's words had already crossed the wire to the party that must not have them, and the
+     *     refusal would destroy their send rather than protect it.
+     *   - a ctrl leaf with NO payload → this was the actual defect. `submitSealLeaf` computed the
+     *     payload, hashed it, and had nowhere to put it, so it was dropped. The seal still succeeded,
+     *     the relay still acked, and three hops later the directory reported `not_carried` and blamed
+     *     the relay's build version — for a value the client never sent. Four reviewed legs shipped
+     *     over that silence. A dropped argument now fails on the machine that dropped it.
+     *
+     * ⚠️ REQUIRED, AND `| null` RATHER THAN `?` — THE TYPE IS THE GUARD.
+     *
+     * I first wrote this optional and covered it with tests. Then I ran the revert test that mattered:
+     * drop the argument at the one call site that must pass it, exactly reproducing the original
+     * defect. **All five new tests stayed green.** An optional parameter makes the defect a silent,
+     * type-legal omission — which is precisely how it shipped through four reviews the first time.
+     *
+     * Required means the omission is a COMPILE ERROR, caught by the gate on the machine that made it,
+     * before any test runs. Every caller must now say what this leaf carries, and `submitMessageHash`
+     * says `null` in one visible place instead of by saying nothing at all.
      */
-    async submitLeaf(node, sessionId, contentHash, leafKind) {
+    async submitLeaf(node, sessionId, contentHash, leafKind, contentBytes) {
+        if (contentBytes !== null && leafKind !== LEAF_KIND_CTRL) {
+            // Logged at ERROR and returned: a caller reaching this line is trying to hand the relay
+            // operator content, and the log must carry it even if the caller swallows the result.
+            this.#logger.error("session.relay.submit.content_not_permitted", {
+                relayPeerId: this.#relayPeerId,
+                leafKind,
+                impact: "the submit was NOT sent. Only a SEAL ctrl leaf may carry its content to the relay; every other leaf kind's content belongs to the operator.",
+                guidance: "Pass contentBytes only with LEAF_KIND_CTRL. If a new leaf kind genuinely needs to disclose its content to the relay, that is a protocol decision, not a call-site one.",
+            });
+            return { ok: false, reason: "content_not_permitted_for_leaf_kind" };
+        }
+        if (contentBytes === null && leafKind === LEAF_KIND_CTRL) {
+            this.#logger.error("session.relay.submit.seal_payload_missing", {
+                relayPeerId: this.#relayPeerId,
+                impact: "the seal leaf was NOT sent. Sending it without its payload produces a certificate the directory cannot check against any participant's signed transcript — silently, and reported downstream as the RELAY being on an old build.",
+                guidance: "A ctrl leaf on this path is a SEAL leaf; pass the encodeSealPayload bytes whose SHA-256(0x02 ‖ payload) is the contentHash argument.",
+            });
+            return { ok: false, reason: "seal_payload_not_carried" };
+        }
+        if (contentBytes !== null) {
+            /**
+             * ⚠️ THE BYTES MUST BE A SEAL PAYLOAD FOR THIS SESSION, AND THEY MUST HASH TO THE HASH BEING
+             * SIGNED — review pass 2, MEDIUM-1 and HIGH-1. The kind check alone was not the property this
+             * parameter's whole justification rests on.
+             *
+             * The justification is: *"the payload is [session_id, final_root, close_timestamp, "PENDING"]
+             * and the relay already knows all four, so nothing is disclosed."* The code enforced
+             * `leafKind === CTRL` and nothing else — so a caller passing a ctrl leaf with four kilobytes
+             * of the operator's text would have transmitted it, and been refused only at the relay, AFTER
+             * it crossed the wire to the party that must not have it. That is the precise harm the local
+             * guard exists to prevent, and the relay learned this same lesson at its own review (H1 in
+             * `relay-frames.ts`) one file over. I wrote the weaker version anyway.
+             *
+             * THE HASH BINDING IS THE MORE IMPORTANT HALF, and it closes a mutant that survived pass 1's
+             * type hardening. Making the parameter required catches an OMITTED argument; it cannot catch a
+             * SUBSTITUTED one. A caller that re-derives the payload instead of passing the one it hashed
+             * — a second `encodeSealPayload` call, a fresh `Date.now()` — compiles, and the mismatch
+             * surfaces at the directory as `seal_payload_unbound`, whose guidance reads *"someone between
+             * them and here altered or fabricated the payload — the relay is the only party on that path.
+             * Treat this as relay tampering, not a version mismatch."*
+             *
+             * **A client-side derivation slip would be published as a named accusation against a healthy
+             * relay operator.** Checking it here makes it a local refusal on the machine that caused it.
+             */
+            const rederived = new Uint8Array(createHash("sha256").update(new Uint8Array([LEAF_KIND_CTRL])).update(contentBytes).digest());
+            if (!Buffer.from(rederived).equals(Buffer.from(contentHash))) {
+                this.#logger.error("session.relay.submit.seal_payload_unbound", {
+                    relayPeerId: this.#relayPeerId,
+                    impact: "the seal leaf was NOT sent. The payload does not hash to the content_hash this leaf signs, so the directory would have reported it as RELAY TAMPERING — a named accusation against a node that did nothing wrong.",
+                    guidance: "Pass the SAME bytes that produced contentHash. Re-deriving the payload at the call site produces a different close_timestamp and breaks the binding.",
+                });
+                return { ok: false, reason: "seal_payload_unbound" };
+            }
+            const decoded = decodeSealPayload(contentBytes);
+            if (!decoded || !Buffer.from(decoded.session_id).equals(Buffer.from(sessionId))) {
+                this.#logger.error("session.relay.submit.seal_payload_invalid", {
+                    relayPeerId: this.#relayPeerId,
+                    impact: "the submit was NOT sent. Only a SEAL payload for THIS session may be disclosed to the relay — arbitrary bytes on a ctrl leaf are still the operator's content, and a payload for another session is a replay.",
+                    guidance: decoded
+                        ? "The payload names a different session than the one being submitted."
+                        : "The bytes are not a decodable SEAL payload. Build them with encodeSealPayload.",
+                });
+                return { ok: false, reason: "seal_payload_invalid" };
+            }
+        }
         // Chain on the prior submit so only one is outstanding at a time (FIFO). The ack
         // carries no session_id, so concurrent submits on one stream would be ambiguous.
-        const run = this.#submitChain.then(() => this.#doSubmit(node, sessionId, contentHash, leafKind));
+        const run = this.#submitChain.then(() => this.#doSubmit(node, sessionId, contentHash, leafKind, contentBytes));
         // Keep the chain alive regardless of this submit's outcome.
         this.#submitChain = run.then(() => undefined, () => undefined);
         return run;
@@ -773,7 +1232,22 @@ export class AgentRelayClient {
      * and returned as-is — retrying those would be pointless traffic masking a real state.
      */
     static #SESSION_NOT_FOUND_ATTEMPTS = 3;
-    async #doSubmit(node, sessionId, contentHash, leafKind) {
+    /**
+     * 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.
         //
@@ -791,7 +1265,7 @@ export class AgentRelayClient {
         // reported `session_not_found`, indistinguishable at the wire from the race — which is why
         // this must be discriminated on OUR state, not on the relay's reason string.
         const recordedBefore = this.#sessions.get(sessionIdHex)?.recorded === true;
-        let result = await this.#doSubmitOnce(node, sessionId, contentHash, leafKind);
+        let result = await this.#doSubmitOnce(node, sessionId, contentHash, leafKind, contentBytes);
         for (let attempt = 1; attempt < _a.#SESSION_NOT_FOUND_ATTEMPTS
             && !recordedBefore
             && !result.ok
@@ -810,7 +1284,52 @@ export class AgentRelayClient {
                 attempt,
                 reason: result.reason,
             });
-            result = await this.#doSubmitOnce(node, sessionId, contentHash, leafKind);
+            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
@@ -825,7 +1344,7 @@ export class AgentRelayClient {
         }
         return result;
     }
-    async #doSubmitOnce(node, sessionId, contentHash, leafKind) {
+    async #doSubmitOnce(node, sessionId, contentHash, leafKind, contentBytes) {
         if (this.#closed)
             return { ok: false, reason: "relay_client_closed" };
         if (!(await this.#ensureConnected(node)))
@@ -872,6 +1391,32 @@ export class AgentRelayClient {
             leaf_kind: leafKind,
             structure1_cbor: structure1,
             sender_signature: signature,
+            /**
+             * `DOD-M15-SEALWIRE-1` bullets 3+4 — the SEAL payload, and ONLY on a ctrl leaf.
+             *
+             * ⚠️ MY REASON FOR THE SPREAD WAS MEASURABLY WRONG, AND THE TRUE RISK IS THE OPPOSITE ONE —
+             * review pass 2, MEDIUM-3, corrected rather than deleted.
+             *
+             * It said an explicit `content_bytes: undefined` *"encodes as a present CBOR key, and the
+             * relay's guard refuses a present-but-unusable value by voiding the whole frame — that would
+             * turn every ordinary message into a refused submit."* Measured through the production encoder:
+             * the key IS emitted (0xf7), but it decodes back to `undefined`, so the relay's guard never
+             * fires and the frame is **accepted with no payload**.
+             *
+             * So the mutation does not produce a loud federation-wide refusal. It produces a silent
+             * `not_carried` at the directory — exactly the silent downgrade this whole unit exists to kill,
+             * and a far worse outcome than the one I warned about. Writing the scarier consequence would
+             * have sent the next reader hunting an availability bug instead of a mute one.
+             *
+             * The spread is still correct, and the ANCHOR test is what pins it: `"content_bytes" in frame`
+             * is TRUE for the `undefined` mutant precisely because the key is present, so that assertion —
+             * not the relay — is what catches this.
+             *
+             * `submitLeaf` has already established that this is set if and only if `leafKind` is ctrl, and
+             * that the bytes are a SEAL payload for this session hashing to the signed `content_hash` —
+             * every direction refused there, at ERROR, before anything reaches the wire.
+             */
+            ...(contentBytes !== null ? { content_bytes: contentBytes } : {}),
         });
         // Set the resolver synchronously (no await between the in-flight check and the set):
         // the submit chain guarantees no other submit runs concurrently, so #pendingAck is null.
@@ -882,6 +1427,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));
@@ -891,6 +1437,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) });
@@ -913,6 +1460,7 @@ export class AgentRelayClient {
                 this.#pendingAck = null;
                 this.#pendingAckSessionHex = null;
                 this.#pendingStructure1 = null;
+                this.#pendingSignature = null;
                 this.#pendingLeafKind = null;
             }
         }