@timqi/pier 0.0.1 → 0.0.2

package/dist/tasks/callbacks.js

@@ -1,7 +1,8 @@
+// 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 { logger } from "../log.js";
+import { Outbox } from "./outbox.js";
 import { TaskStore } from "./store.js";
-const log = logger("tasks");
 export function runResultText(run) {
     let result = run.error ?? "No result";
     if (run.result?.type === "agent")
@@ -13,18 +14,31 @@ 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; open run ${run.id}]`;
+        result = `${result.slice(0, 8000)}\n[truncated — task tool get run_id ${run.id} returns the full text]`;
     return result;
 }
 export class TaskCallbacks {
     store;
-    router;
-    changed;
-    delivering = new Set();
-    constructor(store, router, changed) {
+    outbox;
+    constructor(store, router, changed, unreachable) {
         this.store = store;
-        this.router = router;
-        this.changed = changed;
+        this.outbox = new Outbox(router, {
+            id: (run) => run.id,
+            reload: (id) => this.store.getRun(id),
+            save: (run) => { this.store.saveRun(run); },
+            changed,
+            input: (runs) => ({
+                text: this.text(runs),
+                origin: {
+                    kind: "task-callback",
+                    taskId: runs[0].taskId,
+                    runId: runs[0].id,
+                    sourceSessionId: runs[0].targetSessionId,
+                    runIds: runs.map((run) => run.id),
+                },
+            }),
+            describe: (run) => `the result of "${run.context.definition.name}"`,
+        }, unreachable);
     }
     target(callback, origin) {
         if (callback.type === "session")
@@ -37,94 +51,20 @@ export class TaskCallbacks {
         for (const run of this.store.listPendingCallbacks(now))
             void this.deliver(run);
     }
-    /** Delivers the candidate and, in the same system input, every other
-     * deliverable callback aimed at the same session: one model turn drains the
-     * backlog instead of one turn per run. */
+    /** Delivers the candidate together with every other deliverable callback
+     * aimed at the same session. */
     async deliver(candidate) {
-        if (this.delivering.has(candidate.id))
-            return;
         const first = this.store.getRun(candidate.id);
         if (!first?.callbackSessionId || (first.callbackState !== "pending" && first.callbackState !== "failed"))
             return;
         const sessionId = first.callbackSessionId;
-        // Ignore retry due-times when sweeping the batch: once one callback is
+        // Retry due-times are ignored when sweeping the batch: once one callback is
         // deliverable, everything pending for the session rides along.
-        const batch = this.store.listPendingCallbacks(Number.MAX_SAFE_INTEGER).filter((run) => run.callbackSessionId === sessionId && !this.delivering.has(run.id));
+        const batch = this.store.listPendingCallbacks(Number.MAX_SAFE_INTEGER)
+            .filter((run) => run.callbackSessionId === sessionId);
         if (!batch.some((run) => run.id === first.id))
             return;
-        for (const run of batch)
-            this.delivering.add(run.id);
-        try {
-            const session = await this.router.ensure({ channelId: "task", conversationId: sessionId });
-            // Crash-window idempotency: any run id already present in a persisted
-            // callback input (single or batched) must not be sent again.
-            const seen = new Set();
-            for (const turn of await session.history()) {
-                if (turn.role !== "system" || turn.origin?.kind !== "task-callback")
-                    continue;
-                for (const id of turn.origin.runIds ?? [turn.origin.runId])
-                    seen.add(id);
-            }
-            const fresh = batch.filter((run) => !seen.has(run.id));
-            // Waiting for a busy target is not a delivery attempt: counting it would
-            // inflate `callbackAttempts` once per second and skip the real failure
-            // backoff straight to its ceiling.
-            if (fresh.length > 0 && session.state === "streaming") {
-                for (const run of batch) {
-                    run.callbackNextAttemptAt = Date.now() + 1000;
-                    this.store.saveRun(run);
-                }
-                return;
-            }
-            for (const run of batch) {
-                run.callbackAttempts += 1;
-                run.callbackState = "pending";
-                run.callbackError = null;
-                this.store.saveRun(run);
-            }
-            // `systemInput` resolves when the turn it triggers settles, not when Pi
-            // accepts the input — so mark delivered first and let a rejection below
-            // flip it to failed. Otherwise a recipient turn that runs for minutes
-            // leaves the run "pending" and a restart in that window re-delivers.
-            const sent = fresh.length > 0
-                ? session.systemInput(this.text(fresh), {
-                    kind: "task-callback",
-                    taskId: fresh[0].taskId,
-                    runId: fresh[0].id,
-                    sourceSessionId: fresh[0].targetSessionId,
-                    runIds: fresh.map((run) => run.id),
-                }, "followUp")
-                : Promise.resolve();
-            for (const run of batch) {
-                run.callbackState = "delivered";
-                run.callbackNextAttemptAt = null;
-                this.store.saveRun(run);
-                this.changed(run);
-            }
-            if (fresh.length > 0) {
-                log.debug(`callback for ${fresh.map((run) => run.id).join(", ")} → session ${sessionId}`);
-            }
-            await sent;
-        }
-        catch (error) {
-            // The delegating agent is waiting for an answer that is now late: the
-            // retry is silent, so this line is the only sign it is being retried.
-            log.warn(`callback to session ${sessionId} failed, will retry`, error);
-            for (const stale of batch) {
-                const run = this.store.getRun(stale.id);
-                if (!run)
-                    continue;
-                run.callbackState = "failed";
-                run.callbackError = String(error);
-                run.callbackNextAttemptAt = Date.now() + Math.min(60_000, 1000 * 2 ** Math.min(run.callbackAttempts, 6));
-                this.store.saveRun(run);
-                this.changed(run);
-            }
-        }
-        finally {
-            for (const run of batch)
-                this.delivering.delete(run.id);
-        }
+        await this.outbox.deliver(sessionId, batch);
     }
     text(runs) {
         const sections = runs.map((run) => [

package/dist/tasks/definitions.js

@@ -45,6 +45,8 @@ function parseTrigger(raw) {
     }
     throw new Error("unknown trigger type");
 }
+/** Always computed from `from` (boot recomputes from *now*): cron runs missed
+ *  while Pier was down are skipped, never caught up — no double fire. */
 export function nextRunAt(trigger, from) {
     if (trigger.type === "manual")
         return null;
@@ -266,12 +268,6 @@ export class TaskDefinitions {
                 await this.assertDirectory(cwd);
             session = { mode: "fork", ...(cwd ? { cwd } : {}) };
         }
-        else if (typeof raw.sessionId === "string" && raw.sessionId.trim()) {
-            const sessionId = raw.sessionId.trim();
-            if (!(await this.sessionExists(sessionId)))
-                throw new Error(`unknown session: ${sessionId}`);
-            session = { mode: "reuse", sessionId };
-        }
         else {
             // Validation never mutates: a dedicated session is created explicitly
             // (POST /api/sessions) and then referenced with mode:"reuse".

package/dist/tasks/execution.js

@@ -86,8 +86,17 @@ export class TaskExecution {
             // completion callback: the pending question is the notification.
             if (run.callbackSessionId && !this.host.openDecisionId(run.id))
                 run.callbackState = "pending";
-            this.store.saveRun(run);
             this.controllers.delete(run.id);
+            try {
+                this.store.saveRun(run);
+            }
+            catch (err) {
+                // Waiters settle from the in-memory run below; the callback and any
+                // group join read the stale row and wait — the next boot's interrupt
+                // sweep re-marks it and delivers then. Named here so that delay has
+                // an explanation.
+                log.error(`run ${run.id} final save failed — callback/join deferred to next boot`, err);
+            }
             this.host.changed(run);
             this.host.settled(run);
             if (run.callbackState === "pending")

package/dist/tasks/groups.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
 import { runResultText } from "./callbacks.js";
+import { Outbox } from "./outbox.js";
 import { TaskStore } from "./store.js";
 import { isTerminal } from "./types.js";
 const log = logger("tasks");
@@ -9,15 +10,26 @@ const log = logger("tasks");
  * aggregated callback when the join condition is met (design 04). */
 export class TaskGroups {
     store;
-    router;
     host;
     changed;
-    delivering = new Set();
-    constructor(store, router, host, changed) {
+    outbox;
+    constructor(store, router, host, changed, unreachable) {
         this.store = store;
-        this.router = router;
         this.host = host;
         this.changed = changed;
+        this.outbox = new Outbox(router, {
+            id: (group) => group.id,
+            reload: (id) => this.store.getGroup(id),
+            save: (group) => { this.store.saveGroup(group); },
+            changed,
+            // A group names itself in the origin where a run names its run id, so the
+            // engine's transcript proof works unchanged.
+            input: (groups) => ({
+                text: this.text(groups[0]),
+                origin: { kind: "task-callback", taskId: groups[0].id, runId: groups[0].id, sourceSessionId: null },
+            }),
+            describe: (group) => `the result of a ${String(group.memberRunIds.length)}-run group`,
+        }, unreachable);
     }
     /** Enqueues every member or none: a partially started group is worse than
      * a rejected one. */
@@ -113,53 +125,12 @@ export class TaskGroups {
         if (group.callbackState === "pending")
             void this.deliver(group);
     }
-    /** Same outbox semantics as run callbacks: busy defer, transcript dedupe on
-     * the group id, backoff retry, restart recovery. */
+    /** The engine owns retry, proof and the ceiling; a group is a batch of one. */
     async deliver(candidate) {
-        if (this.delivering.has(candidate.id))
+        const group = this.store.getGroup(candidate.id);
+        if (!group?.callbackSessionId || (group.callbackState !== "pending" && group.callbackState !== "failed"))
             return;
-        this.delivering.add(candidate.id);
-        try {
-            const group = this.store.getGroup(candidate.id);
-            if (!group?.callbackSessionId || (group.callbackState !== "pending" && group.callbackState !== "failed"))
-                return;
-            const session = await this.router.ensure({ channelId: "task", conversationId: group.callbackSessionId });
-            const alreadyDelivered = (await session.history()).some((turn) => turn.role === "system" && turn.origin?.kind === "task-callback" && turn.origin.runId === group.id);
-            // Busy target: waiting is not an attempt (see TaskCallbacks.deliver).
-            if (!alreadyDelivered && session.state === "streaming") {
-                group.callbackNextAttemptAt = Date.now() + 1000;
-                this.store.saveGroup(group);
-                return;
-            }
-            group.callbackAttempts += 1;
-            group.callbackState = "pending";
-            group.callbackError = null;
-            this.store.saveGroup(group);
-            // Delivered means Pi accepted the input, not that the recipient's turn
-            // ended (see TaskCallbacks.deliver); a rejection flips it to failed.
-            const sent = alreadyDelivered
-                ? Promise.resolve()
-                : session.systemInput(this.text(group), { kind: "task-callback", taskId: group.id, runId: group.id, sourceSessionId: null }, "followUp");
-            group.callbackState = "delivered";
-            group.callbackNextAttemptAt = null;
-            this.store.saveGroup(group);
-            this.changed(group);
-            await sent;
-        }
-        catch (error) {
-            log.warn(`group ${candidate.id} callback failed, will retry`, error);
-            const group = this.store.getGroup(candidate.id);
-            if (!group)
-                return;
-            group.callbackState = "failed";
-            group.callbackError = String(error);
-            group.callbackNextAttemptAt = Date.now() + Math.min(60_000, 1000 * 2 ** Math.min(group.callbackAttempts, 6));
-            this.store.saveGroup(group);
-            this.changed(group);
-        }
-        finally {
-            this.delivering.delete(candidate.id);
-        }
+        await this.outbox.deliver(group.callbackSessionId, [group]);
     }
     text(group) {
         const members = group.memberRunIds.map((id) => this.host.getRun(id));

package/dist/tasks/messages.js

@@ -3,7 +3,7 @@ import { EventHub } from "../core/hub.js";
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
 import { TaskStore } from "./store.js";
-import { isTerminal } from "./types.js";
+import { isTerminal, MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
 const log = logger("tasks");
 const MAX_MESSAGE_LENGTH = 16 * 1024;
 function bounded(content) {
@@ -19,16 +19,17 @@ export class TaskMessenger {
     router;
     hub;
     resumeRun;
-    /** Retry schedule for failed injections. In-memory on purpose: a restart
-     * expires undelivered control messages and re-offers decisions anyway. */
-    retries = new Map();
+    unreachable;
     constructor(store, router, hub, 
     /** Continues a terminal child with a supervisor reply as its prompt. */
-    resumeRun) {
+    resumeRun, 
+    /** Reports a delivery nobody can complete (service.ts owns the surfaces). */
+    unreachable) {
         this.store = store;
         this.router = router;
         this.hub = hub;
         this.resumeRun = resumeRun;
+        this.unreachable = unreachable;
     }
     expirePending() {
         for (const message of this.store.expirePendingMessages())
@@ -54,8 +55,8 @@ export class TaskMessenger {
     list(runId) {
         return this.store.listMessages(runId);
     }
-    recent(since, limit = 200) {
-        return this.store.listRecentMessages(since, limit);
+    recent(since) {
+        return this.store.listRecentMessages(since);
     }
     async control(run, fromSessionId, kind, content) {
         const message = this.create(run, kind, fromSessionId, run.targetSessionId ?? "", content, null);
@@ -88,7 +89,7 @@ export class TaskMessenger {
                 this.changed(message);
                 continue;
             }
-            if ((this.retries.get(message.id)?.nextAt ?? 0) > now)
+            if ((message.nextAttemptAt ?? 0) > now)
                 continue;
             const target = message.toSessionId || run.targetSessionId;
             if (target)
@@ -163,6 +164,8 @@ export class TaskMessenger {
             deliveredAt: null,
             answeredAt: null,
             error: null,
+            attempts: 0,
+            nextAttemptAt: null,
         };
         this.store.saveMessage(message);
         this.changed(message);
@@ -171,47 +174,129 @@ export class TaskMessenger {
     /** 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.
-     * Delivery is therefore recorded on hand-off and corrected to `failed` by the
-     * catch; the tick sweep retries from there. */
+     * 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)
             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));
+    }
+    /** The one place a message becomes delivered. */
+    confirmed(id) {
+        const message = this.store.getMessage(id);
+        if (!message || message.state !== "pending")
+            return;
         message.state = "delivered";
         message.deliveredAt = Date.now();
         message.error = null;
+        message.nextAttemptAt = null;
         this.store.saveMessage(message);
         this.changed(message);
-        void this.inject(message, run, targetSessionId, this.mode(message))
-            .catch((error) => { this.failed(message.id, error); });
+    }
+    /** 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;
+        message.answeredAt = Date.now();
+        message.nextAttemptAt = null;
+        this.store.saveMessage(message);
+        this.changed(message);
+        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);
+        }
+        const run = this.store.getRun(message.runId);
+        if (message.kind !== "decision" || !run?.callbackSessionId)
+            return;
+        if (run.callbackState === null && isTerminal(run.state)) {
+            run.callbackState = "pending"; // the tick sweep delivers it
+            this.store.saveRun(run);
+        }
     }
     /** A decision steers — a follow-up would land only after the supervisor runs
      * out of tool calls, leaving the child waiting out the whole turn. */
     mode(message) {
         return message.kind === "steer" || message.kind === "decision" ? "steer" : "follow_up";
     }
-    failed(id, error) {
+    failed(id, error, spent) {
         const message = this.store.getMessage(id);
-        if (!message || message.state === "answered" || message.state === "expired")
+        // 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);
-        const attempts = (this.retries.get(id)?.attempts ?? 0) + 1;
-        this.retries.set(id, { attempts, nextAt: Date.now() + Math.min(60_000, 1000 * 2 ** Math.min(attempts, 6)) });
+        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) {
-        const session = await this.router.ensure({ channelId: "task", conversationId: targetSessionId });
-        const delivered = (await session.history()).some((turn) => turn.role === "system" && turn.origin?.kind === "task-message" && turn.origin.messageId === message.id);
-        if (delivered)
-            return;
-        await session.systemInput(this.format(message, run), this.origin(message, run), mode === "follow_up" ? "followUp" : 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 Pi's queue for the running turn to drain it:
+            // not recorded yet, and sending again would deliver the same steer twice.
+            // Unlike a callback this is not deferred — a steer's whole point is to
+            // reach the turn already running — so the queue is where it sits, and
+            // waiting for it to drain costs no attempt.
+            const queue = await session.pendingQueue();
+            if ([...queue.steering, ...queue.followUp].some((text) => text.includes(message.id)))
+                return;
+            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);
+        }
     }
     format(message, run) {
         const title = run.context.definition.name;

package/dist/tasks/outbox.js

@@ -0,0 +1,157 @@
+// 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.
+import { Router } from "../core/router.js";
+import { logger } from "../log.js";
+import { MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
+const log = logger("tasks");
+export class Outbox {
+    router;
+    kind;
+    unreachable;
+    delivering = new Set();
+    constructor(router, kind, 
+    /** Reports a delivery nobody can complete (service.ts owns the surfaces). */
+    unreachable) {
+        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.
+     */
+    async deliver(sessionId, batch) {
+        const mine = batch.filter((record) => !this.delivering.has(this.kind.id(record)));
+        if (mine.length === 0)
+            return;
+        for (const record of mine)
+            this.delivering.add(this.kind.id(record));
+        try {
+            const session = await this.router.ensure({ channelId: "task", conversationId: sessionId });
+            // The transcript read is both the crash-window dedupe and the proof.
+            const unproven = await this.settle(mine, session);
+            // Checked after the proof: a record whose input did land must not be
+            // given up on for having spent its last attempt landing it.
+            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.
+            if (session.state === "streaming") {
+                for (const record of live)
+                    this.defer(record);
+                return;
+            }
+            for (const record of live)
+                this.sent(record);
+            const { text, origin } = this.kind.input(live);
+            log.debug(`callback for ${live.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, "followUp")
+                .catch((error) => this.retry(sessionId, live, error));
+            // 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.
+            await this.settle(live, session);
+        }
+        catch (error) {
+            this.retry(sessionId, mine, error);
+        }
+        finally {
+            for (const record of mine)
+                this.delivering.delete(this.kind.id(record));
+        }
+    }
+    /** Marks every record the transcript proves; returns the ones it does not. */
+    async settle(records, session) {
+        const seen = new Set();
+        for (const turn of await session.history()) {
+            if (turn.role !== "system" || turn.origin?.kind !== "task-callback")
+                continue;
+            for (const id of turn.origin.runIds ?? [turn.origin.runId])
+                seen.add(id);
+        }
+        const unproven = [];
+        for (const stale of records) {
+            const record = this.kind.reload(this.kind.id(stale)) ?? stale;
+            if (!seen.has(this.kind.id(record)))
+                unproven.push(record);
+            else if (record.callbackState !== "delivered")
+                this.delivered(record);
+        }
+        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. */
+    retry(sessionId, batch, error) {
+        log.warn(`callback to session ${sessionId} failed, will retry`, error);
+        for (const stale of batch) {
+            const record = this.kind.reload(this.kind.id(stale));
+            // Already proven delivered, or already given up on: not a failure.
+            if (!record || (record.callbackState !== "pending" && record.callbackState !== "failed"))
+                continue;
+            this.failed(record, error);
+            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. */
+    spent(record, sessionId) {
+        if (record.callbackAttempts < MAX_DELIVERY_ATTEMPTS)
+            return false;
+        if (record.callbackState !== "abandoned") {
+            record.callbackState = "abandoned";
+            record.callbackError = undeliverable(record.callbackAttempts, record.callbackError);
+            record.callbackNextAttemptAt = null;
+            this.write(record);
+            this.unreachable(sessionId, this.kind.describe(record), record.callbackError);
+        }
+        return true;
+    }
+    /** Busy target: try again shortly, and do not count it. */
+    defer(record) {
+        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. */
+    sent(record) {
+        record.callbackAttempts += 1;
+        record.callbackState = "pending";
+        record.callbackError = null;
+        record.callbackNextAttemptAt = Date.now() + retryDelay(record.callbackAttempts);
+        this.kind.save(record);
+    }
+    delivered(record) {
+        record.callbackState = "delivered";
+        record.callbackError = null;
+        record.callbackNextAttemptAt = null;
+        this.write(record);
+    }
+    /** Counts the attempt too: a target that fails before anything is sent (a
+     *  transcript that no longer exists) would otherwise retry at attempt 0 for
+     *  as long as the process lives, never reaching the ceiling. */
+    failed(record, error) {
+        record.callbackAttempts += 1;
+        record.callbackState = "failed";
+        record.callbackError = String(error);
+        record.callbackNextAttemptAt = Date.now() + retryDelay(record.callbackAttempts);
+        this.write(record);
+    }
+    write(record) {
+        this.kind.save(record);
+        this.kind.changed(record);
+    }
+}