@sema-agent/core 7.52.0 → 7.54.0

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

@@ -1,9 +1,11 @@
 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 { PRINCIPAL_INBOX_HANDLE } from "./cross-session-ref.js";
+import { isGateMintedRecord, principalInboxConsumerOf } from "./org-delivery-gate.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 { judgeCrossSessionInbound, principalInboundLayers, resolveCrossSessionInboundSetting } from "./cross-session-judge.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";
@@ -16,6 +18,10 @@ import { routePeerDeliveryReceipt, routePeerDroppedReceipt, routePeerIdleNotice
 import { thrownText } from "../core/thrown-value.js";
 export const PEER_DRAIN_LEASE_TTL_MS = 5 * 60_000;
 export const PEER_SESSION_ID_UNGRAMMATICAL_CODE = "peer.session_id_ungrammatical";
+export const PRINCIPAL_INBOX_UNMINTED_CAUSE = "not_minted_by_delivery_gate";
+export function terminalsDrainPrincipalInbox(deps) {
+    return principalInboxConsumerOf(deps).kind === "terminals";
+}
 export function judgePeerLaneMount(deps, sessionId) {
     if (deps.peerDirectory === undefined)
         return undefined;
@@ -52,26 +58,37 @@ export function judgeSessionBoxDrain(deps, leg) {
 export const PEER_RESUPPLY_CAP = 1;
 export function createPeerSessionDrain(opts) {
     const { mailbox, sessionId, runId, scope } = opts;
-    const boxHandle = peerSessionBoxHandle(sessionId);
     const storedSessionAddress = (fromSession) => fromSession !== undefined && isPeerSessionId(fromSession) ? peerSessionBoxHandle(fromSession) : undefined;
     const drainOwner = `drain:${runId}`;
     const recipientKey = peerAxisToken(scope, "s", sessionId);
     const ttl = opts.leaseTtlMs ?? PEER_DRAIN_LEASE_TTL_MS;
     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 clockOpt = opts.clock !== undefined ? { clock: opts.clock } : {};
+    const mintLane = (kind) => {
+        const boxHandle = kind === "session" ? peerSessionBoxHandle(sessionId) : PRINCIPAL_INBOX_HANDLE;
+        return {
+            kind,
+            boxHandle,
+            label: kind === "session" ? "this session's box" : "this principal's inbox",
+            ledger: new Map(),
+            ackedUpTo: undefined,
+            disclosedHeld: new Set(),
+            held: peerHeldQueueFor(scope, sessionId, kind === "session" ? clockOpt : { ...clockOpt, box: boxHandle }),
+        };
+    };
+    const lanes = opts.principalInbox === true ? [mintLane("session"), mintLane("principal")] : [mintLane("session")];
+    const sessionLane = lanes[0];
+    const boxHandle = sessionLane.boxHandle;
     const seam = opts.settlement ?? createFrameSettlement();
-    const disclosedHeld = new Set();
     let inFlight = Promise.resolve();
     let noticeRound = 0;
     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, {
+    const idleMachine = peerIdleMachineFor(scope, sessionId, clockOpt);
+    const disclose = (lane, 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 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)"}`
+        message: `cross-session message seq ${m.seq} in ${lane.label} was ${disposition === "held"
+            ? `HELD${heldNote !== undefined ? ` (${heldNote})` : lane.kind === "session" ? " (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)" : " (it entered this session's held queue for the principal inbox and STAYS IN THE BOX until it settles; it is re-judged at every boundary. The sender is another principal: no receipt reaches it from here \u2014 the delivery gate's receipt is its record)"}`
             : disposition === "refused"
                 ? "refused by this session's crossSessionInbound setting"
                 : disposition === "resupply_exhausted"
@@ -81,20 +98,23 @@ export function createPeerSessionDrain(opts) {
                         : 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 },
+        detail: { disposition, cause, seq: m.seq, box: lane.boxHandle, ...(m.peerMeta?.fromSession !== undefined ? { fromSession: m.peerMeta.fromSession } : {}), sessionId, runId },
     });
     const readFacts = () => {
-        const setting = resolveCrossSessionInboundSetting(opts.settingLayers() ?? {});
-        return { setting, selfModeClass: opts.selfModeClass() };
+        const layers = opts.settingLayers() ?? {};
+        return { setting: resolveCrossSessionInboundSetting(layers), principalSetting: resolveCrossSessionInboundSetting(principalInboundLayers(layers)), 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 judgeMeta = (facts, meta) => meta?.fromScope !== undefined
+        ? judgeCrossSessionInbound({ setting: facts.principalSetting, selfModeClass: facts.selfModeClass, sender: { fromScope: meta.fromScope } })
+        : 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,
         scope,
         self: { sessionId, ...(opts.selfName?.() !== undefined ? { name: opts.selfName() } : {}), modeClass: opts.selfModeClass },
         ...(opts.onError !== undefined ? { onError: opts.onError } : {}),
     });
-    const buildPeerMessagePayload = (m) => {
+    const buildPeerMessagePayload = (lane, m) => {
+        const { boxHandle } = lane;
         const meta = m.peerMeta;
         const fields = {
             from: encodePeerAddress(storedSessionAddress(meta?.fromSession) ?? (m.from ?? "unknown")),
@@ -126,8 +146,9 @@ export function createPeerSessionDrain(opts) {
         crossSessionNotice: { kind, text },
         _sema_provenance: { kind: "cross_session_notice", from: encodePeerAddress(storedSessionAddress(m.peerMeta?.fromSession) ?? (m.from ?? "unknown")), taskId: boxHandle, seq: m.seq, ...(m.peerMeta !== undefined ? { peerMeta: { ...m.peerMeta } } : {}) },
     });
-    const receipt = (entry, state) => {
-        const to = entry.peerMeta?.fromSession;
+    const receiptAddress = (lane, entry) => (lane.kind === "session" ? entry.peerMeta?.fromSession : undefined);
+    const receipt = (lane) => (entry, state) => {
+        const to = receiptAddress(lane, entry);
         if (to === undefined)
             return;
         if (state === "dropped")
@@ -135,41 +156,42 @@ export function createPeerSessionDrain(opts) {
         else
             void routePeerDeliveryReceipt(route(), to, state, entry.seq);
     };
-    const heldSink = (live) => ({
+    const heldSink = (lane, live) => ({
         judge: (entry) => judgeMeta(readFacts(), entry.peerMeta),
         ...(live
             ? {
                 inject: (entry) => {
                     if (currentRound === undefined)
                         return "deferred";
-                    const payload = buildPeerMessagePayload(entry);
+                    const payload = buildPeerMessagePayload(lane, entry);
                     if (currentRound.deliver(payload, "next") === "deferred")
                         return "deferred";
-                    noteDelivered(entry.seq, 1, payload, currentRound.carrier);
+                    noteDelivered(lane, entry.seq, 1, payload, currentRound.carrier);
                     return undefined;
                 },
             }
             : {}),
-        receipt,
+        receipt: receipt(lane),
         onHeld: (entry, count, cause, reannounce) => {
-            if (!reannounce && disclosedHeld.has(entry.seq))
+            if (!reannounce && lane.disclosedHeld.has(entry.seq))
                 return;
-            disclosedHeld.add(entry.seq);
-            disclose("held", cause, entry, reannounce ? `still held; its cause moved to ${cause} (${count} held)` : undefined);
+            lane.disclosedHeld.add(entry.seq);
+            disclose(lane, "held", cause, entry, reannounce ? `still held; its cause moved to ${cause} (${count} held)` : undefined);
         },
         onSettled: (entry, settlement, reason, count) => {
-            if (entry.box === boxHandle && settlement !== "delivered")
-                ledger.set(entry.seq, { kind: "terminal", why: `held_${settlement}` });
+            if (entry.box === lane.boxHandle && settlement !== "delivered")
+                lane.ledger.set(entry.seq, { kind: "terminal", why: `held_${settlement}` });
+            const replyTo = receiptAddress(lane, entry);
             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 },
+                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 ${replyTo !== undefined ? "was sent a receipt" : "has no reply address and was not told"}.`,
+                detail: { settlement, reason, seq: entry.seq, box: lane.boxHandle, ...(entry.peerMeta?.fromSession !== undefined ? { fromSession: entry.peerMeta.fromSession } : {}), heldCount: count, sessionId, runId },
             });
         },
     });
     let dialogExpiryMs = resolveCrossSessionDialogExpiry(undefined).ms;
     let dialogExpiryAnnounced = false;
-    const bindHeld = (live) => {
+    const bindHeld = (lane, live) => {
         try {
             const resolved = resolveCrossSessionDialogExpiry(opts.dialogExpiry?.());
             dialogExpiryMs = resolved.ms;
@@ -181,67 +203,84 @@ export function createPeerSessionDrain(opts) {
         catch (e) {
             opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-dialog-expiry" });
         }
-        held.configure({ sink: heldSink(live), dialogExpiryMs });
+        lane.held.configure({ sink: heldSink(lane, live), dialogExpiryMs });
     };
-    bindHeld(true);
+    for (const lane of lanes)
+        bindHeld(lane, true);
     idleMachine.target.configure({
         notify: (sub, notice) => void routePeerIdleNotice(route(), sub.requester, notice),
         judge: (sub) => judgeMeta(readFacts(), { ...(sub.fromMode !== undefined ? { fromMode: sub.fromMode } : {}), ...(sub.selfSent ? { fromSession: sessionId } : {}) }),
-        heldCount: () => held.size(),
+        heldCount: () => lanes.reduce((n, lane) => n + lane.held.size(), 0),
         ...(opts.lastTurnText !== undefined ? { lastTurnText: opts.lastTurnText } : {}),
     });
     idleMachine.requester.configure({
         expired: (o) => void routePeerIdleNotice(route(), sessionId, { kind: "expired", label: o.label }),
     });
-    const adoptHeldDecisions = () => {
-        const decided = held.decisions();
+    const adoptHeldDecisions = (lane) => {
+        const decided = lane.held.decisions();
         if (decided.size === 0)
             return;
         for (const [seq, settlement] of decided) {
-            if (ackedUpTo !== undefined && seq <= ackedUpTo)
+            if (lane.ackedUpTo !== undefined && seq <= lane.ackedUpTo)
                 continue;
-            const mine = ledger.get(seq);
+            const mine = lane.ledger.get(seq);
             if (mine !== undefined && mine.kind !== "held")
                 continue;
-            ledger.set(seq, { kind: "terminal", why: `held_${settlement}` });
+            lane.ledger.set(seq, { kind: "terminal", why: `held_${settlement}` });
         }
     };
-    const reconcileHeld = (lease) => {
-        held.reconcile(new Set(lease.messages.map((m) => m.seq)));
+    const reconcileHeld = (lane, lease) => {
+        lane.held.reconcile(new Set(lease.messages.map((m) => m.seq)));
         let queued;
-        for (const [seq, d] of ledger) {
+        for (const [seq, d] of lane.ledger) {
             if (d.kind !== "held")
                 continue;
-            queued ??= new Set(held.list().filter((e) => e.box === boxHandle).map((e) => e.seq));
+            queued ??= new Set(lane.held.list().filter((e) => e.box === lane.boxHandle).map((e) => e.seq));
             if (!queued.has(seq))
-                ledger.delete(seq);
+                lane.ledger.delete(seq);
         }
     };
     const wantsCompactionEffects = () => {
-        for (const d of ledger.values())
-            if (d.kind === "delivered" || d.kind === "committed")
-                return true;
+        for (const lane of lanes)
+            for (const d of lane.ledger.values())
+                if (d.kind === "delivered" || d.kind === "committed")
+                    return true;
         return false;
     };
-    const noteDelivered = (seq, attempt, payload, carrier) => {
+    const noteDelivered = (lane, seq, attempt, payload, carrier) => {
         const own = taskNotificationDedupKey(payload);
         const key = carrier === undefined ? own : `${carrier}|${own}`;
-        ledger.set(seq, { kind: "delivered", attempt, key, payload });
+        lane.ledger.set(seq, { kind: "delivered", attempt, key, payload });
+        currentRound?.tally(lane, attempt);
+        if (carrier === undefined && payload._sema_provenance?.peerMeta?.fromScope !== undefined) {
+            try {
+                opts.markExternalContent?.(`a letter from another principal (cross-principal message seq ${seq} in ${lane.boxHandle}) was delivered into this session`);
+            }
+            catch (e) {
+                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-external-mark" });
+            }
+        }
         seam.awaiting.set(key, carrier === undefined ? { carrier: own } : { carrier, frameText: renderTaskNotificationXml(payload) });
     };
-    const deriveAckPrefix = (messages) => {
+    const deriveAckPrefix = (lane, messages) => {
         let prefix;
         for (const m of messages) {
-            if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
+            if (lane.ackedUpTo !== undefined && m.seq <= lane.ackedUpTo)
                 continue;
-            if (!isTerminalDisposition(ledger.get(m.seq)))
+            if (!isTerminalDisposition(lane.ledger.get(m.seq)))
                 break;
             prefix = m.seq;
         }
         return prefix;
     };
     const settleLocally = () => {
-        adoptHeldDecisions();
+        const landed = seam.compactions.splice(0);
+        for (const lane of lanes)
+            settleLaneLocally(lane, landed);
+    };
+    const settleLaneLocally = (lane, landed) => {
+        const { ledger, boxHandle } = lane;
+        adoptHeldDecisions(lane);
         const hostWithheldSeqs = [];
         if (seam.receipts.size > 0 || seam.withheld.size > 0 || seam.hostWithheld.size > 0) {
             for (const [seq, d] of ledger) {
@@ -269,7 +308,7 @@ export function createPeerSessionDrain(opts) {
         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 effect of landed) {
             for (const [seq, d] of ledger) {
                 if (d.kind !== "committed")
                     continue;
@@ -281,23 +320,24 @@ export function createPeerSessionDrain(opts) {
         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 } : {}) });
+                disclose(lane, "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 ackSettledPrefix = async (lane, lease) => {
+        const { held, ledger, boxHandle } = lane;
         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)) {
+        const prefix = deriveAckPrefix(lane, lease.messages);
+        if (prefix !== undefined && (lane.ackedUpTo === undefined || prefix > lane.ackedUpTo)) {
             try {
                 const result = await mailbox.ack(scope, boxHandle, drainOwner, prefix);
                 if (result.acked) {
-                    ackedUpTo = prefix;
+                    lane.ackedUpTo = prefix;
                     const gone = [];
                     for (const seq of [...ledger.keys()]) {
                         if (seq > prefix)
@@ -308,7 +348,7 @@ export function createPeerSessionDrain(opts) {
                     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" });
+                    opts.onError?.(new Error(`the ${lane.kind === "session" ? "session box" : "principal inbox"} ${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) {
@@ -321,8 +361,8 @@ export function createPeerSessionDrain(opts) {
         const kind = meta.kind;
         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);
-            currentRound.dispose(m.seq, `notice_unrouted:${kind}`);
+            disclose(sessionLane, "notice_unrouted", `kind=${kind}${notice === undefined ? " without a typed notice" : ` with state=${inlineUntrusted(notice.state, 32)}`}`, m);
+            currentRound.dispose(sessionLane, m.seq, `notice_unrouted:${kind}`);
             return;
         }
         let text;
@@ -341,22 +381,22 @@ export function createPeerSessionDrain(opts) {
         }
         const judged = judgeMeta(facts, meta);
         if (judged.verdict === "refuse") {
-            disclose("refused", `${judged.cause} (a ${kind})`, m);
+            disclose(sessionLane, "refused", `${judged.cause} (a ${kind})`, m);
         }
         else if (judged.verdict === "hold") {
-            disclose("notice_user_only", `${judged.cause}: ${text}`, m);
+            disclose(sessionLane, "notice_user_only", `${judged.cause}: ${text}`, m);
         }
         else {
-            currentRound.batch.push({ payload: buildNoticePayload(m, kind, text), priority: "next", urgent: false, seq: m.seq, attempt: 1 });
+            currentRound.batch.push({ lane: sessionLane, payload: buildNoticePayload(m, kind, text), priority: "next", urgent: false, seq: m.seq, attempt: 1 });
             return;
         }
-        currentRound.dispose(m.seq, judged.verdict === "refuse" ? "refused" : "notice_user_only");
+        currentRound.dispose(sessionLane, 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);
-            currentRound.dispose(m.seq, "subscription_unaddressed");
+            disclose(sessionLane, "notice_unrouted", "kind=idle_subscription without a reply address (fromSession)", m);
+            currentRound.dispose(sessionLane, 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 };
@@ -368,22 +408,22 @@ export function createPeerSessionDrain(opts) {
         if (facts.setting.value === "refuse") {
             void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
             announce("refused", idleMachine.target.size());
-            currentRound.dispose(m.seq, "subscription_refused");
+            currentRound.dispose(sessionLane, 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());
-        currentRound.dispose(m.seq, `subscription_${outcome}`);
+        currentRound.dispose(sessionLane, m.seq, `subscription_${outcome}`);
     };
-    const countWaiting = (lease) => {
+    const countWaiting = (lane, lease) => {
         if (lease === null)
             return { pending: 0, urgent: 0 };
         const waiting = lease.messages.filter((m) => {
-            if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
+            if (lane.ackedUpTo !== undefined && m.seq <= lane.ackedUpTo)
                 return false;
-            const d = ledger.get(m.seq);
+            const d = lane.ledger.get(m.seq);
             return d === undefined || d.kind === "invalidated";
         });
         return { pending: waiting.length, urgent: waiting.filter((m) => m.peerMeta?.urgent === true).length };
@@ -395,9 +435,20 @@ export function createPeerSessionDrain(opts) {
         carrier;
         charBudget;
         injected = 0;
-        resupplied = 0;
-        dispose(seq, why) {
-            ledger.set(seq, { kind: "terminal", why });
+        tallies = new Map();
+        tally(lane, attempt) {
+            const t = this.tallies.get(lane) ?? { fresh: 0, resupplied: 0 };
+            if (attempt > 1)
+                t.resupplied += 1;
+            else
+                t.fresh += 1;
+            this.tallies.set(lane, t);
+        }
+        deliveredIn(lane) {
+            return this.tallies.get(lane) ?? { fresh: 0, resupplied: 0 };
+        }
+        dispose(lane, seq, why) {
+            lane.ledger.set(seq, { kind: "terminal", why });
         }
         batch = [];
         chars = 0;
@@ -437,20 +488,29 @@ export function createPeerSessionDrain(opts) {
             catch {
             }
         }
-        let lease;
-        try {
-            lease = await mailbox.claimLease(scope, boxHandle, drainOwner, ttl);
+        const claims = [];
+        for (const lane of lanes) {
+            try {
+                claims.push({ lane, lease: await mailbox.claimLease(scope, lane.boxHandle, drainOwner, ttl) });
+            }
+            catch (e) {
+                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
+            }
         }
-        catch (e) {
-            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
+        if (claims.length === 0)
             return { pending: 0, urgent: 0 };
-        }
+        const waitingAcross = () => claims.reduce((sum, { lane, lease }) => {
+            const c = countWaiting(lane, lease);
+            return { pending: sum.pending + c.pending, urgent: sum.urgent + c.urgent };
+        }, { pending: 0, urgent: 0 });
         if (pass.settle)
             settleLocally();
-        if (pass.settle && lease !== null)
-            await ackSettledPrefix(lease);
+        if (pass.settle)
+            for (const { lane, lease } of claims)
+                if (lease !== null)
+                    await ackSettledPrefix(lane, lease);
         if (!pass.deliver)
-            return countWaiting(lease);
+            return waitingAcross();
         let facts;
         let admissionConfig;
         try {
@@ -464,92 +524,104 @@ export function createPeerSessionDrain(opts) {
         currentRound = round;
         try {
             idleMachine.target.sweep();
-            if (lease === null)
+            const leased = claims.filter((c) => c.lease !== null);
+            if (leased.length === 0)
                 return { pending: 0, urgent: 0 };
-            bindHeld(true);
-            reconcileHeld(lease);
-            held.rejudge();
+            for (const { lane, lease } of leased) {
+                bindHeld(lane, true);
+                reconcileHeld(lane, lease);
+                lane.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}`);
+                for (const { lane, lease } of leased) {
+                    const { ledger, disclosedHeld, held, boxHandle } = lane;
+                    const ackedUpTo = lane.ackedUpTo;
+                    for (const m of lease.messages) {
+                        const prior = ledger.get(m.seq);
+                        if (prior === undefined || prior.kind !== "invalidated")
                             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 (round.spent)
+                            break;
+                        const attempt = prior.attempt + 1;
+                        round.batch.push({ lane, payload: { ...prior.payload, attempt, resupplied: true }, priority: "next", urgent: false, seq: m.seq, attempt });
                     }
-                    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" });
+                    adoptHeldDecisions(lane);
+                    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 (lane.kind === "principal" && !isGateMintedRecord(meta)) {
+                            disclose(lane, "admission_refused", PRINCIPAL_INBOX_UNMINTED_CAUSE, m);
+                            round.dispose(lane, m.seq, `admission_refused:${PRINCIPAL_INBOX_UNMINTED_CAUSE}`);
+                            continue;
                         }
-                        if (!decoded.ok) {
-                            disclose("notice_unrouted", `kind=engine_frame (${decoded.detail})`, m);
-                            round.dispose(m.seq, `engine_frame_malformed:${decoded.detail}`);
+                        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(lane, "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(lane, "admission_refused", verdict.reason, m);
+                                round.dispose(lane, m.seq, `admission_refused:${verdict.reason}`);
+                                continue;
+                            }
+                        }
+                        if (meta?.kind === "idle_subscription") {
+                            settleSubscription(facts, m, meta);
                             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}`);
+                        if (meta?.kind === "idle_notice" || meta?.kind === "delivery_notice") {
+                            settleNoticeRecord(facts, m, meta);
                             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" });
+                        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(lane, "notice_unrouted", `kind=engine_frame (${decoded.detail})`, m);
+                                round.dispose(lane, m.seq, `engine_frame_malformed:${decoded.detail}`);
+                                continue;
+                            }
+                            round.batch.push({ lane, 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(lane, "refused", judged.cause, m);
+                                round.dispose(lane, 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(lane, m);
+                        }
+                        catch (e) {
+                            disclose(lane, "refused", `record fields cannot be rendered canonically (${e instanceof CrossSessionCodecError ? e.code : thrownText(e)})`, m);
+                            round.dispose(lane, m.seq, "uncanonical_fields");
+                            continue;
+                        }
+                        round.batch.push({ lane, payload, priority: "next", urgent: meta?.urgent === true, seq: m.seq, attempt: 1 });
                     }
-                    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 });
                 }
             }
             finally {
@@ -563,13 +635,15 @@ export function createPeerSessionDrain(opts) {
                         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;
+                    noteDelivered(item.lane, item.seq, item.attempt, item.payload, round.carrier);
                 }
             }
-            const counts = countWaiting(lease);
-            if (counts.pending > 0 && round.out === undefined) {
+            for (const { lane, lease } of leased) {
+                const counts = countWaiting(lane, lease);
+                if (counts.pending === 0 || round.out !== undefined)
+                    continue;
+                const { boxHandle } = lane;
+                const delivered = round.deliveredIn(lane);
                 noticeRound += 1;
                 try {
                     opts.inject({
@@ -578,7 +652,7 @@ export function createPeerSessionDrain(opts) {
                         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 },
+                        inboxNotice: { pending: counts.pending, delivered: delivered.fresh, ...(delivered.resupplied > 0 ? { resupplied: delivered.resupplied } : {}), ...(counts.urgent > 0 ? { urgent: counts.urgent } : {}), box: boxHandle },
                         _sema_provenance: { kind: "inbox_notice", from: boxHandle, taskId: `inbox:${boxHandle}`, seq: noticeRound },
                     }, { priority: "next" });
                 }
@@ -586,7 +660,7 @@ export function createPeerSessionDrain(opts) {
                     opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
                 }
             }
-            return counts;
+            return waitingAcross();
         }
         finally {
             currentRound = undefined;
@@ -613,20 +687,33 @@ export function createPeerSessionDrain(opts) {
         return settled.then(() => ({ delivered: out, pending: counts.pending, urgent: counts.urgent }));
     };
     const finishOnce = async () => {
-        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" });
+        const claimed = [];
+        for (const lane of lanes) {
+            try {
+                claimed.push({ lane, lease: await mailbox.claimLease(scope, lane.boxHandle, drainOwner, ttl) });
+            }
+            catch (e) {
+                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
+            }
         }
-        held.detachLeg();
-        try {
-            await mailbox.releaseLease(scope, boxHandle, drainOwner);
+        if (claimed.length > 0) {
+            try {
+                settleLocally();
+                for (const { lane, lease } of claimed)
+                    if (lease !== null)
+                        await ackSettledPrefix(lane, lease);
+            }
+            catch (e) {
+                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
+            }
         }
-        catch {
+        for (const lane of lanes) {
+            lane.held.detachLeg();
+            try {
+                await mailbox.releaseLease(scope, lane.boxHandle, drainOwner);
+            }
+            catch {
+            }
         }
     };
     const finish = () => {
@@ -642,16 +729,18 @@ export function createPeerSessionDrain(opts) {
             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;
+            for (const lane of lanes)
+                for (const d of lane.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,
+        held: sessionLane.held,
+        ...(lanes[1] !== undefined ? { principalHeld: lanes[1].held } : {}),
         idleMachine,
     };
 }
@@ -684,7 +773,7 @@ export function peerLaneSendMessageSeats(args) {
     };
 }
 export function listAgentsMountable(face) {
-    return face.selector.admits({ name: LIST_AGENTS_TOOL_NAME, aliases: [LIST_AGENTS_TOOL_ALIAS] }) && listAgentsNameFree(face.specTools);
+    return face.leaves({ name: LIST_AGENTS_TOOL_NAME, aliases: [LIST_AGENTS_TOOL_ALIAS] }) && listAgentsNameFree(face.specTools);
 }
 function listAgentsNameFree(specTools) {
     return !specTools.some((t) => t.name === LIST_AGENTS_TOOL_NAME || t.name === LIST_AGENTS_TOOL_ALIAS || t.aliases?.includes(LIST_AGENTS_TOOL_NAME) || t.aliases?.includes(LIST_AGENTS_TOOL_ALIAS));
@@ -692,8 +781,6 @@ function listAgentsNameFree(specTools) {
 export function mountListAgents(args) {
     if (!listAgentsNameFree(args.specTools))
         return undefined;
-    args.toolEffects.set(LIST_AGENTS_TOOL_NAME, "read");
-    args.toolEffects.set(LIST_AGENTS_TOOL_ALIAS, "read");
     return createListAgentsTool({
         ...(args.peerDirectory !== undefined ? { peerDirectory: args.peerDirectory } : {}),
         ...(args.freshWindowMs !== undefined ? { freshWindowMs: args.freshWindowMs } : {}),
@@ -754,6 +841,7 @@ export function bindPeerLaneDrain(harness, args) {
         sessionId: args.sessionId,
         runId: args.runId,
         scope: args.scope,
+        ...(terminalsDrainPrincipalInbox(deps) ? { principalInbox: true } : {}),
         inject: args.inject,
         ...(deps.peerLane !== undefined ? { lane: deps.peerLane } : {}),
         ownTokens: args.ownTokens,
@@ -765,6 +853,7 @@ export function bindPeerLaneDrain(harness, args) {
         ...(args.settlement !== undefined ? { settlement: args.settlement } : {}),
         ...(args.parked !== undefined ? { parked: args.parked } : {}),
         ...(args.lastTurnText !== undefined ? { lastTurnText: args.lastTurnText } : {}),
+        ...(args.markExternalContent !== undefined ? { markExternalContent: args.markExternalContent } : {}),
         ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
         ...(deps.onError !== undefined ? { onError: deps.onError } : {}),
     });