@sema-agent/core 7.29.0 → 7.30.0

package/dist/agents/peer-session-drain.js

@@ -1,8 +1,10 @@
 import { mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
+import { decodeEngineFrame, ENGINE_FRAME_CODEC_VERSION, renderTaskNotificationXml, taskNotificationDedupKey } from "../core/task-notification.js";
+import { createFrameSettlement, toolResultReceiptKey } from "../core/frame-settlement.js";
 import { deliverEngineNotice } from "../core/types.js";
 import { buildCrossSessionEnvelope, CrossSessionCodecError, encodePeerAddress } from "./cross-session-envelope.js";
 import { judgeCrossSessionInbound, resolveCrossSessionInboundSetting } from "./cross-session-judge.js";
-import { judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig } from "./peer-admission.js";
+import { judgePeerAdmission, peerAxisToken, resolvePeerLaneConfig } from "./peer-admission.js";
 import { isPeerSessionId, PEER_SESSION_ID_GRAMMAR, peerSessionBoxHandle } from "./peer-directory.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { createListAgentsTool, LIST_AGENTS_TOOL_ALIAS, LIST_AGENTS_TOOL_NAME } from "./list-agents-tool.js";
@@ -43,9 +45,11 @@ export function judgeSessionBoxDrain(deps, leg) {
         scope: leg.scope,
         handle: peerSessionBoxHandle(leg.sessionId),
         sessionId: leg.sessionId,
+        ...(deps.sessionBoxEngineFrames === true ? { engineFrames: true } : {}),
         onError: (e) => deps.onError?.(e, { phase: "degraded", sessionId: leg.sessionId, classification: "session-box-park" }),
     };
 }
+export const PEER_RESUPPLY_CAP = 1;
 export function createPeerSessionDrain(opts) {
     const { mailbox, sessionId, runId, scope } = opts;
     const boxHandle = peerSessionBoxHandle(sessionId);
@@ -53,28 +57,41 @@ export function createPeerSessionDrain(opts) {
     const drainOwner = `drain:${runId}`;
     const recipientKey = peerAxisToken(scope, "s", sessionId);
     const ttl = opts.leaseTtlMs ?? PEER_DRAIN_LEASE_TTL_MS;
-    let settledUpTo;
+    const TERMINAL_DISPOSITIONS = new Set(["committed", "resupply_exhausted", "terminal"]);
+    const isTerminalDisposition = (d) => d !== undefined && TERMINAL_DISPOSITIONS.has(d.kind);
+    const ledger = new Map();
+    let ackedUpTo;
+    const seam = opts.settlement ?? createFrameSettlement();
     const disclosedHeld = new Set();
     let inFlight = Promise.resolve();
+    let noticeRound = 0;
+    let deprecatedSpellingAnnounced = false;
+    let currentRound;
     const held = peerHeldQueueFor(scope, sessionId, opts.clock !== undefined ? { clock: opts.clock } : {});
     const idleMachine = peerIdleMachineFor(scope, sessionId, opts.clock !== undefined ? { clock: opts.clock } : {});
     const disclose = (disposition, cause, m, heldNote) => deliverEngineNotice(opts.onNotice, {
         code: "peer.inbound_disposition",
         message: `cross-session message seq ${m.seq} in this session's box was ${disposition === "held"
-            ? `HELD${heldNote !== undefined ? ` (${heldNote})` : " (it entered this session's held queue, acked from the box; it is re-judged at every boundary, released or refused with a receipt to the sender, and expires with a receipt under dialogExpiry)"}`
+            ? `HELD${heldNote !== undefined ? ` (${heldNote})` : " (it entered this session's held queue and STAYS IN THE BOX \u2014 the box is that queue's durable seat, so it is not acked until it settles; it is re-judged at every boundary, released or refused with a receipt to the sender, and expires with a receipt under dialogExpiry)"}`
             : disposition === "refused"
                 ? "refused by this session's crossSessionInbound setting"
-                : disposition === "notice_unrouted"
-                    ? "settled WITHOUT delivery (a notice-kind record the notice face cannot render)"
-                    : disposition === "notice_user_only"
-                        ? "surfaced to the user only (a notice whose sender this session's parity would hold; the model did not read it)"
-                        : "refused by the inbound admission gate"}: ${cause}`,
+                : disposition === "resupply_exhausted"
+                    ? "settled WITHOUT being read: its frame was summarized away by a compaction, re-supplied once, and summarized away again \u2014 the engine has stopped handing it over. The sender was not told; reply-worthy content is GONE from this session's context"
+                    : disposition === "notice_unrouted"
+                        ? "settled WITHOUT delivery (a notice-kind record the notice face cannot render)"
+                        : disposition === "notice_user_only"
+                            ? "surfaced to the user only (a notice whose sender this session's parity would hold; the model did not read it)"
+                            : "refused by the inbound admission gate"}: ${cause}`,
         detail: { disposition, cause, seq: m.seq, box: boxHandle, ...(m.peerMeta?.fromSession !== undefined ? { fromSession: m.peerMeta.fromSession } : {}), sessionId, runId },
     });
-    const readFacts = () => ({
-        setting: resolveCrossSessionInboundSetting(opts.settingLayers() ?? {}),
-        selfModeClass: opts.selfModeClass(),
-    });
+    const readFacts = () => {
+        const setting = resolveCrossSessionInboundSetting(opts.settingLayers() ?? {});
+        if (setting.deprecatedLayers !== undefined && !deprecatedSpellingAnnounced) {
+            deprecatedSpellingAnnounced = true;
+            opts.onError?.(new Error(`crossSessionInbound is spelled "accept" in the ${setting.deprecatedLayers.join(", ")} layer(s); that spelling is read as "next-turn" (deliver at the next turn boundary) — update the settings file`), { phase: "degraded", sessionId, classification: "peer-inbound-setting-spelling" });
+        }
+        return { setting, selfModeClass: opts.selfModeClass() };
+    };
     const judgeMeta = (facts, meta) => judgeCrossSessionInbound({ setting: facts.setting, selfModeClass: facts.selfModeClass, sender: { ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: meta?.fromSession !== undefined && meta.fromSession.toLowerCase() === sessionId.toLowerCase() } });
     const route = () => ({
         mailbox,
@@ -125,7 +142,19 @@ export function createPeerSessionDrain(opts) {
     };
     const heldSink = (live) => ({
         judge: (entry) => judgeMeta(readFacts(), entry.peerMeta),
-        ...(live ? { inject: (entry) => opts.inject(buildPeerMessagePayload(entry), { priority: "next" }) } : {}),
+        ...(live
+            ? {
+                inject: (entry) => {
+                    if (currentRound === undefined)
+                        return "deferred";
+                    const payload = buildPeerMessagePayload(entry);
+                    if (currentRound.deliver(payload, "next") === "deferred")
+                        return "deferred";
+                    noteDelivered(entry.seq, 1, payload, currentRound.carrier);
+                    return undefined;
+                },
+            }
+            : {}),
         receipt,
         onHeld: (entry, count, cause, reannounce) => {
             if (!reannounce && disclosedHeld.has(entry.seq))
@@ -133,11 +162,15 @@ export function createPeerSessionDrain(opts) {
             disclosedHeld.add(entry.seq);
             disclose("held", cause, entry, reannounce ? `still held; its cause moved to ${cause} (${count} held)` : undefined);
         },
-        onSettled: (entry, settlement, reason, count) => deliverEngineNotice(opts.onNotice, {
-            code: "peer.held_settled",
-            message: `held cross-session message seq ${entry.seq} left this session's held queue: ${settlement} (${reason}); ${count} still held${settlement === "expired" && reason === "evicted" ? " — the held queue was full, so the oldest entry was expired to make room" : ""}. The sender ${entry.peerMeta?.fromSession !== undefined ? "was sent a receipt" : "has no reply address and was not told"}.`,
-            detail: { settlement, reason, seq: entry.seq, box: boxHandle, ...(entry.peerMeta?.fromSession !== undefined ? { fromSession: entry.peerMeta.fromSession } : {}), heldCount: count, sessionId, runId },
-        }),
+        onSettled: (entry, settlement, reason, count) => {
+            if (entry.box === boxHandle && settlement !== "delivered")
+                ledger.set(entry.seq, { kind: "terminal", why: `held_${settlement}` });
+            deliverEngineNotice(opts.onNotice, {
+                code: "peer.held_settled",
+                message: `held cross-session message seq ${entry.seq} left this session's held queue: ${settlement} (${reason}); ${count} still held${settlement === "expired" && reason === "evicted" ? " — the held queue was full, so the oldest entry was expired to make room" : ""}. The sender ${entry.peerMeta?.fromSession !== undefined ? "was sent a receipt" : "has no reply address and was not told"}.`,
+                detail: { settlement, reason, seq: entry.seq, box: boxHandle, ...(entry.peerMeta?.fromSession !== undefined ? { fromSession: entry.peerMeta.fromSession } : {}), heldCount: count, sessionId, runId },
+            });
+        },
     });
     let dialogExpiryMs = resolveCrossSessionDialogExpiry(undefined).ms;
     let dialogExpiryAnnounced = false;
@@ -165,18 +198,127 @@ export function createPeerSessionDrain(opts) {
     idleMachine.requester.configure({
         expired: (o) => void routePeerIdleNotice(route(), sessionId, { kind: "expired", label: o.label }),
     });
-    const ackSettled = async () => {
-        if (settledUpTo === undefined)
+    const adoptHeldDecisions = () => {
+        const decided = held.decisions();
+        if (decided.size === 0)
             return;
-        const upTo = settledUpTo;
-        settledUpTo = undefined;
-        try {
-            await mailbox.ack(scope, boxHandle, drainOwner, upTo);
+        for (const [seq, settlement] of decided) {
+            if (ackedUpTo !== undefined && seq <= ackedUpTo)
+                continue;
+            const mine = ledger.get(seq);
+            if (mine !== undefined && mine.kind !== "held")
+                continue;
+            ledger.set(seq, { kind: "terminal", why: `held_${settlement}` });
         }
-        catch (e) {
-            if (settledUpTo === undefined || settledUpTo < upTo)
-                settledUpTo = upTo;
-            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-ack" });
+    };
+    const reconcileHeld = (lease) => {
+        held.reconcile(new Set(lease.messages.map((m) => m.seq)));
+        let queued;
+        for (const [seq, d] of ledger) {
+            if (d.kind !== "held")
+                continue;
+            queued ??= new Set(held.list().filter((e) => e.box === boxHandle).map((e) => e.seq));
+            if (!queued.has(seq))
+                ledger.delete(seq);
+        }
+    };
+    const wantsCompactionEffects = () => {
+        for (const d of ledger.values())
+            if (d.kind === "delivered" || d.kind === "committed")
+                return true;
+        return false;
+    };
+    const noteDelivered = (seq, attempt, payload, carrier) => {
+        const own = taskNotificationDedupKey(payload);
+        const key = carrier === undefined ? own : `${carrier}|${own}`;
+        ledger.set(seq, { kind: "delivered", attempt, key, payload });
+        seam.awaiting.set(key, carrier === undefined ? { carrier: own } : { carrier, frameText: renderTaskNotificationXml(payload) });
+    };
+    const deriveAckPrefix = (messages) => {
+        let prefix;
+        for (const m of messages) {
+            if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
+                continue;
+            if (!isTerminalDisposition(ledger.get(m.seq)))
+                break;
+            prefix = m.seq;
+        }
+        return prefix;
+    };
+    const settleLocally = () => {
+        adoptHeldDecisions();
+        const hostWithheldSeqs = [];
+        if (seam.receipts.size > 0 || seam.withheld.size > 0 || seam.hostWithheld.size > 0) {
+            for (const [seq, d] of ledger) {
+                if (d.kind !== "delivered")
+                    continue;
+                if (seam.hostWithheld.delete(d.key)) {
+                    ledger.set(seq, { kind: "terminal", why: "host_withheld" });
+                    hostWithheldSeqs.push(seq);
+                    continue;
+                }
+                if (seam.withheld.delete(d.key)) {
+                    if (d.attempt > 1)
+                        ledger.set(seq, { kind: "invalidated", attempt: d.attempt - 1, payload: d.payload });
+                    else
+                        ledger.delete(seq);
+                    continue;
+                }
+                const entryId = seam.receipts.get(d.key);
+                if (entryId === undefined)
+                    continue;
+                seam.receipts.delete(d.key);
+                ledger.set(seq, { kind: "committed", attempt: d.attempt, key: d.key, entryId, payload: d.payload });
+            }
+        }
+        if (hostWithheldSeqs.length > 0) {
+            opts.onError?.(new Error(`${hostWithheldSeqs.length} cross-session message frame(s) (seq ${hostWithheldSeqs.join(", ")}) could not be found in this session's ReadInbox result as a postToolUse hook rewrote it (removed, truncated or reshaped beyond whitespace) — settled as the host's decision: they leave ${boxHandle} and are not handed over again`), { phase: "degraded", sessionId, classification: "peer-inbox-host-withheld" });
+        }
+        for (const effect of seam.compactions.splice(0)) {
+            for (const [seq, d] of ledger) {
+                if (d.kind !== "committed")
+                    continue;
+                if (effect.summarizedEntryIds === "unknown" || effect.summarizedEntryIds.has(d.entryId)) {
+                    ledger.set(seq, { kind: "invalidated", attempt: d.attempt, payload: d.payload });
+                }
+            }
+        }
+        for (const [seq, d] of ledger) {
+            if (d.kind === "invalidated" && d.attempt > PEER_RESUPPLY_CAP) {
+                const meta = d.payload._sema_provenance?.peerMeta;
+                disclose("resupply_exhausted", `attempt ${d.attempt} of ${PEER_RESUPPLY_CAP + 1} was summarized away too`, { seq, ...(meta !== undefined ? { peerMeta: meta } : {}) });
+                ledger.set(seq, { kind: "resupply_exhausted" });
+            }
+        }
+    };
+    const ackSettledPrefix = async (lease) => {
+        const decided = held.decisions();
+        if (decided.size > 0) {
+            const live = new Set(lease.messages.map((m) => m.seq));
+            held.forgetDecisions([...decided.keys()].filter((seq) => !live.has(seq)));
+        }
+        const prefix = deriveAckPrefix(lease.messages);
+        if (prefix !== undefined && (ackedUpTo === undefined || prefix > ackedUpTo)) {
+            try {
+                const result = await mailbox.ack(scope, boxHandle, drainOwner, prefix);
+                if (result.acked) {
+                    ackedUpTo = prefix;
+                    const gone = [];
+                    for (const seq of [...ledger.keys()]) {
+                        if (seq > prefix)
+                            continue;
+                        gone.push(seq);
+                        ledger.delete(seq);
+                    }
+                    held.forgetDecisions(gone);
+                }
+                else {
+                    opts.onError?.(new Error(`the session box ${boxHandle} refused this leg's ack up to seq ${prefix}: the drain lease is no longer held by ${drainOwner} (it expired and another cycle claimed it). The records stay parked and the lease holder re-serves them.`), { phase: "degraded", sessionId, classification: "peer-box-ack" });
+                }
+            }
+            catch (e) {
+                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-ack" });
+            }
         }
     };
     const settleNoticeRecord = (facts, m, meta) => {
@@ -185,7 +327,7 @@ export function createPeerSessionDrain(opts) {
         const stateFits = notice !== undefined && (kind === "idle_notice" ? isPeerIdleNoticeKind(notice.state) : isPeerDeliveryReceiptState(notice.state));
         if (!stateFits) {
             disclose("notice_unrouted", `kind=${kind}${notice === undefined ? " without a typed notice" : ` with state=${inlineUntrusted(notice.state, 32)}`}`, m);
-            settledUpTo = m.seq;
+            currentRound.dispose(m.seq, `notice_unrouted:${kind}`);
             return;
         }
         let text;
@@ -210,15 +352,16 @@ export function createPeerSessionDrain(opts) {
             disclose("notice_user_only", `${judged.cause}: ${text}`, m);
         }
         else {
-            opts.inject(buildNoticePayload(m, kind, text), { priority: "next" });
+            currentRound.batch.push({ payload: buildNoticePayload(m, kind, text), priority: "next", urgent: false, seq: m.seq, attempt: 1 });
+            return;
         }
-        settledUpTo = m.seq;
+        currentRound.dispose(m.seq, judged.verdict === "refuse" ? "refused" : "notice_user_only");
     };
     const settleSubscription = (facts, m, meta) => {
         const requester = meta.fromSession;
         if (requester === undefined) {
             disclose("notice_unrouted", "kind=idle_subscription without a reply address (fromSession)", m);
-            settledUpTo = m.seq;
+            currentRound.dispose(m.seq, "subscription_unaddressed");
             return;
         }
         const sub = { requester, ...(m.from !== undefined ? { requesterName: m.from } : {}), ...(meta.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: requester.toLowerCase() === sessionId.toLowerCase(), requestedAt: m.sentAt };
@@ -230,17 +373,67 @@ export function createPeerSessionDrain(opts) {
         if (facts.setting.value === "refuse") {
             void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
             announce("refused", idleMachine.target.size());
-            settledUpTo = m.seq;
+            currentRound.dispose(m.seq, "subscription_refused");
             return;
         }
         const outcome = idleMachine.target.subscribe(sub);
         if (outcome === "full")
             void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
         announce(outcome, idleMachine.target.size());
-        settledUpTo = m.seq;
+        currentRound.dispose(m.seq, `subscription_${outcome}`);
+    };
+    const countWaiting = (lease) => {
+        if (lease === null)
+            return { pending: 0, urgent: 0 };
+        const waiting = lease.messages.filter((m) => {
+            if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
+                return false;
+            const d = ledger.get(m.seq);
+            return d === undefined || d.kind === "invalidated";
+        });
+        return { pending: waiting.length, urgent: waiting.filter((m) => m.peerMeta?.urgent === true).length };
     };
     let warmedUp = opts.warmup === undefined;
-    const drainOnce = async () => {
+    class DrainRound {
+        limit;
+        out;
+        carrier;
+        charBudget;
+        injected = 0;
+        resupplied = 0;
+        dispose(seq, why) {
+            ledger.set(seq, { kind: "terminal", why });
+        }
+        batch = [];
+        chars = 0;
+        constructor(limit, out, carrier, charBudget) {
+            this.limit = limit;
+            this.out = out;
+            this.carrier = carrier;
+            this.charBudget = charBudget;
+        }
+        get spent() {
+            return this.injected + this.batch.length >= this.limit;
+        }
+        deliver(payload, priority) {
+            if (this.spent)
+                return "deferred";
+            if (this.out !== undefined) {
+                if (this.charBudget !== undefined) {
+                    const size = renderTaskNotificationXml(payload).length;
+                    if (this.out.length > 0 && this.chars + size > this.charBudget)
+                        return "deferred";
+                    this.chars += size;
+                }
+                this.out.push(payload);
+            }
+            else
+                opts.inject(payload, { priority });
+            this.injected += 1;
+            return undefined;
+        }
+    }
+    const drainRound = async (round, pass) => {
         if (!warmedUp) {
             warmedUp = true;
             try {
@@ -255,91 +448,185 @@ export function createPeerSessionDrain(opts) {
         }
         catch (e) {
             opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
-            return;
+            return { pending: 0, urgent: 0 };
         }
-        const previouslySettled = settledUpTo;
-        await ackSettled();
+        if (pass.settle)
+            settleLocally();
+        if (pass.settle && lease !== null)
+            await ackSettledPrefix(lease);
+        if (!pass.deliver)
+            return countWaiting(lease);
         let facts;
         let admissionConfig;
         try {
             facts = readFacts();
-            admissionConfig = resolvePeerAdmissionConfig(opts.admission, opts.onNotice);
+            admissionConfig = resolvePeerLaneConfig(opts.lane, opts.onNotice);
         }
         catch (e) {
             opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-settings" });
-            return;
+            return { pending: 0, urgent: 0 };
         }
-        bindHeld(true);
-        idleMachine.target.sweep();
-        held.rejudge();
-        if (lease === null)
-            return;
-        for (const m of lease.messages) {
-            if (previouslySettled !== undefined && m.seq <= previouslySettled)
-                continue;
-            const meta = m.peerMeta;
-            if (m.hopChain !== undefined) {
-                const verdict = judgePeerAdmission(scope, recipientKey, { senderKey: meta?.senderKey, body: m.content, prospectiveChain: m.hopChain, ownTokens: opts.ownTokens(), seq: m.seq }, admissionConfig, undefined, "drain");
-                if (!verdict.ok) {
-                    if (verdict.reason === "rate_limited") {
-                        if (!disclosedHeld.has(m.seq)) {
-                            disclosedHeld.add(m.seq);
-                            disclose("held", verdict.reason, m, "it stays in the box; the inbound admission bucket is empty and it is re-judged at a later boundary once the bucket refills");
-                        }
+        currentRound = round;
+        try {
+            idleMachine.target.sweep();
+            if (lease === null)
+                return { pending: 0, urgent: 0 };
+            bindHeld(true);
+            reconcileHeld(lease);
+            held.rejudge();
+            try {
+                for (const m of lease.messages) {
+                    const prior = ledger.get(m.seq);
+                    if (prior === undefined || prior.kind !== "invalidated")
+                        continue;
+                    if (round.spent)
+                        break;
+                    const attempt = prior.attempt + 1;
+                    round.batch.push({ payload: { ...prior.payload, attempt, resupplied: true }, priority: "next", urgent: false, seq: m.seq, attempt });
+                }
+                adoptHeldDecisions();
+                for (const m of lease.messages) {
+                    if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
+                        continue;
+                    if (ledger.has(m.seq))
+                        continue;
+                    if (round.spent)
                         break;
+                    const meta = m.peerMeta;
+                    if (m.hopChain !== undefined) {
+                        const verdict = judgePeerAdmission(scope, recipientKey, { senderKey: meta?.senderKey, body: m.content, prospectiveChain: m.hopChain, ownTokens: opts.ownTokens(), seq: m.seq }, admissionConfig, undefined, "drain");
+                        if (!verdict.ok) {
+                            if (verdict.reason === "rate_limited") {
+                                if (!disclosedHeld.has(m.seq)) {
+                                    disclosedHeld.add(m.seq);
+                                    disclose("held", verdict.reason, m, "it stays in the box; the inbound admission bucket is empty and it is re-judged at a later boundary once the bucket refills");
+                                }
+                                break;
+                            }
+                            disclose("admission_refused", verdict.reason, m);
+                            round.dispose(m.seq, `admission_refused:${verdict.reason}`);
+                            continue;
+                        }
                     }
-                    disclose("admission_refused", verdict.reason, m);
-                    settledUpTo = m.seq;
-                    continue;
+                    if (meta?.kind === "idle_subscription") {
+                        settleSubscription(facts, m, meta);
+                        continue;
+                    }
+                    if (meta?.kind === "idle_notice" || meta?.kind === "delivery_notice") {
+                        settleNoticeRecord(facts, m, meta);
+                        continue;
+                    }
+                    if (meta?.kind === "engine_frame") {
+                        const decoded = decodeEngineFrame(m.content);
+                        if (!decoded.ok && decoded.reason === "newer") {
+                            opts.onError?.(new Error(`engine_frame record seq ${m.seq} in ${boxHandle} carries codec version ${decoded.codecVersion}; this engine reads up to ${ENGINE_FRAME_CODEC_VERSION} — the box stops at that record until an engine that reads it drains the session`), { phase: "degraded", sessionId, classification: "peer-box-engine-frame" });
+                            break;
+                        }
+                        if (!decoded.ok) {
+                            disclose("notice_unrouted", `kind=engine_frame (${decoded.detail})`, m);
+                            round.dispose(m.seq, `engine_frame_malformed:${decoded.detail}`);
+                            continue;
+                        }
+                        round.batch.push({ payload: decoded.payload, priority: decoded.priority, urgent: false, seq: m.seq, attempt: 1 });
+                        continue;
+                    }
+                    const sameTree = meta?.fromRoot !== undefined && meta.fromRoot.toLowerCase() === sessionId.toLowerCase();
+                    if (!sameTree) {
+                        const judged = judgeMeta(facts, meta);
+                        if (judged.verdict === "refuse") {
+                            disclose("refused", judged.cause, m);
+                            round.dispose(m.seq, `refused:${judged.cause}`);
+                            continue;
+                        }
+                        if (judged.verdict === "hold") {
+                            held.hold({ seq: m.seq, box: boxHandle, content: m.content, ...(m.from !== undefined ? { from: m.from } : {}), sentAt: m.sentAt, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}), ...(meta !== undefined ? { peerMeta: { ...meta } } : {}), cause: judged.cause });
+                            if (!ledger.has(m.seq))
+                                ledger.set(m.seq, { kind: "held" });
+                            continue;
+                        }
+                    }
+                    let payload;
+                    try {
+                        payload = buildPeerMessagePayload(m);
+                    }
+                    catch (e) {
+                        disclose("refused", `record fields cannot be rendered canonically (${e instanceof CrossSessionCodecError ? e.code : thrownText(e)})`, m);
+                        round.dispose(m.seq, "uncanonical_fields");
+                        continue;
+                    }
+                    round.batch.push({ payload, priority: "next", urgent: meta?.urgent === true, seq: m.seq, attempt: 1 });
                 }
             }
-            if (meta?.kind === "idle_subscription") {
-                settleSubscription(facts, m, meta);
-                continue;
-            }
-            if (meta?.kind === "idle_notice" || meta?.kind === "delivery_notice") {
-                settleNoticeRecord(facts, m, meta);
-                continue;
+            finally {
+                const ordered = round.batch.splice(0).sort((a, b) => Number(b.urgent) - Number(a.urgent));
+                for (const item of ordered) {
+                    try {
+                        if (round.deliver(item.payload, item.priority) === "deferred")
+                            continue;
+                    }
+                    catch (e) {
+                        opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
+                        break;
+                    }
+                    noteDelivered(item.seq, item.attempt, item.payload, round.carrier);
+                    if (item.attempt > 1)
+                        round.resupplied += 1;
+                }
             }
-            const sameTree = meta?.fromRoot !== undefined && meta.fromRoot.toLowerCase() === sessionId.toLowerCase();
-            if (!sameTree) {
-                const judged = judgeMeta(facts, meta);
-                if (judged.verdict === "refuse") {
-                    disclose("refused", judged.cause, m);
-                    settledUpTo = m.seq;
-                    continue;
+            const counts = countWaiting(lease);
+            if (counts.pending > 0 && round.out === undefined) {
+                noticeRound += 1;
+                try {
+                    opts.inject({
+                        task_id: `inbox:${boxHandle}`,
+                        task_type: "background_agent",
+                        status: "event",
+                        seq: noticeRound,
+                        summary: `inbox notice: ${counts.pending} cross-session message(s) waiting`,
+                        inboxNotice: { pending: counts.pending, delivered: round.injected - round.resupplied, ...(round.resupplied > 0 ? { resupplied: round.resupplied } : {}), ...(counts.urgent > 0 ? { urgent: counts.urgent } : {}), box: boxHandle },
+                        _sema_provenance: { kind: "inbox_notice", from: boxHandle, taskId: `inbox:${boxHandle}`, seq: noticeRound },
+                    }, { priority: "next" });
                 }
-                if (judged.verdict === "hold") {
-                    held.hold({ seq: m.seq, box: boxHandle, content: m.content, ...(m.from !== undefined ? { from: m.from } : {}), sentAt: m.sentAt, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}), ...(meta !== undefined ? { peerMeta: { ...meta } } : {}), cause: judged.cause });
-                    settledUpTo = m.seq;
-                    continue;
+                catch (e) {
+                    opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
                 }
             }
-            let payload;
-            try {
-                payload = buildPeerMessagePayload(m);
-            }
-            catch (e) {
-                disclose("refused", `record fields cannot be rendered canonically (${e instanceof CrossSessionCodecError ? e.code : thrownText(e)})`, m);
-                settledUpTo = m.seq;
-                continue;
-            }
-            try {
-                opts.inject(payload, { priority: "next" });
-            }
-            catch (e) {
-                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
-                break;
-            }
-            settledUpTo = m.seq;
+            return counts;
+        }
+        finally {
+            currentRound = undefined;
         }
     };
-    const drain = () => {
-        inFlight = inFlight.then(drainOnce, drainOnce);
+    const boundPass = (pass) => async () => {
+        await drainRound(new DrainRound(resolvePeerLaneConfig(opts.lane, opts.onNotice).maxMessagesPerRound, undefined), pass);
+    };
+    const serialize = (once) => {
+        inFlight = inFlight.then(once, once);
         return inFlight;
     };
+    const drain = () => serialize(boundPass({ settle: true, deliver: true }));
+    const boundaryRound = (o) => serialize(boundPass({ settle: true, deliver: o.continues }));
+    const pull = (limit, toolCallId, charBudget) => {
+        const out = [];
+        const bound = limit !== undefined && Number.isInteger(limit) && limit > 0 ? limit : resolvePeerLaneConfig(opts.lane, opts.onNotice).maxMessagesPerRound;
+        let counts = { pending: 0, urgent: 0 };
+        const once = async () => {
+            counts = await drainRound(new DrainRound(bound, out, toolCallId !== undefined ? toolResultReceiptKey(toolCallId) : undefined, charBudget), { settle: false, deliver: true });
+        };
+        const settled = inFlight.then(once, once);
+        inFlight = settled;
+        return settled.then(() => ({ delivered: out, pending: counts.pending, urgent: counts.urgent }));
+    };
     const finishOnce = async () => {
-        await ackSettled();
+        try {
+            const lease = await mailbox.claimLease(scope, boxHandle, drainOwner, ttl);
+            settleLocally();
+            if (lease !== null)
+                await ackSettledPrefix(lease);
+        }
+        catch (e) {
+            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
+        }
         held.detachLeg();
         try {
             await mailbox.releaseLease(scope, boxHandle, drainOwner);
@@ -353,7 +640,20 @@ export function createPeerSessionDrain(opts) {
     };
     return {
         drain,
+        boundaryRound,
+        pull,
+        isBoxBacked: (payload) => {
+            const p = payload;
+            if (p === null || typeof p !== "object" || typeof p.task_id !== "string" || typeof p.status !== "string")
+                return false;
+            const key = taskNotificationDedupKey(p);
+            for (const d of ledger.values())
+                if (d.kind === "delivered" && d.key === key)
+                    return true;
+            return false;
+        },
         finish,
+        wantsCompactionEffects,
         busy: () => idleMachine.target.busy(),
         idle: (finishedAt) => idleMachine.target.idle(finishedAt),
         held,
@@ -396,7 +696,8 @@ export function mountListAgents(args) {
     args.toolEffects.set(LIST_AGENTS_TOOL_NAME, "read");
     args.toolEffects.set(LIST_AGENTS_TOOL_ALIAS, "read");
     return createListAgentsTool({
-        peerDirectory: args.peerDirectory,
+        ...(args.peerDirectory !== undefined ? { peerDirectory: args.peerDirectory } : {}),
+        ...(args.freshWindowMs !== undefined ? { freshWindowMs: args.freshWindowMs } : {}),
         self: { sessionId: args.sessionId, scope: args.scope },
         registry: args.registry,
         access: { owner: args.hostTaskId, scope: args.scope, sessionId: args.sessionId },
@@ -414,7 +715,6 @@ export function bindPeerSessionDrain(harness, opts) {
         drain.busy();
         return round();
     });
-    harness.on("turn_boundary", round);
     harness.subscribe((event) => {
         if (event.type === "agent_end")
             return drain.finish().catch(() => undefined);
@@ -448,22 +748,29 @@ export function bindPeerLaneDrain(harness, args) {
             rowName = undefined;
         }
     };
-    return bindPeerSessionDrain(harness, {
+    const drain = bindPeerSessionDrain(harness, {
         mailbox: deps.mailboxStore,
         sessionId: args.sessionId,
         runId: args.runId,
         scope: args.scope,
         inject: args.inject,
-        ...(deps.peerAdmission !== undefined ? { admission: deps.peerAdmission } : {}),
+        ...(deps.peerLane !== undefined ? { lane: deps.peerLane } : {}),
         ownTokens: args.ownTokens,
         settingLayers: () => (typeof deps.crossSessionInbound === "function" ? deps.crossSessionInbound() : deps.crossSessionInbound),
         selfModeClass: () => (args.refs.askEffective !== undefined ? foldPermissionModeClass(args.refs.askEffective) : "unknown"),
         dialogExpiry: () => (typeof deps.crossSessionDialogExpiry === "function" ? deps.crossSessionDialogExpiry() : deps.crossSessionDialogExpiry),
         selfName: () => rowName ?? args.selfName?.(),
         warmup: lookupRowName,
+        ...(args.settlement !== undefined ? { settlement: args.settlement } : {}),
         ...(args.parked !== undefined ? { parked: args.parked } : {}),
         ...(args.lastTurnText !== undefined ? { lastTurnText: args.lastTurnText } : {}),
         ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
         ...(deps.onError !== undefined ? { onError: deps.onError } : {}),
     });
+    args.refs.pull = (limit, toolCallId, charBudget) => drain.pull(limit, toolCallId, charBudget);
+    args.refs.boundaryRound = (o) => drain.boundaryRound(o);
+    args.refs.isBoxBacked = (payload) => drain.isBoxBacked(payload);
+    if (args.settlement !== undefined)
+        args.settlement.wantsEffects = () => drain.wantsCompactionEffects();
+    return drain;
 }