@cello-protocol/daemon 0.0.170 → 0.0.172

package/dist/session-node-manager.js

@@ -97,6 +97,55 @@ const SHUTDOWN_STEP_DEADLINE_MS = 2_000;
  * operator says. It is cleared on a successful dial, so it never delays a live counterparty.
  */
 const REDIAL_COOLDOWN_MS = 15_000;
+/**
+ * DOD-CAP-SELF-HEAL-1 — how long an interrupted session keeps consuming a cap slot.
+ *
+ * ATTRIBUTION ALONE DID NOT FIX THIS, and the reason is worth keeping. Recording who ended a
+ * session only works for sessions ended after the recording started: every row written before the
+ * column existed is unlabelled, and an unlabelled row counts. So the operator's actual backlog —
+ * five finished conversations that were blocking two of their own agents — was untouched by it.
+ * Attribution can never clear history, and history is what fills a cap.
+ *
+ * Age can. An interrupted session nobody has touched for hours is debris, not a live obligation,
+ * and that is true whether our restart or their disconnect produced it.
+ *
+ * D18 SURVIVES BECAUSE THE ATTACK IS A RATE. The disconnect-evasion peer has to drop and reopen
+ * faster than this window to gain anything, so everything it churns is recent and everything it
+ * churns still counts. What ages out is the thing that was never an attack: a conversation that
+ * finished. An attacker who waits out the window to gain one slot per window is not evading the
+ * bound, they are obeying a slower one — and the global anti-swarm cap still applies on top.
+ *
+ * Two hours: comfortably longer than any churn worth attacking with, comfortably shorter than
+ * "yesterday's conversation still blocks me".
+ */
+export const CAP_INTERRUPTED_TTL_MS = Number(process.env["CELLO_CAP_INTERRUPTED_TTL_MS"]) || 2 * 60 * 60 * 1000;
+/**
+ * DOD-CAP-SELF-HEAL-1 — what counts against a per-sender acceptance bound.
+ *
+ * `active` always. `interrupted` ONLY when the counterparty caused it.
+ *
+ * D18 is why `interrupted` has to count at all: a peer can flip a session to `interrupted` for free
+ * by dropping its stream, then open a fresh one, indefinitely. Those are theirs and still count.
+ *
+ * What broke was charging them for OURS. A daemon restart flips every live session to
+ * `interrupted`, nothing resolves them, and the reaper correctly refuses to take any with received
+ * content — so the bound became all-time instead of concurrent. Measured 2026-08-17: two of one
+ * operator's own agents could not open a session, because one held five finished conversations with
+ * the other against a stranger cap of three.
+ *
+ * NULL counts as the counterparty's. The column is new, so every pre-existing row is unlabelled,
+ * and the safe default for an anti-abuse bound is to count rather than to excuse.
+ */
+const CAP_COUNTS = (alias = "") => {
+    const p = alias ? `${alias}.` : "";
+    return `(${p}status = 'active'
+           OR (${p}status = 'interrupted'
+               AND COALESCE(${p}interrupted_by, 'counterparty') != 'local'
+               AND ${p}updated_at >= ?))`;
+};
+const CAP_COUNT_SQL = (where) => `SELECT COUNT(*) AS n FROM sessions WHERE ${where} AND ${CAP_COUNTS()}`;
+/** The cutoff an interrupted session must be newer than to still count. */
+const capStaleBefore = () => Date.now() - CAP_INTERRUPTED_TTL_MS;
 // Persistence bounds are TIER-GRADUATED via DEFAULT_TIER_BOUNDS (contacts-tier-migration). The two
 // consts below DERIVE from the grid's UNKNOWN row rather than restating it — the grid is the single
 // source (DOD-TIER-2 AC4), so these can never drift from it.
@@ -743,6 +792,18 @@ export class SessionNodeManager {
             // Deliberately NOT a status — the session stays sealable, so the operator can still take a
             // unilateral receipt. It stops this side calling them, nothing more.
             "ALTER TABLE sessions ADD COLUMN counterparty_abandoned_at INTEGER",
+            // DOD-CAP-SELF-HEAL-1: WHO caused this session to be interrupted — 'counterparty' when their
+            // stream dropped, 'local' when OUR daemon stopped or started. Only theirs counts against the
+            // acceptance bound. Without this the bound is all-time rather than concurrent: every restart
+            // flips every live session to `interrupted`, nothing ever resolves them, and a pair of agents
+            // that has talked three times can never talk again. NULL means "not recorded" and is treated
+            // as the counterparty's, because the safe default for an anti-abuse bound is to count it.
+            "ALTER TABLE sessions ADD COLUMN interrupted_by TEXT",
+            // DOD-M12B-RESTART-SEAL-1: when automatic sealing exhausted this session, and why. Durable
+            // because the resolver's attempt budget is in memory — without it a machine that restarts
+            // several times a day re-runs the whole budget against a hopeless session on every boot.
+            "ALTER TABLE sessions ADD COLUMN restart_seal_gave_up_at INTEGER",
+            "ALTER TABLE sessions ADD COLUMN restart_seal_gave_up_reason TEXT",
         ]) {
             try {
                 this.#db.exec(ddl);
@@ -1057,7 +1118,10 @@ export class SessionNodeManager {
             for (const row of activeRows) {
                 try {
                     this.#db
-                        .prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?) WHERE agent_id = ? AND session_id = ?")
+                        .prepare(
+                    // DOD-CAP-SELF-HEAL-1: OURS. This is the boot sweep finding sessions a previous
+                    // process left `active`; the counterparty did nothing, so they are not charged for it.
+                    "UPDATE sessions SET status = 'interrupted', updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?), interrupted_by = 'local' WHERE agent_id = ? AND session_id = ?")
                         .run(now, interruptedAt, row.agent_id, row.session_id);
                     if (row.agent_name === null) {
                         this.#logger.error("session.agent.orphaned", {
@@ -1738,8 +1802,8 @@ export class SessionNodeManager {
         if (!this.#db)
             return 0;
         const row = this.#db
-            .prepare("SELECT COUNT(*) AS n FROM sessions WHERE agent_id = ? AND counterparty_pubkey = ? AND status IN ('active', 'interrupted')")
-            .get(this.#requireAgentId(agentName), counterpartyPubkey);
+            .prepare(CAP_COUNT_SQL("agent_id = ? AND counterparty_pubkey = ?"))
+            .get(this.#requireAgentId(agentName), counterpartyPubkey, capStaleBefore());
         return row.n;
     }
     /** M8C-ABUSE-1 (anti-swarm) + DOD-TIER-2: non-terminal sessions this agent holds with UNKNOWN-tier
@@ -1754,13 +1818,14 @@ export class SessionNodeManager {
             return 0;
         const row = this.#db
             .prepare(`SELECT COUNT(*) AS n FROM sessions s
-         WHERE s.agent_id = ? AND s.status IN ('active', 'interrupted')
+         WHERE s.agent_id = ?
+           AND ${CAP_COUNTS("s")}
            AND NOT EXISTS (
              SELECT 1 FROM contacts c
              WHERE c.agent_id = s.agent_id AND c.pubkey = s.counterparty_pubkey
                AND c.tier >= ${TIER.KNOWN} AND c.tier <= ${TIER.VIP}
            )`)
-            .get(this.#requireAgentId(agentName));
+            .get(this.#requireAgentId(agentName), capStaleBefore());
         return row.n;
     }
     /** M8C-ABUSE-1 + DOD-TIER-2/3: is a NEW inbound session from this counterparty within the
@@ -1776,6 +1841,10 @@ export class SessionNodeManager {
         const perSenderCap = this.resolveTierBound(agentName, tier, "max_sessions");
         const perSender = this.countActiveSessionsForCounterparty(agentName, counterpartyPubkey);
         if (perSender >= perSenderCap) {
+            // BYTE-IDENTICAL to every other refusal, deliberately — DOD-TIER-3. A BLOCKED sender and an
+            // over-cap UNKNOWN must be indistinguishable, or the refusal tells someone they are blocked.
+            // The operator's alarm needs numbers, so it asks for them SEPARATELY via capDiagnostics;
+            // hanging them off this object would put a distinguishing oracle in the return value.
             return { ok: false, reason: "abuse_bound_sessions_per_sender" };
         }
         // The global stranger cap is only for the UNKNOWN pool. A KNOWN+ sender is past it by trust;
@@ -2572,6 +2641,18 @@ export class SessionNodeManager {
         };
         await this.#handleContentStream(agentName, sessionId, source, remotePeerId);
     }
+    /** DOD-CAP-SELF-HEAL-1 test seam: the shutdown sweep's effect, without a shutdown. Mirrors the
+     *  real UPDATE at gracefulShutdown so a test cannot pass against a label production never sets. */
+    markSessionsInterruptedByLocalShutdownForTest() {
+        // SCOPED TO UNLABELLED ROWS. Unscoped, this would relabel rows already marked
+        // `counterparty` — one call excusing every interruption every attacker ever caused, on every
+        // agent. Production never relabels; nor does this.
+        this.#db?.prepare("UPDATE sessions SET interrupted_by = 'local' WHERE status = 'interrupted' AND interrupted_by IS NULL").run();
+    }
+    /** DOD-CAP-SELF-HEAL-1 test seam: the counterparty's stream closing, without a real peer. */
+    markInterruptedByCounterpartyForTest(agentName, sessionId) {
+        this.#db?.prepare("UPDATE sessions SET interrupted_by = 'counterparty' WHERE agent_id = ? AND session_id = ?").run(this.#requireAgentId(agentName), sessionId);
+    }
     /** Test seam (same spirit as getDb()): seed per-session direct-path liveness, which is otherwise
      *  only set by the live node's onPeerConnect/onPeerDisconnect (#wireSessionLiveness). Lets a
      *  DB-seeded test exercise the CC-5 reaper's "alive counterparty must survive" gate without standing
@@ -2726,7 +2807,10 @@ export class SessionNodeManager {
         // surface as interrupted so AC-010 recovery handles them at next login.
         // The session.node.destroyed log preserves the original reason for observability.
         const dbStatus = reason === "sealed" ? "sealed" : "interrupted";
-        this.#updateSessionStatus(agentName, sessionId, dbStatus);
+        // DOD-CAP-SELF-HEAL-1: OURS. Every caller of this with a non-sealed reason is a local teardown
+        // — the operator's kill switch (`cello_set_agent_offline`), an internal error, a node replaced.
+        // The counterparty did nothing, so they must not be charged a cap slot for it.
+        this.#updateSessionStatus(agentName, sessionId, dbStatus, dbStatus === "interrupted" ? "local" : undefined);
         this.#activeNodes.delete(this.#k(agentName, sessionId));
         // Evict the in-memory per-session caches on teardown. The tree is durable in
         // SQLite (getSessionTree reloads it on demand), and the received-content buffer
@@ -2979,7 +3063,9 @@ export class SessionNodeManager {
         else {
             const interruptedAt = new Date(now).toISOString();
             try {
-                this.#db.prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?) WHERE status = 'active'").run(now, interruptedAt);
+                this.#db.prepare(
+                // DOD-CAP-SELF-HEAL-1: OURS. Our own shutdown ended these, not the counterparty.
+                "UPDATE sessions SET status = 'interrupted', updated_at = ?, interrupted_at = COALESCE(interrupted_at, ?), interrupted_by = 'local' WHERE status = 'active'").run(now, interruptedAt);
             }
             catch (err) {
                 this.#logger.error("session.interrupt.db.write.failed", {
@@ -3076,6 +3162,69 @@ export class SessionNodeManager {
          WHERE s.status = ? AND a.state != 'retired'`)
             .all(status);
     }
+    /**
+     * DOD-M12B-RESTART-SEAL-1 — the sessions OUR OWN stop orphaned, and only those.
+     *
+     * `interrupted_by` is the whole safety argument. `'local'` means the boot sweep, the shutdown
+     * sweep, or the operator's own kill switch ended this session — nobody else did, and it cannot be
+     * resumed because the transport keypairs died with the process. Those are the ones the resolver
+     * may seal on its own.
+     *
+     * Everything else is excluded and must stay excluded:
+     *   'counterparty'        — they hung up. SI-001: the operator may still want to wait.
+     *   'relay_stream_close'  — our relay witness link ended; the session itself may be fine.
+     *   NULL                  — written before the column existed, so the cause is UNKNOWN. An
+     *                           unknown cause is not a licence to notarize; it is the reason not to.
+     *
+     * Same INNER JOIN discipline as getSessionsByStatus: a retired agent's rows are kept for
+     * accountability and are not resumable, so they are not offered for sealing either.
+     */
+    listRestartOrphanedSessions() {
+        if (!this.#db)
+            return [];
+        const rows = this.#db
+            .prepare(
+        // `message_count > 0` — a never-messaged interrupted session is a dead HANDSHAKE, which
+        // `classifySession` deliberately hides in the "failed" bucket so it does not clutter
+        // status. Sealing one spends a directory ceremony to obtain a receipt over nothing, and
+        // then moves it into the operator's CLOSED list, making the clutter visible. The whole
+        // justification for this work is "3,576 messages produced nothing" — zero messages is
+        // nothing to produce.
+        //
+        // `restart_seal_gave_up_at IS NULL` — a session we have already exhausted. Without it a
+        // machine restarting ~6 times a day re-runs five ceremonies against a hopeless session on
+        // every boot, forever.
+        `SELECT s.session_id AS session_id, s.message_count AS message_count, a.agent_name AS agent_name
+         FROM sessions s JOIN agents a ON a.agent_id = s.agent_id
+         WHERE s.status = 'interrupted' AND s.interrupted_by = 'local' AND a.state != 'retired'
+           AND s.message_count > 0
+           AND s.restart_seal_gave_up_at IS NULL
+         ORDER BY s.updated_at ASC`)
+            .all();
+        return rows.map((r) => ({
+            agentName: r.agent_name,
+            sessionId: r.session_id,
+            messageCount: r.message_count ?? 0,
+        }));
+    }
+    /**
+     * DOD-M12B-RESTART-SEAL-1 — record that automatic sealing has exhausted this session.
+     *
+     * Durable on purpose. The resolver's attempt budget is in memory, so without this the budget
+     * resets on every boot and a session that can never seal costs five directory ceremonies a day
+     * for the life of the machine.
+     *
+     * IT IS NOT A DEAD END FOR THE OPERATOR. The row keeps status `interrupted`, so a manual
+     * `cello_close_session` still works on it and — since DOD-M12B-INTERRUPTED-ESCALATE-1 — still
+     * escalates to a unilateral seal. This column only withdraws the session from AUTOMATIC retries.
+     */
+    markRestartSealGaveUp(agentName, sessionId, reason) {
+        if (!this.#db)
+            return;
+        this.#db
+            .prepare("UPDATE sessions SET restart_seal_gave_up_at = ?, restart_seal_gave_up_reason = ? WHERE agent_id = ? AND session_id = ?")
+            .run(Date.now(), reason, this.#requireAgentId(agentName), sessionId);
+    }
     /**
      * cello_list_sessions: every persisted session for one agent, regardless of
      * status (active, interrupted, sealed, seal_interrupted_pending). Ordered most
@@ -3121,6 +3270,31 @@ export class SessionNodeManager {
      * persisted); in that case we no-op rather than throw — the cert still flows through the
      * live return path. The legibility content is identical regardless of delivery timing.
      */
+    /**
+     * DOD-M12B-INTERRUPTED-ESCALATE-1 — flip a session to `sealed`, synchronously, without needing a
+     * live node.
+     *
+     * **`destroySessionNode(…, "sealed")` cannot be relied on to do this.** It returns early at
+     * `if (!entry) return`, and the status write lives 26 lines BELOW that guard — so it flips the
+     * status only for a session that still has an `#activeNodes` entry. An interrupted session has
+     * none by construction: every producer of that status deletes the entry. Before this method, a
+     * unilateral seal on an interrupted session stored the notarized root and the certificate and
+     * left the row saying `interrupted` — the receipt landed and nothing that represents it moved.
+     * `cello_sessions` still showed it stuck, `cello_close_session` still refused it by name, and the
+     * restart-seal resolver re-selected it on the next boot to run the whole ceremony again against a
+     * session that already held a receipt.
+     *
+     * STATUS FIRST AND SYNCHRONOUS, teardown second — the order `abandonSession` uses and the one
+     * `retireSession` documents. The flip is the load-bearing half; the teardown makes memory agree
+     * with it. `#updateSessionStatus` also runs the terminal disposition hooks (held content is
+     * annexed, not stranded), which the early return skipped entirely.
+     */
+    markSealed(agentName, sessionId) {
+        // The terminal guard (abandoned/sealed must not be overwritten) lives in #updateSessionStatus,
+        // so it holds for destroySessionNode and retireSession too — not only for callers of this
+        // wrapper.
+        return this.#updateSessionStatus(agentName, sessionId, "sealed");
+    }
     recordSealCertificate(agentName, sessionId, sealedRootHex, legibilityJson) {
         if (!this.#db)
             return;
@@ -3227,7 +3401,21 @@ export class SessionNodeManager {
             // the pre-check above raced (it cannot — DatabaseSync is synchronous), the
             // UPDATE only mutates a row that is still active.
             this.#db
-                .prepare("UPDATE sessions SET status = 'interrupted', updated_at = ?, message_count = ?, interrupted_at = ? WHERE agent_id = ? AND session_id = ? AND status = 'active'")
+                .prepare(
+            // DOD-CAP-SELF-HEAL-1: labelled by SOURCE, because the two are not the same event.
+            //
+            //   relay_frame  — the relay telling us the counterparty went. THEIRS. The D18
+            //                  disconnect-evasion move, and it must keep counting.
+            //   stream_close — OUR witness stream to the relay ended. That fires on a relay restart,
+            //                  a relay fleet roll, or a local network blip. Claiming the counterparty
+            //                  did it means three relay deploys permanently refuse a peer who was
+            //                  never involved — and relay deploys are routine, so it ratchets faster
+            //                  than daemon restarts do.
+            //
+            // `relay_stream_close` is its own label and STILL COUNTS (the bound excuses only 'local'),
+            // because an attacker who can disturb our relay link must not get a free cap reset. It is
+            // recorded honestly rather than blamed on the wrong party.
+            `UPDATE sessions SET status = 'interrupted', updated_at = ?, message_count = ?, interrupted_at = ?, interrupted_by = '${source === "relay_frame" ? "counterparty" : "relay_stream_close"}' WHERE agent_id = ? AND session_id = ? AND status = 'active'`)
                 .run(now, authoritativeCount, interruptedAt, this.#requireAgentId(agentName), sessionId);
         }
         catch (err) {
@@ -4026,6 +4214,33 @@ export class SessionNodeManager {
         // this point wins, the second short-circuits. The check+set is SYNCHRONOUS (before any await) so
         // two near-simultaneous triggers (e.g. B's own close racing A's delivered SEAL ctrl leaf) cannot
         // both submit. Cleared below on a relay submit failure so a genuine retry can proceed.
+        // DOD-M12B-INTERRUPTED-ESCALATE-1 — THE MARK MUST SURVIVE A RESTART, or one automatic retry
+        // permanently forfeits the receipt.
+        //
+        // `#responderSealSubmitted` is in memory. A session whose close was in flight when the daemon
+        // stopped already has our SEAL ctrl leaf in the relay log — and on the next boot the mark is
+        // empty, so the restart-seal resolver's automatic close would submit a SECOND one. The
+        // directory requires exactly one ctrl leaf (`ctrlLeaves.length !== 1 → unilateral_seal_leaf_invalid`)
+        // and the carry is durable, so every future attempt would carry both and be refused forever.
+        //
+        // The durable evidence already exists and was simply not consulted: our own ctrl leaf is in
+        // `session_seal_leaves`. Recover the escalation values from it instead of submitting again.
+        if (!this.#responderSealSubmitted.has(sealKey)) {
+            const durable = this.#recoverOwnSealCtrlLeaf(agentName, sessionId);
+            if (durable === "unknown") {
+                // REFUSE, do not submit. A second ctrl leaf makes the session unsealable forever, and the
+                // question "is one already there?" just failed to answer. Refusing costs this close; a
+                // second leaf costs the receipt permanently.
+                return { ok: false, reason: "seal_leaf_recovery_unavailable" };
+            }
+            if (durable !== "none") {
+                this.#logger.info("session.seal.leaf.already_submitted.recovered", {
+                    sessionId, agentName, sequenceNumber: durable.sequenceNumber,
+                    impact: "our SEAL ctrl leaf is already in the relay log from a previous run; submitting a second would make this session unsealable forever",
+                });
+                this.#responderSealSubmitted.set(sealKey, durable);
+            }
+        }
         if (this.#responderSealSubmitted.has(sealKey)) {
             // M8B FINDING-1: carry the FIRST submit's reported root/sequence so a retry close can
             // still escalate to a unilateral seal. A null value means that submit is still in
@@ -4881,6 +5096,69 @@ export class SessionNodeManager {
     /** DOD-M12B-INDEX-1 — this agent's own K_local pubkey, for attributing its own held content.
      *  Null when it cannot be resolved: an UNATTRIBUTED annex row is true, a falsely attributed one
      *  is not, and this is the record that outlives the session. */
+    /**
+     * DOD-M12B-INTERRUPTED-ESCALATE-1 — our own SEAL ctrl leaf, if a previous run already posted one.
+     *
+     * Returns the two values a unilateral escalation runs on, rebuilt from durable state:
+     * the ctrl leaf's relay-assigned sequence, and the root the tree WOULD have with that leaf
+     * appended. The content hash cannot be recomputed — the seal payload embeds a `close_timestamp`
+     * — so it is read out of the signed Structure 1 the store already holds.
+     *
+     * Null when there is no own ctrl leaf, which is the ordinary first-close case.
+     */
+    #recoverOwnSealCtrlLeaf(agentName, sessionId) {
+        const ownPubkey = this.#ownPubkeyHex(agentName);
+        // "I CANNOT TELL" IS NOT "THERE IS NONE". Returning the absent answer here would let the caller
+        // submit a second SEAL ctrl leaf — the exact permanent loss this method exists to prevent — on
+        // the strength of a lookup that failed. Every path that could not determine the answer says so.
+        if (!ownPubkey) {
+            this.#logger.warn("session.seal.leaf.recover.failed", {
+                sessionId, agentName, reason: "own_pubkey_unresolved",
+                impact: "cannot tell whether a SEAL ctrl leaf was already posted, so the close refuses rather than risk a second one",
+            });
+            return "unknown";
+        }
+        let own;
+        try {
+            own = this.getSealCarry(ownPubkey, sessionId)
+                .find((l) => l.leafKind === LEAF_KIND_CTRL && l.senderPubkeyHex === ownPubkey);
+        }
+        catch (err) {
+            this.#logger.warn("session.seal.leaf.recover.failed", {
+                sessionId, agentName, reason: "carry_read_failed",
+                error: err instanceof Error ? err.message : String(err),
+                impact: "cannot tell whether a SEAL ctrl leaf was already posted, so the close refuses rather than risk a second one",
+            });
+            return "unknown";
+        }
+        if (!own)
+            return "none";
+        try {
+            // Canonical Structure 1 is [version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp].
+            const fields = decode(own.structure1Cbor);
+            const contentHash = fields[1];
+            if (!(contentHash instanceof Uint8Array)) {
+                this.#logger.warn("session.seal.leaf.recover.failed", {
+                    sessionId, agentName, reason: "structure1_content_hash_missing",
+                    impact: "cannot tell whether a SEAL ctrl leaf was already posted, so the close refuses rather than risk a second one",
+                });
+                return "unknown";
+            }
+            const contentHashHex = Buffer.from(contentHash).toString("hex");
+            return {
+                reportedRootHex: this.getSessionTree(agentName, sessionId).rootWithAppendedHex(contentHashHex),
+                sequenceNumber: own.sequenceNumber,
+            };
+        }
+        catch (err) {
+            this.#logger.warn("session.seal.leaf.recover.failed", {
+                sessionId, agentName, reason: "structure1_decode_failed",
+                error: err instanceof Error ? err.message : String(err),
+                impact: "cannot tell whether a SEAL ctrl leaf was already posted, so the close refuses rather than risk a second one",
+            });
+            return "unknown";
+        }
+    }
     #ownPubkeyHex(agentName) {
         if (!this.#db)
             return null;
@@ -5180,6 +5458,41 @@ export class SessionNodeManager {
             return false;
         }
     }
+    /**
+     * DOD-CAP-SELF-HEAL-1 — the numbers behind a cap refusal, for the OPERATOR'S alarm only.
+     *
+     * Kept off `checkUnknownSenderAcceptanceBound`'s return on purpose. That refusal is byte-identical
+     * across tiers by design (DOD-TIER-3) so a blocked party cannot tell blocking from throttling;
+     * attaching the counts to it would put the oracle straight into the value the refusal path
+     * carries. This is a separate, purely local read, and nothing it returns crosses the wire.
+     */
+    capDiagnostics(agentName, counterpartyPubkey) {
+        const tier = this.getTier(agentName, counterpartyPubkey);
+        const cap = this.resolveTierBound(agentName, tier, "max_sessions");
+        const counted = this.countActiveSessionsForCounterparty(agentName, counterpartyPubkey);
+        return {
+            tier, cap, counted,
+            // How many to close to get UNDER the cap — not how many exist. At 5 against a cap of 3 the
+            // answer is 3, and "close 5" tells the operator to do more than the job needs.
+            mustClear: Math.max(0, counted - cap + 1),
+            blocked: tier === TIER.BLOCKED,
+        };
+    }
+    /** DOD-CAP-SELF-HEAL-1: the sessions with this counterparty that are consuming cap slots, oldest
+     *  first. The operator is told to close some — this is WHICH, because "close three of them" with
+     *  no list is not an instruction they can follow. */
+    sessionsConsumingCap(agentName, counterpartyPubkey, limit = 10) {
+        if (!this.#db)
+            return [];
+        try {
+            const rows = this.#db.prepare(`SELECT session_id FROM sessions WHERE agent_id = ? AND counterparty_pubkey = ? AND ${CAP_COUNTS()}
+         ORDER BY updated_at ASC LIMIT ?`).all(this.#requireAgentId(agentName), counterpartyPubkey, capStaleBefore(), limit);
+            return rows.map((r) => r.session_id);
+        }
+        catch {
+            return [];
+        }
+    }
     /** DOD-M12B-ABANDON-NOTIFY-1: has the counterparty told us they hung up? */
     counterpartyAbandonedAt(agentName, sessionId) {
         if (!this.#db)
@@ -7001,6 +7314,14 @@ export class SessionNodeManager {
             const sender = row.origin === "sent" ? this.#ownPubkeyHex(agentName) : counterparty;
             if (this.recordSealedAnnex(agentName, sessionId, row.content_hash_hex, new Uint8Array(row.content_blob), sender)) {
                 this.#deleteHeldContent(agentName, sessionId, row.canonical_seq);
+                // AND OUT OF THE IN-MEMORY MAP. Measured live 2026-08-17 on daemon 0.0.170: this frame is
+                // now safe in the annex and its durable row is gone — but teardown still found it in the
+                // map, counted `held_content` for the session, got 0, and fired
+                // `session.content.held.lost`: "verified content was destroyed". Ten frames were annexed
+                // and the same ten were reported destroyed, in the same second. A false alarm on the most
+                // serious event in the system is worse than no alarm, because the next investigation goes
+                // looking for content that was never lost.
+                this.#heldContent.get(this.#k(agentName, sessionId))?.delete(row.canonical_seq);
                 annexed++;
             }
             else {
@@ -7014,13 +7335,53 @@ export class SessionNodeManager {
             impact: "these messages arrived and verified but never joined the chain — they are readable from the annex, not the transcript",
         });
     }
-    #updateSessionStatus(agentName, sessionId, status) {
+    #updateSessionStatus(agentName, sessionId, status, 
+    // DOD-CAP-SELF-HEAL-1: who caused an interruption, when this call is the one causing it.
+    // Omitting it leaves the column NULL, which the acceptance bound reads as the counterparty's —
+    // so a LOCAL teardown that forgets to say so is charged to the peer. That is exactly how the
+    // operator's own kill switch (`cello_set_agent_offline` → destroySessionNode) was locking out
+    // a counterparty who had done nothing.
+    interruptedBy) {
         if (!this.#db)
             return false;
+        // THE TERMINAL GUARD LIVES HERE, not in one wrapper, because there are three writers of
+        // "sealed": markSealed, destroySessionNode, and retireSession on the witnessed-submit path.
+        // Guarding only the wrapper asserts the invariant in a test while two other paths still break
+        // it.
+        //
+        //   abandoned → sealed  REFUSED. A force-abandon is the documented way to give up a receipt.
+        //     A certificate arriving afterwards must not silently overturn the operator's decision. The
+        //     certificate is still stored by recordSealCertificate and stays retrievable.
+        //   sealed → sealed     REFUSED. Nothing to write, and re-running the terminal disposition
+        //     hooks for a no-op should not be reported as a status that landed.
+        if (status === "sealed") {
+            const current = this.getSessionRecord(agentName, sessionId)?.status;
+            if (current === "abandoned" || current === "sealed") {
+                this.#logger.info("session.seal.status.not_written", {
+                    agentName, sessionId, currentStatus: current,
+                    impact: current === "abandoned"
+                        ? "a certificate arrived for a session the operator force-abandoned; it is stored and retrievable, but the row keeps saying abandoned"
+                        : "already sealed — nothing to write",
+                });
+                return false;
+            }
+            if (current === undefined) {
+                // ORDINARY, not an error. recordSealCertificate documents this case: the seal can arrive
+                // before the row is persisted. Falling through would emit `session.status.write.missed` at
+                // ERROR level for a shape the system expects.
+                this.#logger.info("session.seal.status.no_row", {
+                    agentName, sessionId,
+                    impact: "no session row yet — the certificate is still recorded and retrievable",
+                });
+                return false;
+            }
+        }
         const now = Date.now();
         try {
             const res = this.#db
-                .prepare("UPDATE sessions SET status = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?")
+                .prepare(interruptedBy === undefined
+                ? "UPDATE sessions SET status = ?, updated_at = ? WHERE agent_id = ? AND session_id = ?"
+                : "UPDATE sessions SET status = ?, updated_at = ?, interrupted_by = 'local' WHERE agent_id = ? AND session_id = ?")
                 .run(status, now, this.#requireAgentId(agentName), sessionId);
             // "Did not throw" is NOT "landed". An UPDATE whose WHERE matches no row — a wrong agent_id, a
             // session_id with no row — succeeds silently and changes nothing. Reporting that as a written