@cello-protocol/daemon 0.0.182 → 0.0.183

package/dist/session-relay-client.js

@@ -72,6 +72,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;
@@ -167,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;
@@ -182,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;
@@ -205,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() {
@@ -236,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).
@@ -327,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);
@@ -472,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.
@@ -479,7 +628,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 +636,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 +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)
@@ -559,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.
     }
@@ -570,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)
@@ -622,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" });
@@ -646,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) });
@@ -667,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) {
@@ -906,6 +1232,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 +1286,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 +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));
@@ -1050,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) });
@@ -1072,6 +1460,7 @@ export class AgentRelayClient {
                 this.#pendingAck = null;
                 this.#pendingAckSessionHex = null;
                 this.#pendingStructure1 = null;
+                this.#pendingSignature = null;
                 this.#pendingLeafKind = null;
             }
         }