@north-light/crouter 0.3.311 → 0.3.313

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -1,22 +1,10 @@
-// canvas-inbox-watcher.ts — in-process delivery of a canvas node's active inbox.
-//
-// The watcher polls the append-only inbox in physical order, coalesces each quiet
-// burst, and hands hidden context cards and visible deliveries to pi. A
-// burst mixing a person's words with node reports splits into several visible
-// deliveries, one per cycle. A send return is only a handoff. Exact cursor persistence at agent_settled is the
-// durable boundary; an uncommitted process exit is recovered by rereading from
-// the unchanged cursor.
-//
-// Context sends never trigger a turn: the visible human delivery is the sole
-// trigger, so the agent cannot run on context alone before hearing the person.
-// A context-only batch keeps its wake by triggering on its LAST card while idle,
-// and rides the running turn while streaming. A deferred-only idle batch stays
-// held until either durable mail wakes a turn or the broker prepends it to an
-// already-admitted live human prompt; that bridge still commits only at
-// agent_settled.
+// Wake mail is claimed through the daemon and acknowledged by delivery identity
+// only after Pi settles. Deferred mail rides a natural input; a refused turn
+// releases its claims instead of acknowledging content the model never consumed.
 import { envNodeId, envProfileId, envWatcherDebounceMs, envWatcherTickMs } from '../shared/env.js';
-import { coalesceBrokerInbox, entryCards, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
-import { advanceBrokerInboxCursor, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { coalesceBrokerInbox, entryCards, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
+import { acknowledgeBrokerMail, claimBrokerMail, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { wasTurnRefused } from '../core/runtime/broker/extension-abort.js';
 import { announceMessageOrigin } from '../core/runtime/stamp/channel.js';
 import { captureGoalIfAbsent, generateAndCommitInitialName } from './broker-local.js';
 import { emitEvent } from '../core/events/emit.js';
@@ -45,23 +33,11 @@ function currentNodeId() {
     const nodeId = envNodeId();
     return nodeId === undefined || nodeId.trim() === '' ? undefined : nodeId;
 }
-/** The node's profile, read fresh each poll: `crtr profile pause` mutates the
- *  manifest file directly, so a live broker sees the flip on its next tick with
- *  no daemon round-trip. '' is the historical no-profile row. */
+/** Profile pause is read fresh each poll from its owning scoped store. */
 function profilePaused() {
     const profileId = envProfileId();
     return profileId !== undefined && profileId !== '' && isProfilePaused(profileId);
 }
-function isFilesystemError(error) {
-    if (typeof error !== 'object' || error === null)
-        return false;
-    try {
-        return typeof error.code === 'string';
-    }
-    catch {
-        return false;
-    }
-}
 function safeErrorClass(error) {
     try {
         return errorClassFromError(error);
@@ -75,7 +51,7 @@ function emitBestEffort(input) {
         emitEvent(input);
     }
     catch {
-        // Canonical events are observational; delivery and cursor state stay authoritative.
+        // SQL delivery state remains authoritative if diagnostics fail.
     }
 }
 function emitFreshBestEffort(input) {
@@ -207,8 +183,8 @@ class CanvasInboxWatcher {
     lastCtx;
     streaming = false;
     nodeId;
-    cursor;
-    durableCursor;
+    claims = new Map();
+    tickInFlight;
     buffer = [];
     lastArrival = 0;
     pendingHandoffs = [];
@@ -272,10 +248,10 @@ class CanvasInboxWatcher {
                 return;
             try {
                 this.assertNodeOwnership(nodeId, 'settle');
-                // agent_settled is the authoritative durable boundary: Pi guarantees
-                // every queued continuation has drained, so hasPendingMessages() must
-                // not veto the commit here. Await crtrd before changing the in-memory
-                // durable cursor; a failed commit remains replayable after process exit.
+                await this.tickInFlight;
+                // Include kickoff claims even when the first turn settled before a poll.
+                if (!this.seeded)
+                    await this.claimMail(nodeId);
                 const result = await this.settle(nodeId, ctx, false, true);
                 if (result === 'refresh_held')
                     this.dispose('refresh', false);
@@ -306,9 +282,7 @@ class CanvasInboxWatcher {
                 });
             }
             try {
-                // This is the graceful fallback when no agent_settled fired before exit.
-                // crtrd rejects a cursor commit for a refresh, preserving every handoff
-                // that may have reached this discarded conversation for the next broker.
+                // Refresh rejects receipts, preserving claims for the replacement broker.
                 await this.disposeAtSettlement(reason, this.lastCtx);
             }
             catch (error) {
@@ -338,11 +312,7 @@ class CanvasInboxWatcher {
             this.reportNodesRefreshing = false;
         }
     }
-    /** True when delivery must wait a tick for a report-node projection refresh.
-     *  The projection captured at session_start omits every node created since —
-     *  each reply-bearing `crtr human send` bridge and each child this node spawns — so their
-     *  reports would render as bare refs instead of inlined bodies. One refresh
-     *  per unknown node id keeps a genuinely missing node from stalling delivery. */
+    /** Refresh once per unknown report sender, so new children can inline their reports. */
     refreshForUnknownReportRefs() {
         const unknown = [];
         for (const entry of this.buffer) {
@@ -371,9 +341,7 @@ class CanvasInboxWatcher {
         // the normal debounce owns delivery instead of waiting a full tick.
         this.runTick('schedule');
     }
-    /** Settle the graceful-shutdown fallback before disposing its retry state.
-     * The daemon decides whether a refresh preserves the cursor, and this method
-     * awaits that decision so a process exit never outruns an accepted commit. */
+    /** Await graceful-shutdown receipts before disposing their in-process state. */
     async disposeAtSettlement(reason, ctx) {
         const nodeId = currentNodeId();
         if (nodeId === undefined) {
@@ -402,8 +370,7 @@ class CanvasInboxWatcher {
                 ...this.pendingHandoffs.splice(0),
             ];
             this.buffer.length = 0;
-            this.cursor = undefined;
-            this.durableCursor = undefined;
+            this.claims.clear();
             this.reportNodes.clear();
             this.reportNodesAsked.clear();
             this.pendingCommit = undefined;
@@ -502,85 +469,66 @@ class CanvasInboxWatcher {
         }
         this.escapeFatal(fatal, 'schedule');
     }
-    runTick(fatalMode = 'throw') {
-        if (!this.canMutate())
+    runTick(_fatalMode = 'throw') {
+        if (!this.canMutate() || this.tickInFlight !== undefined)
             return;
-        try {
-            this.tick();
-        }
-        catch (error) {
-            if (error instanceof WatcherFatalError) {
-                this.escapeFatal(error, fatalMode);
-                return;
-            }
-            if (isFilesystemError(error))
-                return;
-            let fatal;
-            try {
-                this.raiseReadFatal('poll', error);
-            }
-            catch (tagged) {
-                fatal = tagged;
-            }
-            this.escapeFatal(fatal, fatalMode);
-        }
-    }
-    pollRead(read) {
-        try {
-            return { ok: true, value: read() };
-        }
-        catch (error) {
-            if (isFilesystemError(error))
-                return { ok: false };
-            this.raiseReadFatal('poll', error);
-        }
+        const attempt = this.tick().catch((error) => {
+            if (this.canMutate())
+                this.scheduleHandlerFatal(error, 'poll');
+        }).finally(() => {
+            if (this.tickInFlight === attempt)
+                this.tickInFlight = undefined;
+        });
+        this.tickInFlight = attempt;
     }
-    seed(nodeId) {
+    async claimMail(nodeId) {
         this.assertNodeOwnership(nodeId, 'poll');
-        if (this.seeded)
-            return true;
-        const initial = this.pollRead(() => readBrokerCursor(nodeId));
-        if (!initial.ok)
+        const result = await claimBrokerMail(nodeId, 'wake');
+        if (!this.canMutate())
+            return false;
+        if (result.action === 'hold')
             return false;
         this.nodeId = nodeId;
-        this.cursor = initial.value;
-        this.durableCursor = initial.value;
         this.seeded = true;
+        const activeIds = new Set(result.deliveries.map((claim) => claim.entry.entry_id));
+        // A canceled buffered delivery disappears from the daemon's claim query.
+        const canceled = this.buffer.filter((entry) => !activeIds.has(entry.entry_id));
+        for (const entry of canceled)
+            this.claims.delete(entry.entry_id);
+        this.buffer.splice(0, this.buffer.length, ...this.buffer.filter((entry) => activeIds.has(entry.entry_id)));
+        for (const claim of result.deliveries) {
+            const id = claim.entry.entry_id;
+            if (this.claims.has(id))
+                continue;
+            this.claims.set(id, claim);
+            if (claim.handoff === 'inherited') {
+                operationIdContext.fresh((operationId) => {
+                    this.pendingHandoffs.push({ ...deliveryFacts([claim.entry], 'visible'), operationId, settleAtAgentSettled: true });
+                });
+            }
+            else {
+                this.buffer.push(claim.entry);
+                this.lastArrival = Date.now();
+            }
+        }
         return true;
     }
-    tick() {
+    async tick() {
         const nodeId = currentNodeId();
-        if (nodeId === undefined || !this.seed(nodeId))
+        if (nodeId === undefined)
             return;
         if (this.pendingCommit !== undefined) {
-            this.retryPendingCommitOnTick(nodeId);
+            const result = await this.retryPendingCommit(nodeId);
+            if (result === 'refresh_held' && this.canMutate())
+                this.dispose('refresh', false);
             return;
         }
-        if (this.promptJoinInFlight)
-            return;
-        // A paused profile is inert: read nothing, send nothing, leave the cursor
-        // where it is, so every queued entry — critical included, since aborting the
-        // live turn is exactly the punch-through pause forbids — is still there to
-        // deliver on resume. Pause is not a kill: the turn already running finishes,
-        // and an in-flight handoff still commits above.
-        if (profilePaused())
+        if (this.promptJoinInFlight || profilePaused())
             return;
-        if (this.buffer.length === 0 && this.pendingHandoffs.length >= MAX_PENDING_HANDOFFS)
+        if (this.pendingHandoffs.length >= MAX_PENDING_HANDOFFS)
             return;
-        if (this.buffer.length > 0) {
-            const plan = this.ordinaryPlan();
-            if (plan.sendCount > 0 && this.pendingHandoffs.length + plan.sendCount > MAX_PENDING_HANDOFFS)
-                return;
-        }
-        const read = this.pollRead(() => readBrokerInboxSince(nodeId, this.cursor));
-        if (!read.ok)
+        if (!await this.claimMail(nodeId))
             return;
-        const newEntries = read.value;
-        if (newEntries.length > 0) {
-            this.cursor = newEntries.at(-1).entry_id;
-            this.buffer.push(...newEntries);
-            this.lastArrival = Date.now();
-        }
         if (this.buffer.length > 0 && Date.now() - this.lastArrival >= this.cadence.debounceMs) {
             if (this.refreshForUnknownReportRefs())
                 return;
@@ -588,16 +536,8 @@ class CanvasInboxWatcher {
         }
     }
     missingChannelEntries(entries) {
-        // Interrupt-canceled entries (a human Esc racing a not-yet-injected send —
-        // `POST /v1/nodes/{id}/interrupt`) are excluded from BOTH channels. Read
-        // fresh each plan build: the cancel can land AFTER the entry was buffered.
-        // Skipped entries are never handed off; the durable cursor covers them
-        // positionally when a later entry settles (or they are re-filtered after a
-        // restart).
-        const canceled = this.nodeId === undefined ? undefined : readBrokerCanceledEntryIds(this.nodeId);
-        const live = canceled === undefined || canceled.size === 0
-            ? entries
-            : entries.filter((entry) => !canceled.has(entry.entry_id));
+        // Each claim refresh removes canceled buffered entries before either channel sends.
+        const live = entries.filter((entry) => this.claims.has(entry.entry_id));
         const hiddenCoverage = this.coveredEntryIds('hidden');
         const visibleCoverage = this.coveredEntryIds('visible');
         return {
@@ -863,10 +803,7 @@ class CanvasInboxWatcher {
         this.requeueFromBatch(batch, execution.requeueEntryIds);
         return 'attempted';
     }
-    /** Claim the deferred-only idle batch for the human prompt already admitted
-     * by the broker. Each rendered delivery is persisted before that prompt, but
-     * no cursor may advance until the prompt's agent_settled event proves the
-     * turn consumed it. */
+    /** Deferred mail joins an admitted human prompt but remains unacknowledged until settlement. */
     async prependHeldDeferredInbox(session) {
         if (!this.canMutate() || this.nodeId === undefined || profilePaused())
             return;
@@ -950,15 +887,6 @@ class CanvasInboxWatcher {
         }
         return covered;
     }
-    retryPendingCommitOnTick(nodeId) {
-        void this.retryPendingCommit(nodeId).then((result) => {
-            if (result === 'refresh_held' && this.canMutate())
-                this.dispose('refresh', false);
-        }).catch((error) => {
-            if (this.canMutate())
-                this.dispose('shutdown', false, undefined, { error, stage: 'settle' });
-        });
-    }
     retryPendingCommit(nodeId) {
         const pending = this.pendingCommit;
         if (pending === undefined)
@@ -973,28 +901,40 @@ class CanvasInboxWatcher {
         return attempt;
     }
     async attemptPendingCommit(nodeId, pending) {
+        let acknowledged = false;
         try {
-            const directive = await advanceBrokerInboxCursor(nodeId, {
-                throughEntryId: pending.throughEntryId,
-                brokerPid: process.pid,
-            });
-            if (directive.action === 'hold_refresh')
+            const directive = await acknowledgeBrokerMail(nodeId, pending.receipts);
+            if (directive.action === 'hold')
                 return 'refresh_held';
+            for (const receipt of pending.receipts) {
+                const result = directive.results.find((result) => result.delivery_id === receipt.delivery_id);
+                if (result?.outcome !== receipt.disposition && result?.outcome !== 'stale')
+                    throw new Error('daemon returned no terminal mail settlement outcome');
+            }
+            acknowledged = directive.results.every((result) => result.outcome === 'acknowledged');
         }
         catch (error) {
             if (this.pendingCommit === pending) {
                 for (const handoff of pending.handoffs) {
-                    emitDeliveryFailure(handoff.operationId, handoff, 'cursor_commit', error);
+                    emitDeliveryFailure(handoff.operationId, handoff, 'receipt_commit', error);
                 }
             }
             return 'held';
         }
         if (this.pendingCommit !== pending)
             return 'settled';
-        this.durableCursor = pending.throughEntryId;
+        for (const id of pending.entryIds)
+            this.claims.delete(id);
+        if (pending.receipts.some((receipt) => receipt.disposition === 'released')) {
+            const released = new Set(pending.entryIds);
+            this.buffer.splice(0, this.buffer.length, ...this.buffer.filter((entry) => !released.has(entry.entry_id)));
+        }
         this.pendingCommit = undefined;
-        for (const handoff of pending.handoffs)
-            emitDeliveryCompleted(handoff);
+        const completed = this.detachPending((handoff) => handoff.entryIds.every((id) => !this.claims.has(id)));
+        for (const handoff of completed) {
+            if (acknowledged)
+                emitDeliveryCompleted(handoff);
+        }
         return 'settled';
     }
     async settle(nodeId, ctx, holdPendingMessages, atAgentSettled = false) {
@@ -1009,109 +949,23 @@ class CanvasInboxWatcher {
         }
         if (this.pendingCommit !== undefined)
             return this.retryPendingCommit(nodeId);
-        if (this.pendingHandoffs.length === 0)
+        const refused = wasTurnRefused();
+        const buffered = new Set(this.buffer.map((entry) => entry.entry_id));
+        const eligible = this.pendingHandoffs.filter((handoff) => atAgentSettled || handoff.settleAtAgentSettled !== true);
+        const handedOff = new Set(eligible.flatMap((handoff) => [...handoff.entryIds]));
+        const entryIds = [...this.claims.keys()].filter((id) => refused || (handedOff.has(id) && !buffered.has(id)));
+        if (entryIds.length === 0)
             return 'settled';
-        const physical = this.readPhysicalSettlementState(nodeId);
-        if (physical.durableIndex >= 0) {
-            const alreadyDurable = this.detachPending((handoff) => physical.throughIndexes.get(handoff) <= physical.durableIndex);
-            for (const handoff of alreadyDurable)
-                emitDeliveryCompleted(handoff);
-        }
-        const agentSettledBlock = atAgentSettled
-            ? undefined
-            : this.pendingHandoffs
-                .filter((handoff) => handoff.settleAtAgentSettled === true)
-                .map((handoff) => physical.throughIndexes.get(handoff))
-                .reduce((first, index) => first === undefined ? index : Math.min(first, index), undefined);
-        const eligible = this.pendingHandoffs.filter((handoff) => {
-            const throughIndex = physical.throughIndexes.get(handoff);
-            return (handoff.settleAtAgentSettled !== true || atAgentSettled)
-                && (physical.blockedIndex === undefined || throughIndex < physical.blockedIndex)
-                && (agentSettledBlock === undefined || throughIndex < agentSettledBlock);
-        });
-        if (eligible.length === 0)
-            return 'settled';
-        let target = eligible[0];
-        for (const handoff of eligible.slice(1)) {
-            if (physical.throughIndexes.get(handoff) > physical.throughIndexes.get(target))
-                target = handoff;
-        }
-        const committing = new Set(eligible);
         this.pendingCommit = {
-            handoffs: this.detachPending((handoff) => committing.has(handoff)),
-            throughEntryId: target.throughEntryId,
+            handoffs: eligible,
+            entryIds,
+            receipts: entryIds.map((id) => {
+                const claim = this.claims.get(id);
+                return { delivery_id: claim.delivery_id, attempts: claim.attempts, disposition: refused ? 'released' : 'acknowledged' };
+            }),
         };
         return this.retryPendingCommit(nodeId);
     }
-    readPhysicalSettlementState(nodeId) {
-        let entries;
-        try {
-            entries = readBrokerInboxSince(nodeId);
-        }
-        catch (error) {
-            this.raiseReadFatal('settle', error);
-        }
-        try {
-            const indexes = new Map();
-            entries.forEach((entry, index) => indexes.set(entry.entry_id, index));
-            const indexOf = (entryId, owner) => {
-                const index = indexes.get(entryId);
-                if (index === undefined)
-                    throw new Error(`${owner} entry_id is absent from the physical inbox: ${entryId}`);
-                return index;
-            };
-            const durableIndex = this.durableCursor === undefined ? -1 : indexOf(this.durableCursor, 'durable cursor');
-            const cursorIndex = this.cursor === undefined ? -1 : indexOf(this.cursor, 'read cursor');
-            if (cursorIndex < durableIndex)
-                throw new Error('read cursor precedes the durable cursor');
-            let previousBufferIndex = -1;
-            let blockedIndex;
-            const bufferedIds = new Set();
-            for (const entry of this.buffer) {
-                if (bufferedIds.has(entry.entry_id))
-                    throw new Error(`buffer contains duplicate entry_id: ${entry.entry_id}`);
-                bufferedIds.add(entry.entry_id);
-                const index = indexOf(entry.entry_id, 'buffer');
-                if (index <= previousBufferIndex)
-                    throw new Error('buffer is not in physical inbox order');
-                if (index <= durableIndex)
-                    throw new Error('buffer contains an entry at or before the durable cursor');
-                if (cursorIndex < index)
-                    throw new Error('buffer contains an entry beyond the read cursor');
-                previousBufferIndex = index;
-                blockedIndex = blockedIndex === undefined ? index : Math.min(blockedIndex, index);
-            }
-            const throughIndexes = new Map();
-            for (const handoff of this.pendingHandoffs) {
-                if (handoff.entryIds.length === 0)
-                    throw new Error('pending handoff has no entry_ids');
-                if (handoff.entryIds.at(-1) !== handoff.throughEntryId) {
-                    throw new Error('pending handoff through_entry_id is not its physical-last attempted entry');
-                }
-                let previousIndex = -1;
-                const handoffIds = new Set();
-                for (const entryId of handoff.entryIds) {
-                    if (handoffIds.has(entryId))
-                        throw new Error(`pending handoff contains duplicate entry_id: ${entryId}`);
-                    handoffIds.add(entryId);
-                    const index = indexOf(entryId, 'pending handoff');
-                    if (index <= previousIndex)
-                        throw new Error('pending handoff entry_ids are not in physical inbox order');
-                    if (cursorIndex < index)
-                        throw new Error('pending handoff contains an entry beyond the read cursor');
-                    previousIndex = index;
-                }
-                const throughIndex = indexOf(handoff.throughEntryId, 'pending handoff through');
-                if (throughIndex !== previousIndex)
-                    throw new Error('pending handoff through_entry_id is physically inconsistent');
-                throughIndexes.set(handoff, throughIndex);
-            }
-            return { throughIndexes, durableIndex, blockedIndex };
-        }
-        catch (error) {
-            this.raiseReadFatal('settle', error);
-        }
-    }
     detachPending(predicate) {
         const removed = [];
         for (let index = this.pendingHandoffs.length - 1; index >= 0; index -= 1) {

package/dist/pi-extensions/canvas-passive-context.d.ts

@@ -1,4 +1,5 @@
-import { type BrokerPassiveEntry } from '../core/runtime/broker/passive.js';
+import type { MailEntryDTO } from '../api/dto/mail.js';
+type BrokerPassiveEntry = MailEntryDTO;
 interface InputEventLike {
     type: 'input';
     text: string;
@@ -15,7 +16,8 @@ type InputEventResultLike = {
     action: 'handled';
 };
 interface PiLike {
-    on: (event: 'input', handler: (event: InputEventLike, ctx: any) => InputEventResultLike | void | Promise<InputEventResultLike | void>) => void;
+    on(event: 'input', handler: (event: InputEventLike, ctx: any) => InputEventResultLike | void | Promise<InputEventResultLike | void>): void;
+    on(event: 'agent_settled' | 'session_shutdown', handler: (event: any, ctx: any) => void | Promise<void>): void;
 }
 /**
  * Render drained passive entries (oldest first) into one XML pre-text block.
@@ -32,11 +34,5 @@ export declare function formatPassive(entries: BrokerPassiveEntry[], reportNodes
  * becomes the body's first child instead.
  */
 export declare function placeBacklog(text: string, preText: string): string;
-/**
- * Register the passive-context drain on `pi`.
- *
- * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
- * is the whole extension: drain on every message, prepend when non-empty.
- */
 export declare function registerCanvasPassiveContext(pi: PiLike): void;
 export default registerCanvasPassiveContext;

package/dist/pi-extensions/canvas-passive-context.js

@@ -1,28 +1,11 @@
-// canvas-passive-context.ts — pi extension for pi-native canvas agent nodes.
-//
-// Loaded into every canvas node's pi process via the node's launch.extensions
-// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
-//
-// The passive-subscription drain. A PASSIVE subscription (active=false edge)
-// never wakes its subscriber: `push` routes its pointers to passive.jsonl, which
-// the inbox-watcher never polls. They simply accumulate. This extension is what
-// finally surfaces them — the moment the node is MESSAGED.
-//
-// pi fires an `input` event for every user message (human-typed, an RPC, or an
-// extension's sendUserMessage — including the inbox-watcher's own wake). On that
-// event we DRAIN the node's passive accumulator and, when non-empty, prepend
-// every entry as timestamped XML to the message text via the `transform` action.
-// So the backlog rides in as pre-text on whatever message next engages the node,
-// before the LLM sees it — and is cleared in the same step (drain = read+clear),
-// so it surfaces exactly once.
-//
-// Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
-// crouter's own tsc build without a dep on the pi packages.
+// Passive mail is claimed only on natural input and acknowledged after settlement.
+// Formatting failures retain the SQL claim; refused turns release it for replay.
 import { envNodeId } from '../shared/env.js';
 import { existsSync, readFileSync } from 'node:fs';
-import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { acknowledgeBrokerMail, claimBrokerMail, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
+import { wasTurnRefused } from '../core/runtime/broker/extension-abort.js';
+import { emitEvent } from '../core/events/emit.js';
 import { reportPathFromRef } from '../core/runtime/broker-extension-render.js';
-import { drainBrokerPassive } from '../core/runtime/broker/passive.js';
 import { parseCard } from '../shared/generated-context.js';
 // Per-entry body cap so a single fat report can't blow the context budget. The
 // full report stays on disk at `ref` if the agent needs more.
@@ -126,30 +109,95 @@ export function placeBacklog(text, preText) {
     return `${text.slice(0, bodyStart)}${preText}\n${text.slice(bodyStart)}`;
 }
 // Extension
-/**
- * Register the passive-context drain on `pi`.
- *
- * Returns immediately (inert) when CRTR_NODE_ID is absent. The `input` handler
- * is the whole extension: drain on every message, prepend when non-empty.
- */
 export function registerCanvasPassiveContext(pi) {
+    const claims = new Map();
+    let pending;
+    let settlement;
+    function reportFailure(error) {
+        try {
+            emitEvent({ level: 'error', event: 'inbox.delivery.failed', outcome: 'failed', error, fields: { channel: 'passive' } });
+        }
+        catch {
+            // SQL claims and pending receipts remain authoritative if diagnostics fail.
+        }
+    }
+    async function settle(nodeId) {
+        if (settlement !== undefined)
+            return settlement;
+        if (pending === undefined) {
+            pending = [...claims.values()].filter((item) => item.injected).map(({ claim }) => ({
+                delivery_id: claim.delivery_id, attempts: claim.attempts,
+                disposition: wasTurnRefused() ? 'released' : 'acknowledged',
+            }));
+        }
+        if (pending.length === 0) {
+            pending = undefined;
+            return true;
+        }
+        const receipts = pending;
+        const attempt = (async () => {
+            try {
+                const result = await acknowledgeBrokerMail(nodeId, receipts);
+                if (result.action === 'hold')
+                    return false;
+                for (const receipt of receipts) {
+                    const confirmed = result.results.find((result) => result.delivery_id === receipt.delivery_id);
+                    if (confirmed?.outcome !== receipt.disposition && confirmed?.outcome !== 'stale')
+                        throw new Error(`passive mail settlement has no terminal outcome: ${receipt.delivery_id}`);
+                }
+                for (const receipt of receipts)
+                    claims.delete(receipt.delivery_id);
+                pending = undefined;
+                return true;
+            }
+            catch (error) {
+                reportFailure(error);
+                return false;
+            }
+        })().finally(() => { if (settlement === attempt)
+            settlement = undefined; });
+        settlement = attempt;
+        return attempt;
+    }
     pi.on('input', async (event) => {
+        const nodeId = envNodeId();
+        if (nodeId === undefined || nodeId.trim() === '')
+            return;
         try {
-            const nodeId = envNodeId();
-            if (nodeId === undefined || nodeId.trim() === '')
-                return; // not a canvas node
-            const drained = drainBrokerPassive(nodeId);
-            if (drained.length === 0)
-                return; // nothing accumulated → leave the message as-is
+            if (pending !== undefined && !await settle(nodeId))
+                return;
+            const result = await claimBrokerMail(nodeId, 'passive');
+            if (result.action === 'hold')
+                return;
+            for (const claim of result.deliveries) {
+                if (!claims.has(claim.delivery_id))
+                    claims.set(claim.delivery_id, { claim, injected: false });
+            }
+            const unsent = [...claims.values()].filter((item) => !item.injected);
+            if (unsent.length === 0)
+                return;
             const state = await brokerExtensionState(nodeId);
             const reportNodes = new Map(state.report_nodes.map((node) => [node.node_id, node]));
-            const text = placeBacklog(event.text, formatPassive(drained, reportNodes));
+            const text = placeBacklog(event.text, formatPassive(unsent.map(({ claim }) => claim.entry), reportNodes));
+            for (const item of unsent)
+                item.injected = true;
             return { action: 'transform', text, images: event.images };
         }
-        catch {
-            // Best-effort: a drain/format failure must never drop the user's message.
+        catch (error) {
+            // The original input proceeds; unformatted mail remains held and unacknowledged.
+            reportFailure(error);
             return;
         }
     });
+    pi.on('agent_settled', async () => {
+        const nodeId = envNodeId();
+        if (nodeId !== undefined && nodeId !== '')
+            await settle(nodeId);
+    });
+    pi.on('session_shutdown', async (_event, ctx) => {
+        const nodeId = envNodeId();
+        if (nodeId !== undefined && nodeId !== '' && ctx?.hasPendingMessages?.() !== true)
+            await settle(nodeId);
+    });
 }
 export default registerCanvasPassiveContext;