@cello-protocol/daemon 0.0.32 → 0.0.33

package/dist/session-node-manager.js

@@ -81,7 +81,18 @@ import { encodeSealPayload } from "@cello-protocol/protocol-types";
 import { AgentRelayClient, LEAF_KIND_CTRL } from "./session-relay-client.js";
 import { RelayReceiptStore } from "./relay-receipt-store.js";
 import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
+import { PassthroughGatewayClient, GATEWAY_UNAVAILABLE, GOVERNANCE_TIMEOUT, } from "@cello-protocol/gateway";
 const CBOR_ENC = new Encoder({ tagUint8Array: false });
+// M8C-ABUSE-1: persistence bounds — the non-M9 remainder (per-message cap + outbound rate are
+// M9's, not rebuilt here). "Whitelisted senders bounded only by disk" (DoD) — these bounds apply
+// ONLY to sessions/senders that are NOT a known contact (CONTACT-1's whitelist).
+/** Anti-drip-feed: cumulative RECEIVED bytes per session, from a non-contact sender. */
+export const ABUSE_MAX_SESSION_RECEIVED_BYTES = 25 * 1024 * 1024; // 25 MB
+/** Anti-drip-feed via many sessions: active sessions a single unknown counterparty may hold open
+ *  with one agent at once. */
+export const ABUSE_MAX_SESSIONS_PER_UNKNOWN_SENDER = 3;
+/** Anti-swarm: total active sessions from ALL unknown (non-contact) counterparties combined, per agent. */
+export const ABUSE_MAX_UNKNOWN_SESSIONS_GLOBAL = 50;
 // ─── SessionNodeManager ───────────────────────────────────────────────────────
 export class SessionNodeManager {
     #factory;
@@ -92,6 +103,11 @@ export class SessionNodeManager {
     #relayReceiptStore = null;
     /** FED-OPTIONB-SEAL-001: the per-session leaf log (both parties) carried at a unilateral seal. */
     #sealLeafStore = null;
+    // M9-CORE-001: the inbound screening seam. Every byte that reaches the agent passes
+    // through #appendVerifiedContent's buffer write; screenInbound gates it there, on every
+    // arrival path (direct, held-release, recovered-park). Defaults to always-allow when no
+    // gateway is configured (SI-001: still a verdict, not an ungated pass).
+    #securityGateway;
     #activeNodes = new Map();
     // M7 DOD-SPINE-6 / MSG-001-3b: ONE relay witness client per AGENT (keyed by agent name).
     // The relay authenticates and keys delivery by the agent's K_local pubkey, so all of an
@@ -219,6 +235,7 @@ export class SessionNodeManager {
         }
         this.#autoNatProbers = opts.autoNatProbers ?? (() => []);
         this.#srRetryDelaysMs = opts.standingReceiverRetryDelaysMs ?? [1_000, 5_000, 15_000];
+        this.#securityGateway = opts.securityGateway ?? new PassthroughGatewayClient();
     }
     /**
      * CELLO-M7-MSG-001: wire the durable-backstop side effects of the awaiting-ACK
@@ -242,30 +259,40 @@ export class SessionNodeManager {
      * MSG-001-3b (2b): deposit un-confirmed content to the relay store-and-forward backstop — keyed
      * to the recipient, on the SAME relay this session is witnessed by — so an offline recipient
      * recovers it (at the sequence the witness already assigned, R1). Best-effort, never throws.
+     * DOD-LEAVEMSG-1: returns whether the deposit actually succeeded (false if no hook/relay is
+     * configured, or the hook rejects) so a caller with a live response to shape (sendContent) can
+     * distinguish "genuinely parked" from "nothing recoverable" instead of guessing. Callers that
+     * fire this from an async backstop with no live caller (the TTF-expiry path) may ignore the
+     * result — the deposit itself and its logging are unchanged either way.
      */
-    #parkContent(agentName, sessionId, contentHashHex, content, structure1Cbor, structure2Cbor) {
+    async #parkContent(agentName, sessionId, contentHashHex, content, structure1Cbor, structure2Cbor) {
         const hook = this.#contentParkHook;
         const entry = this.#activeNodes.get(this.#k(agentName, sessionId));
         if (!hook || !entry || !entry.relayPeerId || !entry.relayAddrs)
-            return;
-        void hook({
-            sessionId,
-            recipientPubkeyHex: entry.counterpartyPubkey,
-            relayPeerId: entry.relayPeerId,
-            relayAddrs: entry.relayAddrs,
-            contentHashHex,
-            content,
-            // DOD-MSG-4 (2b): carry the relay's signed ordering record so the parked entry is self-ordering
-            // on recover too (sealed INTO the ciphertext envelope — INV-3: the relay still sees only ciphertext).
-            structure1Cbor,
-            structure2Cbor,
-        }).catch((err) => {
+            return false;
+        try {
+            await hook({
+                sessionId,
+                recipientPubkeyHex: entry.counterpartyPubkey,
+                relayPeerId: entry.relayPeerId,
+                relayAddrs: entry.relayAddrs,
+                contentHashHex,
+                content,
+                // DOD-MSG-4 (2b): carry the relay's signed ordering record so the parked entry is self-ordering
+                // on recover too (sealed INTO the ciphertext envelope — INV-3: the relay still sees only ciphertext).
+                structure1Cbor,
+                structure2Cbor,
+            });
+            return true;
+        }
+        catch (err) {
             this.#logger.warn("content.park.deposit.failed", {
                 sessionId,
                 contentHash: contentHashHex,
                 error: err instanceof Error ? err.message : String(err),
             });
-        });
+            return false;
+        }
     }
     // ─── Initialization ──────────────────────────────────────────────────────
     async initialize() {
@@ -396,6 +423,31 @@ export class SessionNodeManager {
         last_delivered_seq INTEGER NOT NULL,
         PRIMARY KEY (agent_name, session_id)
       )
+    `);
+        // M8C-CONTACT-1: binary per-agent contact whitelist. This is an ACCESS-CONTROL LIST, not a
+        // setting — it belongs alongside message_watermarks/sessions as its own real subsystem, not
+        // behind the parked M9-CFG-001 config store. Identity PINS to the pubkey at add time (never
+        // re-resolved); known stays known until explicitly removed (no TTL/expiry on membership).
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS contacts (
+        agent_name TEXT NOT NULL,
+        pubkey TEXT NOT NULL,
+        added_at INTEGER NOT NULL,
+        PRIMARY KEY (agent_name, pubkey)
+      )
+    `);
+        // M8C-TGDOOR-1: daemon-wide Telegram settings (bot token + allowlisted operator chat). A
+        // NEW dedicated table — NOT folded into the parked M9-CFG-001 config store, because a bot
+        // token has no sensible default (a required credential, unlike AWAY/TTL/CONTACT's real
+        // defaults) and can't legitimately wait for M9. Singleton row (id=1) — "token = daemon
+        // setting" (DoD), not per-agent.
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS telegram_settings (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        bot_token TEXT NOT NULL,
+        allowlisted_chat_id TEXT NOT NULL,
+        updated_at INTEGER NOT NULL
+      )
     `);
         // Step 2: Detect interrupted sessions (SIGKILL detection — AC-010).
         // Any 'active' row in a freshly-started daemon is a remnant of a prior
@@ -574,6 +626,121 @@ export class SessionNodeManager {
             .all(agentName);
         return rows;
     }
+    /** M8C-CONTACT-1: is this pubkey a known contact of this agent? */
+    isContact(agentName, pubkey) {
+        if (!this.#db)
+            return false;
+        const row = this.#db.prepare("SELECT 1 FROM contacts WHERE agent_name = ? AND pubkey = ?").get(agentName, pubkey);
+        return row !== undefined;
+    }
+    /** M8C-CONTACT-1: pin a contact at add time — idempotent (re-adding an existing contact is a
+     *  no-op, never refreshes added_at; identity does not get re-resolved). */
+    addContact(agentName, pubkey) {
+        if (!this.#db || !pubkey)
+            return;
+        this.#db
+            .prepare("INSERT OR IGNORE INTO contacts (agent_name, pubkey, added_at) VALUES (?, ?, ?)")
+            .run(agentName, pubkey, Date.now());
+    }
+    /** M8C-CONTACT-1: known stays known until explicitly removed. */
+    removeContact(agentName, pubkey) {
+        if (!this.#db)
+            return false;
+        const res = this.#db.prepare("DELETE FROM contacts WHERE agent_name = ? AND pubkey = ?").run(agentName, pubkey);
+        return res.changes > 0;
+    }
+    /** M8C-CONTACT-1: list an agent's known contacts, oldest-added first. */
+    listContacts(agentName) {
+        if (!this.#db)
+            return [];
+        return this.#db
+            .prepare("SELECT pubkey, added_at FROM contacts WHERE agent_name = ? ORDER BY added_at ASC")
+            .all(agentName);
+    }
+    /** M8C-ABUSE-1: cumulative RECEIVED byte total for a session (anti-drip-feed accounting). */
+    #getReceivedBytesTotal(agentName, sessionId) {
+        if (!this.#db)
+            return 0;
+        const row = this.#db
+            .prepare("SELECT COALESCE(SUM(LENGTH(blob)), 0) AS total FROM transcript WHERE agent_name = ? AND session_id = ? AND direction = 'received'")
+            .get(agentName, sessionId);
+        return row.total;
+    }
+    /** M8C-ABUSE-1 (reviewer HIGH fix, D18): bytes currently sitting in the out-of-order hold
+     *  buffer for this session — NOT yet committed leaves, but real bytes in memory that would
+     *  otherwise let multiple held chunks each individually pass the size gate while cumulatively
+     *  exceeding it once #releaseHeld drains them. */
+    #getHeldBytesTotal(agentName, sessionId) {
+        const held = this.#heldContent.get(this.#k(agentName, sessionId));
+        if (!held)
+            return 0;
+        let total = 0;
+        for (const entry of held.values())
+            total += entry.content.length;
+        return total;
+    }
+    /** M8C-ABUSE-1: non-terminal sessions this agent currently holds with the given counterparty.
+     *  Reviewer HIGH fix (aeffb82f, D18): counting `status = 'active'` ONLY let a counterparty
+     *  evade the bound for free by disconnecting (a trivial, attacker-controlled action that flips
+     *  a session to 'interrupted' — markInterruptedWithDetails) and opening a fresh session,
+     *  repeated indefinitely. 'interrupted' sessions still accept content (ingestReceivedContent
+     *  explicitly allows both statuses) and are NOT terminal (sealed/seal_interrupted_pending are),
+     *  so they must still count against the bound. */
+    countActiveSessionsForCounterparty(agentName, counterpartyPubkey) {
+        if (!this.#db)
+            return 0;
+        const row = this.#db
+            .prepare("SELECT COUNT(*) AS n FROM sessions WHERE agent_name = ? AND counterparty_pubkey = ? AND status IN ('active', 'interrupted')")
+            .get(agentName, counterpartyPubkey);
+        return row.n;
+    }
+    /** M8C-ABUSE-1 (anti-swarm): non-terminal sessions this agent holds with counterparties that are
+     *  NOT a known contact — the global cap counts across ALL unknown senders combined. Same
+     *  'interrupted'-status fix as countActiveSessionsForCounterparty above. */
+    countActiveSessionsFromUnknownSenders(agentName) {
+        if (!this.#db)
+            return 0;
+        const row = this.#db
+            .prepare(`SELECT COUNT(*) AS n FROM sessions s
+         WHERE s.agent_name = ? AND s.status IN ('active', 'interrupted')
+           AND NOT EXISTS (SELECT 1 FROM contacts c WHERE c.agent_name = s.agent_name AND c.pubkey = s.counterparty_pubkey)`)
+            .get(agentName);
+        return row.n;
+    }
+    /** M8C-ABUSE-1: is a NEW inbound session from this counterparty within the acceptance bounds?
+     *  Known contacts are exempt entirely ("bounded only by disk" — DoD). Checked BEFORE accepting
+     *  a fresh inbound session (the counts reflect sessions already active, not yet counting this one). */
+    checkUnknownSenderAcceptanceBound(agentName, counterpartyPubkey) {
+        if (this.isContact(agentName, counterpartyPubkey))
+            return { ok: true };
+        const perSender = this.countActiveSessionsForCounterparty(agentName, counterpartyPubkey);
+        if (perSender >= ABUSE_MAX_SESSIONS_PER_UNKNOWN_SENDER) {
+            return { ok: false, reason: "abuse_bound_sessions_per_sender" };
+        }
+        const globalUnknown = this.countActiveSessionsFromUnknownSenders(agentName);
+        if (globalUnknown >= ABUSE_MAX_UNKNOWN_SESSIONS_GLOBAL) {
+            return { ok: false, reason: "abuse_bound_unknown_sessions_global" };
+        }
+        return { ok: true };
+    }
+    /** M8C-TGDOOR-1: the daemon-wide Telegram bot settings, or null if never configured. */
+    getTelegramSettings() {
+        if (!this.#db)
+            return null;
+        const row = this.#db
+            .prepare("SELECT bot_token, allowlisted_chat_id FROM telegram_settings WHERE id = 1")
+            .get();
+        return row ? { botToken: row.bot_token, allowlistedChatId: row.allowlisted_chat_id } : null;
+    }
+    /** M8C-TGDOOR-1: persist (or replace) the singleton Telegram settings row. */
+    setTelegramSettings(botToken, allowlistedChatId) {
+        if (!this.#db)
+            return;
+        this.#db
+            .prepare(`INSERT INTO telegram_settings (id, bot_token, allowlisted_chat_id, updated_at) VALUES (1, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET bot_token = excluded.bot_token, allowlisted_chat_id = excluded.allowlisted_chat_id, updated_at = excluded.updated_at`)
+            .run(botToken, allowlistedChatId, Date.now());
+    }
     /** DOD-LOOP-1: whether the given agent has a standing receiver ready (any agent if omitted). */
     getStandingReceiverReady(agentName) {
         if (agentName !== undefined)
@@ -1839,7 +2006,7 @@ export class SessionNodeManager {
                 await stream.close();
             }
             catch { /* best-effort close */ }
-            return { ok: true };
+            return { ok: true, delivered: true };
         }
         catch (err) {
             // The send failed after (possibly) arming the awaiting tracking — drop it so a
@@ -1848,7 +2015,13 @@ export class SessionNodeManager {
             // 2b: direct delivery failed (counterparty offline). The hash is already witnessed (R1, the
             // sequence is assigned), so deposit the content to the relay store-and-forward backstop now;
             // the recipient pulls + recovers it on next online (DOD-MSG-3/4).
-            this.#parkContent(agentName, sessionId, Buffer.from(contentHash).toString("hex"), content, orderingS1, orderingS2);
+            // DOD-LEAVEMSG-1: the deposit is now AWAITED (was fire-and-forget) so a genuine park success
+            // can be reported as "dispatched to relay" instead of a raw stream failure — the operator/
+            // agent sees the truth (the message IS in flight, just not direct), not a false negative.
+            const parked = await this.#parkContent(agentName, sessionId, Buffer.from(contentHash).toString("hex"), content, orderingS1, orderingS2);
+            if (parked) {
+                return { ok: true, delivered: false, parked: true };
+            }
             // error.message extracted — never [object Object]. libp2p/cross-package errors are not
             // always `instanceof Error` in this realm, so fall back to a message property / JSON.
             const errMsg = err instanceof Error
@@ -2078,7 +2251,7 @@ export class SessionNodeManager {
      *
      * @returns the appended leaf index (as sequenceNumber) on success.
      */
-    ingestReceivedContent(agentName, sessionId, content, contentHash, correlationId) {
+    async ingestReceivedContent(agentName, sessionId, content, contentHash, correlationId) {
         // The transcript is frozen ONLY once it is COMMITTED + signed — 'sealed' or
         // 'seal_interrupted_pending' (the bilateral seal commitment) — because a later FROST
         // notarization attests that exact root; a late leaf would diverge from it.
@@ -2140,6 +2313,151 @@ export class SessionNodeManager {
             // entry (e.g. after auto-recover already drained it) must not count it as a fresh recovery.
             return { ok: true, leafIndex: existingIdx, sequenceNumber: existingIdx, appendedCount: 0 };
         }
+        // M8C-ABUSE-1 (reviewer HIGH fix, D18): per-session total-size cap (anti-drip-feed) —
+        // "whitelisted senders bounded only by disk" (DoD), so a known contact is exempt entirely.
+        // MUST run BEFORE the hold-branch below — the original placement (after it) let a
+        // non-contact sender drip-feed unbounded bytes by making every message arrive "out of order"
+        // relative to the relay witness (held content skipped the cap entirely, then #releaseHeld
+        // appended it later with no re-check). Accounts for bytes already committed AND bytes
+        // currently sitting in the hold buffer (multiple held chunks could otherwise each individually
+        // pass the check while cumulatively exceeding it once released). Runs BEFORE the M9 screening
+        // seam below (cheap + synchronous — fail fast on volume before spending gateway compute on
+        // content headed for rejection anyway); both gates are independent and either rejects on its
+        // own criteria, so ordering between them does not change correctness.
+        if (!this.isContact(agentName, senderPubkey)) {
+            const priorTotal = this.#getReceivedBytesTotal(agentName, sessionId);
+            const heldTotal = this.#getHeldBytesTotal(agentName, sessionId);
+            if (priorTotal + heldTotal + content.length > ABUSE_MAX_SESSION_RECEIVED_BYTES) {
+                this.#logger.warn("session.content.abuse_bound.session_size_exceeded", {
+                    sessionId,
+                    agentName,
+                    senderPubkey,
+                    priorTotal,
+                    heldTotal,
+                    incoming: content.length,
+                    cap: ABUSE_MAX_SESSION_RECEIVED_BYTES,
+                    correlationId,
+                });
+                return { ok: false, reason: "session_size_limit_exceeded" };
+            }
+        }
+        // M9-CORE-001: the inbound screening seam (INV-5). Screen here — after the content is proven
+        // authentic (hash cross-check) and confirmed not a duplicate, before it is either held for
+        // ordering or appended to the agent-facing buffer. This is the SINGLE inbound funnel: direct
+        // arrivals, recovered/parked content (daemon recover → here), and held-then-released content
+        // (held below, screened now, released already-screened) all pass this point. A non-allow
+        // verdict means the content is NOT delivered to the agent: it is not held, not buffered, and
+        // no leaf is appended — the message stays un-acked so the sender's TTF/park/retry redelivers
+        // it once the gateway is reachable again (DB-001 fail-closed: hold, never expose ungated).
+        const inboundVerdict = await this.#securityGateway.screenInbound(content, {
+            direction: "inbound",
+            agentName,
+            sessionId,
+            correlationId,
+        });
+        // M9 terminal-vs-transient split. A TERMINAL block (inboundVerdict.terminal) is a detector
+        // rejecting the CONTENT itself — a confident non-allowlisted language (IN-003), a high-score
+        // injection (IN-002), or an oversized payload (IN-001). The identical bytes would be rejected
+        // identically on redelivery, so holding them un-acked would loop the sender forever. Instead a
+        // terminal block is `screenedOut`: it records a leaf binding the ORIGINAL content hash and is
+        // acknowledged (the sender stops), but is NEVER buffered for the agent (cello_receive never sees
+        // it). The leaf is REQUIRED, not cosmetic: the sender appended this leaf at its CANONICAL position
+        // on send, so a terminal block must take the SAME strict-in-order path as a delivered message —
+        // record the leaf at its canonical index, not in arrival order — or the two parties' hash chains
+        // diverge by POSITION and the bilateral seal cross-check mismatches (code-review HIGH-1). The only
+        // difference from a normal message is that it leafs WITHOUT buffering. A TRANSIENT block (a
+        // fail-closed gateway_unavailable / governance_timeout) records nothing and is not acked.
+        const terminalBlock = inboundVerdict.disposition === "block" && inboundVerdict.terminal === true;
+        if (inboundVerdict.disposition !== "allow" && inboundVerdict.disposition !== "redact" && !terminalBlock) {
+            // TRANSIENT block / warn HOLD (do not deliver, do not leaf, do not ack). The message stays
+            // un-acked so the sender's TTF/park/retry redelivers and re-screens it once the gateway recovers.
+            // (If we committed a leaf, dedup would later swallow the redelivery and the agent would never
+            // receive it.)
+            if (inboundVerdict.reason === GOVERNANCE_TIMEOUT) {
+                this.#logger.error("security.gateway.timeout", {
+                    sessionId,
+                    reason: inboundVerdict.reason,
+                    correlationId,
+                });
+            }
+            else if (inboundVerdict.reason === GATEWAY_UNAVAILABLE) {
+                this.#logger.error("security.gateway.unavailable", {
+                    direction: "inbound",
+                    reason: inboundVerdict.reason,
+                    correlationId,
+                });
+            }
+            else {
+                this.#logger.warn("security.gateway.inbound.blocked", {
+                    sessionId,
+                    disposition: inboundVerdict.disposition,
+                    reason: inboundVerdict.reason,
+                    correlationId,
+                });
+            }
+            return { ok: false, reason: inboundVerdict.reason ?? "inbound_screen_blocked" };
+        }
+        if (terminalBlock) {
+            this.#logger.warn("security.gateway.inbound.terminal_block", {
+                sessionId,
+                disposition: inboundVerdict.disposition,
+                reason: inboundVerdict.reason,
+                correlationId,
+            });
+        }
+        // M9-IN-001: a `redact` verdict (inbound sanitization) DELIVERS the sanitized text to the agent,
+        // while the Merkle leaf still binds the ORIGINAL content hash below — the transcript records what
+        // the peer actually sent; the agent sees the sanitized form. `allow` leaves the content unchanged.
+        // A terminal block carries the original bytes here only so its leaf binds the right hash; it is
+        // never delivered (the screenedOut flag below routes it to a leaf-without-buffer).
+        const deliverContent = inboundVerdict.disposition === "redact" && inboundVerdict.content !== undefined
+            ? inboundVerdict.content
+            : content;
+        // B1 (review): screenInbound above is the ONLY suspension point in this method. Before M9 the
+        // dedup check (indexOfHash, above) and the leaf append (below) ran with no yield between them,
+        // so check-then-append was atomic under Node's single thread. The await reopened that window:
+        // two concurrent ingests of the SAME content hash — e.g. a direct retry and a park-recovery
+        // racing on reconnect — could BOTH pass the dedup check before either appends, producing two
+        // leaves for one hash (DOD-MSG-5 break → leafIndex≠canonicalSeq → root divergence). Re-check
+        // dedup now that we have resumed; everything from here to the append is synchronous (atomic),
+        // so the first to resume appends and the second sees its leaf and dedups.
+        const dedupAfterScreen = this.getSessionTree(agentName, sessionId).indexOfHash(contentHashHex);
+        if (dedupAfterScreen >= 0) {
+            this.#logger.info("session.content.deduplicated", {
+                sessionId,
+                contentHashHex,
+                sequenceNumber: dedupAfterScreen,
+                correlationId,
+            });
+            return { ok: true, leafIndex: dedupAfterScreen, sequenceNumber: dedupAfterScreen, appendedCount: 0, ...(terminalBlock ? { screenedOut: true } : {}) };
+        }
+        // M8C-ABUSE-1 (cello-unit-reviewer HIGH fix, post-M9INT-1 merge): re-check the size cap here,
+        // in the SAME synchronous window as the dedup re-check above. The original check (before the
+        // screenInbound await) used totals that can go stale: two concurrent ingests for the same
+        // non-contact session — e.g. a live direct arrival racing a recoverParkedFromRelay pull —
+        // could each independently pass the pre-await check using the SAME stale totals, then both
+        // append/hold, jointly exceeding the cap. Symmetric to the dedup fix: everything from here to
+        // the append/hold branch is synchronous, so whichever call resumes first appends/holds before
+        // the second's re-check runs, and the second's freshly-recomputed totals correctly include the
+        // first's contribution.
+        if (!this.isContact(agentName, senderPubkey)) {
+            const priorTotal = this.#getReceivedBytesTotal(agentName, sessionId);
+            const heldTotal = this.#getHeldBytesTotal(agentName, sessionId);
+            if (priorTotal + heldTotal + content.length > ABUSE_MAX_SESSION_RECEIVED_BYTES) {
+                this.#logger.warn("session.content.abuse_bound.session_size_exceeded", {
+                    sessionId,
+                    agentName,
+                    senderPubkey,
+                    priorTotal,
+                    heldTotal,
+                    incoming: content.length,
+                    cap: ABUSE_MAX_SESSION_RECEIVED_BYTES,
+                    correlationId,
+                    recheck: true,
+                });
+                return { ok: false, reason: "session_size_limit_exceeded" };
+            }
+        }
         // DOD-MSG-4 (strict in-order gate): the RELAY is the ordering authority. If B holds the
         // canonical sequence for this hash (witnessed via leaf_deliver) and it is AHEAD of the next
         // expected leaf, HOLD the content rather than append it out of order. The missing in-between
@@ -2157,18 +2475,22 @@ export class SessionNodeManager {
                 held = new Map();
                 this.#heldContent.set(key, held);
             }
-            held.set(canonicalSeq, { content, contentHashHex, correlationId });
+            // A terminal block out of canonical order is held WITHOUT delivery (screenedOut): #releaseHeld
+            // leafs it at its canonical index when the gap fills, but never buffers it for the agent. This
+            // keeps leafIndex === canonicalSeq for screened-out content too (code-review HIGH-1).
+            held.set(canonicalSeq, { content: deliverContent, contentHashHex, correlationId, ...(terminalBlock ? { screenedOut: true } : {}) });
             this.#logger.info("session.content.held", {
                 sessionId,
                 canonicalSeq,
                 nextExpected,
                 gap: canonicalSeq - nextExpected,
+                screenedOut: terminalBlock,
                 correlationId,
             });
             // Held content is NOT yet a durable leaf, so it is deliberately NOT acknowledged `persisted`
             // (the caller checks `held`). The sender's TTF→park backstop and the recover/dedup path
             // guarantee eventual delivery; B never claims persisted for content it only holds in memory.
-            return { ok: true, leafIndex: canonicalSeq, sequenceNumber: canonicalSeq, held: true };
+            return { ok: true, leafIndex: canonicalSeq, sequenceNumber: canonicalSeq, held: true, ...(terminalBlock ? { screenedOut: true } : {}) };
         }
         if (canonicalSeq !== undefined && canonicalSeq < nextExpected) {
             // Contradiction (review finding #2): the witness says this hash belongs BEHIND the current
@@ -2184,12 +2506,16 @@ export class SessionNodeManager {
                 correlationId,
             });
         }
-        const { leafIndex } = this.#appendVerifiedContent(agentName, sessionId, content, contentHashHex, senderPubkey, correlationId);
+        // In-order append. A terminal block leafs the ORIGINAL content hash WITHOUT buffering it for the
+        // agent (screenedOut); a delivered message buffers + leafs via #appendVerifiedContent.
+        const leafIndex = terminalBlock
+            ? this.appendSessionLeaf(agentName, sessionId, "msg", contentHashHex, correlationId).leafIndex
+            : this.#appendVerifiedContent(agentName, sessionId, deliverContent, contentHashHex, senderPubkey, correlationId).leafIndex;
         // A just-appended leaf may unblock held out-of-order arrivals whose turn is now next.
         // appendedCount = this leaf + any held leaves released by it, so a caller (recover) can tally the
         // leaves ACTUALLY written, not just the directly-ingested one (review #3).
         const released = this.#releaseHeld(agentName, sessionId, senderPubkey);
-        return { ok: true, leafIndex, sequenceNumber: leafIndex, appendedCount: 1 + released };
+        return { ok: true, leafIndex, sequenceNumber: leafIndex, appendedCount: 1 + released, ...(terminalBlock ? { screenedOut: true } : {}) };
     }
     /**
      * DOD-MSG-4: record the relay-witnessed canonical sequence for a content hash. The relay is the
@@ -2277,11 +2603,19 @@ export class SessionNodeManager {
             if (!entry)
                 break;
             held.delete(nextExpected);
-            this.#appendVerifiedContent(agentName, sessionId, entry.content, entry.contentHashHex, senderPubkey, entry.correlationId);
+            // A screened-out (terminal-blocked) held entry leafs at its canonical index but is NEVER
+            // buffered for the agent; a normal held entry buffers + leafs (code-review HIGH-1).
+            if (entry.screenedOut) {
+                this.appendSessionLeaf(agentName, sessionId, "msg", entry.contentHashHex, entry.correlationId);
+            }
+            else {
+                this.#appendVerifiedContent(agentName, sessionId, entry.content, entry.contentHashHex, senderPubkey, entry.correlationId);
+            }
             released++;
             this.#logger.info("session.content.released", {
                 sessionId,
                 sequenceNumber: nextExpected,
+                screenedOut: entry.screenedOut === true,
                 correlationId: entry.correlationId,
             });
             if (held.size === 0) {
@@ -2425,7 +2759,10 @@ export class SessionNodeManager {
         // store-and-forward so the recipient recovers it (at the witnessed sequence). The durable
         // awaiting entry above remains the crash backstop. Carry the retained ordering record (review #1)
         // so a TTF-parked entry self-orders on recover, exactly like the direct-dial-fail park.
-        this.#parkContent(agentName, sessionId, hashHex, entry.content, entry.structure1Cbor, entry.structure2Cbor);
+        // Fire-and-forget: unlike sendContent's live caller, nothing here is awaiting an IPC response
+        // to shape (the TTF timer fires long after cello_send already returned) — the deposit's own
+        // success/failure logging inside #parkContent is the only observability this path needs.
+        void this.#parkContent(agentName, sessionId, hashHex, entry.content, entry.structure1Cbor, entry.structure2Cbor);
     }
     /**
      * Send an unsigned `persisted` delivery ACK back to the sender over the same
@@ -2447,6 +2784,15 @@ export class SessionNodeManager {
                 correlation_id: correlationId,
             });
             stream.send(lp.encode.single(frame));
+            // The receiver-side counterpart to the sender's content.delivery.acked: B has acknowledged
+            // this content `persisted`, so the sender stops retrying/parking. Emitted for BOTH a normally
+            // delivered message AND a terminal-screen block (the block is a definitive receipt — the leaf
+            // is recorded, so the sender must stop) — and deliberately NOT for a transient hold.
+            this.#logger.info("content.delivery.ack.sent", {
+                sessionId,
+                contentHash: Buffer.from(contentHash).toString("hex"),
+                correlationId,
+            });
             try {
                 await stream.close();
             }
@@ -2658,7 +3004,7 @@ export class SessionNodeManager {
             }
             // AC-001: carry the sender's correlationId from the frame into the receive
             // path so both sides log the same flow id (never re-minted on receipt).
-            const ingest = this.ingestReceivedContent(agentName, sessionId, contentBytes, contentHash, correlationId);
+            const ingest = await this.ingestReceivedContent(agentName, sessionId, contentBytes, contentHash, correlationId);
             // AC-001: after the content is durably ingested AND its hash cross-check
             // succeeds, emit an unsigned `persisted` delivery ACK back to the sender. A
             // rejected ingest (tamper / not-active) produces NO ACK, so the sender's TTF