@timqi/pier 0.1.0 → 0.1.1

package/dist/tasks/messages.js

@@ -1,15 +1,16 @@
-// What a parent and a child say to each other while a run is going: steer,
-// follow-up and resume in one direction, progress and decision questions in
-// the other. Every message is a durable row before it is a delivery, because
-// 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 { logger } from "../log.js";
+// What a parent and a child say to each other while a run is going. Every
+// message is a durable row before it is a delivery: either end may be mid-turn
+// or gone, and an undelivered message is retried, expired and said, never
+// dropped (§5). Delivery itself belongs to outbox.ts.
 import { runSource } from "./callbacks.js";
 import { newId } from "./definitions.js";
-import { isTerminal, MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
-const log = logger("tasks");
+import { Outbox } from "./outbox.js";
+import { isTerminal } from "./types.js";
 const MAX_MESSAGE_LENGTH = 16 * 1024;
+/** `answered` is a delivery that was read; `expired` is one given up on. */
+const ENGINE_STATE = {
+    pending: "pending", failed: "failed", delivered: "delivered", answered: "delivered", expired: "abandoned",
+};
 function bounded(content) {
     const text = content.trim();
     if (!text)
@@ -20,22 +21,56 @@ function bounded(content) {
 }
 export class TaskMessenger {
     store;
-    router;
     hub;
     prepareResume;
     unreachable;
     startRun;
+    outbox;
     constructor(store, router, hub, 
     /** Prepares a continuation; it starts only after the reply commits. */
     prepareResume, 
     /** Reports a delivery nobody can complete (service.ts owns the surfaces). */
     unreachable, startRun) {
         this.store = store;
-        this.router = router;
         this.hub = hub;
         this.prepareResume = prepareResume;
         this.unreachable = unreachable;
         this.startRun = startRun;
+        this.outbox = new Outbox(router, {
+            id: ({ message }) => message.id,
+            reload: (id) => {
+                const message = this.store.getMessage(id);
+                return message && this.carry(message);
+            },
+            save: ({ message, callbackState, callbackAttempts, callbackError, callbackNextAttemptAt }) => {
+                message.attempts = callbackAttempts;
+                message.error = callbackError;
+                message.nextAttemptAt = callbackNextAttemptAt;
+                if (callbackState === "delivered") {
+                    message.state = "delivered";
+                    message.deliveredAt = Date.now();
+                }
+                else if (callbackState === "abandoned") {
+                    message.state = "expired";
+                    message.answeredAt = Date.now();
+                }
+                else
+                    message.state = callbackState ?? "pending";
+                this.store.saveMessage(message);
+            },
+            changed: ({ message }) => this.changed(message),
+            input: (records) => {
+                const message = records[0].message;
+                const run = this.store.getRun(message.runId);
+                if (!run)
+                    throw new Error(`unknown task run: ${message.runId}`);
+                return { text: this.format(message, run), origin: this.origin(message, run) };
+            },
+            abandoned: ({ message }, _sessionId, why) => this.told(message, why),
+            // A follow-up joins the recipient's queue now: the run it guides may end
+            // with the turn it would otherwise wait out.
+            queues: true,
+        });
     }
     expirePending() {
         for (const message of this.store.expirePendingMessages())
@@ -70,7 +105,7 @@ export class TaskMessenger {
         const message = this.create(run, kind, fromSessionId, run.targetSessionId ?? "", content, null);
         this.changed(message);
         if (run.targetSessionId)
-            this.deliver(message, run, run.targetSessionId);
+            this.deliver(message, run.targetSessionId);
         return this.require(message.id);
     }
     deliverPendingControls(run) {
@@ -79,12 +114,11 @@ export class TaskMessenger {
         for (const message of this.store.listMessages(run.id)) {
             if (message.state !== "pending" || (message.kind !== "steer" && message.kind !== "follow_up"))
                 continue;
-            this.deliver(message, run, run.targetSessionId);
+            this.deliver(message, run.targetSessionId);
         }
     }
-    /** Injection is fire-and-forget, so this sweep is what closes a failed one.
-     * `inject` dedupes on the recipient transcript, so a retry cannot double
-     * deliver. Controls aimed at a finished run are dead and expire here. */
+    /** Delivery is fire-and-forget, so this sweep is what closes a failed one.
+     * Controls aimed at a finished run are dead and expire here. */
     retryUndelivered(now = Date.now()) {
         for (const { message, run } of this.store.listUndeliveredMessages()) {
             if (!run)
@@ -97,26 +131,19 @@ export class TaskMessenger {
                 this.changed(message);
                 continue;
             }
-            // A reply that resumed a terminal run was never a system input: its text
-            // is the continuation's prompt, so the transcript read below would find
-            // nothing and re-inject a second copy, starting a turn no run owns. The
-            // continuation is the proof instead. `startedAt` is written one statement
-            // before the prompt reaches the session (agent.ts), so `delivered` here
-            // means "handed to the run that reports for it" — a `systemInput` that
-            // then throws fails *that* run, and the failure reaches the replier
-            // through its callback.
+            // A reply that resumed a terminal run is the continuation's prompt, not a
+            // system input: the transcript read would re-inject it and start a turn no
+            // run owns. The continuation's `startedAt` is the proof instead.
             if (message.kind === "reply" && isTerminal(run.state)) {
                 const resumed = message.resumeRunId ? this.store.getRun(message.resumeRunId) : undefined;
                 if (resumed?.startedAt)
-                    this.confirmed(message.id);
+                    this.delivered(message);
                 else if (!resumed)
                     this.abandon(message, `continuation ${message.resumeRunId ?? "(none)"} is gone`);
                 else if (isTerminal(resumed.state)) {
-                    // Never started, and never will: say so rather than wait for a
-                    // ceiling that would only report the same thing four minutes later.
-                    // Both ends hear it here; the supervisor may also get the
-                    // continuation's own cancelled callback, and a duplicate beats a
-                    // special case that could suppress the only report either gets.
+                    // Never started and never will: said now, not four minutes later at
+                    // the ceiling. A duplicate report beats a special case that could
+                    // suppress the only one.
                     this.abandon(message, `continuation ${resumed.id} ${resumed.state} before it started`);
                 }
                 continue;
@@ -125,15 +152,12 @@ export class TaskMessenger {
                 continue;
             const target = message.toSessionId || run.targetSessionId;
             if (target)
-                this.deliver(message, run, target);
+                this.deliver(message, target);
         }
     }
-    /** Asynchronous by design: returns the receipt immediately. A decision
-     * child states what it awaits and ends its turn; the reply arrives as a
-     * follow-up (active run) or resumes the session (terminal run).
-     * A decision steers the supervisor: a follow-up only lands once the
-     * supervisor has no tool calls left, so a blocked child would wait out the
-     * whole turn. Progress stays a follow-up — nobody waits on it. */
+    /** Returns the receipt immediately; the reply arrives as a follow-up (active
+     *  run) or resumes the session (terminal run). A decision steers the
+     *  supervisor, or a blocked child would wait out its whole turn. */
     async contact(run, fromSessionId, reason, content) {
         if (!run.invokedBySessionId)
             throw new Error("run has no supervisor session");
@@ -142,7 +166,7 @@ export class TaskMessenger {
         }
         const message = this.create(run, reason, fromSessionId, run.invokedBySessionId, content, null);
         this.changed(message);
-        this.deliver(message, run, run.invokedBySessionId);
+        this.deliver(message, run.invokedBySessionId);
         return this.require(message.id);
     }
     async reply(questionId, fromSessionId, content) {
@@ -185,7 +209,7 @@ export class TaskMessenger {
         if (continuation)
             this.startRun(continuation);
         else if (run.targetSessionId)
-            this.deliver(reply, run, run.targetSessionId);
+            this.deliver(reply, run.targetSessionId);
         return this.require(reply.id);
     }
     create(run, kind, fromSessionId, toSessionId, content, replyTo) {
@@ -208,30 +232,28 @@ export class TaskMessenger {
         this.store.saveMessage(message);
         return message;
     }
-    /** Never awaits the recipient: the seam's `systemInput` settles with the turn
-     * the input triggers, so awaiting it would block the sender — a child's
-     * `contact` on its supervisor's whole answer turn — which the design forbids.
-     * So `delivered` is written by `confirmed`, against the one proof that
-     * survives an abort or a restart: the message visible in the recipient's own
-     * transcript. Until then it stays pending and the sweep tries again. */
-    deliver(candidate, run, targetSessionId) {
-        const message = this.require(candidate.id);
-        if (message.state !== "pending" && message.state !== "failed")
-            return;
-        if (message.toSessionId !== targetSessionId)
+    /** A control created before its run had a session is aimed once it has one. */
+    deliver(message, targetSessionId) {
+        if (message.toSessionId !== targetSessionId) {
             message.toSessionId = targetSessionId;
-        message.state = "pending";
-        message.error = null;
-        this.store.saveMessage(message);
-        this.changed(message);
-        void this.inject(message, run, targetSessionId, this.mode(message))
-            .catch((error) => log.error(`message ${message.id} delivery collapsed`, error));
+            this.store.saveMessage(message);
+        }
+        void this.outbox.deliver(targetSessionId, [this.carry(message)]);
     }
-    /** The one place a message becomes delivered. */
-    confirmed(id) {
-        const message = this.store.getMessage(id);
-        if (!message || message.state !== "pending")
-            return;
+    carry(message) {
+        return {
+            message,
+            callbackState: ENGINE_STATE[message.state],
+            callbackAttempts: message.attempts,
+            callbackError: message.error,
+            callbackNextAttemptAt: message.nextAttemptAt,
+            // Steer whatever someone is blocked on: a follow-up lands only once the
+            // recipient runs out of tool calls. Progress is a follow-up because nobody waits.
+            ...(message.kind === "follow_up" || message.kind === "progress" ? {} : { callbackMode: "steer" }),
+        };
+    }
+    /** Proven by something other than the recipient's transcript. */
+    delivered(message) {
         message.state = "delivered";
         message.deliveredAt = Date.now();
         message.error = null;
@@ -239,37 +261,6 @@ export class TaskMessenger {
         this.store.saveMessage(message);
         this.changed(message);
     }
-    /** Waiting is not a failed attempt: the message is in flight or the turn it
-     *  has to wait for is still running, so it is tried again shortly and the
-     *  ceiling is left for the deliveries that actually failed (the rule
-     *  outbox.ts keeps for callbacks). */
-    defer(id) {
-        const message = this.store.getMessage(id);
-        if (!message || message.state !== "pending")
-            return;
-        message.nextAttemptAt = Date.now() + 1000;
-        this.store.saveMessage(message);
-    }
-    /** Counts one hand-off and says whether it may happen: a recipient that
-     *  never records the message must not be re-sent once a second forever.
-     *  False means the ceiling was reached and the message is now expired. */
-    spend(id) {
-        const message = this.store.getMessage(id);
-        if (!message || message.state !== "pending")
-            return false;
-        message.attempts += 1;
-        message.nextAttemptAt = Date.now() + retryDelay(message.attempts);
-        if (message.attempts > MAX_DELIVERY_ATTEMPTS) {
-            this.abandon(message, undeliverable(message.attempts - 1, message.error));
-            return false;
-        }
-        this.store.saveMessage(message);
-        return true;
-    }
-    /** Out of attempts. Both ends are told — the recipient that was owed it and
-     *  the sender waiting on the answer — and a decision that expires here stops
-     *  suppressing its run's completion callback, which `execution.ts` decided
-     *  once, at the end of the run, and never revisits. */
     abandon(message, why) {
         message.state = "expired";
         message.error = why;
@@ -277,6 +268,11 @@ export class TaskMessenger {
         message.nextAttemptAt = null;
         this.store.saveMessage(message);
         this.changed(message);
+        this.told(message, why);
+    }
+    /** Both ends are told, and an expired decision stops suppressing its run's
+     *  completion callback, which `execution.ts` decided once and never revisits. */
+    told(message, why) {
         this.unreachable(message.toSessionId, `a ${message.kind} from run ${message.runId}`, why);
         if (message.fromSessionId && message.fromSessionId !== message.toSessionId) {
             this.unreachable(message.fromSessionId, `your ${message.kind} on run ${message.runId}`, why);
@@ -289,69 +285,6 @@ export class TaskMessenger {
             this.store.saveRun(run);
         }
     }
-    /** Steer whatever someone is blocked on: a decision, and the reply that
-     * answers it — a follow-up lands only once the recipient runs out of tool
-     * calls, so each would wait out a whole turn (the reply waited 3 minutes
-     * behind one on 2026-09-07). Progress is a follow-up because nobody waits. */
-    mode(message) {
-        return message.kind === "follow_up" || message.kind === "progress" ? "follow_up" : "steer";
-    }
-    failed(id, error, spent) {
-        const message = this.store.getMessage(id);
-        // Only a still-pending message can fail: a late rejection must not undo a
-        // delivery a newer attempt already proved, nor revive an expired one.
-        if (message?.state !== "pending")
-            return;
-        // Both ends are waiting on this one: the sender for an answer, the
-        // recipient for a message it never got told about.
-        log.warn(`${message.kind} ${id} to session ${message.toSessionId} failed`, error);
-        message.state = "failed";
-        message.error = String(error);
-        // A pass that died before the send never spent its attempt — an
-        // unresolvable target dies there every time, and would retry forever.
-        if (!spent)
-            message.attempts += 1;
-        message.nextAttemptAt = Date.now() + retryDelay(message.attempts);
-        this.store.saveMessage(message);
-        this.changed(message);
-        if (message.attempts > MAX_DELIVERY_ATTEMPTS) {
-            this.abandon(message, undeliverable(message.attempts - 1, message.error));
-        }
-    }
-    /** One pass at getting the message into the recipient: the dedupe on a retry
-     *  and the proof of delivery are the same transcript read. Owns its own
-     *  failure, so an attempt is counted exactly once whether the pass died
-     *  before the send or the send itself was refused. */
-    async inject(message, run, targetSessionId, mode) {
-        let spent = false;
-        try {
-            const session = await this.router.ensure({ channelId: "task", conversationId: targetSessionId });
-            const recorded = async () => (await session.history()).some((turn) => turn.role === "system" && turn.origin?.kind === "task-message" && turn.origin.messageId === message.id);
-            if (await recorded())
-                return this.confirmed(message.id);
-            // Accepted and waiting in the recipient's queue for the running turn to
-            // drain it: not recorded yet, and sending again would deliver the same
-            // guidance twice. Unlike a callback this is not deferred on a busy
-            // target — a steer's whole point is to reach the turn already running —
-            // so the queue is where it sits, and waiting for it costs no attempt.
-            if (await this.queued(session, message.id))
-                return this.defer(message.id);
-            spent = this.spend(message.id);
-            if (!spent)
-                return;
-            await session.systemInput(this.format(message, run), this.origin(message, run), mode === "follow_up" ? "followUp" : mode);
-            if (await recorded())
-                this.confirmed(message.id);
-        }
-        catch (error) {
-            this.failed(message.id, error, spent);
-        }
-    }
-    /** In the recipient's queue, by the id its origin carries — the transcript
-     *  read above answers "landed", this answers "handed over and waiting". */
-    async queued(session, id) {
-        return (await session.pendingSystemInputs()).some((origin) => origin.kind === "task-message" && origin.messageId === id);
-    }
     format(message, run) {
         const title = run.context.definition.name;
         if (message.kind === "progress") {

package/dist/tasks/outbox.js

@@ -1,36 +1,28 @@
-// One delivery engine for everything that has to reach a session as a system
-// input: run callbacks and group callbacks. Its whole reason to exist is that
-// this logic was written twice and the two copies drifted — the ceiling was
-// checked in one order here and another there, and only one of them counted a
-// failed attempt.
+// One delivery engine for everything that reaches a session as a system input:
+// run callbacks, group callbacks and run messages.
 import { logger } from "../log.js";
 import { MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
 const log = logger("tasks");
 /** The records a delivery names, from either side of the seam: a batch names
- *  every one of them, a group names itself. */
-const callbackIds = (origin) => origin?.kind === "task-callback" ? origin.runIds ?? [origin.runId] : [];
+ *  every one of them, a group names itself, a message names its id. */
+const recordIds = (origin) => {
+    if (origin?.kind === "task-callback")
+        return origin.runIds ?? [origin.runId];
+    if (origin?.kind === "task-message")
+        return [origin.messageId];
+    return [];
+};
 export class Outbox {
     router;
     kind;
-    unreachable;
     delivering = new Set();
-    constructor(router, kind, 
-    /** Reports a delivery nobody can complete (service.ts owns the surfaces). */
-    unreachable) {
+    constructor(router, kind) {
         this.router = router;
         this.kind = kind;
-        this.unreachable = unreachable;
     }
-    /**
-     * Delivers a batch aimed at one session: one model turn drains the backlog
-     * instead of one turn per record.
-     *
-     * `delivered` is written only against proof — the input visible in the
-     * recipient's own transcript. Pi's queues are memory, so an abort or a
-     * restart drops an accepted input and `systemInput` resolving proves
-     * nothing; a delivery reported on a resolved send is how a delegating agent
-     * ends up waiting forever on a result that was never read.
-     */
+    /** One model turn drains the batch instead of one per record. `delivered` is
+     *  written only against the input visible in the recipient's transcript: Pi's
+     *  queues are memory, so a resolved `systemInput` proves nothing. */
     async deliver(sessionId, batch) {
         const mine = batch.filter((record) => !this.delivering.has(this.kind.id(record)));
         if (mine.length === 0)
@@ -47,22 +39,16 @@ export class Outbox {
             const live = unproven.filter((record) => !this.spent(record, sessionId));
             if (live.length === 0)
                 return;
-            // Waiting for a busy target is not a delivery attempt: counting it would
-            // inflate the attempts once per second and skip the failure backoff
-            // straight to its ceiling. A record delegated with `steer` is the
-            // exception it asked for — it joins the running turn instead, and the
-            // rest of the batch keeps waiting for the turn to end. But only once:
-            // handed over, a steer sits in Pi's in-memory queue, invisible in the
-            // transcript until the turn drains it, so the queue is the second place
-            // this has to look before deciding nothing arrived (messages.ts:340).
-            const streaming = session.state === "streaming";
             let sending = live;
-            if (streaming) {
+            // Waiting for a busy target is not an attempt, or the ceiling arrives in
+            // seconds. A `steer` record joins the running turn instead, but only once:
+            // handed over, it sits in Pi's in-memory queue, invisible in the transcript.
+            if (session.state === "streaming") {
                 const handedOver = await this.queued(session);
-                const steerNow = (record) => record.callbackMode === "steer" && !handedOver.has(this.kind.id(record));
-                sending = live.filter(steerNow);
+                const sendNow = (record) => (record.callbackMode === "steer" || this.kind.queues === true) && !handedOver.has(this.kind.id(record));
+                sending = live.filter(sendNow);
                 for (const record of live)
-                    if (!steerNow(record))
+                    if (!sendNow(record))
                         this.defer(record);
                 if (sending.length === 0)
                     return;
@@ -72,14 +58,12 @@ export class Outbox {
                 counted.add(this.kind.id(record));
             }
             const { text, origin } = this.kind.input(sending);
+            const mode = sending.every((record) => record.callbackMode === "steer") ? "steer" : "followUp";
             log.debug(`callback for ${sending.map((r) => this.kind.id(r)).join(", ")} → session ${sessionId}`);
-            // Not awaited: `systemInput` settles with the recipient's whole turn, and
-            // holding the delivery lock that long would keep the proof from ever
-            // being read — which is the only thing that marks this delivered.
-            session.systemInput(text, origin, streaming ? "steer" : "followUp")
+            // Not awaited: `systemInput` settles with the recipient's whole turn.
+            session.systemInput(text, origin, mode)
                 .catch((error) => this.retry(sessionId, sending, error, counted));
-            // Pi records the input as it starts the turn, so the proof is usually
-            // here already; the tick sweep is the backstop when it is not.
+            // Pi records the input as it starts the turn; the tick sweep is the backstop.
             await this.settle(sending, session);
         }
         catch (error) {
@@ -90,13 +74,11 @@ export class Outbox {
                 this.delivering.delete(this.kind.id(record));
         }
     }
-    /** Handed over and waiting in the recipient's queue for the running turn to
-     *  drain it — what the transcript cannot answer yet. Empty unless the
-     *  session is streaming: Pi drops the list when the turn ends. */
+    /** What the transcript cannot answer yet; empty unless the session is streaming. */
     async queued(session) {
         const ids = new Set();
         for (const origin of await session.pendingSystemInputs())
-            for (const id of callbackIds(origin))
+            for (const id of recordIds(origin))
                 ids.add(id);
         return ids;
     }
@@ -106,7 +88,7 @@ export class Outbox {
         for (const turn of await session.history()) {
             if (turn.role !== "system")
                 continue;
-            for (const id of callbackIds(turn.origin))
+            for (const id of recordIds(turn.origin))
                 seen.add(id);
         }
         const unproven = [];
@@ -119,9 +101,7 @@ export class Outbox {
         }
         return unproven;
     }
-    /** The recipient is waiting for an answer that is now late: the retry itself
-     *  is silent, so this line is the only sign it is being retried — and the
-     *  ceiling is what ends the retrying out loud. */
+    /** The retry itself is silent, so this line is the only sign of it. */
     retry(sessionId, batch, error, counted) {
         log.warn(`callback to session ${sessionId} failed, will retry`, error);
         for (const stale of batch) {
@@ -134,8 +114,7 @@ export class Outbox {
             this.spent(record, sessionId);
         }
     }
-    /** Out of attempts: stop, record why, and report it. An agent waiting on a
-     *  result it will never get must not be left waiting on silence. */
+    /** An agent waiting on a result it will never get must not wait on silence. */
     spent(record, sessionId) {
         if (record.callbackAttempts < MAX_DELIVERY_ATTEMPTS)
             return false;
@@ -144,7 +123,7 @@ export class Outbox {
             record.callbackError = undeliverable(record.callbackAttempts, record.callbackError);
             record.callbackNextAttemptAt = null;
             this.write(record);
-            this.unreachable(sessionId, this.kind.describe(record), record.callbackError);
+            this.kind.abandoned(record, sessionId, record.callbackError);
         }
         return true;
     }
@@ -153,8 +132,8 @@ export class Outbox {
         record.callbackNextAttemptAt = Date.now() + 1000;
         this.kind.save(record);
     }
-    /** Handed over, proof pending. Backs off like a failure, so an input the
-     *  recipient never records is re-sent on a curve, not once a second. */
+    /** Backs off like a failure, so an input never recorded is re-sent on a
+     *  curve, not once a second. */
     sent(record) {
         record.callbackAttempts += 1;
         record.callbackState = "pending";

package/dist/tasks/routes.js

@@ -1,7 +1,5 @@
-// The area's HTTP surface: tasks, runs, group and message routes for the
-// Console, plus the Activity snapshot it draws its graph from. A route reads
-// its body, names the caller and hands the decision to TaskService — policy
-// that lives here would be policy the task tool does not get.
+// The area's HTTP surface. A route names the caller and hands the decision to
+// TaskService: policy here would be policy the task tool does not get.
 import { record, requiredString } from "./definitions.js";
 /** Reject malformed filters instead of silently widening a global query. */
 function runQuery(params) {
@@ -224,9 +222,8 @@ export function registerTaskRoutes(app, tasks, activity) {
         const body = record(await jsonBody(c.req));
         const input = body && "input" in body ? body.input : null;
         try {
-            // A caller that names a mode gets an answer about it: dropping an
-            // unsupported override would run the definition's own policy instead —
-            // on a reuse definition, work injected into a live session.
+            // Dropping an unsupported override would run the definition's own policy
+            // instead — on a reuse definition, work injected into a live session.
             if (body?.sessionMode !== undefined && body.sessionMode !== "fresh") {
                 throw new Error(`unsupported sessionMode: ${String(body.sessionMode)}`);
             }

package/dist/tasks/runs.js

@@ -1,8 +1,5 @@
-// A definition plus an input becomes a queued run: where it came from, how
-// deep in a subagent chain it sits, whether it overlaps a run already going,
-// and which session hears about it. The limits that keep a chain from
-// exploding (depth, children per root) are decided here, once, because every
-// caller — scheduler, tool, HTTP — enqueues through this one door.
+// A definition plus an input becomes a queued run. The depth and per-root
+// limits are decided here because every caller enqueues through this one door.
 import { logger } from "../log.js";
 import { newId } from "./definitions.js";
 const log = logger("tasks");
@@ -92,10 +89,8 @@ export class TaskRunQueue {
         const { id, depth, triggerSource: source } = run;
         const overlapped = run.skipReason === "overlap";
         const definition = run.context.definition;
-        // Why a run exists is the first question asked of a surprising one, and it
-        // is answerable only here: the row keeps the ids, not the reason. A watch
-        // probe queues on every interval and mostly matches nothing, so it says so
-        // at debug and lets its settled line (execution.ts) carry the news.
+        // Why a run exists is answerable only here: the row keeps the ids, not the
+        // reason. A watch probe queues every interval, so it logs at debug.
         const queued = `run ${id} ${run.state}: ${definition.name} via ${source}` +
             `${overlapped ? " (overlapped)" : ""}${depth > 0 ? ` depth ${String(depth)}` : ""}`;
         if (source === "watch" && !overlapped)