@sema-agent/core 7.3.1 → 7.4.0

package/dist/agents/peer-session-drain.d.ts

@@ -8,6 +8,8 @@ import { type PeerDirectory } from "./peer-directory.js";
 import { createListAgentsTool } from "./list-agents-tool.js";
 import type { AskEffective } from "../core/wiring-manifest.js";
 import type { SendMessageToolOptions } from "./send-message-tool.js";
+import { type PeerClock, type PeerHeldQueue } from "./peer-held-queue.js";
+import { type PeerIdleMachine } from "./peer-idle.js";
 /** design/385 §1.2④ — the drain lease TTL. Same sizing law as the tier-3 revive lease: well under the
  *  store's stale-row floor, long enough to cover one turn (a longer turn renews on the same owner at
  *  its next boundary; an expired lease re-serves the batch — at-least-once). */
@@ -34,6 +36,8 @@ export declare function judgePeerLaneMount(deps: {
     peerDirectory?: PeerDirectory;
     mailboxStore?: MailboxStore;
 }, sessionId?: string): PeerLaneMountVerdict | undefined;
+/** The disposition arms of a `peer.inbound_disposition` notice (closed set; `detail.disposition`). */
+export type PeerInboundDisposition = "refused" | "held" | "admission_refused" | "notice_unrouted" | "notice_user_only";
 export interface PeerSessionDrainOptions {
     mailbox: MailboxStore;
     /** This session (the box owner) and this leg's cycle id (the lease owner). */
@@ -53,6 +57,17 @@ export interface PeerSessionDrainOptions {
     settingLayers: () => CrossSessionInboundSettingLayers | undefined;
     /** The recipient's own permission-mode class, read at every drain (the manifest's ask fold). */
     selfModeClass: () => PermissionModeClass | "unknown";
+    /** This session's display name (its directory row's name), for receipts and idle notices it authors. */
+    selfName?: () => string | undefined;
+    /** Awaited ONCE before the first round (a directory lookup that fills `selfName`, say); a rejection is swallowed. */
+    warmup?: () => Promise<unknown>;
+    /** The deployment's `dialogExpiry` (raw; resolved at bind — an out-of-vocabulary value is announced
+     *  once through `onError` and the default applies). Absent ⇒ the default (5 m). */
+    dialogExpiry?: () => unknown;
+    /** The last turn's text, for the idle notice's one-line detail (CC `getLastTurnText`). */
+    lastTurnText?: () => string | undefined;
+    /** Whether the run is parked on a pending ask / review at its end (a parked run is `blocked`, not idle). */
+    parked?: () => boolean;
     onNotice?: (notice: EngineNotice) => void;
     onError?: (error: unknown, ctx: {
         phase: "degraded";
@@ -60,12 +75,22 @@ export interface PeerSessionDrainOptions {
         classification: string;
     }) => void;
     leaseTtlMs?: number;
+    /** Tests: a virtual clock for the held deadlines and idle timers (honored when this process first sees the session). */
+    clock?: PeerClock;
 }
 export interface PeerSessionDrain {
     /** One drain round (serialized: a boundary never overlaps a still-running round). */
     drain(): Promise<void>;
     /** Run end: ack the last batch and release the lease so the session's next cycle claims at once. */
     finish(): Promise<void>;
+    /** The run began working (cancels a pending idle fire). */
+    busy(): void;
+    /** The run ended with nothing queued and no pending ask: the one-shot idle fire is scheduled (§5.2). */
+    idle(finishedAt: number): void;
+    /** This session's held queue (process-level; the host review face reads/settles through it). */
+    readonly held: PeerHeldQueue;
+    /** This session's idle machine (process-level). */
+    readonly idleMachine: PeerIdleMachine;
 }
 export declare function createPeerSessionDrain(opts: PeerSessionDrainOptions): PeerSessionDrain;
 /** The lane's late-bound facts: the ask fold resolves after the manifest derivation, the mount runs
@@ -134,26 +159,36 @@ export interface PeerDrainHarness {
     on(type: "turn_boundary" | "before_agent_start", handler: () => Promise<undefined>): unknown;
     subscribe(listener: (event: {
         type: string;
+        nextTurnCount?: number;
+        undrainedSteerCount?: number;
+        undrainedFollowUpCount?: number;
     }) => void | Promise<void>): unknown;
 }
 /**
  * Bind the drain to a leg: the run's own injector at the `next` tier, run open (the loop's first
  * steering drain follows the `before_agent_start` hook) + every turn boundary, and the run-end
- * ack/release on `agent_end`.
+ * ack/release on `agent_end`. Slice 4: the harness's `settled` account (the frame after `agent_end`)
+ * is the idle judgment's seat — "finished its turn with nothing queued" = no next-turn frames, no
+ * undrained user inputs, and (through `opts.parked`) no pending ask/review; the held queue's own
+ * emptiness is the machine's to check.
  */
 export declare function bindPeerSessionDrain(harness: PeerDrainHarness, opts: PeerSessionDrainOptions): PeerSessionDrain;
 /**
  * The leg-side spelling of {@link bindPeerSessionDrain}: the deployment seats the drain reads
- * (`mailboxStore` / `peerAdmission` / `crossSessionInbound` / the two sinks) come straight off deps, the
- * recipient's mode class folds off the lane refs — one binding call per leg, no per-seat plumbing.
+ * (`mailboxStore` / `peerAdmission` / `crossSessionInbound` / `crossSessionDialogExpiry` / the two
+ * sinks) come straight off deps, the recipient's mode class folds off the lane refs — one binding call
+ * per leg, no per-seat plumbing.
  */
 export declare function bindPeerLaneDrain(harness: PeerDrainHarness, args: {
-    deps: Pick<RunnerDeps, "mailboxStore" | "peerAdmission" | "crossSessionInbound" | "onNotice" | "onError">;
+    deps: Pick<RunnerDeps, "mailboxStore" | "peerDirectory" | "peerAdmission" | "crossSessionInbound" | "crossSessionDialogExpiry" | "onNotice" | "onError">;
     sessionId: string;
     runId: string;
     scope: string;
     inject: PeerSessionDrainOptions["inject"];
     ownTokens: () => readonly string[];
     refs: PeerLaneRefs;
+    selfName?: () => string | undefined;
+    parked?: () => boolean;
+    lastTurnText?: () => string | undefined;
 }): PeerSessionDrain;
 export {};

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

@@ -7,6 +7,10 @@ import { isPeerSessionId, PEER_SESSION_ID_GRAMMAR, peerSessionBoxHandle } from "
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { createListAgentsTool, LIST_AGENTS_TOOL_ALIAS, LIST_AGENTS_TOOL_NAME } from "./list-agents-tool.js";
 import { foldPermissionModeClass } from "./cross-session-judge.js";
+import { peerHeldQueueFor } from "./peer-held-queue.js";
+import { peerIdleMachineFor } from "./peer-idle.js";
+import { describePeerIdleSubscription, isPeerDeliveryReceiptState, isPeerIdleNoticeKind, peerIdleNoticeLabel, renderCrossSessionDeliveryNotice, renderCrossSessionDroppedNotice, renderCrossSessionIdleNotice, resolveCrossSessionDialogExpiry } from "./peer-notices.js";
+import { routePeerDeliveryReceipt, routePeerDroppedReceipt, routePeerIdleNotice } from "./peer-notice-route.js";
 export const PEER_DRAIN_LEASE_TTL_MS = 5 * 60_000;
 export const PEER_SESSION_ID_UNGRAMMATICAL_CODE = "peer.session_id_ungrammatical";
 export function judgePeerLaneMount(deps, sessionId) {
@@ -30,17 +34,122 @@ export function judgePeerLaneMount(deps, sessionId) {
 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;
     let settledUpTo;
     const disclosedHeld = new Set();
     let inFlight = Promise.resolve();
-    const disclose = (disposition, cause, m, heldNote = "the held-message review face is not mounted in this build") => deliverEngineNotice(opts.onNotice, {
+    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 (it stays parked; ${heldNote})` : disposition === "refused" ? "refused by this session's crossSessionInbound setting" : disposition === "notice_unrouted" ? "settled WITHOUT delivery (a notice-kind record; the notice face is not mounted in this build)" : "refused by the inbound admission gate"}: ${cause}`,
+        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)"}`
+            : 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}`,
         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 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,
+        scope,
+        self: { sessionId, ...(opts.selfName?.() !== undefined ? { name: opts.selfName() } : {}), modeClass: opts.selfModeClass },
+        ...(opts.onError !== undefined ? { onError: opts.onError } : {}),
+    });
+    const buildPeerMessagePayload = (m) => {
+        const meta = m.peerMeta;
+        const fields = {
+            from: encodePeerAddress(storedSessionAddress(meta?.fromSession) ?? (m.from ?? "unknown")),
+            ...(meta?.fromSession !== undefined ? { fromSession: meta.fromSession } : {}),
+            ...(m.from !== undefined ? { fromName: m.from } : {}),
+            ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}),
+            ...(meta?.fromScope !== undefined ? { fromScope: meta.fromScope } : {}),
+        };
+        buildCrossSessionEnvelope(fields, m.content);
+        return {
+            task_id: boxHandle,
+            task_type: "background_agent",
+            status: "event",
+            summary: `cross-session message from ${m.from ?? fields.from}`,
+            result: m.content,
+            seq: m.seq,
+            peer: { hopChain: m.hopChain !== undefined ? [...m.hopChain] : [] },
+            crossSessionMessage: { ...fields, body: m.content },
+            _sema_provenance: { kind: "cross_session_message", from: fields.from, taskId: boxHandle, seq: m.seq, ...(meta !== undefined ? { peerMeta: { ...meta } } : {}) },
+        };
+    };
+    const buildNoticePayload = (m, kind, text) => ({
+        task_id: boxHandle,
+        task_type: "background_agent",
+        status: "event",
+        summary: kind === "delivery_notice" ? "cross-session delivery notice" : "cross-session idle notice",
+        result: text,
+        seq: m.seq,
+        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;
+        if (to === undefined)
+            return;
+        if (state === "dropped")
+            void routePeerDroppedReceipt(route(), to, entry.seq);
+        else
+            void routePeerDeliveryReceipt(route(), to, state, entry.seq);
+    };
+    const heldSink = (live) => ({
+        judge: (entry) => judgeMeta(readFacts(), entry.peerMeta),
+        ...(live ? { inject: (entry) => opts.inject(buildPeerMessagePayload(entry), { priority: "next" }) } : {}),
+        receipt,
+        onHeld: (entry, count, cause, reannounce) => {
+            if (!reannounce && disclosedHeld.has(entry.seq))
+                return;
+            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 },
+        }),
+    });
+    let dialogExpiryMs = resolveCrossSessionDialogExpiry(undefined).ms;
+    let dialogExpiryAnnounced = false;
+    const bindHeld = (live) => {
+        try {
+            const resolved = resolveCrossSessionDialogExpiry(opts.dialogExpiry?.());
+            dialogExpiryMs = resolved.ms;
+            if (resolved.invalid && !dialogExpiryAnnounced) {
+                dialogExpiryAnnounced = true;
+                opts.onError?.(new Error(`crossSessionDialogExpiry holds a value outside its vocabulary (60s|5m|10m|never); the default ${resolved.value} is in force for held cross-session messages`), { phase: "degraded", sessionId, classification: "peer-dialog-expiry" });
+            }
+        }
+        catch (e) {
+            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-dialog-expiry" });
+        }
+        held.configure({ sink: heldSink(live), dialogExpiryMs });
+    };
+    bindHeld(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(),
+        ...(opts.lastTurnText !== undefined ? { lastTurnText: opts.lastTurnText } : {}),
+    });
+    idleMachine.requester.configure({
+        expired: (o) => void routePeerIdleNotice(route(), sessionId, { kind: "expired", label: o.label }),
+    });
     const ackSettled = async () => {
         if (settledUpTo === undefined)
             return;
@@ -53,7 +162,76 @@ export function createPeerSessionDrain(opts) {
             opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-ack" });
         }
     };
+    const settleNoticeRecord = (facts, m, meta) => {
+        const notice = meta.notice;
+        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);
+            settledUpTo = m.seq;
+            return;
+        }
+        let text;
+        if (kind === "idle_notice") {
+            const idleKind = notice.state;
+            const from = meta.fromSession;
+            const selfAuthored = from !== undefined && from.toLowerCase() === sessionId.toLowerCase();
+            const settled = from !== undefined && !selfAuthored ? idleMachine.requester.settle(from, idleKind) : { cleared: 0 };
+            const label = (notice.target !== undefined ? peerIdleNoticeLabel(notice.target) : undefined) ?? settled.label ?? peerIdleNoticeLabel(m.from ?? storedSessionAddress(from) ?? "") ?? "(unnamed session)";
+            text = renderCrossSessionIdleNotice({ kind: idleKind, label, ...(notice.finishedAt !== undefined ? { finishedAt: notice.finishedAt } : {}), ...(notice.detail !== undefined ? { detail: peerIdleNoticeLabel(notice.detail) ?? "" } : {}) });
+        }
+        else {
+            const state = notice.state;
+            const recipients = [notice.recipient ?? m.from ?? ""];
+            text = state === "dropped" ? renderCrossSessionDroppedNotice(1, recipients, [notice.dropReason]) : renderCrossSessionDeliveryNotice(state, 1, recipients);
+        }
+        const judged = judgeMeta(facts, meta);
+        if (judged.verdict === "refuse") {
+            disclose("refused", `${judged.cause} (a ${kind})`, m);
+        }
+        else if (judged.verdict === "hold") {
+            disclose("notice_user_only", `${judged.cause}: ${text}`, m);
+        }
+        else {
+            opts.inject(buildNoticePayload(m, kind, text), { priority: "next" });
+        }
+        settledUpTo = m.seq;
+    };
+    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;
+            return;
+        }
+        const sub = { requester, ...(m.from !== undefined ? { requesterName: m.from } : {}), ...(meta.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: requester.toLowerCase() === sessionId.toLowerCase(), requestedAt: m.sentAt };
+        const announce = (outcome, live) => deliverEngineNotice(opts.onNotice, {
+            code: "peer.idle_subscription",
+            message: outcome === "recorded" || outcome === "refreshed" ? `${describePeerIdleSubscription(encodePeerAddress(peerSessionBoxHandle(requester)))} (${outcome}; ${live} live)` : `A peer session at ${encodePeerAddress(peerSessionBoxHandle(requester))} asked to be told when this session is next idle and was answered "unavailable": ${outcome === "full" ? "this session's subscription table is full" : `this session's crossSessionInbound setting is "refuse"`}.`,
+            detail: { outcome, fromSession: requester, live, seq: m.seq, box: boxHandle, sessionId, runId },
+        });
+        if (facts.setting.value === "refuse") {
+            void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
+            announce("refused", idleMachine.target.size());
+            settledUpTo = m.seq;
+            return;
+        }
+        const outcome = idleMachine.target.subscribe(sub);
+        if (outcome === "full")
+            void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
+        announce(outcome, idleMachine.target.size());
+        settledUpTo = m.seq;
+    };
+    let warmedUp = opts.warmup === undefined;
     const drainOnce = async () => {
+        if (!warmedUp) {
+            warmedUp = true;
+            try {
+                await opts.warmup();
+            }
+            catch {
+            }
+        }
         let lease;
         try {
             lease = await mailbox.claimLease(scope, boxHandle, drainOwner, ttl);
@@ -64,20 +242,21 @@ export function createPeerSessionDrain(opts) {
         }
         const previouslySettled = settledUpTo;
         await ackSettled();
-        if (lease === null)
-            return;
-        let setting;
+        let facts;
         let admissionConfig;
-        let selfModeClass;
         try {
-            setting = resolveCrossSessionInboundSetting(opts.settingLayers() ?? {});
-            admissionConfig = resolvePeerAdmissionConfig(opts.admission);
-            selfModeClass = opts.selfModeClass();
+            facts = readFacts();
+            admissionConfig = resolvePeerAdmissionConfig(opts.admission, opts.onNotice);
         }
         catch (e) {
             opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-settings" });
             return;
         }
+        bindHeld(true);
+        idleMachine.target.sweep();
+        held.rejudge();
+        if (lease === null)
+            return;
         for (const m of lease.messages) {
             if (previouslySettled !== undefined && m.seq <= previouslySettled)
                 continue;
@@ -88,7 +267,7 @@ export function createPeerSessionDrain(opts) {
                     if (verdict.reason === "rate_limited") {
                         if (!disclosedHeld.has(m.seq)) {
                             disclosedHeld.add(m.seq);
-                            disclose("held", verdict.reason, m, "the inbound admission bucket is empty; it is re-judged at a later boundary once the bucket refills");
+                            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;
                     }
@@ -97,53 +276,36 @@ export function createPeerSessionDrain(opts) {
                     continue;
                 }
             }
-            if (meta?.kind !== undefined && meta.kind !== "peer_message") {
-                disclose("notice_unrouted", `kind=${meta.kind}`, m);
-                settledUpTo = m.seq;
+            if (meta?.kind === "idle_subscription") {
+                settleSubscription(facts, m, meta);
+                continue;
+            }
+            if (meta?.kind === "idle_notice" || meta?.kind === "delivery_notice") {
+                settleNoticeRecord(facts, m, meta);
                 continue;
             }
             {
-                const judged = judgeCrossSessionInbound({ setting, selfModeClass, sender: { ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: meta?.fromSession !== undefined && meta.fromSession.toLowerCase() === sessionId.toLowerCase() } });
+                const judged = judgeMeta(facts, meta);
                 if (judged.verdict === "refuse") {
                     disclose("refused", judged.cause, m);
                     settledUpTo = m.seq;
                     continue;
                 }
                 if (judged.verdict === "hold") {
-                    if (!disclosedHeld.has(m.seq)) {
-                        disclosedHeld.add(m.seq);
-                        disclose("held", `${judged.cause}: ${judged.message}${judged.warning !== undefined ? ` (${judged.warning})` : ""}`, m);
-                    }
-                    break;
+                    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;
                 }
             }
-            let fields;
+            let payload;
             try {
-                fields = {
-                    from: encodePeerAddress(meta?.fromSession !== undefined ? peerSessionBoxHandle(meta.fromSession) : (m.from ?? "unknown")),
-                    ...(meta?.fromSession !== undefined ? { fromSession: meta.fromSession } : {}),
-                    ...(m.from !== undefined ? { fromName: m.from } : {}),
-                    ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}),
-                    ...(meta?.fromScope !== undefined ? { fromScope: meta.fromScope } : {}),
-                };
-                buildCrossSessionEnvelope(fields, m.content);
+                payload = buildPeerMessagePayload(m);
             }
             catch (e) {
                 disclose("refused", `record fields cannot be rendered canonically (${e instanceof CrossSessionCodecError ? e.code : e instanceof Error ? e.message : String(e)})`, m);
                 settledUpTo = m.seq;
                 continue;
             }
-            const payload = {
-                task_id: boxHandle,
-                task_type: "background_agent",
-                status: "event",
-                summary: `cross-session message from ${m.from ?? fields.from}`,
-                result: m.content,
-                seq: m.seq,
-                peer: { hopChain: m.hopChain !== undefined ? [...m.hopChain] : [] },
-                crossSessionMessage: { ...fields, body: m.content },
-                _sema_provenance: { kind: "cross_session_message", from: fields.from, taskId: boxHandle, seq: m.seq, ...(meta !== undefined ? { peerMeta: { ...meta } } : {}) },
-            };
             try {
                 opts.inject(payload, { priority: "next" });
             }
@@ -160,6 +322,7 @@ export function createPeerSessionDrain(opts) {
     };
     const finishOnce = async () => {
         await ackSettled();
+        held.detachLeg();
         try {
             await mailbox.releaseLease(scope, boxHandle, drainOwner);
         }
@@ -170,7 +333,14 @@ export function createPeerSessionDrain(opts) {
         inFlight = inFlight.then(finishOnce, finishOnce);
         return inFlight;
     };
-    return { drain, finish };
+    return {
+        drain,
+        finish,
+        busy: () => idleMachine.target.busy(),
+        idle: (finishedAt) => idleMachine.target.idle(finishedAt),
+        held,
+        idleMachine,
+    };
 }
 export function announcePeerLaneMount(deps, leg) {
     const verdict = judgePeerLaneMount(deps, leg.sessionId);
@@ -222,13 +392,44 @@ export function bindPeerSessionDrain(harness, opts) {
         await drain.drain();
         return undefined;
     };
-    harness.on("before_agent_start", round);
+    harness.on("before_agent_start", async () => {
+        drain.busy();
+        return round();
+    });
     harness.on("turn_boundary", round);
-    harness.subscribe((event) => (event.type === "agent_end" ? drain.finish().catch(() => undefined) : undefined));
+    harness.subscribe((event) => {
+        if (event.type === "agent_end")
+            return drain.finish().catch(() => undefined);
+        if (event.type === "settled") {
+            const nothingQueued = (event.nextTurnCount ?? 0) === 0 && event.undrainedSteerCount === undefined && event.undrainedFollowUpCount === undefined;
+            let parked = false;
+            try {
+                parked = opts.parked?.() ?? false;
+            }
+            catch {
+                parked = true;
+            }
+            if (nothingQueued && !parked)
+                drain.idle(Date.now());
+        }
+        return undefined;
+    });
     return drain;
 }
 export function bindPeerLaneDrain(harness, args) {
     const { deps } = args;
+    let rowName;
+    const lookupRowName = async () => {
+        if (deps.peerDirectory === undefined)
+            return;
+        try {
+            const rows = await deps.peerDirectory.listPeerSessions({ scope: args.scope });
+            rowName = rows.find((r) => r.sessionId.toLowerCase() === args.sessionId.toLowerCase())?.name;
+        }
+        catch {
+            rowName = undefined;
+        }
+    };
     return bindPeerSessionDrain(harness, {
         mailbox: deps.mailboxStore,
         sessionId: args.sessionId,
@@ -239,6 +440,11 @@ export function bindPeerLaneDrain(harness, args) {
         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.parked !== undefined ? { parked: args.parked } : {}),
+        ...(args.lastTurnText !== undefined ? { lastTurnText: args.lastTurnText } : {}),
         ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
         ...(deps.onError !== undefined ? { onError: deps.onError } : {}),
     });

package/dist/agents/send-message-tool.d.ts

@@ -137,10 +137,17 @@ export interface SendMessageToolOptions {
      */
     enrichCtx?: ToolCtxEnricher;
     /** design/176 — caller tuning for the always-on peer-message admission gate (per-field
-     *  range-validated; out-of-range values fall back to that field's default; there is no off
+     *  range-validated; a value outside its range — or one that is not a finite number — falls back to
+     *  that field's default and is ANNOUNCED once per process through {@link onNotice}; there is no off
      *  switch). The Runner mount threads {@link import("../core/types.js").RunnerDeps.peerAdmission}
      *  here. Read per call — a changed value governs the next message. */
     admission?: Partial<PeerAdmissionConfig>;
+    /** #551 — the deployment's structured notice sink, used by this face for ONE fact: a
+     *  {@link admission} field the resolver could not use falls back to its default and announces
+     *  `config.peer_admission_out_of_range` through here. The Runner mount threads
+     *  {@link import("../core/types.js").RunnerDeps.onNotice}; a direct mount that leaves it absent
+     *  still gets the line on `console.warn` (the shared delivery throat's unwired arm). */
+    onNotice?: (notice: import("../core/types.js").EngineNotice) => void;
     /** design/176 — the SENDING run's peer-identity carrier (trusted internals chain; ctx twin
      *  {@link import("../core/types.js").ToolExecuteContext.peerSelfRef} wins when present). Supplies
      *  the sender's bucket key and the hop token appended to every outbound chain. A direct mount