@ouro.bot/cli 0.1.0-alpha.776 → 0.1.0-alpha.777

package/dist/senses/private-runtime-worker.js

@@ -57,6 +57,15 @@ const spend_ledger_1 = require("../rsvp/spend-ledger");
 const run_ledger_1 = require("../heart/run-ledger");
 const autonomy_budget_1 = require("../heart/autonomy-budget");
 const habit_lifecycle_guard_1 = require("./habit-lifecycle-guard");
+function createQueueCompletion(rejectOnError) {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject, errors: [], rejectOnError };
+}
 function isUsageData(value) {
     const usage = value;
     return !!usage
@@ -492,226 +501,287 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
         timer.unref?.();
         return () => clearInterval(timer);
     };
-    async function run(reason, taskId, habitName, awaitName, trigger, privateTurnDecision, noSend, externalEvent) {
+    async function run(reason, taskId, habitName, awaitName, trigger, privateTurnDecision, noSend, externalEvent, dispatchId) {
+        const completion = createQueueCompletion(dispatchId !== undefined);
+        let activeCompletion = completion;
         if (running) {
-            queue.push({ reason, taskId, habitName, awaitName, trigger, privateTurnDecision, noSend, externalEvent, ...(externalEvent ? { stopExternalEventHeartbeat: startExternalEventHeartbeat(externalEvent) } : {}) });
-            return;
+            queue.push({ reason, taskId, habitName, awaitName, trigger, privateTurnDecision, noSend, externalEvent, dispatchId, completion, ...(externalEvent ? { stopExternalEventHeartbeat: startExternalEventHeartbeat(externalEvent) } : {}) });
+            return completion.promise;
         }
         running = true;
-        try {
-            let nextReason = reason;
-            let nextTaskId = taskId;
-            let nextHabitName = habitName;
-            let nextAwaitName = awaitName;
-            let nextTrigger = trigger;
-            let nextPrivateTurnDecision = privateTurnDecision;
-            let nextExternalEvent = externalEvent;
-            let nextExternalEventHeartbeat = externalEvent ? startExternalEventHeartbeat(externalEvent) : undefined;
-            let nextNoSend = reason === "habit" ? noSend : undefined;
-            let nextHabitRun = null;
-            let consecutiveInstinctTurns = reason === "instinct" ? 1 : 0;
-            runLoop: do {
-                const currentReason = nextReason;
-                const currentHabitName = nextHabitName;
-                const currentTrigger = nextTrigger ?? "overdue";
-                const currentNoSend = nextNoSend;
-                const currentExternalEvent = nextExternalEvent;
-                const currentExternalEventHeartbeat = nextExternalEventHeartbeat;
-                nextExternalEventHeartbeat = undefined;
-                const currentHabitRun = currentReason === "habit" && currentHabitName
-                    ? nextHabitRun && nextHabitRun.habit.name === currentHabitName
-                        ? nextHabitRun
-                        : await prepareHabitRun(currentHabitName, currentTrigger, new Date(nowSource()).toISOString())
-                    : null;
-                nextHabitRun = null;
-                let currentHabitRunFinalized = false;
-                const finalizeCurrentHabitRun = () => {
-                    if (!currentHabitRun || currentHabitRunFinalized)
-                        return;
-                    recordHabitCompletion(currentHabitRun, new Date(nowSource()).toISOString());
-                    currentHabitRunFinalized = true;
-                };
-                const turnErrors = [];
-                if (!(currentReason === "habit" && currentHabitName === "heartbeat")) {
-                    clearHeartbeatRestShield();
-                }
-                let turnResult;
-                let blockedAutonomyTurn = false;
-                try {
-                    const turnStartedAt = new Date(nowSource()).toISOString();
-                    const autonomyDecision = currentHabitRun && !currentHabitRun.blockedReason
-                        ? reserveHabitAutonomyBudget(currentHabitRun, turnStartedAt)
+        void (async () => {
+            try {
+                let nextReason = reason;
+                let nextTaskId = taskId;
+                let nextHabitName = habitName;
+                let nextAwaitName = awaitName;
+                let nextTrigger = trigger;
+                let nextPrivateTurnDecision = privateTurnDecision;
+                let nextExternalEvent = externalEvent;
+                let nextExternalEventHeartbeat = externalEvent ? startExternalEventHeartbeat(externalEvent) : undefined;
+                let nextCompletion = completion;
+                let nextNoSend = reason === "habit" ? noSend : undefined;
+                let nextHabitRun = null;
+                let consecutiveInstinctTurns = reason === "instinct" ? 1 : 0;
+                runLoop: do {
+                    const currentReason = nextReason;
+                    const currentHabitName = nextHabitName;
+                    const currentTrigger = nextTrigger ?? "overdue";
+                    const currentNoSend = nextNoSend;
+                    const currentExternalEvent = nextExternalEvent;
+                    const currentExternalEventHeartbeat = nextExternalEventHeartbeat;
+                    const currentCompletion = nextCompletion;
+                    activeCompletion = currentCompletion;
+                    nextExternalEventHeartbeat = undefined;
+                    nextCompletion = undefined;
+                    const currentHabitRun = currentReason === "habit" && currentHabitName
+                        ? nextHabitRun && nextHabitRun.habit.name === currentHabitName
+                            ? nextHabitRun
+                            : await prepareHabitRun(currentHabitName, currentTrigger, new Date(nowSource()).toISOString())
                         : null;
-                    if (currentHabitRun)
-                        recordHabitStartIfNeeded(currentHabitRun);
-                    if (currentHabitRun?.blockedReason) {
-                        blockedAutonomyTurn = true;
-                        turnResult = {
-                            turnOutcome: "blocked",
-                            reason: currentHabitRun.blockedReason,
-                        };
+                    nextHabitRun = null;
+                    let currentHabitRunFinalized = false;
+                    const finalizeCurrentHabitRun = () => {
+                        if (!currentHabitRun || currentHabitRunFinalized)
+                            return;
+                        recordHabitCompletion(currentHabitRun, new Date(nowSource()).toISOString());
+                        currentHabitRunFinalized = true;
+                    };
+                    const turnErrors = [];
+                    if (!(currentReason === "habit" && currentHabitName === "heartbeat")) {
                         clearHeartbeatRestShield();
                     }
-                    else if (autonomyDecision && !autonomyDecision.allowed) {
-                        blockedAutonomyTurn = true;
-                        const reason = `autonomy budget blocked: ${autonomyDecision.reason}`;
-                        turnErrors.push(reason);
-                        turnResult = {
-                            turnOutcome: "blocked",
-                            reason,
-                            autonomyReceiptId: autonomyDecision.receiptId,
-                        };
-                        clearHeartbeatRestShield();
-                    }
-                    else {
-                        const turnOptions = {
-                            reason: nextReason,
-                            taskId: nextTaskId,
-                            habitName: nextHabitName,
-                            awaitName: nextAwaitName,
-                            ...(currentNoSend ? { noSend: true } : {}),
-                            ...(nextPrivateTurnDecision ? { privateTurnDecision: nextPrivateTurnDecision } : {}),
-                            ...(nextExternalEvent ? { externalEvent: nextExternalEvent } : {}),
-                            ...(currentHabitRun
-                                ? {
-                                    trigger: currentHabitRun.trigger,
-                                    preparedHabit: {
-                                        runId: currentHabitRun.runId,
+                    let turnResult;
+                    let blockedAutonomyTurn = false;
+                    try {
+                        const turnStartedAt = new Date(nowSource()).toISOString();
+                        const autonomyDecision = currentHabitRun && !currentHabitRun.blockedReason
+                            ? reserveHabitAutonomyBudget(currentHabitRun, turnStartedAt)
+                            : null;
+                        if (currentHabitRun)
+                            recordHabitStartIfNeeded(currentHabitRun);
+                        if (currentHabitRun?.blockedReason) {
+                            blockedAutonomyTurn = true;
+                            turnResult = {
+                                turnOutcome: "blocked",
+                                reason: currentHabitRun.blockedReason,
+                            };
+                            clearHeartbeatRestShield();
+                        }
+                        else if (autonomyDecision && !autonomyDecision.allowed) {
+                            blockedAutonomyTurn = true;
+                            const reason = `autonomy budget blocked: ${autonomyDecision.reason}`;
+                            turnErrors.push(reason);
+                            turnResult = {
+                                turnOutcome: "blocked",
+                                reason,
+                                autonomyReceiptId: autonomyDecision.receiptId,
+                            };
+                            clearHeartbeatRestShield();
+                        }
+                        else {
+                            const turnOptions = {
+                                reason: nextReason,
+                                taskId: nextTaskId,
+                                habitName: nextHabitName,
+                                awaitName: nextAwaitName,
+                                ...(currentNoSend ? { noSend: true } : {}),
+                                ...(nextPrivateTurnDecision ? { privateTurnDecision: nextPrivateTurnDecision } : {}),
+                                ...(nextExternalEvent ? { externalEvent: nextExternalEvent } : {}),
+                                ...(currentHabitRun
+                                    ? {
                                         trigger: currentHabitRun.trigger,
-                                        operationId: currentHabitRun.operationId,
-                                        habit: currentHabitRun.habit,
-                                        priorSessionSummary: currentHabitRun.priorSessionSummary,
-                                    },
-                                    habitSession: {
-                                        runId: currentHabitRun.runId,
-                                        sessionPath: currentHabitRun.paths.sessionPath,
-                                        pendingDir: currentHabitRun.paths.pendingDir,
-                                        permissionEnvelope: currentHabitRun.permissionEnvelope,
-                                        toolPolicy: currentHabitRun.toolPolicy,
-                                        ...(currentHabitRun.rsvpPolicy ? { rsvpPolicy: currentHabitRun.rsvpPolicy } : {}),
-                                        friendStore: currentHabitRun.friendStore,
-                                        recordProducedRef: (ref) => { currentHabitRun.producedRefs.push(ref); },
-                                        recordSurfaceAttempt: (attempt) => { currentHabitRun.surfaceAttempts.push(attempt); },
-                                        recordError: (error) => { currentHabitRun.errors.push(error); },
-                                    },
-                                }
-                                : {}),
-                        };
-                        turnResult = await runTurn(turnOptions);
+                                        preparedHabit: {
+                                            runId: currentHabitRun.runId,
+                                            trigger: currentHabitRun.trigger,
+                                            operationId: currentHabitRun.operationId,
+                                            habit: currentHabitRun.habit,
+                                            priorSessionSummary: currentHabitRun.priorSessionSummary,
+                                        },
+                                        habitSession: {
+                                            runId: currentHabitRun.runId,
+                                            sessionPath: currentHabitRun.paths.sessionPath,
+                                            pendingDir: currentHabitRun.paths.pendingDir,
+                                            permissionEnvelope: currentHabitRun.permissionEnvelope,
+                                            toolPolicy: currentHabitRun.toolPolicy,
+                                            ...(currentHabitRun.rsvpPolicy ? { rsvpPolicy: currentHabitRun.rsvpPolicy } : {}),
+                                            friendStore: currentHabitRun.friendStore,
+                                            recordProducedRef: (ref) => { currentHabitRun.producedRefs.push(ref); },
+                                            recordSurfaceAttempt: (attempt) => { currentHabitRun.surfaceAttempts.push(attempt); },
+                                            recordError: (error) => { currentHabitRun.errors.push(error); },
+                                        },
+                                    }
+                                    : {}),
+                            };
+                            turnResult = await runTurn(turnOptions);
+                        }
                     }
-                }
-                catch (error) {
-                    clearHeartbeatRestShield();
-                    turnErrors.push(error instanceof Error ? error.message : String(error));
-                    (0, runtime_1.emitNervesEvent)({
-                        level: "error",
-                        component: "senses",
-                        event: "senses.private_runtime_worker_error",
-                        message: "private-runtime worker turn failed",
-                        meta: {
-                            reason: nextReason,
-                            error: error instanceof Error ? error.message : String(error),
-                        },
-                    });
-                }
-                currentExternalEventHeartbeat?.();
-                if (currentReason === "habit" && currentHabitName === "heartbeat") {
-                    heartbeatOkRestedAt = isHeartbeatOkRestResult(turnResult) ? nowSource() : null;
-                }
-                if (currentHabitRun) {
-                    currentHabitRun.results.push(turnResult);
-                    currentHabitRun.errors.push(...turnErrors);
-                }
-                // Drain queue first. Externally-queued work resets the instinct cap
-                // because a real outside trigger arrived between turns.
-                while (queue.length > 0) {
-                    const next = queue.shift();
-                    if (next.reason === "habit" && next.habitName === "heartbeat" && shouldReuseHeartbeatOkRest(next.habitName)) {
-                        finalizeCurrentHabitRun();
-                        await reuseHeartbeatOkRest(next.habitName);
-                        continue;
-                    }
-                    if (!(next.reason === "habit" && next.habitName === "heartbeat")) {
+                    catch (error) {
                         clearHeartbeatRestShield();
-                    }
-                    finalizeCurrentHabitRun();
-                    nextReason = next.reason;
-                    nextTaskId = next.taskId;
-                    nextHabitName = next.habitName;
-                    nextAwaitName = next.awaitName;
-                    nextTrigger = next.trigger;
-                    nextPrivateTurnDecision = next.privateTurnDecision;
-                    nextExternalEvent = next.externalEvent;
-                    nextExternalEventHeartbeat = next.stopExternalEventHeartbeat;
-                    nextNoSend = next.reason === "habit" ? next.noSend : undefined;
-                    consecutiveInstinctTurns = nextReason === "instinct" ? consecutiveInstinctTurns + 1 : 0;
-                    continue runLoop;
-                }
-                if (blockedAutonomyTurn) {
-                    finalizeCurrentHabitRun();
-                    break;
-                }
-                // Then check hasPendingWork fallback. This is the loop site: any
-                // tool that writes to the private-runtime pending dir during a turn
-                // would cause hasPendingWork() to be true here, producing a
-                // self-sustaining "instinct" loop with no external input. Cap it.
-                if (hasPendingWork(currentHabitRun?.paths.pendingDir)) {
-                    if (currentExternalEvent && (turnErrors.length > 0
-                        || (turnResult && typeof turnResult === "object" && "turnOutcome" in turnResult && turnResult.turnOutcome === "errored"))) {
-                        finalizeCurrentHabitRun();
-                        break;
-                    }
-                    clearHeartbeatRestShield();
-                    if (consecutiveInstinctTurns >= exports.MAX_CONSECUTIVE_INSTINCT_TURNS) {
+                        turnErrors.push(error instanceof Error ? error.message : String(error));
                         (0, runtime_1.emitNervesEvent)({
-                            level: "warn",
+                            level: "error",
                             component: "senses",
-                            event: "senses.private_runtime_worker_instinct_loop_capped",
-                            message: "private-runtime worker stopped chaining instinct turns; pending work remains for next external trigger",
+                            event: "senses.private_runtime_worker_error",
+                            message: "private-runtime worker turn failed",
                             meta: {
-                                consecutiveInstinctTurns,
-                                cap: exports.MAX_CONSECUTIVE_INSTINCT_TURNS,
-                                lastReason: nextReason,
+                                reason: nextReason,
+                                error: error instanceof Error ? error.message : String(error),
                             },
                         });
-                        finalizeCurrentHabitRun();
-                        break;
                     }
-                    if (currentReason === "habit" && currentHabitName && currentHabitRun) {
-                        consecutiveInstinctTurns += 1;
-                        nextReason = "habit";
-                        nextTaskId = undefined;
-                        nextHabitName = currentHabitName;
-                        nextAwaitName = undefined;
-                        nextTrigger = currentTrigger;
-                        nextPrivateTurnDecision = undefined;
-                        nextExternalEvent = undefined;
-                        nextExternalEventHeartbeat = undefined;
-                        nextNoSend = currentNoSend;
-                        nextHabitRun = currentHabitRun;
+                    currentExternalEventHeartbeat?.();
+                    if (currentExternalEvent) {
+                        const turnOutcome = turnResult && typeof turnResult === "object" && "turnOutcome" in turnResult
+                            ? turnResult.turnOutcome
+                            : undefined;
+                        const failureReason = turnErrors.length > 0 || turnOutcome === "errored"
+                            ? "private-runtime external-event turn failed"
+                            : blockedAutonomyTurn || turnOutcome === "blocked" || turnOutcome === "suspended"
+                                ? "external-event turn was blocked"
+                                : "external-event turn completed without a terminal disposition";
+                        let settledIncomplete = false;
+                        for (const member of [currentExternalEvent, ...(currentExternalEvent.relatedEvents ?? [])]) {
+                            const result = (0, router_1.settleExternalEventFailureIfOwned)(member.recordPath, {
+                                owner: member.claimOwner,
+                                expectedGeneration: member.generation,
+                                error: failureReason,
+                            });
+                            settledIncomplete = result.settled || settledIncomplete;
+                        }
+                        if (settledIncomplete && turnErrors.length === 0)
+                            turnErrors.push(failureReason);
+                    }
+                    if (currentReason === "habit" && currentHabitName === "heartbeat") {
+                        heartbeatOkRestedAt = isHeartbeatOkRestResult(turnResult) ? nowSource() : null;
+                    }
+                    if (currentHabitRun) {
+                        currentHabitRun.results.push(turnResult);
+                        currentHabitRun.errors.push(...turnErrors);
                     }
-                    else {
+                    currentCompletion?.errors.push(...turnErrors);
+                    const settleCurrentCompletion = () => {
+                        /* v8 ignore next -- every run and queued entry is constructed with a completion @preserve */
+                        if (!currentCompletion)
+                            return;
+                        if (currentCompletion.rejectOnError && currentCompletion.errors.length > 0)
+                            currentCompletion.reject(new Error(currentCompletion.errors.join("; ")));
+                        else
+                            currentCompletion.resolve();
+                        if (activeCompletion === currentCompletion)
+                            activeCompletion = undefined;
+                    };
+                    // Drain queue first. Externally-queued work resets the instinct cap
+                    // because a real outside trigger arrived between turns.
+                    if (queue.length > 0)
+                        settleCurrentCompletion();
+                    while (queue.length > 0) {
+                        const next = queue.shift();
+                        activeCompletion = next.completion;
+                        if (next.reason === "habit" && next.habitName === "heartbeat" && shouldReuseHeartbeatOkRest(next.habitName)) {
+                            finalizeCurrentHabitRun();
+                            await reuseHeartbeatOkRest(next.habitName);
+                            next.completion.resolve();
+                            /* v8 ignore next -- activeCompletion was assigned from this exact queue entry immediately above @preserve */
+                            if (activeCompletion === next.completion)
+                                activeCompletion = undefined;
+                            continue;
+                        }
+                        if (!(next.reason === "habit" && next.habitName === "heartbeat")) {
+                            clearHeartbeatRestShield();
+                        }
                         finalizeCurrentHabitRun();
-                        consecutiveInstinctTurns += 1;
-                        nextReason = "instinct";
-                        nextTaskId = undefined;
-                        nextHabitName = undefined;
-                        nextAwaitName = undefined;
-                        nextTrigger = undefined;
-                        nextPrivateTurnDecision = undefined;
-                        nextExternalEvent = undefined;
-                        nextExternalEventHeartbeat = undefined;
-                        nextNoSend = undefined;
+                        nextReason = next.reason;
+                        nextTaskId = next.taskId;
+                        nextHabitName = next.habitName;
+                        nextAwaitName = next.awaitName;
+                        nextTrigger = next.trigger;
+                        nextPrivateTurnDecision = next.privateTurnDecision;
+                        nextExternalEvent = next.externalEvent;
+                        nextExternalEventHeartbeat = next.stopExternalEventHeartbeat;
+                        nextCompletion = next.completion;
+                        nextNoSend = next.reason === "habit" ? next.noSend : undefined;
+                        consecutiveInstinctTurns = nextReason === "instinct" ? consecutiveInstinctTurns + 1 : 0;
+                        continue runLoop;
                     }
-                    continue;
-                }
-                finalizeCurrentHabitRun();
-                break;
-            } while (true);
-        }
-        finally {
-            running = false;
-        }
+                    if (blockedAutonomyTurn) {
+                        finalizeCurrentHabitRun();
+                        settleCurrentCompletion();
+                        break;
+                    }
+                    // Then check hasPendingWork fallback. This is the loop site: any
+                    // tool that writes to the private-runtime pending dir during a turn
+                    // would cause hasPendingWork() to be true here, producing a
+                    // self-sustaining "instinct" loop with no external input. Cap it.
+                    if (hasPendingWork(currentHabitRun?.paths.pendingDir)) {
+                        if (currentExternalEvent && (turnErrors.length > 0
+                            || (turnResult && typeof turnResult === "object" && "turnOutcome" in turnResult && turnResult.turnOutcome === "errored"))) {
+                            finalizeCurrentHabitRun();
+                            settleCurrentCompletion();
+                            break;
+                        }
+                        clearHeartbeatRestShield();
+                        if (consecutiveInstinctTurns >= exports.MAX_CONSECUTIVE_INSTINCT_TURNS) {
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "senses",
+                                event: "senses.private_runtime_worker_instinct_loop_capped",
+                                message: "private-runtime worker stopped chaining instinct turns; pending work remains for next external trigger",
+                                meta: {
+                                    consecutiveInstinctTurns,
+                                    cap: exports.MAX_CONSECUTIVE_INSTINCT_TURNS,
+                                    lastReason: nextReason,
+                                },
+                            });
+                            finalizeCurrentHabitRun();
+                            settleCurrentCompletion();
+                            break;
+                        }
+                        if (currentReason === "habit" && currentHabitName && currentHabitRun) {
+                            consecutiveInstinctTurns += 1;
+                            nextReason = "habit";
+                            nextTaskId = undefined;
+                            nextHabitName = currentHabitName;
+                            nextAwaitName = undefined;
+                            nextTrigger = currentTrigger;
+                            nextPrivateTurnDecision = undefined;
+                            nextExternalEvent = undefined;
+                            nextExternalEventHeartbeat = undefined;
+                            nextNoSend = currentNoSend;
+                            nextHabitRun = currentHabitRun;
+                        }
+                        else {
+                            finalizeCurrentHabitRun();
+                            consecutiveInstinctTurns += 1;
+                            nextReason = "instinct";
+                            nextTaskId = undefined;
+                            nextHabitName = undefined;
+                            nextAwaitName = undefined;
+                            nextTrigger = undefined;
+                            nextPrivateTurnDecision = undefined;
+                            nextExternalEvent = undefined;
+                            nextExternalEventHeartbeat = undefined;
+                            nextNoSend = undefined;
+                        }
+                        nextCompletion = currentCompletion;
+                        continue;
+                    }
+                    finalizeCurrentHabitRun();
+                    settleCurrentCompletion();
+                    break;
+                } while (true);
+            }
+            finally {
+                running = false;
+            }
+        })().catch((error) => {
+            activeCompletion?.reject(error);
+            for (const queued of queue.splice(0)) {
+                queued.stopExternalEventHeartbeat?.();
+                queued.completion.reject(error);
+            }
+        });
+        return completion.promise;
     }
     async function handleMessage(message) {
         if (!message || typeof message !== "object")
@@ -725,7 +795,7 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
                 return;
             }
             recordHabitFireForRecursion(habitName);
-            await run("habit", undefined, maybeMessage.habitName, undefined, maybeMessage.trigger ?? "overdue", maybeMessage.privateTurnDecision, maybeMessage.noSend);
+            await run("habit", undefined, maybeMessage.habitName, undefined, maybeMessage.trigger ?? "overdue", maybeMessage.privateTurnDecision, maybeMessage.noSend, undefined, maybeMessage.dispatchId);
             return;
         }
         if (maybeMessage.type === "await") {
@@ -733,7 +803,7 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
             /* v8 ignore next -- defensive fallback: live await dispatch always sets awaitName @preserve */
             const awaitName = maybeMessage.awaitName ?? "(unnamed)";
             recordHabitFireForRecursion(`await:${awaitName}`);
-            await run("await", undefined, undefined, maybeMessage.awaitName, undefined, maybeMessage.privateTurnDecision);
+            await run("await", undefined, undefined, maybeMessage.awaitName, undefined, maybeMessage.privateTurnDecision, undefined, undefined, maybeMessage.dispatchId);
             return;
         }
         if (maybeMessage.type === "heartbeat") {
@@ -743,25 +813,34 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
                 return;
             }
             recordHabitFireForRecursion("heartbeat");
-            await run("habit", undefined, "heartbeat", undefined, "overdue", maybeMessage.privateTurnDecision);
+            await run("habit", undefined, "heartbeat", undefined, "overdue", maybeMessage.privateTurnDecision, undefined, undefined, maybeMessage.dispatchId);
             return;
         }
         if (maybeMessage.type === "poke") {
             clearHeartbeatRestShield();
-            await run("instinct", maybeMessage.taskId, undefined, undefined, undefined, maybeMessage.privateTurnDecision);
+            await run("instinct", maybeMessage.taskId, undefined, undefined, undefined, maybeMessage.privateTurnDecision, undefined, undefined, maybeMessage.dispatchId);
             return;
         }
         if (maybeMessage.type === "chat" ||
             maybeMessage.type === "message") {
             clearHeartbeatRestShield();
-            await run("instinct", undefined, undefined, undefined, undefined, maybeMessage.privateTurnDecision, undefined, maybeMessage.externalEvent);
+            await run("instinct", undefined, undefined, undefined, undefined, maybeMessage.privateTurnDecision, undefined, maybeMessage.externalEvent, maybeMessage.dispatchId);
             return;
         }
         if (maybeMessage.type === "shutdown") {
             process.exit(0);
         }
     }
-    return { run, handleMessage };
+    function cancelMessage(dispatchId) {
+        const index = queue.findIndex((entry) => entry.dispatchId === dispatchId);
+        if (index < 0)
+            return false;
+        const [cancelled] = queue.splice(index, 1);
+        cancelled?.stopExternalEventHeartbeat?.();
+        cancelled?.completion.reject(new Error(`Private-runtime dispatch ${dispatchId} was cancelled.`));
+        return true;
+    }
+    return { run, handleMessage, cancelMessage };
 }
 async function startPrivateRuntimeWorker(options = {}) {
     const worker = createPrivateRuntimeWorker();

package/dist/senses/private-runtime.js

@@ -837,10 +837,13 @@ function buildHeldReturnWakeMessage() {
 }
 function buildExternalEventLeaseMessage(event) {
     const members = [event, ...(event.relatedEvents ?? [])];
+    const dispositionInstruction = members.length === 1
+        ? "Investigate the current observation, then call external_event_disposition once for this lease before settling."
+        : "Investigate the current observations, then call external_event_disposition once with one bounded batch containing every listed lease before settling.";
     return [
         "[current external-event disposition contract]",
         "This exact lease frame is authoritative for this turn. Ignore older receipts, failed tool arguments, held-work summaries, and checkpoints when choosing disposition arguments.",
-        "Investigate the current observation, then call external_event_disposition once for every listed lease before settling.",
+        dispositionInstruction,
         ...members.flatMap((member, index) => [
             "",
             `lease ${index + 1}:`,