@cello-protocol/daemon 0.0.208 → 0.0.210

package/dist/session-relay.js

@@ -130,8 +130,15 @@ export class SessionRelay {
              * what looks like a fleet-wide outage.
              */
             if (refusal?.tryAnotherRelay && !this.#ctx.shuttingDown) {
+                /**
+                 * ⚠️ **THE QUARANTINE ACTS; THE REBUILD USED TO AND NO LONGER CAN — 056-SLOTDEAD.**
+                 *
+                 * This used to `rebuildStandingReceiver` so the new node would reserve against the rest of
+                 * the pool. A rebuilt receiver reserves NOTHING now (055-ONDEMAND), so the rebuild bought
+                 * nothing and cost the agent its transport identity. The quarantine is the half that still
+                 * does the work: the next offer reserves against the pool minus this relay.
+                 */
                 this.#quarantineRelay(agentName, relayPeerId, refusal.reason);
-                void this.#ctx.receivers.rebuildStandingReceiver(agentName);
             }
         }
         else {
@@ -742,18 +749,20 @@ export class SessionRelay {
             this.#ctx.srReservationRetry.delete(agentName);
             this.#ctx.srLastRejectionReason.delete(agentName);
         }
-        if (endpoints.length === 0 || this.#ctx.shuttingDown)
-            return;
-        const sr = this.#ctx.standingReceivers.get(agentName);
-        if (!sr)
-            return; // not ensured yet — the coming ensure reads the map
-        if (sr.node.listenAddresses().some((a) => a.includes("/p2p-circuit")))
-            return; // already reserved
-        this.#ctx.logger.info("session.standing_receiver.reservation.rebuild", {
-            agentName,
-            relayPeerIds: endpoints.map((e) => e.relayPeerId),
-        });
-        void this.#ctx.receivers.rebuildStandingReceiver(agentName);
+        /**
+         * ⚠️ **ENDPOINTS ARRIVING NO LONGER REBUILD THE RECEIVER — 055-ONDEMAND.**
+         *
+         * This used to rebuild so the new node could reserve with the relays that had just been
+         * announced, because reservations were fixed at node creation and acquired at login. Neither is
+         * true now: nothing is reserved at login, and a running node can take one on demand.
+         *
+         * So a rebuild here would buy nothing and cost something real. The receiver it replaces may be
+         * holding the circuit a LIVE SESSION's counterparty was told to dial — throwing that away in
+         * response to a routine directory announcement would drop the route silently, at both ends.
+         *
+         * The endpoints are still recorded above, which is all they were ever needed for: they are the
+         * candidate list an offer reserves against.
+         */
     }
     /**
      * Is this agent currently skipping this relay? The observable half of the failover decision — a
@@ -880,35 +889,45 @@ export class SessionRelay {
      * That is precisely the silent-loss-of-inbound failure this whole story exists to
      * kill, so it cannot be left to chance: we watch for it and re-pick a relay.
      *
-     * Only receivers that HAD a reservation are watched. One that never got one is
-     * already degraded and already loud (reservation.none / reservation.timeout);
-     * rebuilding it on a timer would just thrash against relays we know are refusing.
+     * ⚠️ 056-SLOTDEAD: this paragraph used to end "Only receivers that HAD a reservation are watched.
+     * One that never got one is already degraded and already loud (reservation.none /
+     * reservation.timeout); rebuilding it on a timer would just thrash against relays we know are
+     * refusing." Every clause of that is now false — an idle receiver holds nothing BY DESIGN so
+     * "degraded" is the normal state, `reservation.none` is not emitted at build any more, and
+     * nothing rebuilds. What is watched is a receiver whose recorded set has shrunk, and what
+     * happens is a re-take in place for a LIVE session, never a rebuild.
      */
     /**
-     * DOD-M12B-RESERVATION-RETRY-1 — ask again for a reservation the relay refused.
+     * DOD-M12B-RESERVATION-RETRY-1 / 055-ONDEMAND — is a re-attempt due, and claim it if so.
+     *
+     * ⚠️ **TWO DOC BLOCKS DESCRIBING `#retryReservationIfDue` USED TO SIT HERE — 056-SLOTDEAD, review
+     * F7.** That function is deleted. One of them said "the rebuild is the re-attempt … which is why
+     * it stays", so a reader following the comment landed on this function and concluded a rebuild
+     * ladder was still running. There is no rebuild anywhere in this file.
      *
-     * The rebuild is the re-attempt. ⚠️ It is a CHOICE, not the only option: its old justification
-     * ("a circuit listener is fixed at node creation") stopped being true when `listenOnCircuit`
-     * landed. A fresh receiver re-runs the whole walk, proof included, which is why it stays.
+     * What this does: a live session that lost its circuit re-takes it IN PLACE, on the node that
+     * already has the session, and this owns whether it is allowed to try yet. ONE ladder — a
+     * reservation is scarce, the relay holds it for its full TTL even after the client disconnects,
+     * and this file's own warning is that churning attempts across a fleet is how a relay is
+     * exhausted.
      */
-    #retryReservationIfDue(agentName) {
+    #retryDue(agentName) {
         const now = Date.now();
         const state = this.#ctx.srReservationRetry.get(agentName)
             ?? { attempts: 0, nextAt: now + this.#ctx.srReservationRetryMs, correlationId: randomUUID() };
-        // The reason the LAST attempt was refused, captured where it is actually known.
         const lastReason = this.#ctx.srLastRejectionReason.get(agentName);
         if (lastReason !== undefined)
             state.lastReason = lastReason;
-        if (state.attempts === 0 && !this.#ctx.srReservationRetry.has(agentName)) {
-            // First sighting — schedule, do not fire. The creation attempt just happened.
+        if (!this.#ctx.srReservationRetry.has(agentName)) {
+            // First sighting — schedule, do not fire. Something just tried.
             this.#ctx.srReservationRetry.set(agentName, state);
-            return;
+            return false;
         }
         if (now < state.nextAt)
-            return;
+            return false;
         if (state.attempts >= SR_RESERVATION_MAX_RETRIES) {
             if (state.attempts === SR_RESERVATION_MAX_RETRIES) {
-                state.attempts += 1; // mark as reported, so this fires exactly once
+                state.attempts += 1; // report once
                 this.#ctx.srReservationRetry.set(agentName, state);
                 this.#ctx.logger.error("session.standing_receiver.reservation.gave_up", {
                     agentName,
@@ -917,51 +936,43 @@ export class SessionRelay {
                     // WHY, not just the consequence. Three different problems reach this one message and they
                     // need three different responses: `relay_granted_no_reservation` is relay CAPACITY (and a
                     // trustless-cello problem), `relay_unreachable` is the NETWORK, and
-                    // `reservation_did_not_complete_in_time` is LATENCY — and the only one of the three that
-                    // can pin a slot it never uses, so its appearance is also the signal that this retry
-                    // budget needs tightening.
+                    // `reservation_did_not_complete_in_time` is LATENCY.
                     ...(state.lastReason !== undefined ? { lastRejectionReason: state.lastReason } : {}),
-                    // "No relay would grant" and "there was no relay to ask" are different facts and lead to
-                    // different places — the first at relay capacity, the second at this agent's directory
-                    // connection. Without this they are the same sentence.
-                    //
-                    // 032-RELAYSPREAD: this was also called `reservationsRequested` — the same mis-naming as
-                    // the reachability events, in its worst form, because here the value is a BOOLEAN under a
-                    // name that reads as a count. It is NOT `relaysOffered`: that field counts the merged
-                    // candidate list the walk actually asks (directory pool + persisted endpoints, minus
-                    // quarantine), and this reads the directory pool alone. Two populations must not share
-                    // one field name, so this one is named for what it measures.
+                    /**
+                     * ⚠️ **THESE TWO CAME BACK — 056-SLOTDEAD, review F9.** The deleted emitter of this SAME
+                     * event name carried them; the surviving one did not, so the fields quietly vanished from
+                     * an operator's view while the event kept appearing.
+                     *
+                     * "No relay would grant" and "there was no relay to ask" are different facts that lead to
+                     * different places — the first at relay capacity, the second at this agent's directory
+                     * connection. Without them they are the same sentence.
+                     *
+                     * `hadRelayToAsk` reads the directory pool alone; `relaysOffered` is the merged,
+                     * quarantine-filtered candidate list the re-take actually walks. Two populations, so two
+                     * names — the mis-naming that made `reservationsRequested` unreadable is the reason this
+                     * note exists.
+                     */
                     hadRelayToAsk: (this.#ctx.directoryRelayEndpoints.get(agentName)?.length ?? 0) > 0,
-                    // …and HOW MANY the walk actually asks, so this event stands on its own instead of
-                    // needing the last reachability line to be read beside it. Same population and same
-                    // meaning as `relaysOffered` everywhere else: the merged, quarantine-filtered candidate
-                    // list.
                     relaysOffered: this.reservationCircuitAddrs(agentName).addrs.length,
-                    impact: "no relay would grant this agent a circuit reservation, so anyone behind NAT cannot reach or dial it — inbound sessions will only arrive from peers that can connect directly, and everything else falls back to the relay's store-and-forward",
+                    impact: "a live session lost the circuit its counterparty dials, and no relay would give " +
+                        "it back inside the retry budget. Messages still reach this agent through the relay's " +
+                        "store-and-forward; a direct dial to it will not connect until the session is rebuilt.",
                 });
             }
-            return;
+            return false;
         }
         state.attempts += 1;
-        // The FINAL attempt gets a fixed settle window rather than another doubled wait: at the top of
-        // the ladder that would be 80 minutes of silence after the last thing we did, which is a long
-        // time to tell an operator nothing. Every earlier attempt doubles, which is what keeps a fleet
-        // off a scarce relay.
-        state.nextAt = now + (state.attempts >= SR_RESERVATION_MAX_RETRIES
-            ? this.#ctx.srReservationRetryMs
-            : this.#ctx.srReservationRetryMs * 2 ** (state.attempts - 1));
+        // Doubling, floored at the configured interval. 056-SLOTDEAD: this said "the same shape the
+        // rebuild ladder uses" — there is no rebuild ladder any more, this IS the ladder. The reason is
+        // unchanged: a fixed short interval is what exhausts a relay.
+        state.nextAt = now + this.#ctx.srReservationRetryMs * Math.pow(2, state.attempts - 1);
         this.#ctx.srReservationRetry.set(agentName, state);
-        this.#ctx.logger.warn("session.standing_receiver.reservation.retry", {
-            agentName,
-            attempt: state.attempts,
-            maxAttempts: SR_RESERVATION_MAX_RETRIES,
-            correlationId: state.correlationId,
-            ...(state.lastReason !== undefined ? { lastRejectionReason: state.lastReason } : {}),
-            impact: "this agent currently holds no circuit reservation, so a NAT'd peer cannot dial it",
+        this.#ctx.logger.info("session.standing_receiver.reservation.retry", {
+            agentName, attempts: state.attempts, correlationId: state.correlationId,
         });
-        void this.#ctx.receivers.rebuildStandingReceiver(agentName);
+        return true;
     }
-    #reservationWatchdogTick() {
+    async #reservationWatchdogTick() {
         if (this.#ctx.shuttingDown)
             return;
         for (const [agentName, sr] of this.#ctx.standingReceivers) {
@@ -982,6 +993,99 @@ export class SessionRelay {
             // full TTL even after the client disconnects, and churning attempts across a fleet is how a
             // relay is exhausted (`#startReceiverNode` records that hazard).
             if (sr.relayPeerIds.length === 0) {
+                /**
+                 * ⚠️ **AN IDLE AGENT HOLDING NOTHING IS THE DESIGN NOW, NOT A DEGRADATION — 055-ONDEMAND.**
+                 *
+                 * Everything above this line was written when a receiver reserved at login and holding zero
+                 * meant an agent dialable by nobody for its whole life. A reservation is taken at OFFER time
+                 * now and given back at the seal, so zero is the correct steady state for an agent nobody is
+                 * calling — and retrying here would have every idle agent in the fleet asking relays for
+                 * slots the design says it must not hold. That is the exact churn the note below warns
+                 * about, pointed at the whole fleet instead of one receiver.
+                 *
+                 * The retry still matters for an agent that HAS a live session and lost the circuit that
+                 * session depends on, which is what the condition now says.
+                 */
+                const liveSessions = [...this.#ctx.activeNodes.values()].filter((e) => e.agentName === agentName);
+                if (liveSessions.length === 0)
+                    continue;
+                /**
+                 * ⚠️ **RE-TAKE THE SESSION'S CIRCUIT — REBUILDING THE RECEIVER NO LONGER DOES IT.**
+                 *
+                 * `#retryReservationIfDue` rebuilds the receiver, and a rebuilt receiver reserves NOTHING
+                 * (055-ONDEMAND). So on its own the retry ladder became a no-op by construction: a relay
+                 * that flapped mid-session would leave that session permanently un-dialable while the
+                 * ladder churned receivers to no effect.
+                 *
+                 * The circuit a live session needs is the one its ASSIGNMENT named, which is persisted with
+                 * the session — so ask for that one back, rather than rebuilding and hoping.
+                 */
+                /**
+                 * ⚠️ **ON THE SAME BUDGET AND BACKOFF AS THE LADDER IT REPLACES.** A reservation is scarce:
+                 * the relay holds it for its full TTL even after the client disconnects, and this file's own
+                 * warning is that churning attempts across a fleet is how a relay is exhausted. Asking on
+                 * every 30-second tick would be exactly that churn, wearing a new name — measured here as 52
+                 * asks where the budget allows 37.
+                 */
+                /**
+                 * ⚠️ **WHAT ACTUALLY NEEDS A CIRCUIT, DECIDED BEFORE THE BUDGET IS TOUCHED —
+                 * `DOD-M15-IDLERETRY-1`.**
+                 *
+                 * `#retryDue` was called FIRST, and it does not merely answer a question: on an agent it has
+                 * not seen before it WRITES a retry entry and returns false. So simply having a live session
+                 * while holding no circuit was enough to open a retry ladder — and for the INITIATOR of a
+                 * call that state is permanent and wrong, because an initiator DIALS OUT and never needs to
+                 * be dialable (055-ONDEMAND narrowed the reservation to the party being dialed, deliberately).
+                 *
+                 * Two things followed, and both were measured live on 2026-09-11 rather than reasoned:
+                 *   - `cello_status` reported `retrying` for a healthy agent from its first call onward,
+                 *     cleared only by a daemon restart — the same "a broken agent looks like a fine one"
+                 *     defect 060-READY had just fixed, in a case it did not cover;
+                 *   - worse, it is not cosmetic. Held past the retry interval, both agents emitted a real
+                 *     `session.standing_receiver.reservation.retry` — the daemon asking relays for slots on
+                 *     behalf of sessions that need none. That is churn against the scarce resource this
+                 *     whole story exists to conserve.
+                 *
+                 * So the question "is there anything to re-take?" is answered from the SESSION NODES first.
+                 * A session that already holds its circuit, or has no relay endpoint recorded, needs
+                 * nothing. If none needs anything, this tick is a no-op and must leave no trace.
+                 */
+                const needRetake = liveSessions.filter((entry) => {
+                    const ep = this.#ctx.queries.getPersistedRelayEndpoint(agentName, entry.sessionId);
+                    if (!ep || ep.relayAddrs.length === 0)
+                        return false;
+                    /**
+                     * ⚠️ `heldRelayIdsOf`, NOT a substring test — the same distinction 056-SLOTDEAD had to
+                     * make one layer up. A circuit address that does not NAME its relay cannot be dialled
+                     * through, so a session announcing one holds nothing usable and DOES need a re-take.
+                     * A substring test counts it as held and leaves that session silently unreachable.
+                     */
+                    return heldRelayIdsOf(entry.node).length === 0;
+                });
+                if (needRetake.length === 0)
+                    continue;
+                if (!this.#retryDue(agentName))
+                    continue;
+                /**
+                 * ⚠️ **ON THE SESSION'S OWN NODE, NOT THE IDLE RECEIVER — and the first version got this
+                 * wrong in a way that was worse than doing nothing.**
+                 *
+                 * It called the take path, which reserves on `standingReceivers.get(agentName).node`. That
+                 * is the fresh receiver built after the promotion — a DIFFERENT peer id from the one the
+                 * counterparty was told to dial. So the circuit it obtained helped no one, and it made an
+                 * IDLE receiver hold a relay slot, which is the exact thing this unit exists to stop. It
+                 * also set `relayPeerIds` non-empty, hiding the real loss from every later tick.
+                 */
+                let retook = false;
+                for (const entry of needRetake) {
+                    const ep = this.#ctx.queries.getPersistedRelayEndpoint(agentName, entry.sessionId);
+                    const base = ep.relayAddrs[0];
+                    const circuitAddr = base.includes(`/p2p/${ep.relayPeerId}`) ? `${base}/p2p-circuit` : `${base}/p2p/${ep.relayPeerId}/p2p-circuit`;
+                    if (await this.#ctx.retakeReservationOn(agentName, entry.node, circuitAddr, entry.correlationId))
+                        retook = true;
+                }
+                if (retook)
+                    continue;
                 // …unless one has arrived since. Review F4, same class as the recompute below: the
                 // slow-start path installs a receiver before every circuit has bound, so "held nothing at
                 // install" is not the same fact as "holds nothing now". Adopting it here is what stops the
@@ -989,7 +1093,19 @@ export class SessionRelay {
                 const arrived = heldRelayIdsOf(sr.node)
                     .filter((id) => sr.node.getConnections().some((c) => c.peerId === id && c.status === "open"));
                 if (arrived.length === 0) {
-                    this.#retryReservationIfDue(agentName);
+                    /**
+                     * ⚠️ **`#retryReservationIfDue` WAS CALLED HERE AND COULD NEVER DO ANYTHING — 056-SLOTDEAD.**
+                     *
+                     * It guards on `now < state.nextAt`, and `#retryDue` above advances that same state on
+                     * this very tick, so the second call always returned immediately. Reachable, referenced,
+                     * and inert — the shape a reference scan cannot find.
+                     *
+                     * *(The first version of this order claimed it DOUBLE-ADVANCED the budget and triggered a
+                     * useless rebuild. That was wrong, and it was wrong because it was reasoned rather than
+                     * run. It was a no-op.)*
+                     *
+                     * Nothing replaces it: `#retryDue` owns the budget and the re-take above owns the work.
+                     */
                     continue;
                 }
                 sr.relayPeerIds = arrived;
@@ -1069,117 +1185,75 @@ export class SessionRelay {
                 // client for this (agent, relay) pair kept the error that ended its reader; that is the
                 // nearest thing to an upstream cause available here, and its absence is how 2,061 of these
                 // went untraced.
-                const upstreamReason = this.#ctx.relayClients.get(`${agentName}::${relayPeerId}`)?.getLastReaderError();
+                /**
+                 * ⚠️ **A DIAGNOSTIC MUST NOT BE ABLE TO KILL THE WATCHDOG TICK.** This is optional-chained on
+                 * the map lookup but the METHOD was called unguarded, so a client without it threw — an
+                 * unhandled rejection inside the tick, which takes the rest of the sweep with it. Surfaced
+                 * when 055-ONDEMAND made this branch reachable in more cases. The cause line is worth
+                 * having; it is not worth the loss detection it rides on.
+                 */
+                const client = this.#ctx.relayClients.get(`${agentName}::${relayPeerId}`);
+                const upstreamReason = typeof client?.getLastReaderError === "function" ? client.getLastReaderError() : null;
                 this.#ctx.logger.warn("session.standing_receiver.reservation.lost", {
                     agentName,
                     relayPeerId,
                     reason: open.includes(relayPeerId) ? "circuit_address_vanished" : "relay_connection_gone",
                     ...(upstreamReason ? { upstreamReason } : {}),
                     reservationsHeld: stillHeld.length,
-                    // The line an operator reads, and the two cases are not the same event at all.
+                    /**
+                     * The line an operator reads, and the two cases are not the same event at all.
+                     *
+                     * ⚠️ **THE ZERO CASE PROMISED A REPAIR THAT NO LONGER HAPPENS — 056-SLOTDEAD, review F3.**
+                     * It ended "The receiver is being rebuilt against the rest of the pool", which was true
+                     * when this branch rebuilt. Nothing rebuilds now. An operator reading the old line would
+                     * wait for a recovery that was never coming, and the only thing that WOULD have told them
+                     * otherwise is a `zero_held` line at debug level they are not reading. Both branches now
+                     * say what actually happens next and who owns it.
+                     */
                     impact: stillHeld.length > 0
                         ? "this agent still holds " + stillHeld.length + " other circuit reservation(s), so it "
-                            + "stays dialable from behind NAT and the receiver is NOT rebuilt. Losing one relay "
-                            + "costs this agent nothing it can feel."
-                        : "this agent now holds NO circuit reservation, so nobody behind a home router can "
-                            + "reach it. The receiver is being rebuilt against the rest of the pool.",
+                            + "stays dialable from behind NAT. Losing one relay costs this agent nothing it can feel."
+                        : "this agent now holds NO circuit reservation. If it has no live session that is the "
+                            + "normal idle state and costs nothing — a slot is taken when someone calls. If it "
+                            + "DOES have a live session, that session's counterparty can no longer dial it, and "
+                            + "the re-take above is what gets it back, on a bounded budget. Nothing rebuilds the "
+                            + "receiver any more, so do not wait for one.",
                 });
             }
+            /**
+             * ⚠️ **DRAIN ON THE LOSS ITSELF — 056-SLOTDEAD.** This used to happen one step downstream, as
+             * a side effect of the rebuild below: lose every reservation → rebuild → the new receiver
+             * reports ready → drain. Deleting the rebuild would have deleted the drain with it, leaving
+             * content the counterparty parked to sit until the periodic backstop. The loss is the cause
+             * and always was; the rebuild was only where it happened to be noticed.
+             */
+            this.#ctx.park.fireParkedDrain(agentName, "reservation_lost");
             if (stillHeld.length === 0) {
-                // ZERO HELD IS STILL THE LOUD, STRUCTURAL CASE — the agent is unreachable behind NAT and
-                // only a new node can take a new reservation, because a circuit listener is fixed at node
-                // creation.
-                void this.#ctx.receivers.rebuildStandingReceiver(agentName);
+                /**
+                 * ⚠️ **THIS REBUILT THE RECEIVER ON A JUSTIFICATION THAT STOPPED BEING TRUE IN UNIT 1, AND
+                 * UNDER ON-DEMAND IT DESTROYS AN IN-FLIGHT OFFER'S RESERVATION — 056-SLOTDEAD.**
+                 *
+                 * It read: *"only a new node can take a new reservation, because a circuit listener is fixed
+                 * at node creation."* `listenOnCircuit` removed that constraint (`DOD-M15-RELAYPROVE-ORDER-1`),
+                 * and a rebuilt receiver now reserves nothing at all.
+                 *
+                 * The state it fires in is the dangerous one: between an offer taking a reservation and the
+                 * session being created, the receiver holds exactly one circuit. Lose the connection in that
+                 * window and this rebuilt the node — discarding the slot the offer just took, after the
+                 * accept may already have advertised it. **Observed**, not reasoned: a fixture that reported
+                 * no relay connection drove this path and the test caught the rebuild.
+                 *
+                 * Nothing replaces it here. An idle agent holding zero is the design; a LIVE session that
+                 * lost its circuit is re-taken on its own node by the branch above, on a bounded budget.
+                 */
+                this.#ctx.logger.debug("session.standing_receiver.reservation.zero_held", {
+                    agentName,
+                    impact: "this agent holds no circuit. If it has no live session that is the idle steady " +
+                        "state; if it does, the re-take above owns getting it back.",
+                });
                 continue;
             }
-            /**
-             * STILL REACHABLE, SO THE RECEIVER STANDS, AND NOTHING ELSE HAPPENS HERE. That second half is
-             * the part worth reading, because the obvious next line is wrong twice over.
-             *
-             * **A LOST CONFIGURED CIRCUIT CANNOT BE RETAKEN BY THIS NODE.** Read out of
-             * `@libp2p/circuit-relay-v2@4.2.5`, not assumed: for an explicit relay address
-             * `transport/listener.js#listen()` is a ONE-SHOT — it reserves once and nothing calls it
-             * again; `reservation-store.js#removeReservation()` clears the refresh timeout and deletes
-             * the entry; and the listener's `_onAddRelayPeer` returns early for `type === 'configured'`,
-             * so even a later reservation would not be announced. A circuit listener is fixed at node
-             * creation, and the only thing that takes a new one is a NEW NODE — which is exactly the
-             * rebuild this branch exists to refuse.
-             *
-             * **AND RE-PROVING TO THE LOST RELAY WOULD REBUILD THE RECEIVER ANYWAY.** Review F3: an
-             * earlier version called `authenticateStandingReceiver` here to "remove the relay-side
-             * reason for the revocation". That function ends with `if (refusal?.tryAnotherRelay) { …
-             * void this.#ctx.receivers.rebuildStandingReceiver(agentName); }` — and a dead or misconfigured relay is
-             * precisely the one that answers that way. So the common case was: lose relay A while
-             * holding B, decline to rebuild, prove to A, A refuses, rebuild the whole receiver and throw
-             * B's healthy reservation away. The churn engine, re-entered through the back door.
-             *
-             * **THE BOUND, STATED PLAINLY BECAUSE IT IS A REAL SHORTFALL AGAINST THE DoD:** a lost
-             * circuit is gone until the receiver is next rebuilt for another reason. What the agent buys
-             * is that it never STOPS BEING REACHABLE while that is true — the surviving relays carry it,
-             * the loss is named in the log with its cause, and the lost relay's inbound carve-out is
-             * revoked above. That is availability, not restoration in place.
-             *
-             * WHICH LEAVES A RATCHET, and `#respreadIfDecayed` below is what stops it: relays are only
-             * ever lost between rebuilds, never regained, so an agent nobody talks to walks itself back
-             * down to one relay — the exact state this unit exists to get it out of.
-             */
-        }
-        for (const agentName of this.#ctx.standingReceivers.keys()) {
-            if (this.#ctx.agentsWantingReceiver.has(agentName))
-                this.#respreadIfDecayed(agentName);
-        }
-    }
-    /**
-     * 032-RELAYSPREAD — **AN IDLE AGENT MUST NOT RATCHET ITSELF BACK DOWN TO ONE RELAY.**
-     *
-     * Spreading happens when a receiver is BUILT, and between builds the count only falls: a lost
-     * circuit is not retaken from here (`listenOnCircuit` could; nothing does), and a relay the
-     * directory announces later is skipped while any circuit is held. An agent in
-     * conversation re-spreads constantly — the receiver is handed into each session and a fresh one
-     * is built behind it — so this is about the agent nobody has talked to for a day. It loses relays
-     * one at a time, nothing pulls it back up, and it ends up exactly where this unit found it:
-     * reachable through one relay, one relay away from being reachable through none.
-     *
-     * **THE COST OF FIXING IT IS A NEW PEER ID**, which is why it is fenced three ways rather than
-     * simply rebuilding on sight:
-     *   - **ONLY WHEN IDLE.** A rebuild replaces the receiver's transport identity, and a counterparty
-     *     may be holding the old one from a `session_offer_accept`. With a live session for this agent
-     *     we leave it alone — a degraded spread costs redundancy, a changed peer id mid-conversation
-     *     costs the conversation.
-     *   - **ONLY WHEN THERE IS SOMETHING TO GAIN.** Holding every relay that was offered is not decay.
-     *   - **ON ITS OWN SLOW CLOCK**, never the watchdog's 30-second grid. A reservation is scarce —
-     *     the relay holds it for its full TTL even after we disconnect — so this reuses the
-     *     reservation retry interval rather than inventing a faster one.
-     */
-    #respreadIfDecayed(agentName) {
-        if (this.#ctx.shuttingDown)
-            return;
-        const sr = this.#ctx.standingReceivers.get(agentName);
-        if (!sr || sr.relayPeerIds.length === 0)
-            return; // zero held is the loud path
-        for (const entry of this.#ctx.activeNodes.values()) {
-            if (entry.agentName === agentName)
-                return; // in conversation — hands off
         }
-        const offered = this.reservationCircuitAddrs(agentName).addrs.length;
-        if (sr.relayPeerIds.length >= offered)
-            return; // nothing to gain
-        const now = Date.now();
-        const last = this.#ctx.srLastRespreadAt.get(agentName) ?? 0;
-        if (now - last < this.#ctx.srReservationRetryMs)
-            return;
-        this.#ctx.srLastRespreadAt.set(agentName, now);
-        this.#ctx.logger.info("session.standing_receiver.respread", {
-            agentName,
-            reservationsHeld: sr.relayPeerIds.length,
-            relaysOffered: offered,
-            impact: "this agent is idle and holds fewer relay reservations than it was offered, so its " +
-                "receiver is being rebuilt to take the rest. Without this it can only lose relays between " +
-                "rebuilds, and an agent nobody talks to drifts back down to a single relay — one relay " +
-                "away from being unreachable behind NAT, which is the state this whole mechanism exists " +
-                "to keep it out of.",
-        });
-        void this.#ctx.receivers.rebuildStandingReceiver(agentName);
     }
     /** Start the reservation watchdog (idempotent). Stopped by gracefulShutdown. */
     startReservationWatchdog() {
@@ -1190,7 +1264,7 @@ export class SessionRelay {
         this.#ctx.park.armBackstopClock(Date.now());
         this.#ctx.reservationWatchdog = setInterval(() => {
             try {
-                this.#reservationWatchdogTick();
+                void this.#reservationWatchdogTick();
                 this.#ctx.park.parkedDrainBackstopTick(Date.now());
             }
             catch (err) {
@@ -1249,6 +1323,61 @@ export class SessionRelay {
      * `tryAnotherRelay: false` precisely so the client STOPS walking the fleet; without the verdict,
      * the loop walked it anyway, turning one client-side fault into what reads as a fleet outage.
      */
+    /**
+     * 055-ONDEMAND — **tell the relay this agent has finished with its slot.**
+     *
+     * The only thing that actually frees one: closing a circuit listener sends the relay nothing, and
+     * the relay reclaims on its own only at the reservation TTL (two hours) or under reaper pressure.
+     * Best-effort by design — an undelivered release costs a slot until that TTL, and must never fail
+     * the seal that triggered it.
+     */
+    async tellRelayReleased(agentName, relayPeerId, node, correlationId) {
+        /**
+         * ⚠️ **THE NODE IS THE SOURCE OF TRUTH FOR WHERE THIS RELAY IS — review MEDIUM-6.**
+         *
+         * The first version looked the relay up in `directoryRelayEndpoints`. But the reservation was
+         * taken on the relay the OFFER named, whose addresses came off that frame; if the directory's
+         * last announcement does not contain it — a pool relay dropped from the roster, a stale
+         * announcement — the release warns `no_endpoint` and the slot is held to its TTL. The node
+         * announces the circuit it actually holds, so derive the address from that and fall back to the
+         * directory list only when there is nothing to derive from.
+         */
+        const fromNode = node.listenAddresses()
+            .filter((a) => a.split("/").includes("p2p-circuit") && a.includes(`/p2p/${relayPeerId}/`))
+            .map((a) => a.split("/p2p-circuit")[0])
+            .filter((a) => a.length > 0);
+        const ep = this.#ctx.directoryRelayEndpoints.get(agentName)?.find((e) => e.relayPeerId === relayPeerId);
+        const relayAddrs = fromNode.length > 0 ? [...new Set(fromNode)] : (ep ? [...ep.relayAddrs] : []);
+        if (relayAddrs.length === 0) {
+            this.#ctx.logger.warn("session.relay.reservation_release.no_endpoint", {
+                agentName, relayPeerId, correlationId,
+                impact: "no address is known for this relay, so it cannot be told the slot is free and " +
+                    "holds it until the reservation TTL expires.",
+            });
+            return;
+        }
+        let client;
+        try {
+            client = this.#ctx.detachedRelayClientBuilder?.(agentName, relayPeerId, relayAddrs, {
+                receiptStore: this.#ctx.relayReceiptStore ?? undefined,
+                sealLeafStore: this.#ctx.sealLeafStore ?? undefined,
+                onlineToken: () => this.#ctx.getDirectoryOnlineToken(agentName),
+            });
+            if (!client)
+                return;
+            await client.releaseReservation(node);
+        }
+        catch (err) {
+            this.#ctx.logger.warn("session.relay.reservation_release.failed", {
+                agentName, relayPeerId, correlationId,
+                error: extractErrorMessage(err),
+                impact: "the relay holds this slot until its TTL expires.",
+            });
+        }
+        finally {
+            client?.close();
+        }
+    }
     async proveToRelay(agentName, circuitAddr, node, correlationId, 
     /**
      * Whether this proof is the STANDING RECEIVER's, and may therefore write the surface