@plurnk/plurnk-service 1.4.0 → 1.5.0

package/dist/server/Daemon.js

@@ -2,6 +2,7 @@
 // the transport-free plugin-module seam ({§rpc}).
 import { readFile } from "node:fs/promises";
 import { resolve, dirname } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { execPollBackoffMs } from "./exec-poll-backoff.js";
 import ChannelWrite from "../core/ChannelWrite.js";
 import { Paths } from "../index.js";
@@ -32,6 +33,7 @@ import BranchBatches from "./BranchBatches.js";
 import ErrorDetail from "../core/ErrorDetail.js";
 import { observed, observedSync } from "../observe/spans.js";
 import { LOOP_TERMINALS, recordCounter } from "../observe/metrics.js";
+import { readOptimisticSettlementMs } from "../core/optimistic-settlement.js";
 const clientActionFailure = (error) => {
     if (error instanceof OperationFailureError)
         return error.result;
@@ -72,6 +74,7 @@ export default class Daemon {
     // (subscriptions + Exec.idle), and a concluding stream routes through
     // inject() like any other loop source.
     #activeDrains = new Map();
+    #drainExitTasks = new Set();
     // Per-worker cancellation scope. Loops AND the streams they spawn (execs)
     // share this signal, so loop.cancel / shutdown abort it once and every
     // in-flight subscription tears down — even a spawn that registers AFTER the
@@ -93,6 +96,10 @@ export default class Daemon {
     // never deadlock. The drain honors the owed wake at the worker's next park, closing the conclude-
     // before-park race. (Only a live exec stream, unbounded absent a timeout, may hold a park open.)
     #owedWakes = new Set();
+    // {§worker-optimistic-settlement} — one non-sliding completion-wake batch
+    // per worker. Durable conclusions and client events land before this gate;
+    // only the parked loop's provider-dispatch requeue waits.
+    #completionWakeGates = new Map();
     constructor({ db, schemes, mimetypes, provider, nodeModulesPath, }) {
         this.#db = db;
         this.#lifecycle = new LoopLifecycle(db);
@@ -126,10 +133,9 @@ export default class Daemon {
         });
         this.#branchBatches = new BranchBatches(db, this.#workspaceGate, {
             settleWorkspace: async (workspaceId) => this.#engine.drainWorkspaceDerivations(workspaceId),
-            createChild: async ({ workspaceId, parentWorkerId, op, name, prompt, flags, origin }) => {
-                const providerSpec = resolveActiveAlias();
-                if (providerSpec === null)
-                    throw new Error("Branch worker: active provider has no resolvable alias");
+            createChild: async ({ workspaceId, parentWorkerId, parentLoopId, op, name, prompt, flags, origin }) => {
+                const parentPolicy = await this.#providerPolicyForLoop(parentLoopId);
+                const providerSpec = parentPolicy.childProviderSpec ?? parentPolicy.providerSpec;
                 const workerName = WorkerName.assert(name);
                 const workerId = op === "FORK"
                     ? await Fork.fork(this.#db, parentWorkerId, workerName)
@@ -145,6 +151,7 @@ export default class Daemon {
                     workerId,
                     prompt,
                     providerSpec,
+                    childProviderSpec: parentPolicy.childProviderSpec,
                     flags,
                 });
                 return { workerId, loopId };
@@ -162,7 +169,7 @@ export default class Daemon {
             },
             wakeParent: async (workspaceId, workerId) => {
                 const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
-                await this.#wakeParkedWorker(workspaceId, workerId, systemPrompt, false);
+                await this.#settleCompletionWake(workspaceId, workerId, systemPrompt, false);
             },
             notify: (workspaceId, payload) => {
                 this.#broadcast({ workspaceId }, "workspace/branch-batch", payload);
@@ -182,14 +189,25 @@ export default class Daemon {
             // daemon owns provider + the law-file system prompt; the worker scheme
             // handler carries neither. Fire-and-forget: the returned drain runs
             // independently (the sister is its own worker). {§machine-processes}
-            injectWorker: async ({ workspaceId, workerId, prompt, flags }) => {
-                if (this.#provider === null)
-                    throw new Error("injectWorker: no provider configured");
+            injectWorker: async ({ workspaceId, workerId, prompt, flags, parentLoopId }) => {
                 const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
-                const providerSpec = resolveActiveAlias();
+                const parentPolicy = parentLoopId === undefined
+                    ? null
+                    : await this.#providerPolicyForLoop(parentLoopId);
+                const providerSpec = parentPolicy === null
+                    ? resolveActiveAlias()
+                    : parentPolicy.childProviderSpec ?? parentPolicy.providerSpec;
                 if (providerSpec === null)
                     throw new Error("injectWorker: active provider has no resolvable alias");
-                const { action, loopId } = await this.inject({ workspaceId, workerId, prompt, providerSpec, systemPrompt, ...(flags === undefined ? {} : { flags }) });
+                const { action, loopId } = await this.inject({
+                    workspaceId,
+                    workerId,
+                    prompt,
+                    providerSpec,
+                    ...(parentPolicy === null ? {} : { childProviderSpec: parentPolicy.childProviderSpec }),
+                    systemPrompt,
+                    ...(flags === undefined ? {} : { flags }),
+                });
                 return { action, loopId };
             },
             branchWorker: async (args) => this.#branchBatches.enqueue(args),
@@ -243,6 +261,11 @@ export default class Daemon {
         const openPaths = ClientInput.assertOpenPaths("runLoop", args.openPaths);
         const alias = ClientInput.assertOptionalSelector("runLoop", "alias", args.alias);
         const model = ClientInput.assertOptionalSelector("runLoop", "model", args.model);
+        const childAlias = ClientInput.assertOptionalChildAlias("runLoop", args.childAlias);
+        const childModel = ClientInput.assertOptionalSelector("runLoop", "childModel", args.childModel);
+        if (childAlias === null && childModel !== undefined) {
+            throw daemonFailure("daemon:input", "child-provider-conflict", 400, "childModel cannot accompany an inherited child provider policy.", { field: "childModel", recovery: "Omit childModel or select a child alias.", retryable: false });
+        }
         const flags = ClientInput.normalizeLoopFlags("runLoop", args.flags);
         // {§methods-loop-run-model} — a client sends alias/model on every loop, so a
         // switch takes effect turn-to-turn. `model` (client-resolved <provider>/<model>) wins
@@ -256,6 +279,14 @@ export default class Daemon {
                 retryable: false,
             }));
         }
+        // {§methods-loop-run-child-provider}
+        const configuredChildAlias = childAlias === undefined && childModel === undefined
+            ? process.env.PLURNK_MODEL_CHILD
+            : childAlias;
+        const childSelection = configuredChildAlias === null
+            || (configuredChildAlias === undefined && childModel === undefined)
+            ? null
+            : await this.#resolveLoopProvider(configuredChildAlias, childModel);
         const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
         // {§machine-processes} — the model NEVER runs in a client-origin worker (its packets would carry
         // client-action rows). The module resolves the model worker via ensureModelWorker and passes it (or a
@@ -296,6 +327,7 @@ export default class Daemon {
             ...(openPaths !== undefined ? { openPaths } : {}),
             turnCeiling,
             providerSpec: selection,
+            childProviderSpec: childSelection,
             systemPrompt,
         });
         return { status: 100, action, loopId, ...(turnSeq !== undefined ? { turnSeq } : {}) };
@@ -332,26 +364,40 @@ export default class Daemon {
         }
         return spec;
     }
-    async #providerSpecForLoop(loopId) {
-        const row = await this.#db.drain_loop_provider_spec.get({ loop_id: loopId });
-        if (row === undefined)
-            throw new Error(`loop ${loopId}: provider selection row is missing`);
+    #parseProviderSpec(loopId, field, encoded) {
         let parsed;
         try {
-            parsed = JSON.parse(row.provider_spec);
+            parsed = JSON.parse(encoded);
         }
         catch {
-            throw new Error(`loop ${loopId}: persisted provider selection is malformed — refusing boot-default substitution`);
+            throw new Error(`loop ${loopId}: persisted ${field} is malformed`);
         }
-        if (parsed === null
-            || typeof parsed.alias !== "string" || parsed.alias.length === 0
+        if (parsed === null)
+            return null;
+        if (typeof parsed.alias !== "string" || parsed.alias.length === 0
             || typeof parsed.provider !== "string" || parsed.provider.length === 0
             || typeof parsed.model !== "string" || parsed.model.length === 0
             || (parsed.baseUrl !== undefined && typeof parsed.baseUrl !== "string")) {
-            throw new Error(`loop ${loopId}: persisted provider selection is missing or invalid — refusing boot-default substitution`);
+            throw new Error(`loop ${loopId}: persisted ${field} is invalid`);
         }
         return parsed;
     }
+    async #providerPolicyForLoop(loopId) {
+        const row = await this.#db.drain_loop_provider_spec.get({ loop_id: loopId });
+        if (row === undefined)
+            throw new Error(`loop ${loopId}: provider selection row is missing`);
+        const providerSpec = this.#parseProviderSpec(loopId, "provider_spec", row.provider_spec);
+        if (providerSpec === null) {
+            throw new Error(`loop ${loopId}: persisted provider selection is missing or invalid — refusing boot-default substitution`);
+        }
+        return {
+            providerSpec,
+            childProviderSpec: this.#parseProviderSpec(loopId, "child_provider_spec", row.child_provider_spec),
+        };
+    }
+    async #providerSpecForLoop(loopId) {
+        return (await this.#providerPolicyForLoop(loopId)).providerSpec;
+    }
     async #providerForLoop(loopId) {
         return ProviderInstantiate.instantiateProvider(await this.#providerSpecForLoop(loopId));
     }
@@ -370,6 +416,19 @@ export default class Daemon {
             });
         }
     }
+    async #assertLoopChildProvider(loopId, requested) {
+        const selected = (await this.#providerPolicyForLoop(loopId)).childProviderSpec;
+        if (JSON.stringify(selected) !== JSON.stringify(requested)) {
+            throw daemonFailure("daemon:provider", "loop-child-provider-conflict", 409, `Loop ${loopId} already has a different child provider policy.`, {
+                loopId,
+                selectedChildAlias: selected?.alias ?? null,
+                requestedChildAlias: requested?.alias ?? null,
+                stage: "loop-injection",
+                recovery: "Cancel or conclude the loop before changing its child provider policy.",
+                retryable: false,
+            });
+        }
+    }
     async #assertLoopMaxTurns(loopId, requested) {
         if (requested === undefined)
             return;
@@ -960,6 +1019,7 @@ export default class Daemon {
     }
     async #recoverLifecycle() {
         await this.#db.recovery_fail_active_loops.run({});
+        await this.#db.recovery_fail_open_provider_attempts.run({});
         await this.#db.recovery_fail_ownerless_proposals.run({});
         await this.#db.recovery_error_orphan_subscription_channels.run({});
         await this.#db.recovery_fail_orphan_subscriptions.run({});
@@ -1009,7 +1069,9 @@ export default class Daemon {
         // Settle the stopped world FIRST: a drain paused at a pending proposal awaits a resolution
         // that will never arrive once clients are gone — allSettled(drains) below would deadlock
         // the stop forever (a daemon with a pending HITL proposal could not shut down).
+        const derivationAbort = new DOMException("daemon stopping", "AbortError");
         this.#engine.cancelAllProposals("daemon_stopping");
+        this.#engine.cancelDerivations(derivationAbort);
         this.#branchBatches.beginStop();
         for (const scope of this.#workerAborts.values()) {
             if (!scope.signal.aborted)
@@ -1028,10 +1090,11 @@ export default class Daemon {
         await this.#branchBatches.idle();
         const drainPromises = [...this.#activeDrains.values()].map((d) => d.promise);
         await Promise.allSettled(drainPromises);
+        await Promise.allSettled([...this.#drainExitTasks]);
         const closeResults = await moduleClose;
         const [streamingResult] = await Promise.allSettled([this.#drainStreamingSchemes()]);
         const [derivationResult] = await Promise.allSettled([
-            this.#engine.drainDerivations(), // active workspace warms finish before the db closes upstream
+            this.#engine.drainDerivations(derivationAbort), // active workspace warms settle before the db closes upstream
         ]);
         const mimetypeResults = this.#ownsMimetypes
             ? await Promise.allSettled([this.#mimetypes.dispose()])
@@ -1108,6 +1171,8 @@ export default class Daemon {
             if (active !== undefined) {
                 await this.#assertFoldPosture(workerId, args.flags, active.id); // compare with the exact durable loop
                 await this.#assertLoopProvider(active.id, args.providerSpec);
+                if (args.childProviderSpec !== undefined)
+                    await this.#assertLoopChildProvider(active.id, args.childProviderSpec);
                 await this.#assertLoopMaxTurns(active.id, args.turnCeiling?.source === "explicit" ? args.turnCeiling.effective : undefined);
             }
             const result = await this.#engine.inject(workerId, prompt, args.openPaths ?? []);
@@ -1125,6 +1190,8 @@ export default class Daemon {
             if (slept !== undefined) {
                 await this.#assertFoldPosture(workerId, args.flags, slept.id); // resume drops nothing silently
                 await this.#assertLoopProvider(slept.id, args.providerSpec);
+                if (args.childProviderSpec !== undefined)
+                    await this.#assertLoopChildProvider(slept.id, args.childProviderSpec);
                 await this.#assertLoopMaxTurns(slept.id, args.turnCeiling?.source === "explicit" ? args.turnCeiling.effective : undefined);
                 const injected = await this.#engine.inject(workerId, prompt, args.openPaths ?? []);
                 await this.#lifecycle.wake(slept.id);
@@ -1138,6 +1205,7 @@ export default class Daemon {
             workerId,
             prompt,
             providerSpec: args.providerSpec,
+            childProviderSpec: args.childProviderSpec ?? null,
             maxTurns: args.turnCeiling?.effective,
             flags: args.flags,
             openPaths: args.openPaths,
@@ -1168,6 +1236,7 @@ export default class Daemon {
                 sequence: seqRow.next,
                 prompt: args.prompt,
                 provider_spec: JSON.stringify(args.providerSpec),
+                child_provider_spec: JSON.stringify(args.childProviderSpec),
                 max_turns: args.maxTurns ?? Number(process.env.PLURNK_SERVICE_MAX_TURNS ?? "50"),
             });
             if (loopRow === undefined)
@@ -1353,12 +1422,18 @@ export default class Daemon {
                     // {§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.
-                    const usage = currentLoopId === null
-                        ? { promptTokens: 0, completionTokens: 0, costUsd: 0, costs: [], contextTokens: 0, promptBudget: null, meta: {} }
-                        : await this.#engine.loopUsage(currentLoopId);
-                    const attributions = currentLoopId === null
-                        ? []
-                        : await this.#engine.loopAttributions(currentLoopId);
+                    let usage = {
+                        promptTokens: 0,
+                        completionTokens: 0,
+                        reasoningTokens: 0,
+                        cachedTokens: 0,
+                        costUsd: 0,
+                        costs: [],
+                        contextTokens: 0,
+                        promptBudget: null,
+                        meta: {},
+                    };
+                    let attributions = [];
                     const message = ErrorDetail.preview(controller.signal.reason ?? "user_cancelled")
                         || "no reason was supplied";
                     if (currentLoopId !== null) {
@@ -1369,6 +1444,10 @@ export default class Daemon {
                             stage: "loop",
                             retryable: false,
                         }), { terminatedBy: "cancel" });
+                        [usage, attributions] = await Promise.all([
+                            this.#engine.loopUsage(currentLoopId),
+                            this.#engine.loopAttributions(currentLoopId),
+                        ]);
                         if (cancelled !== null) {
                             this.#broadcast({ workspaceId }, "loop/terminated", {
                                 workerId,
@@ -1456,8 +1535,12 @@ export default class Daemon {
         // Topology join ({§worker-loop-lifecycle}): when this drain exits having CONCLUDED the worker, wake its parent
         // if parked. Runs after the drain fully tears down (settled promise) so the quiescence check sees
         // final state; speculative (#onDrainExit no-ops unless the worker concluded AND the parent is parked).
-        void drainPromise.then(() => this.#onDrainExit(workspaceId, workerId, systemPrompt), () => this.#onDrainExit(workspaceId, workerId, systemPrompt)).catch((err) => {
+        const drainExitTask = drainPromise.then(() => this.#onDrainExit(workspaceId, workerId, systemPrompt), () => this.#onDrainExit(workspaceId, workerId, systemPrompt));
+        this.#drainExitTasks.add(drainExitTask);
+        void drainExitTask.catch((err) => {
             console.error(`parent wake after worker ${workerId} settlement failed:`, err);
+        }).finally(() => {
+            this.#drainExitTasks.delete(drainExitTask);
         });
         // Swallow unhandled rejections (drain aborts with no awaiter); the
         // error already surfaced via firstLoopPromise or was logged inside.
@@ -1515,6 +1598,7 @@ export default class Daemon {
                 prompt: first.body,
                 flags: first.flags,
                 provider_spec: first.provider_spec,
+                child_provider_spec: first.child_provider_spec,
                 max_turns: first.max_turns,
                 open_paths: first.open_paths ?? "[]",
                 orphan_source_loop_id: endedLoopId,
@@ -1632,23 +1716,24 @@ export default class Daemon {
     }
     /**
      * Wake-on-completion handler. Streaming schemes call this when a
-     * subscription closes. If the worker has an active loop, the channel
-     * transition will surface at that loop's next turn boundary — no new
-     * loop needed. Otherwise we open a fresh loop with the synthetic
-     * summary as the user prompt so the model gets a chance to react.
+     * subscription closes. A parked loop resumes in place; an active loop
+     * observes the channel transition at its next turn boundary. No synthetic
+     * prompt or replacement loop is created.
      *
      * Skipped on result.status=499 (aborted): the model already knows about
-     * its own SEND[499], and a forcefully-cancelled loop's spawn-abort
-     * shouldn't resurrect into a wake loop (defeats the cancel).
+     * its own SEND[499], and a forcefully-cancelled loop's spawn-abort must
+     * not resurrect the worker.
      */
     async #handleWakeWorker(payload) {
+        const { entryOwnerId, ...wake } = payload;
+        const conclusion = { ...wake, workerId: entryOwnerId };
         // {§search-gate} — settle the dedup registration: promote on a 200 conclusion, drop on
         // failure (a dead search must never serve as a duplicate). No-op for non-search streams.
         this.#engine.searchGate.settle(payload.target.replace(/^[a-z+.-]+:\/\//, "/").replace(/^\/+/, "/"), payload.result.status);
         // Aborted streams don't wake — the abort was deliberate.
         if (payload.result.status === 499) {
             this.#broadcast({ workspaceId: payload.workspaceId }, "stream/concluded", {
-                ...payload, wakeAction: "skipped-aborted",
+                ...conclusion, wakeAction: "skipped-aborted",
             });
             return;
         }
@@ -1662,7 +1747,7 @@ export default class Daemon {
         const scope = this.#workerAborts.get(payload.workerId);
         if (scope?.signal.aborted === true && !this.#activeDrains.has(payload.workerId)) {
             this.#broadcast({ workspaceId: payload.workspaceId }, "stream/concluded", {
-                ...payload, wakeAction: "skipped-cancelled",
+                ...conclusion, wakeAction: "skipped-cancelled",
             });
             return;
         }
@@ -1676,16 +1761,14 @@ export default class Daemon {
             // the manifest. {§worker-lifecycle-wake-liveness}.
             const slept = await this.#db.drain_find_slept_loop.get({ worker_id: payload.workerId });
             if (slept !== undefined) {
-                await this.#lifecycle.wake(slept.id);
-                const started = await this.#ensureDrain({
-                    workspaceId: payload.workspaceId, workerId: payload.workerId,
-                    systemPrompt,
+                // {§worker-optimistic-settlement} — publish this conclusion now,
+                // then let the worker-local gate coalesce only the provider
+                // dispatch. Concurrent stream/child callbacks join that one gate.
+                void this.#settleCompletionWake(payload.workspaceId, payload.workerId, systemPrompt, false).catch((err) => {
+                    console.error("completion wake settlement failed:", err instanceof Error ? err.message : String(err));
                 });
                 this.#broadcast({ workspaceId: payload.workspaceId }, "stream/concluded", {
-                    ...payload, wakeAction: "resumed-loop", wakeLoopId: slept.id,
-                });
-                started?.drainPromise?.catch((err) => {
-                    console.error("wake resume drain failed:", err instanceof Error ? err.message : String(err));
+                    ...conclusion, wakeAction: "resumed-loop", wakeLoopId: slept.id,
                 });
                 return;
             }
@@ -1695,14 +1778,14 @@ export default class Daemon {
             // synthesis (which clobbered the model's actual goal) is retired; just tell the client.
             if (this.#activeDrains.has(payload.workerId)) {
                 this.#broadcast({ workspaceId: payload.workspaceId }, "stream/concluded", {
-                    ...payload, wakeAction: "no-op-active-loop",
+                    ...conclusion, wakeAction: "no-op-active-loop",
                 });
                 return;
             }
             // No slept loop, no active drain — nothing to resume (e.g. a SEND[200]-done worker whose
             // streams were swept). Surface the conclusion without opening a loop.
             this.#broadcast({ workspaceId: payload.workspaceId }, "stream/concluded", {
-                ...payload, wakeAction: "no-loop",
+                ...conclusion, wakeAction: "no-loop",
             });
         }
         catch (err) {
@@ -1748,13 +1831,13 @@ export default class Daemon {
             delayMs = execPollBackoffMs(step, base, turns);
             this.#pollBackoff.set(workerId, step + 1);
         }
-        // Floored by the post-EXEC breath (PLURNK_SERVICE_EXEC_WAIT_MS) so a `<…,1>` can't wake the loop
-        // faster than a turn settles — {§exec-poll}.
-        const execWaitMs = Number(process.env.PLURNK_SERVICE_EXEC_WAIT_MS ?? "0");
+        // Floored by the optimistic settlement cap so a `<…,1>` cannot wake a
+        // parked loop faster than the preceding turn's settlement scale.
+        const optimisticWaitMs = readOptimisticSettlementMs();
         const timer = setTimeout(() => {
             this.#pollTimers.delete(workerId);
             void this.#wakeParkedWorker(workspaceId, workerId, systemPrompt);
-        }, Math.max(delayMs, execWaitMs));
+        }, Math.max(delayMs, optimisticWaitMs));
         timer.unref();
         this.#pollTimers.set(workerId, timer);
     }
@@ -1763,6 +1846,8 @@ export default class Daemon {
      *  or a child worker finishing ({§worker-loop-lifecycle} topology join) all call this. A no-op if the worker was
      *  cancelled or isn't actually parked (no slept loop) — so calling it speculatively is safe. */
     async #wakeParkedWorker(workspaceId, workerId, systemPrompt, oweIfActive = true) {
+        if (!this.#started)
+            return;
         const scope = this.#workerAborts.get(workerId);
         if (scope?.signal.aborted === true && !this.#activeDrains.has(workerId))
             return; // cancelled — no resurrection
@@ -1772,17 +1857,100 @@ export default class Daemon {
             // conclusion that fired this wake arrived before the 202 committed (the conclude-before-park
             // race). Owe the wake: the drain honors it at park so a worker hibernation never deadlocks.
             // (No active drain → already concluded/running; nothing to wake.)
-            if (oweIfActive && this.#activeDrains.has(workerId))
-                this.#owedWakes.add(workerId);
+            if (this.#activeDrains.has(workerId)) {
+                if (oweIfActive)
+                    this.#owedWakes.add(workerId);
+            }
             return;
         }
-        await this.#lifecycle.wake(slept.id);
+        const woke = await this.#lifecycle.wake(slept.id);
+        if (!woke)
+            return;
         const started = await this.#ensureDrain({
             workspaceId, workerId, systemPrompt,
         });
         started?.drainPromise?.catch((err) => {
-            console.error("wake-parked resume drain failed:", err instanceof Error ? err.message : String(err));
+            if (this.#started) {
+                console.error("wake-parked resume drain failed:", err instanceof Error ? err.message : String(err));
+            }
+        });
+    }
+    async #workerHasLiveObligation(workerId) {
+        const [openSubscriptions, liveChild] = await Promise.all([
+            this.#db.find_open_subscriptions_for_worker.all({ worker_id: workerId }),
+            this.#db.engine_worker_has_live_child.get({ worker_id: workerId }),
+        ]);
+        return openSubscriptions.length > 0 || liveChild !== undefined;
+    }
+    #settleCompletionWake(workspaceId, workerId, systemPrompt, oweIfActive = true) {
+        const existing = this.#completionWakeGates.get(workerId);
+        if (existing !== undefined) {
+            existing.conclusions++;
+            existing.poke.resolve();
+            return existing.promise;
+        }
+        const completed = Promise.withResolvers();
+        const gate = {
+            conclusions: 1,
+            poke: Promise.withResolvers(),
+            promise: completed.promise,
+        };
+        this.#completionWakeGates.set(workerId, gate);
+        void this.#runCompletionWake(workspaceId, workerId, systemPrompt, oweIfActive, gate).then(completed.resolve, completed.reject).finally(() => {
+            if (this.#completionWakeGates.get(workerId) === gate) {
+                this.#completionWakeGates.delete(workerId);
+            }
         });
+        return gate.promise;
+    }
+    async #runCompletionWake(workspaceId, workerId, systemPrompt, oweIfActive, gate) {
+        const slept = await this.#db.drain_find_slept_loop.get({ worker_id: workerId });
+        if (slept === undefined) {
+            this.#releaseCompletionWake(workerId, gate);
+            return this.#wakeParkedWorker(workspaceId, workerId, systemPrompt, oweIfActive);
+        }
+        const timeoutMs = readOptimisticSettlementMs();
+        if (timeoutMs === 0 || !(await this.#workerHasLiveObligation(workerId))) {
+            this.#releaseCompletionWake(workerId, gate);
+            return this.#wakeParkedWorker(workspaceId, workerId, systemPrompt, false);
+        }
+        return observed("worker.wake.settlement", { "window.ms": timeoutMs }, async (span) => {
+            const startedAt = performance.now();
+            const signal = this.#workerAborts.get(workerId)?.signal;
+            const deadline = delay(timeoutMs, "deadline", { signal, ref: false })
+                .catch((cause) => {
+                if (signal?.aborted === true)
+                    return "cancelled";
+                throw cause;
+            });
+            let release = "quiescent";
+            while (await this.#workerHasLiveObligation(workerId)) {
+                const poke = gate.poke;
+                const outcome = await Promise.race([
+                    poke.promise.then(() => "arrival"),
+                    deadline,
+                ]);
+                if (outcome === "arrival") {
+                    if (gate.poke === poke)
+                        gate.poke = Promise.withResolvers();
+                    continue;
+                }
+                release = outcome;
+                break;
+            }
+            span.setAttribute("release", release);
+            span.setAttribute("conclusions", gate.conclusions);
+            span.setAttribute("elapsed.ms", Math.round(performance.now() - startedAt));
+            this.#releaseCompletionWake(workerId, gate);
+            if (release === "cancelled")
+                return;
+            return this.#wakeParkedWorker(workspaceId, workerId, systemPrompt, false);
+        });
+    }
+    #releaseCompletionWake(workerId, gate) {
+        if (this.#completionWakeGates.get(workerId) === gate) {
+            this.#completionWakeGates.delete(workerId);
+        }
     }
     /** A worker's drain exited. If the worker truly CONCLUDED — no 202-blocked loop, no open stream — then
      *  wake its PARENT in place if the parent is blocked on the join (the structured-concurrency join — a
@@ -1800,7 +1968,7 @@ export default class Daemon {
         const parent = await this.#db.worker_parent_id.get({ worker_id: workerId });
         if (parent?.parent_worker_id == null)
             return; // a root worker — nobody to wake
-        await this.#wakeParkedWorker(workspaceId, parent.parent_worker_id, systemPrompt);
+        await this.#settleCompletionWake(workspaceId, parent.parent_worker_id, systemPrompt);
     }
     // {§methods-event-subscribe} — subscriber failures are transport-local:
     // log them at this boundary and never re-enter engine control flow.