@timqi/pier 0.0.28 → 0.1.0

package/dist/tasks/agent.js

@@ -4,11 +4,10 @@
 // agents specifically — a bash run costs a process, an agent run costs a
 // model's context and someone's rate limit.
 import { quietLabel, splitReply } from "../core/reply.js";
-import { Router } from "../core/router.js";
+import { logger } from "../log.js";
 import { runSource } from "./callbacks.js";
-import { TaskMessenger } from "./messages.js";
-import { TaskStore } from "./store.js";
 const MAX_ACTIVE_AGENTS = 4;
+const log = logger("tasks");
 /** What a child cannot know unless told. Every session gets the chat-surface
  * contract (<pier>/AGENTS.md), task runs included — so the delegation prompt
  * says which of it does not apply here, and a supervised run how to reach the
@@ -44,11 +43,18 @@ export class AgentTaskRunner {
         this.changed = changed;
     }
     async execute(run, action, signal, start) {
-        await this.acquireSlot(run, signal);
-        try {
-            const session = await this.resolveSession(run, action);
-            return await this.withSession(session.id, async () => {
+        // Reserve reuse order before resolving the session: a slow resume must not
+        // let a later run pass it. Fresh runs each have their own queue key.
+        return this.withSession(run.targetSessionId ?? run.id, signal, async () => {
+            const reused = run.targetSessionId ? await this.resolveSession(run, action, signal) : undefined;
+            if (reused)
+                await this.waitUntilIdle(reused, signal);
+            await this.acquireSlot(run, signal);
+            try {
+                const session = reused ?? await this.resolveSession(run, action, signal);
+                // A reused session may have become busy while we waited for a slot.
                 await this.waitUntilIdle(session, signal);
+                signal.throwIfAborted();
                 // Task requests come seconds apart — the 1h Anthropic cache-write premium
                 // never earns its 2× back, so task runs use the 5m TTL. Set here, not in
                 // resolveSession: this covers create, reuse and resume alike, on
@@ -85,22 +91,16 @@ export class AgentTaskRunner {
                         failure = event.error;
                     }
                 });
-                // The race below also settles this attempt if Pi ignores the abort:
-                // a hung turn must not hold one of the 4 slots (and its waiters)
-                // forever — the same guard execution.ts gives task-type children.
-                let rejectAborted = () => { };
-                const abortedTurn = new Promise((_, reject) => { rejectAborted = reject; });
-                abortedTurn.catch(() => { }); // handled via the race; never unhandled
+                // Cancel the SDK turn, but release our wait even if its abort hangs.
                 const abort = () => {
-                    void session.abort();
-                    rejectAborted(new Error("cancelled"));
+                    void Promise.resolve().then(() => session.abort())
+                        .catch((error) => log.warn(`run ${run.id} session abort failed`, error));
                 };
                 signal.addEventListener("abort", abort, { once: true });
-                // A pre-aborted signal never fires the listener: check before the
-                // prompt starts or a cancelled run would hang until its timeout.
-                if (signal.aborted)
-                    throw new Error("cancelled");
                 try {
+                    // Pre-abort does not fire a newly registered listener; keep the check
+                    // inside finally's scope so it also restores retention/subscriptions.
+                    signal.throwIfAborted();
                     const turn = session.systemInput(prompt, {
                         kind: "task-delegation",
                         taskId: run.taskId,
@@ -110,7 +110,7 @@ export class AgentTaskRunner {
                     }, "prompt");
                     await Promise.resolve();
                     this.messages.deliverPendingControls(run);
-                    await Promise.race([turn, abortedTurn]);
+                    await this.untilAborted(turn, signal);
                     if (signal.aborted)
                         throw new Error("cancelled");
                     // Before the fallback below: on a reused session that reads the
@@ -119,7 +119,7 @@ export class AgentTaskRunner {
                     if (failure)
                         throw new Error(failure);
                     if (!text) {
-                        const history = await session.history();
+                        const history = await this.untilAborted(session.history(), signal);
                         text = [...history].reverse().find((turn) => turn.role === "assistant")?.text ?? "";
                     }
                     // The chat contract is injected into task sessions too, so a child's
@@ -138,15 +138,16 @@ export class AgentTaskRunner {
                     signal.removeEventListener("abort", abort);
                     unsubscribe();
                 }
-            });
-        }
-        finally {
-            this.releaseSlot(run.id);
-        }
+            }
+            finally {
+                this.releaseSlot(run.id);
+            }
+        });
     }
-    async resolveSession(run, action) {
+    async resolveSession(run, action, signal) {
+        signal.throwIfAborted();
         if (run.targetSessionId) {
-            return this.router.ensure({ channelId: "task", conversationId: run.targetSessionId });
+            return this.untilAborted(this.router.ensure({ channelId: "task", conversationId: run.targetSessionId }), signal);
         }
         const policy = action.session;
         // Definitions stored before fork was removed still say `"fork"`. Refused by
@@ -157,7 +158,8 @@ export class AgentTaskRunner {
         }
         const cwd = policy.mode === "fresh"
             ? policy.cwd
-            : (await this.factory.find(policy.sessionId))?.cwd ?? "";
+            : (await this.untilAborted(this.factory.find(policy.sessionId), signal))?.cwd ?? "";
+        signal.throwIfAborted();
         if (!cwd)
             throw new Error("could not resolve child working directory");
         const opts = {
@@ -169,33 +171,52 @@ export class AgentTaskRunner {
                 (run.sourceSessionId ? this.router.modelOf(run.sourceSessionId) : undefined),
             thinking: action.launch?.thinking,
         };
-        const session = await this.factory.create(opts);
-        run.targetSessionId = session.id;
-        run.context.sessionId = session.id;
-        run.context.cwd = cwd;
-        this.store.saveRun(run);
-        this.router.attach({ channelId: "task", conversationId: session.id }, session);
-        this.changed(run);
+        const opening = this.factory.create(opts).then(async (session) => {
+            // SDK creation cannot be cancelled. A late session still belongs to
+            // this run; read back its terminal row so delivery updates are preserved.
+            // Remember it on the live run too: cancellation's final save can race
+            // this callback before it finishes writing the terminal record.
+            run.targetSessionId = session.id;
+            run.context.sessionId = session.id;
+            run.context.cwd = cwd;
+            const owner = signal.aborted ? this.store.getRun(run.id) ?? run : run;
+            owner.targetSessionId = run.targetSessionId;
+            owner.context = run.context;
+            try {
+                this.store.saveRun(owner);
+                this.changed(owner);
+            }
+            finally {
+                if (signal.aborted)
+                    await session.dispose();
+                else
+                    this.router.attach({ channelId: "task", conversationId: session.id }, session);
+            }
+            return session;
+        });
+        // A late rejection cannot reach execute's already-cancelled race.
+        void opening.catch((error) => {
+            if (signal.aborted)
+                log.warn(`session creation for cancelled run ${run.id} failed`, error);
+        });
+        const session = await this.untilAborted(opening, signal);
+        signal.throwIfAborted();
         return session;
     }
     async acquireSlot(run, signal) {
         while (this.active.size >= MAX_ACTIVE_AGENTS) {
-            if (signal.aborted)
-                throw new Error("cancelled");
-            await new Promise((resolve, reject) => {
-                const wake = () => {
-                    signal.removeEventListener("abort", abort);
-                    this.slotWaiters.delete(wake);
-                    resolve();
-                };
-                const abort = () => {
-                    this.slotWaiters.delete(wake);
-                    reject(new Error("cancelled"));
-                };
-                this.slotWaiters.add(wake);
-                signal.addEventListener("abort", abort, { once: true });
-            });
+            let wake = () => { };
+            try {
+                await this.untilAborted(new Promise((resolve) => {
+                    wake = resolve;
+                    this.slotWaiters.add(wake);
+                }), signal);
+            }
+            finally {
+                this.slotWaiters.delete(wake);
+            }
         }
+        signal.throwIfAborted();
         this.active.add(run.id);
     }
     releaseSlot(id) {
@@ -203,43 +224,58 @@ export class AgentTaskRunner {
         for (const wake of this.slotWaiters)
             wake();
     }
-    async withSession(sessionId, fn) {
+    async untilAborted(promise, signal) {
+        let abort = () => { };
+        const cancelled = new Promise((_, reject) => {
+            abort = () => reject(new Error("cancelled"));
+            signal.addEventListener("abort", abort, { once: true });
+            if (signal.aborted)
+                abort();
+        });
+        try {
+            return await Promise.race([promise, cancelled]);
+        }
+        finally {
+            signal.removeEventListener("abort", abort);
+        }
+    }
+    async withSession(sessionId, signal, fn) {
+        signal.throwIfAborted();
         const previous = this.sessionTails.get(sessionId) ?? Promise.resolve();
         let release = () => { };
         const gate = new Promise((resolve) => { release = resolve; });
         const tail = previous.then(() => gate);
         this.sessionTails.set(sessionId, tail);
-        await previous;
+        // Even if this waiter is cancelled, its tail still includes its predecessor.
+        // Only delete after that tail drains, or a new arrival could skip the queue.
+        void tail.then(() => {
+            if (this.sessionTails.get(sessionId) === tail)
+                this.sessionTails.delete(sessionId);
+        });
         try {
+            await this.untilAborted(previous, signal);
+            signal.throwIfAborted();
             return await fn();
         }
         finally {
             release();
-            if (this.sessionTails.get(sessionId) === tail)
-                this.sessionTails.delete(sessionId);
         }
     }
     async waitUntilIdle(session, signal) {
         // The session's own event stream is the only busy/idle signal — no polling.
         while (session.state === "streaming") {
-            if (signal.aborted)
-                throw new Error("cancelled");
-            await new Promise((resolve, reject) => {
-                const settle = (error) => {
-                    unsubscribe();
-                    signal.removeEventListener("abort", onAbort);
-                    if (error)
-                        reject(error);
-                    else
-                        resolve();
-                };
-                const onAbort = () => settle(new Error("cancelled"));
-                const unsubscribe = session.subscribe((event) => {
-                    if (event.type === "state" && event.state === "idle")
-                        settle();
-                });
-                signal.addEventListener("abort", onAbort, { once: true });
-            });
+            let unsubscribe = () => { };
+            try {
+                await this.untilAborted(new Promise((resolve) => {
+                    unsubscribe = session.subscribe((event) => {
+                        if (event.type === "state" && event.state === "idle")
+                            resolve();
+                    });
+                }), signal);
+            }
+            finally {
+                unsubscribe();
+            }
         }
     }
 }

package/dist/tasks/callbacks.js

@@ -1,8 +1,6 @@
 // What a finished run says to the session that delegated it. Delivery itself
 // belongs to outbox.ts; this file owns the run vocabulary and the batching.
-import { Router } from "../core/router.js";
 import { Outbox } from "./outbox.js";
-import { TaskStore } from "./store.js";
 /** How a run is named to the session that gets its result: the run id, and the
  *  session that did the work — a relayer's next move is a deep link to it
  *  (`#/session/<id>`), and without this line that costs a second tool call.
@@ -28,7 +26,7 @@ export function runResultText(run) {
     if (run.result?.type === "watch")
         result = "Watch condition did not match";
     if (result.length > 8000)
-        result = `${result.slice(0, 8000)}\n[truncated — task tool get run_id ${run.id} returns the full text]`;
+        result = `${result.slice(0, 8000)}\n[truncated — task tool recover run_id ${run.id} with a reason returns the full text]`;
     return result;
 }
 export class TaskCallbacks {

package/dist/tasks/command.js

@@ -5,6 +5,7 @@ import { spawn } from "node:child_process";
 import { logger } from "../log.js";
 const log = logger("tasks");
 const OUTPUT_LIMIT = 1024 * 1024;
+const KILL_GRACE_MS = 250;
 class CappedOutput {
     chunks = [];
     bytes = 0;
@@ -38,34 +39,52 @@ export function runBash(script, cwd, input, signal) {
         const stdout = new CappedOutput();
         const stderr = new CappedOutput();
         let settled = false;
-        const kill = () => {
+        let killTimer;
+        const kill = (signal) => {
             if (!child.pid)
                 return;
             try {
                 if (process.platform === "win32")
-                    child.kill("SIGTERM");
+                    child.kill(signal);
                 else
-                    process.kill(-child.pid, "SIGTERM");
+                    process.kill(-child.pid, signal);
             }
-            catch {
-                // The process may have exited between the state check and kill.
+            catch (err) {
+                // ESRCH means the owned process group already exited.
+                if (err.code !== "ESRCH")
+                    log.warn(`run ${signal} failed: ${String(err)}`);
             }
         };
-        signal.addEventListener("abort", kill, { once: true });
+        const abort = () => {
+            kill("SIGTERM");
+            killTimer = setTimeout(() => kill("SIGKILL"), KILL_GRACE_MS);
+            killTimer.unref();
+        };
+        const cleanup = () => {
+            clearTimeout(killTimer);
+            signal.removeEventListener("abort", abort);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
         child.stdout.on("data", (chunk) => stdout.add(chunk));
         child.stderr.on("data", (chunk) => stderr.add(chunk));
         child.on("error", (err) => {
             if (settled)
                 return;
             settled = true;
-            signal.removeEventListener("abort", kill);
+            cleanup();
             reject(err);
         });
         child.on("close", (code) => {
             if (settled)
                 return;
             settled = true;
-            signal.removeEventListener("abort", kill);
+            // A TERM trap may exit the shell while a descendant ignores TERM and
+            // has redirected its pipes. Closing the shell must not spare that group.
+            if (signal.aborted)
+                kill("SIGKILL");
+            cleanup();
             resolve({
                 exitCode: code,
                 stdout: stdout.text(),

package/dist/tasks/execution.js

@@ -3,11 +3,7 @@
 // while it goes, settled exactly once. Command and agent work lives in
 // command.ts and agent.ts; this file owns the lifecycle they share.
 import { logger } from "../log.js";
-import { AgentTaskRunner } from "./agent.js";
-import { TaskCallbacks } from "./callbacks.js";
 import { runBash } from "./command.js";
-import { TaskDefinitions } from "./definitions.js";
-import { TaskStore } from "./store.js";
 const log = logger("tasks");
 export class TaskExecution {
     store;
@@ -40,6 +36,8 @@ export class TaskExecution {
         let timedOut = false;
         let cause;
         const timeout = setTimeout(() => {
+            if (controller.signal.aborted)
+                return;
             timedOut = true;
             controller.abort();
         }, run.context.definition.timeoutSeconds * 1000);
@@ -58,6 +56,7 @@ export class TaskExecution {
             }
             if (run.matched !== false)
                 run.result = await this.executeAction(run, controller.signal);
+            controller.signal.throwIfAborted();
             run.state = "succeeded";
             if (definition.trigger.type === "watch" && !run.resumedFromRunId && definition.trigger.mode === "once" && run.matched) {
                 // As the definition's own creator: a one-shot watch retiring itself is
@@ -112,6 +111,7 @@ export class TaskExecution {
         }
     }
     async executeAction(run, signal) {
+        signal.throwIfAborted();
         const action = run.context.definition.action;
         if (action.type === "bash") {
             this.markRunning(run);
@@ -143,6 +143,8 @@ export class TaskExecution {
                 rejectWait(new Error("cancelled"));
             };
             signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
             try {
                 const done = await Promise.race([this.host.waitForRun(child.id), aborted]);
                 if (done.state !== "succeeded")

package/dist/tasks/groups.js

@@ -2,12 +2,10 @@
 // separate endings into one answer — when the join condition is met, which
 // members are cancelled, and the single aggregated callback that goes back.
 // Delivering it is the outbox's job; deciding it is this file's.
-import { Router } from "../core/router.js";
 import { logger } from "../log.js";
 import { runRef, runResultText } from "./callbacks.js";
 import { newId } from "./definitions.js";
 import { Outbox } from "./outbox.js";
-import { TaskStore } from "./store.js";
 import { isTerminal } from "./types.js";
 const log = logger("tasks");
 /** Core-owned fan-out join: members run detached, the group delivers one
@@ -16,11 +14,13 @@ export class TaskGroups {
     store;
     host;
     changed;
+    unreachable;
     outbox;
     constructor(store, router, host, changed, unreachable) {
         this.store = store;
         this.host = host;
         this.changed = changed;
+        this.unreachable = unreachable;
         this.outbox = new Outbox(router, {
             id: (group) => group.id,
             reload: (id) => this.store.getGroup(id),
@@ -38,21 +38,21 @@ export class TaskGroups {
     }
     /** Enqueues every member or none: a partially started group is worse than
      * a rejected one. */
-    runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId) {
-        const group = this.create(join, callerSessionId, callbackSessionId);
-        const runs = [];
-        try {
-            for (const definition of definitions) {
-                runs.push(this.host.startMember(definition.id, group.id, callerSessionId, parentRunId));
-            }
-        }
-        catch (error) {
-            log.warn(`group ${group.id} rolled back after ${String(runs.length)} members`, error);
-            for (const run of runs)
-                this.host.cancel(run.id);
-            throw error;
-        }
-        this.setMembers(group, runs.map((run) => run.id));
+    runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode) {
+        if (definitions.length < 2)
+            throw new Error("a task group needs at least 2 members");
+        const { group, runs } = this.store.transact(() => {
+            const group = this.create(join, callerSessionId, callbackSessionId, callbackMode);
+            const runs = definitions.map((definition) => this.host.prepareMember(definition.id, group.id, callerSessionId, parentRunId));
+            group.memberRunIds = runs.map((run) => run.id);
+            this.store.saveGroup(group);
+            return { group, runs };
+        });
+        this.changed(group);
+        for (const run of runs)
+            this.host.startMember(run);
+        // Skipped members do not pass through execution's settled hook.
+        this.evaluate(this.get(group.id));
         return { group: this.get(group.id), runs };
     }
     members(id) {
@@ -64,12 +64,13 @@ export class TaskGroups {
             this.host.cancel(runId);
         return this.get(id);
     }
-    create(join, invokedBySessionId, callbackSessionId) {
-        const group = {
+    create(join, invokedBySessionId, callbackSessionId, callbackMode) {
+        return {
             id: newId(),
             join,
             invokedBySessionId,
             callbackSessionId,
+            ...(callbackMode === "steer" ? { callbackMode } : {}),
             memberRunIds: [],
             winnerRunId: null,
             callbackState: null,
@@ -79,13 +80,6 @@ export class TaskGroups {
             createdAt: Date.now(),
             finishedAt: null,
         };
-        this.store.saveGroup(group);
-        return group;
-    }
-    setMembers(group, runIds) {
-        group.memberRunIds = runIds;
-        this.store.saveGroup(group);
-        this.changed(group);
     }
     get(id) {
         const group = this.store.getGroup(id);
@@ -109,6 +103,21 @@ export class TaskGroups {
         }
     }
     evaluate(group) {
+        if (group.finishedAt !== null)
+            return;
+        // Old versions could leave an empty group when admission failed. Retire
+        // that broken record without inventing a successful zero-member join.
+        if (group.memberRunIds.length === 0) {
+            group.finishedAt = Date.now();
+            group.callbackState = group.callbackSessionId ? "abandoned" : null;
+            group.callbackError = "group admission failed before its members were recorded";
+            this.store.saveGroup(group);
+            this.changed(group);
+            log.error(`group ${group.id}: ${group.callbackError}`);
+            if (group.callbackSessionId)
+                this.unreachable(group.callbackSessionId, `task group ${group.id}`, group.callbackError);
+            return;
+        }
         const members = group.memberRunIds.map((id) => this.host.getRun(id));
         if (group.join === "first") {
             const winner = members.find((run) => isTerminal(run.state));

package/dist/tasks/messages.js

@@ -4,12 +4,9 @@
 // the two ends are different sessions and either may be mid-turn, gone, or
 // finished — an undelivered message is retried, expired and *said*, never
 // dropped (§5b).
-import { EventHub } from "../core/hub.js";
-import { Router } from "../core/router.js";
 import { logger } from "../log.js";
 import { runSource } from "./callbacks.js";
 import { newId } from "./definitions.js";
-import { TaskStore } from "./store.js";
 import { isTerminal, MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
 const log = logger("tasks");
 const MAX_MESSAGE_LENGTH = 16 * 1024;
@@ -25,18 +22,20 @@ export class TaskMessenger {
     store;
     router;
     hub;
-    resumeRun;
+    prepareResume;
     unreachable;
+    startRun;
     constructor(store, router, hub, 
-    /** Continues a terminal child with a supervisor reply as its prompt. */
-    resumeRun, 
+    /** Prepares a continuation; it starts only after the reply commits. */
+    prepareResume, 
     /** Reports a delivery nobody can complete (service.ts owns the surfaces). */
-    unreachable) {
+    unreachable, startRun) {
         this.store = store;
         this.router = router;
         this.hub = hub;
-        this.resumeRun = resumeRun;
+        this.prepareResume = prepareResume;
         this.unreachable = unreachable;
+        this.startRun = startRun;
     }
     expirePending() {
         for (const message of this.store.expirePendingMessages())
@@ -49,6 +48,7 @@ export class TaskMessenger {
     /** A manual continuation supersedes an unanswered decision (design 04):
      * one continuation per run, never two racing ones. */
     expireDecisions(runId, reason) {
+        const expired = [];
         for (const message of this.store.listMessages(runId)) {
             if (message.kind !== "decision" || (message.state !== "pending" && message.state !== "delivered"))
                 continue;
@@ -56,8 +56,9 @@ export class TaskMessenger {
             message.error = reason;
             message.answeredAt = Date.now();
             this.store.saveMessage(message);
-            this.changed(message);
+            expired.push(message);
         }
+        return expired;
     }
     list(runId) {
         return this.store.listMessages(runId);
@@ -67,6 +68,7 @@ export class TaskMessenger {
     }
     async control(run, fromSessionId, kind, content) {
         const message = this.create(run, kind, fromSessionId, run.targetSessionId ?? "", content, null);
+        this.changed(message);
         if (run.targetSessionId)
             this.deliver(message, run, run.targetSessionId);
         return this.require(message.id);
@@ -139,6 +141,7 @@ export class TaskMessenger {
             throw new Error("run already has a pending supervisor decision");
         }
         const message = this.create(run, reason, fromSessionId, run.invokedBySessionId, content, null);
+        this.changed(message);
         this.deliver(message, run, run.invokedBySessionId);
         return this.require(message.id);
     }
@@ -161,25 +164,28 @@ export class TaskMessenger {
         const run = this.store.getRun(question.runId);
         if (!run)
             throw new Error(`unknown task run: ${question.runId}`);
-        const reply = this.create(run, "reply", fromSessionId, question.fromSessionId, text, question.id);
-        question.state = "answered";
-        question.answeredAt = Date.now();
-        this.store.saveMessage(question);
+        // A rejected continuation must leave the question answerable. Persist the
+        // answer and its queued run together, before either publishes or executes.
+        const { reply, continuation } = this.store.transact(() => {
+            const reply = this.create(run, "reply", fromSessionId, question.fromSessionId, text, question.id);
+            question.state = "answered";
+            question.answeredAt = Date.now();
+            this.store.saveMessage(question);
+            const continuation = isTerminal(run.state)
+                ? this.prepareResume(run.id, this.format(reply, run), fromSessionId)
+                : undefined;
+            if (continuation) {
+                reply.resumeRunId = continuation.id;
+                this.store.saveMessage(reply);
+            }
+            return { reply, continuation };
+        });
         this.changed(question);
-        // Core routes the reply: follow-up into an active run, auto-resume of a
-        // terminal one — the replier gets the continuation's callback.
-        if (run.targetSessionId && (run.state === "queued" || run.state === "running")) {
+        this.changed(reply);
+        if (continuation)
+            this.startRun(continuation);
+        else if (run.targetSessionId)
             this.deliver(reply, run, run.targetSessionId);
-        }
-        else if (isTerminal(run.state)) {
-            // Creating the continuation is not delivering the reply: the run is
-            // queued, and a restart or a cancel before it starts loses the prompt
-            // that carries the text. So the id is recorded and the sweep below
-            // settles it against the continuation's own `startedAt`.
-            reply.resumeRunId = this.resumeRun(run.id, this.format(reply, run), fromSessionId).id;
-            this.store.saveMessage(reply);
-            this.changed(reply);
-        }
         return this.require(reply.id);
     }
     create(run, kind, fromSessionId, toSessionId, content, replyTo) {
@@ -200,7 +206,6 @@ export class TaskMessenger {
             nextAttemptAt: null,
         };
         this.store.saveMessage(message);
-        this.changed(message);
         return message;
     }
     /** Never awaits the recipient: the seam's `systemInput` settles with the turn
@@ -377,6 +382,7 @@ export class TaskMessenger {
             throw new Error(`unknown task message: ${id}`);
         return message;
     }
+    /** Publish only after any transaction changing this message has committed. */
     changed(message) {
         this.hub.emitWorkspace({ type: "task-message-changed", runId: message.runId, messageId: message.id });
     }