@plurnk/plurnk-service 4.2.1 → 4.3.0

package/dist/server/DrainSupervisor.js

@@ -3,7 +3,6 @@ import { aggregateProviderAccounting } from "@plurnk/plurnk-providers";
 import { routeForSpec } from "./model-route.js";
 import ChannelWrite from "../core/ChannelWrite.js";
 import ErrorDetail from "../core/ErrorDetail.js";
-import LoopLifecycle from "../core/LoopLifecycle.js";
 import MessageResources from "../core/MessageResources.js";
 import { Knob } from "@plurnk/plurnk-meta";
 import Results, { OperationFailureError } from "../core/results.js";
@@ -23,13 +22,13 @@ export default class DrainSupervisor {
     #loopAttributions;
     #discardLoopNotices;
     #cancelSubscription;
+    #subscriptionConcluded;
+    #reapLoopStreams;
     #hasActiveStreams;
     #readSystemPrompt;
     #emitLogEntry;
     #emit;
     #completeAbandonedMessages;
-    // The handle is the drain identity. Start/exit compare by reference so an
-    // exiting drain cannot clobber a successor that raced in.
     #activeDrains = new Map();
     #settlementTasks = new Set();
     #settlementFailures = [];
@@ -40,8 +39,10 @@ export default class DrainSupervisor {
     #drainLocks = new Map();
     #admissionLocks = new Map();
     #completionWakeGates = new Map();
+    // {§notifications-stream-concluded} A closed subscription's `stream/concluded`, until it is published.
+    #streamAnnouncements = new Map();
     #acceptingWork = false;
-    constructor({ db, lifecycle, injectPrompt, assertInjectionCompatibility, runLoop, loopUsage, loopAttributions, discardLoopNotices, cancelSubscription, hasActiveStreams, readSystemPrompt, emitLogEntry, emit, completeAbandonedMessages, }) {
+    constructor({ db, lifecycle, injectPrompt, assertInjectionCompatibility, runLoop, loopUsage, loopAttributions, discardLoopNotices, cancelSubscription, subscriptionConcluded, reapLoopStreams, hasActiveStreams, readSystemPrompt, emitLogEntry, emit, completeAbandonedMessages, }) {
         this.#completeAbandonedMessages = completeAbandonedMessages ?? (async () => { });
         this.#db = db;
         this.#lifecycle = lifecycle;
@@ -52,6 +53,8 @@ export default class DrainSupervisor {
         this.#loopAttributions = loopAttributions;
         this.#discardLoopNotices = discardLoopNotices;
         this.#cancelSubscription = cancelSubscription;
+        this.#subscriptionConcluded = subscriptionConcluded;
+        this.#reapLoopStreams = reapLoopStreams;
         this.#hasActiveStreams = hasActiveStreams;
         this.#readSystemPrompt = readSystemPrompt;
         this.#emitLogEntry = emitLogEntry;
@@ -153,7 +156,7 @@ export default class DrainSupervisor {
             return { action: "enqueued_new_loop", ...accepted };
         }));
         const started = await this.ensureDrain({ workspaceId, workerId, systemPrompt: args.systemPrompt });
-        return { ...delivery, ...(started ?? {}) };
+        return { ...delivery, ...started };
     }
     async #enqueueFreshLoop(args) {
         // {§worker-model-selection} — resolve the complete route before persistence;
@@ -190,254 +193,247 @@ export default class DrainSupervisor {
         // The drain runs under the worker's cancellation scope (shared with the
         // execs its loops spawn), so loop.cancel/shutdown abort it as a unit.
         const controller = this.#workerSignal(workerId);
-        const handle = {
-            controller, promise: Promise.resolve(),
-        };
-        let resolveFirst = () => { };
-        let rejectFirst = () => { };
-        const firstLoopPromise = new Promise((res, rej) => {
-            resolveFirst = res;
-            rejectFirst = rej;
-        });
-        let firstSettled = false;
-        const claim = () => this.#db.drain_claim_next_loop.get({ worker_id: workerId });
-        const drainPromise = (async () => {
-            let loopsDrained = 0;
-            let lastResult = null;
-            let currentLoopId = null; // the loop being drained — for abort→499 settlement
-            try {
-                while (true) {
-                    controller.signal.throwIfAborted();
-                    let loopRow = await claim();
-                    if (loopRow === undefined) {
-                        // {§worker-lifecycle-no-lost-loop}
-                        // Queue empty → teardown UNDER the per-worker drain lock (R4 / I1),
-                        // serialized against ensureDrain so a concurrent inject can't
-                        // start a 2nd drain in the gap. Re-claim while holding the lock;
-                        // relinquish the registry slot only if it's empty too. A loop
-                        // that raced in is returned and run — we stay registered, so
-                        // there's no transient delete for ensureDrain to catch.
-                        loopRow = await this.#withDrainLock(workerId, async () => {
-                            const claimed = await claim();
-                            if (claimed === undefined && this.#activeDrains.get(workerId) === handle) {
-                                this.#activeDrains.delete(workerId);
-                            }
-                            return claimed;
-                        });
-                        if (loopRow === undefined)
-                            break;
-                    }
-                    currentLoopId = loopRow.id;
-                    this.#clearLoopTimer(loopRow.id);
-                    await this.#emitLoopStatus(workspaceId, workerId, loopRow.id, 102);
-                    const onSettled = async (logEntryId) => {
-                        await this.#emitLogEntry(workspaceId, logEntryId).catch((error) => {
-                            console.error("log/entry broadcast failed:", error instanceof Error ? error.message : String(error));
-                        });
-                    };
-                    const result = await observed("loop.run", { workspaceId, workerId, "loop.id": loopRow.id }, async (span) => {
-                        const loopResult = await this.#runLoop({
-                            workspaceId,
-                            workerId,
-                            loopId: loopRow.id,
-                            maxTurns: loopRow.max_turns,
-                            prompt: loopRow.prompt,
-                            systemPrompt,
-                            signal: controller.signal,
-                            onSettled,
-                        });
-                        span.setAttribute("status", loopResult.result.status);
-                        recordCounter(LOOP_TERMINALS, { status: loopResult.result.status });
-                        return loopResult;
-                    });
-                    if (result.result.status === 202) {
-                        await this.#withDrainLock(workerId, () => this.#emitLoopStatus(workspaceId, workerId, loopRow.id, 202));
-                        // The loop parked — suspended, not terminated. Leave it at 202
-                        // (resumable); no loop/terminated, no orphan-reconcile. A stream conclusion
-                        // through handleWakeWorker re-queues it; the durable wait deadline also
-                        // wakes it to inspect ({§worker-wait-timing}). {§worker-lifecycle-wake-liveness}.
-                        await this.scheduleWakes(workspaceId, workerId, systemPrompt);
-                        // Serialize the park boundary against message injection.
-                        // Whichever side arrives first owns a wake edge: injection wakes
-                        // an already-parked loop, while this check wakes a message written
-                        // just before runLoop finished parking.
-                        const messageWaiting = await this.#withDrainLock(workerId, async () => {
-                            const unpublished = await this.#db.drain_unpublished_messages_for_loop.get({ loop_id: loopRow.id });
-                            if (unpublished === undefined)
-                                return false;
-                            return this.#wakeLoop(workspaceId, workerId, loopRow.id);
-                        });
-                        if (messageWaiting) {
-                            currentLoopId = null;
-                            continue;
-                        }
-                        // {§loop-wake-identity}: events observed by another loop
-                        // cannot consume this loop's completion wake.
-                        if (await this.#withDrainLock(workerId, () => this.#wakeLoop(workspaceId, workerId, loopRow.id, { eventOnly: true }))) {
-                            currentLoopId = null;
-                            continue;
-                        }
-                        // {§loop-wake-identity}: the wait now belongs to its completion
-                        // obligations and inherited observation, not this drain.
-                        currentLoopId = null;
-                        continue;
-                    }
-                    const [usage, attributions, turnIds] = await Promise.all([
-                        this.#loopUsage(loopRow.id),
-                        this.#loopAttributions(loopRow.id),
-                        this.#lifecycle.turnIds(loopRow.id),
-                    ]);
-                    await this.#publishTermination(workspaceId, {
-                        workerId,
-                        loopId: loopRow.id,
-                        result: result.result,
-                        hitMaxTurns: result.hitMaxTurns,
-                        turnIds,
-                        usage,
-                        attributions,
-                    });
-                    loopsDrained++;
-                    const loopResult = {
-                        loopId: loopRow.id,
-                        turnIds,
-                        result: result.result,
-                        hitMaxTurns: result.hitMaxTurns,
-                        usage,
-                        attributions,
-                    };
-                    lastResult = loopResult;
-                    if (!firstSettled) {
-                        firstSettled = true;
-                        resolveFirst(loopResult);
-                    }
-                    // A message this loop ended before publishing (a wake conclusion or a
-                    // runLoop-while-active arrival) is promoted to a fresh queued loop so it's
-                    // never silently dropped ({§message-loop-containment}).
-                    await this.reconcileOrphanedMessages(workerId, loopRow.id);
-                    await this.#abandonUnanswered(workspaceId, workerId, loopRow.id, result.result.status);
+        const handle = { controller, promise: Promise.resolve() };
+        const firstLoop = Promise.withResolvers();
+        const first = { settled: false, resolve: firstLoop.resolve, reject: firstLoop.reject };
+        const drainPromise = this.#drain({ workspaceId, workerId, systemPrompt, controller, handle, first });
+        handle.promise = drainPromise;
+        this.#activeDrains.set(workerId, handle);
+        // Swallow unhandled rejections (drain aborts with no awaiter); the
+        // error already surfaced via firstLoopPromise or was logged inside.
+        drainPromise.catch(() => { });
+        firstLoop.promise.catch(() => { });
+        return { firstLoopPromise: firstLoop.promise, drainPromise };
+    }
+    // The drain itself: claim, run, then park or conclude, until the queue is empty under the lock. A
+    // cancellation or a failure settles the loop in flight before the drain exits, the first loop's
+    // settlement is delivered exactly once, and the exit always schedules the worker's wakes.
+    async #drain(scope) {
+        const { workspaceId, workerId, systemPrompt, controller, handle, first } = scope;
+        let loopsDrained = 0;
+        let lastResult = null;
+        let currentLoopId = null; // the loop being drained — for abort→499 settlement
+        try {
+            while (true) {
+                controller.signal.throwIfAborted();
+                const loopRow = await this.#claimLoop(workerId, handle);
+                if (loopRow === undefined)
+                    break;
+                currentLoopId = loopRow.id;
+                const result = await this.#runClaimedLoop(scope, loopRow);
+                if (result.result.status === 202) {
+                    await this.#parkLoop(scope, loopRow.id);
                     currentLoopId = null;
+                    continue;
                 }
-            }
-            catch (err) {
-                if (controller.signal.aborted) {
-                    // {§methods-loop-cancel} — loop.cancel / shutdown aborted the live drain. A cancellation
-                    // is the loop's TERMINAL state (499), delivered via loop/terminated (runLoop no
-                    // longer blocks to return it). A genuine error rejects firstLoopPromise.
-                    let usage = {
-                        accounting: aggregateProviderAccounting([]),
-                        curationWeight: null,
-                        curationBudget: null,
-                        contextTokens: null,
-                        contextCapacity: null,
-                        meta: {},
-                    };
-                    let attributions = [];
-                    const message = ErrorDetail.preview(controller.signal.reason ?? "user_cancelled")
-                        || "no reason was supplied";
-                    if (currentLoopId !== null) {
-                        // {§methods-loop-cancel}/{§worker-lifecycle-terminal-result} —
-                        // persist the exact 499 cancellation result before broadcasting it.
-                        const cancelled = await this.#lifecycle.finish(currentLoopId, Results.failure("lifecycle:cancel", "loop-cancelled", 499, `The loop was cancelled: ${message}.`, {}, {
-                            reason: message,
-                            stage: "loop",
-                            retryable: false,
-                        }), { terminatedBy: "cancel" });
-                        [usage, attributions] = await Promise.all([
-                            this.#loopUsage(currentLoopId),
-                            this.#loopAttributions(currentLoopId),
-                        ]);
-                        if (cancelled !== null) {
-                            await this.#publishTermination(workspaceId, {
-                                workerId,
-                                loopId: currentLoopId,
-                                result: cancelled,
-                                hitMaxTurns: false,
-                                turnIds: await this.#lifecycle.turnIds(currentLoopId),
-                                usage,
-                                attributions,
-                            });
-                            await this.#abandonUnanswered(workspaceId, workerId, currentLoopId, cancelled.status);
-                        }
-                    }
-                    if (!firstSettled) {
-                        firstSettled = true;
-                        resolveFirst({
-                            loopId: currentLoopId ?? 0,
-                            turnIds: [],
-                            result: currentLoopId === null
-                                ? Results.failure("lifecycle:cancel", "loop-cancelled", 499, `The loop was cancelled: ${message}.`, {}, {
-                                    reason: message,
-                                    stage: "loop",
-                                    retryable: false,
-                                })
-                                : await this.#lifecycle.result(currentLoopId)
-                                    ?? Results.failure("lifecycle:cancel", "loop-cancelled", 499, `The loop was cancelled: ${message}.`, {}, {
-                                        reason: message,
-                                        stage: "loop",
-                                        retryable: false,
-                                    }),
-                            hitMaxTurns: false,
-                            usage,
-                        });
-                    }
-                }
-                else {
-                    // {§worker-lifecycle-terminal-result} — a non-abort drain
-                    // failure becomes an exact durable 500 and terminal notification;
-                    // daemon diagnostics retain the complete caught error.
-                    console.error(`drain error (workspace ${workspaceId}, worker ${workerId}, loop ${currentLoopId ?? "?"}):`, err);
-                    if (currentLoopId !== null) {
-                        const failure = err instanceof OperationFailureError
-                            ? err.result
-                            : Results.failure("daemon:drain", "loop-threw", 500, "The loop failed outside its operation result contract.", {}, {
-                                stage: "loop",
-                                retryable: false,
-                            });
-                        const settled = await this.#lifecycle.finish(currentLoopId, failure)
-                            ?? await this.#lifecycle.result(currentLoopId);
-                        if (settled === null) {
-                            throw new Error(`drain could not settle loop ${currentLoopId}`, { cause: err });
-                        }
-                        const [usage, attributions] = await Promise.all([
-                            this.#loopUsage(currentLoopId),
-                            this.#loopAttributions(currentLoopId),
-                        ]);
-                        await this.#publishTermination(workspaceId, {
-                            workerId,
-                            loopId: currentLoopId,
-                            result: settled,
-                            hitMaxTurns: false,
-                            turnIds: await this.#lifecycle.turnIds(currentLoopId),
-                            usage,
-                            attributions,
-                        });
-                        await this.#abandonUnanswered(workspaceId, workerId, currentLoopId, settled.status);
-                    }
-                    if (!firstSettled) {
-                        firstSettled = true;
-                        rejectFirst(err);
-                    }
+                const { loopResult, announced } = await this.#concludeLoop(scope, loopRow.id, result);
+                loopsDrained++;
+                lastResult = loopResult;
+                if (!first.settled) {
+                    first.settled = true;
+                    first.resolve(loopResult);
                 }
-                throw err;
+                // A message this loop ended before publishing (a wake conclusion or a
+                // runLoop-while-active arrival) is promoted to a fresh queued loop so it's
+                // never silently dropped ({§message-loop-containment}).
+                await this.reconcileOrphanedMessages(workerId, loopRow.id);
+                if (announced)
+                    await this.#abandonUnanswered(workspaceId, workerId, loopRow.id, result.result.status);
+                currentLoopId = null;
+            }
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                await this.#settleCancelledDrain(scope, currentLoopId);
+            else
+                await this.#settleFailedDrain(scope, currentLoopId, err);
+            throw err;
+        }
+        finally {
+            if (!first.settled) {
+                first.settled = true;
+                first.reject(new Error("drain exited without producing a result"));
+            }
+            if (this.#activeDrains.get(workerId) === handle)
+                this.#activeDrains.delete(workerId);
+            await this.scheduleWakes(workspaceId, workerId, systemPrompt);
+        }
+        return { loopsDrained, lastResult };
+    }
+    // {§worker-lifecycle-no-lost-loop} The next queued loop. An empty queue is re-claimed UNDER the per-worker
+    // drain lock (R4 / I1), serialized against ensureDrain so a concurrent inject can't start a 2nd drain
+    // in the gap; the registry slot is relinquished only if it is empty there too, and a loop that raced in
+    // is returned and run — the drain stays registered, so there's no transient delete for ensureDrain to
+    // catch.
+    async #claimLoop(workerId, handle) {
+        const claim = () => this.#db.drain_claim_next_loop.get({ worker_id: workerId });
+        const claimed = await claim();
+        if (claimed !== undefined)
+            return claimed;
+        return this.#withDrainLock(workerId, async () => {
+            const reclaimed = await claim();
+            if (reclaimed === undefined && this.#activeDrains.get(workerId) === handle) {
+                this.#activeDrains.delete(workerId);
+            }
+            return reclaimed;
+        });
+    }
+    // One claimed loop under observation: its timer cleared, 102 announced, every settled row broadcast.
+    async #runClaimedLoop(scope, loopRow) {
+        const { workspaceId, workerId, systemPrompt, controller } = scope;
+        this.#clearLoopTimer(loopRow.id);
+        await this.#emitLoopStatus(workspaceId, workerId, loopRow.id, 102);
+        const onSettled = async (logEntryId) => {
+            await this.#emitLogEntry(workspaceId, logEntryId).catch((error) => {
+                console.error("log/entry broadcast failed:", error instanceof Error ? error.message : String(error));
+            });
+        };
+        return observed("loop.run", { workspaceId, workerId, "loop.id": loopRow.id }, async (span) => {
+            const loopResult = await this.#runLoop({
+                workspaceId,
+                workerId,
+                loopId: loopRow.id,
+                maxTurns: loopRow.max_turns,
+                prompt: loopRow.prompt,
+                systemPrompt,
+                signal: controller.signal,
+                onSettled,
+            });
+            span.setAttribute("status", loopResult.result.status);
+            recordCounter(LOOP_TERMINALS, { status: loopResult.result.status });
+            return loopResult;
+        });
+    }
+    // A parked loop (202) is suspended, not terminated: it stays resumable, with no loop/terminated and no
+    // orphan reconcile. A stream conclusion through handleWakeWorker re-queues it; the durable wait deadline
+    // also wakes it to inspect ({§worker-wait-timing}). {§worker-lifecycle-wake-liveness}
+    async #parkLoop(scope, loopId) {
+        const { workspaceId, workerId, systemPrompt } = scope;
+        await this.#withDrainLock(workerId, () => this.#emitLoopStatus(workspaceId, workerId, loopId, 202));
+        await this.scheduleWakes(workspaceId, workerId, systemPrompt);
+        // Serialize the park boundary against message injection.
+        // Whichever side arrives first owns a wake edge: injection wakes
+        // an already-parked loop, while this check wakes a message written
+        // just before runLoop finished parking.
+        const messageWaiting = await this.#withDrainLock(workerId, async () => {
+            const unpublished = await this.#db.drain_unpublished_messages_for_loop.get({ loop_id: loopId });
+            if (unpublished === undefined)
+                return false;
+            return this.#wakeLoop(workspaceId, workerId, loopId);
+        });
+        if (messageWaiting)
+            return;
+        // {§loop-wake-identity}: events observed by another loop cannot consume this loop's completion
+        // wake. Whether or not one wakes it here, the wait now belongs to its completion obligations and
+        // inherited observation, not this drain.
+        await this.#withDrainLock(workerId, () => this.#wakeLoop(workspaceId, workerId, loopId, { eventOnly: true }));
+    }
+    // A loop's terminal: its streams reaped, usage, attributions and turns gathered, loop/terminated published, and
+    // the result the drain reports. A loop a cancellation retired is reaped and announced by that cancellation instead.
+    async #concludeLoop(scope, loopId, result) {
+        const { workspaceId, workerId } = scope;
+        const cancelled = await this.#lifecycle.cancelled(loopId);
+        // {§notifications-loop-terminated} {§exec-lifetime} The streams the loop's terminal reaps conclude before it is announced.
+        if (!cancelled)
+            await this.#reapLoop(loopId);
+        const [usage, attributions, turnIds] = await Promise.all([
+            this.#loopUsage(loopId),
+            this.#loopAttributions(loopId),
+            this.#lifecycle.turnIds(loopId),
+        ]);
+        const loopResult = {
+            loopId: loopId,
+            turnIds,
+            result: result.result,
+            hitMaxTurns: result.hitMaxTurns,
+            usage,
+            attributions,
+        };
+        if (!cancelled)
+            await this.#publishTermination(workspaceId, { workerId, ...loopResult });
+        return { loopResult, announced: !cancelled };
+    }
+    // {§methods-loop-cancel} loop.cancel / shutdown aborted the live drain. A cancellation is the loop's
+    // TERMINAL state (499), delivered via loop/terminated (runLoop no longer blocks to return it), and the
+    // exact 499 is persisted before it is broadcast ({§worker-lifecycle-terminal-result}).
+    async #settleCancelledDrain(scope, currentLoopId) {
+        const { workspaceId, workerId, controller, first } = scope;
+        const message = ErrorDetail.preview(controller.signal.reason ?? "user_cancelled")
+            || "no reason was supplied";
+        const cancelledResult = () => Results.failure("lifecycle:cancel", "loop-cancelled", 499, `The loop was cancelled: ${message}.`, {}, {
+            reason: message,
+            stage: "loop",
+            retryable: false,
+        });
+        let usage = {
+            accounting: aggregateProviderAccounting([]),
+            curationWeight: null,
+            curationBudget: null,
+            contextTokens: null,
+            contextCapacity: null,
+            meta: {},
+        };
+        let attributions = [];
+        if (currentLoopId !== null) {
+            const cancelled = await this.#lifecycle.finish(currentLoopId, cancelledResult(), { terminatedBy: "cancel" });
+            [usage, attributions] = await Promise.all([
+                this.#loopUsage(currentLoopId),
+                this.#loopAttributions(currentLoopId),
+            ]);
+            if (cancelled !== null) {
+                await this.#reapLoop(currentLoopId);
+                await this.#publishTermination(workspaceId, {
+                    workerId,
+                    loopId: currentLoopId,
+                    result: cancelled,
+                    hitMaxTurns: false,
+                    turnIds: await this.#lifecycle.turnIds(currentLoopId),
+                    usage,
+                    attributions,
+                });
+                await this.#abandonUnanswered(workspaceId, workerId, currentLoopId, cancelled.status);
             }
-            finally {
-                if (!firstSettled) {
-                    firstSettled = true;
-                    rejectFirst(new Error("drain exited without producing a result"));
+        }
+        if (!first.settled) {
+            first.settled = true;
+            first.resolve({
+                loopId: currentLoopId ?? 0,
+                turnIds: [],
+                result: currentLoopId === null
+                    ? cancelledResult()
+                    : await this.#lifecycle.result(currentLoopId) ?? cancelledResult(),
+                hitMaxTurns: false,
+                usage,
+            });
+        }
+    }
+    // {§worker-lifecycle-terminal-result} A non-abort drain failure becomes an exact durable 500 and terminal
+    // notification; daemon diagnostics retain the complete caught error.
+    async #settleFailedDrain(scope, currentLoopId, err) {
+        const { workspaceId, workerId, first } = scope;
+        console.error(`drain error (workspace ${workspaceId}, worker ${workerId}, loop ${currentLoopId ?? "?"}):`, err);
+        if (currentLoopId !== null) {
+            const failure = err instanceof OperationFailureError
+                ? err.result
+                : Results.failure("daemon:drain", "loop-threw", 500, "The loop failed outside its operation result contract.", {}, {
+                    stage: "loop",
+                    retryable: false,
+                });
+            const finished = await this.#lifecycle.finish(currentLoopId, failure);
+            // A loop a cancellation retired is that cancellation's to announce.
+            if (finished !== null || !await this.#lifecycle.cancelled(currentLoopId)) {
+                const settled = finished ?? await this.#lifecycle.result(currentLoopId);
+                if (settled === null) {
+                    throw new Error(`drain could not settle loop ${currentLoopId}`, { cause: err });
                 }
-                if (this.#activeDrains.get(workerId) === handle)
-                    this.#activeDrains.delete(workerId);
-                await this.scheduleWakes(workspaceId, workerId, systemPrompt);
+                await this.#reapLoop(currentLoopId);
+                await this.#announce(workspaceId, workerId, currentLoopId, settled);
             }
-            return { loopsDrained, lastResult };
-        })();
-        handle.promise = drainPromise;
-        this.#activeDrains.set(workerId, handle);
-        // Swallow unhandled rejections (drain aborts with no awaiter); the
-        // error already surfaced via firstLoopPromise or was logged inside.
-        drainPromise.catch(() => { });
-        firstLoopPromise.catch(() => { });
-        return { firstLoopPromise, drainPromise };
+        }
+        if (!first.settled) {
+            first.settled = true;
+            first.reject(err);
+        }
     }
     // Per-worker drain-transition lock (R4 / {§worker-lifecycle-single-drain}). ensureDrain's
     // start and a drain's teardown relinquish both run under it, serialized, so the two
@@ -523,10 +519,11 @@ export default class DrainSupervisor {
         const owner = await this.#db.drain_get_worker_workspace.get({ worker_id: workerId });
         if (owner === undefined)
             throw new Error(`cancellation worker ${workerId} does not exist`);
-        const { cancelled, subscriptions } = await this.#withAdmissionLock(owner.workspace_id, async () => {
-            const cancelled = await this.#lifecycle.cancelTree(workerId, reason, includeRoot);
-            const subscriptions = (await Promise.all(cancelled.workerIds.map((id) => ChannelWrite.findOpenSubscriptionsForWorker(this.#db, id)))).flat();
-            for (const targetWorkerId of cancelled.workerIds) {
+        const { cancelled, subscriptions, drains } = await this.#withAdmissionLock(owner.workspace_id, async () => {
+            const tree = await this.#lifecycle.cancelTree(workerId, reason, includeRoot);
+            const open = await Promise.all(tree.workerIds.map(async (id) => [id, await ChannelWrite.findOpenSubscriptionsForWorker(this.#db, id)]));
+            const draining = new Map();
+            for (const targetWorkerId of tree.workerIds) {
                 for (const [loopId, timer] of this.#loopTimers) {
                     if (timer.workerId === targetWorkerId)
                         this.#clearLoopTimer(loopId);
@@ -534,32 +531,43 @@ export default class DrainSupervisor {
                 const scope = this.#workerAborts.get(targetWorkerId);
                 if (scope !== undefined && !scope.signal.aborted)
                     scope.abort(reason);
+                const drain = this.#activeDrains.get(targetWorkerId);
+                if (drain !== undefined)
+                    draining.set(targetWorkerId, drain.promise);
             }
-            return { cancelled, subscriptions };
+            return { cancelled: tree, subscriptions: new Map(open), drains: draining };
         });
-        await Promise.all(subscriptions.map(({ id }) => this.#cancelSubscription(id)));
+        await Promise.all([...subscriptions.values()].flat().map(({ id }) => this.#cancelSubscription(id)));
         for (const { loopId, workerId: targetWorkerId, result } of cancelled.loops) {
             const row = await this.#db.drain_get_worker_workspace.get({
                 worker_id: targetWorkerId,
             });
             if (row === undefined)
                 continue;
-            const [usage, attributions] = await Promise.all([
-                this.#loopUsage(loopId),
-                this.#loopAttributions(loopId),
-            ]);
-            await this.#publishTermination(row.workspace_id, {
-                workerId: targetWorkerId,
-                loopId,
-                result,
-                hitMaxTurns: false,
-                turnIds: await this.#lifecycle.turnIds(loopId),
-                usage,
-                attributions,
-            });
-            await this.#abandonUnanswered(row.workspace_id, targetWorkerId, loopId, result.status);
+            const announce = () => this.#announce(row.workspace_id, targetWorkerId, loopId, result);
+            // {§notifications-loop-terminated} What a retired loop held settles as its worker's drain unwinds the turn
+            // and its streams close; the terminal follows both. The caller is not held: it may be that turn.
+            const drain = drains.get(targetWorkerId);
+            const held = [
+                ...drain === undefined ? [] : [drain],
+                ...(subscriptions.get(targetWorkerId) ?? []).map(({ id }) => this.#streamConcluded(id)),
+            ];
+            if (held.length === 0)
+                await announce();
+            else
+                void this.#trackSettlement(Promise.allSettled(held).then(announce), `announce(${loopId})`);
         }
     }
+    // A terminal loop's loop/terminated, then what it left unanswered answered for it.
+    async #announce(workspaceId, workerId, loopId, result) {
+        const [usage, attributions, turnIds] = await Promise.all([
+            this.#loopUsage(loopId),
+            this.#loopAttributions(loopId),
+            this.#lifecycle.turnIds(loopId),
+        ]);
+        await this.#publishTermination(workspaceId, { workerId, loopId, result, hitMaxTurns: false, turnIds, usage, attributions });
+        await this.#abandonUnanswered(workspaceId, workerId, loopId, result.status);
+    }
     // {§message-abandonment} — after a loop's end is durable and published, whatever it left unanswered is
     // answered for it. A failure here is logged, never a second failure of the loop that already ended.
     async #abandonUnanswered(workspaceId, workerId, loopId, status) {
@@ -585,17 +593,37 @@ export default class DrainSupervisor {
     // {§module-shutdown-order}: the producer emits synchronously, while the
     // supervisor owns the asynchronous scheduler work and its shutdown truth.
     notifyWakeWorker(payload) {
-        this.#trackSettlement(this.#handleWakeWorker(payload), "wake-on-completion");
+        const { subscriptionId } = payload;
+        const announced = Promise.withResolvers();
+        const announcement = { workerId: payload.workerId, delivered: announced.promise };
+        this.#streamAnnouncements.set(subscriptionId, announcement);
+        const handled = this.#handleWakeWorker(payload, announced.resolve).finally(() => {
+            announced.resolve();
+            if (this.#streamAnnouncements.get(subscriptionId) === announcement)
+                this.#streamAnnouncements.delete(subscriptionId);
+        });
+        void this.#trackSettlement(handled, "wake-on-completion");
+    }
+    // {§notifications-loop-terminated} A subscription's conclusion as its observers receive it: its close delivered,
+    // then its `stream/concluded` published.
+    async #streamConcluded(subscriptionId) {
+        await this.#subscriptionConcluded(subscriptionId);
+        await this.#streamAnnouncements.get(subscriptionId)?.delivered;
+    }
+    // {§notifications-loop-terminated} {§exec-lifetime} What the loop's terminal reaps, concluded and announced.
+    async #reapLoop(loopId) {
+        const reaped = await this.#reapLoopStreams(loopId);
+        await Promise.all(reaped.map((subscriptionId) => this.#streamConcluded(subscriptionId)));
     }
     async operationSettled(workspaceId, logEntryId) {
         const recipients = await this.#db.message_reply_recipients.all({ log_entry_id: logEntryId });
         if (recipients.length === 0)
             return;
-        const systemPrompt = await this.#readSystemPrompt();
+        const systemPrompt = await this.#readSystemPrompt(); // {§card-read-per-wake}
         for (const { worker_id: workerId } of recipients) {
             // {§worker-optimistic-settlement}: the sender must finish its own
             // program while the recipient coalesces replies and conclusions.
-            this.#trackSettlement(this.settleCompletionWake(workspaceId, workerId, systemPrompt), "wake-on-reply");
+            void this.#trackSettlement(this.settleCompletionWake(workspaceId, workerId, systemPrompt), "wake-on-reply");
         }
     }
     #trackSettlement(task, label) {
@@ -607,19 +635,21 @@ export default class DrainSupervisor {
         });
         return task;
     }
-    async #handleWakeWorker(payload) {
+    async #handleWakeWorker(payload, announced) {
         const { workspaceId, ...conclusion } = payload;
+        const conclude = (wakeAction) => {
+            this.#emit(workspaceId, "stream/concluded", { ...conclusion, wakeAction });
+            announced();
+        };
         // {§worker-lifecycle-no-resurrection}: scope cancellation, not the
         // command's result code, prevents a wake. Cancelling one command still
         // produces an observation owed to its live worker.
         const scope = this.#workerAborts.get(payload.workerId);
         if (scope?.signal.aborted === true) {
-            this.#emit(workspaceId, "stream/concluded", {
-                ...conclusion, wakeAction: payload.result.status === 499 ? "skipped-aborted" : "skipped-cancelled",
-            });
+            conclude(payload.result.status === 499 ? "skipped-aborted" : "skipped-cancelled");
             return;
         }
-        const systemPrompt = await this.#readSystemPrompt();
+        const systemPrompt = await this.#readSystemPrompt(); // {§card-read-per-wake}
         // {§notifications-stream-concluded}: publish the terminal stream fact
         // before settlement. Rechecked wait identities, not this event, decide
         // whether any loop actually resumes.
@@ -629,25 +659,19 @@ export default class DrainSupervisor {
             // then let the worker-local gate coalesce only the provider
             // dispatch. Concurrent stream/child callbacks join that one gate.
             const settlement = this.settleCompletionWake(workspaceId, payload.workerId, systemPrompt);
-            this.#emit(workspaceId, "stream/concluded", {
-                ...conclusion, wakeAction: "wake-pending",
-            });
+            conclude("wake-pending");
             await settlement;
             return;
         }
         // No slept loop. A live loop surfaces the concluded stream ambiently via the
         // environment-observation injector ({§exec-stream}) on its next turn; the client is told.
         if (this.#activeDrains.has(payload.workerId)) {
-            this.#emit(workspaceId, "stream/concluded", {
-                ...conclusion, wakeAction: "no-op-active-loop",
-            });
+            conclude("no-op-active-loop");
             return;
         }
         // No slept loop, no active drain — nothing to resume (e.g. a completed worker whose
         // streams were swept). Surface the conclusion without opening a loop.
-        this.#emit(workspaceId, "stream/concluded", {
-            ...conclusion, wakeAction: "no-loop",
-        });
+        conclude("no-loop");
     }
     #clearLoopTimer(loopId) {
         const current = this.#loopTimers.get(loopId);
@@ -685,7 +709,7 @@ export default class DrainSupervisor {
             if (this.#loopTimers.get(loopId)?.timer !== timer)
                 return;
             this.#loopTimers.delete(loopId);
-            this.#trackSettlement(this.#wakeTimedLoop(workspaceId, workerId, systemPrompt, loopId, revision), "wake-on-completion");
+            void this.#trackSettlement(this.#wakeTimedLoop(workspaceId, workerId, systemPrompt, loopId, revision), "wake-on-completion");
         }, Math.max(1, Math.min(dueAt - Date.now(), 2_147_483_647)));
         timer.unref();
         this.#loopTimers.set(loopId, { workerId, revision, dueAt, timer });
@@ -707,9 +731,9 @@ export default class DrainSupervisor {
         if (wait === undefined)
             return;
         const waitUntil = wait?.wait_poll_at ?? null;
-        const { claimedAt, packetCount } = await this.#lifecycle.observation(loopId);
+        const { loopSeq, claimedAt, packetCount } = await this.#lifecycle.observation(loopId);
         this.#emit(workspaceId, "notice/event", {
-            workerId, loopId, notice: { source: "engine:lifecycle", kind: "loop_status", level: "info", status, waitUntil, packetCount, claimedAt },
+            workerId, loopId, notice: { source: "engine:lifecycle", kind: "loop_status", level: "info", status, loopSeq, waitUntil, packetCount, claimedAt },
         });
     }
     async #wakeLoop(workspaceId, workerId, loopId, condition = {}) {
@@ -825,10 +849,14 @@ export default class DrainSupervisor {
     }
     // {§notifications-loop-terminated} — the terminal carries the stamp a snapshot reads.
     async #publishTermination(workspaceId, event) {
-        const { terminatedAt } = await this.#lifecycle.observation(event.loopId);
+        const { loopSeq, terminatedAt } = await this.#lifecycle.observation(event.loopId);
+        // A durable close releases the live handle before its announcement is delivered.
+        await Promise.all([...this.#streamAnnouncements.values()]
+            .filter(({ workerId }) => workerId === event.workerId)
+            .map(({ delivered }) => delivered));
         this.#discardLoopNotices(event.loopId);
-        this.#emit(workspaceId, "loop/terminated", { ...event, terminatedAt });
-        this.#trackSettlement(this.#notifyParentCompletion(workspaceId, event.workerId), "wake-on-completion");
+        this.#emit(workspaceId, "loop/terminated", { ...event, loopSeq, terminatedAt });
+        void this.#trackSettlement(this.#notifyParentCompletion(workspaceId, event.workerId), "wake-on-completion");
     }
     // {§worker-lifecycle-child-wake}: completion belongs to a task, not drain teardown.
     async #notifyParentCompletion(workspaceId, workerId) {