opencode-courier 0.6.0 → 0.7.1

package/dist/tree/rpc.d.ts

@@ -7,6 +7,8 @@ declare const Summary: Schema.Struct<{
     readonly waiting: Schema.Int;
     /** Not running: done, or waiting for a message. */
     readonly idle: Schema.Int;
+    /** Left a courier message waiting while idle, and did not take it once woken again; the session itself counts too. Absent at 0. */
+    readonly stalled: Schema.optionalKey<Schema.Int>;
     readonly groups: Schema.$Array<Schema.Struct<{
         readonly name: Schema.String;
         readonly reported: Schema.Int;
@@ -33,8 +35,13 @@ declare const Row: Schema.Struct<{
     readonly title: Schema.String;
     /** A child of the panel's session is at depth 1. */
     readonly depth: Schema.Int;
-    /** `waiting` on a request to the person or a form it shows them; `gone` when OpenCode no longer knows it. */
-    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "gone"]>;
+    /**
+     * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+     * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+     */
+    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+    /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+    readonly stalled: Schema.optionalKey<Schema.Number>;
     /** How its last turn ended. */
     readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
     /** Set when courier_stop stopped it since its last prompt. */
@@ -81,8 +88,13 @@ declare const Tree: Schema.Struct<{
         readonly title: Schema.String;
         /** A child of the panel's session is at depth 1. */
         readonly depth: Schema.Int;
-        /** `waiting` on a request to the person or a form it shows them; `gone` when OpenCode no longer knows it. */
-        readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "gone"]>;
+        /**
+         * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+         * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+         */
+        readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+        /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+        readonly stalled: Schema.optionalKey<Schema.Number>;
         /** How its last turn ended. */
         readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
         /** Set when courier_stop stopped it since its last prompt. */
@@ -123,6 +135,8 @@ declare const Tree: Schema.Struct<{
     }>>;
     /** How many older sessions the listing left out, when it had more than `maxTotal`: the live ones come first, then the newest. */
     readonly truncated: Schema.optionalKey<Schema.Int>;
+    /** Since when a courier message has waited in the panel's own session, when that session is stalled. */
+    readonly stalled: Schema.optionalKey<Schema.Number>;
 }>;
 export type Row = typeof Row.Type;
 export type Tree = typeof Tree.Type;
@@ -159,22 +173,24 @@ export declare const treeRpc: {
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly running: number;
-                readonly waiting: number;
                 readonly idle: number;
                 readonly groups: readonly {
                     readonly name: string;
                     readonly reported: number;
                     readonly members: number;
                 }[];
+                readonly waiting: number;
+                readonly stalled?: number | undefined;
             }, {
                 readonly running: number;
-                readonly waiting: number;
                 readonly idle: number;
                 readonly groups: readonly {
                     readonly name: string;
                     readonly reported: number;
                     readonly members: number;
                 }[];
+                readonly waiting: number;
+                readonly stalled?: number | undefined;
             }> & Schema.Struct<{
                 /** Running, and waiting on no request or form. */
                 readonly running: Schema.Int;
@@ -182,6 +198,8 @@ export declare const treeRpc: {
                 readonly waiting: Schema.Int;
                 /** Not running: done, or waiting for a message. */
                 readonly idle: Schema.Int;
+                /** Left a courier message waiting while idle, and did not take it once woken again; the session itself counts too. Absent at 0. */
+                readonly stalled: Schema.optionalKey<Schema.Int>;
                 readonly groups: Schema.$Array<Schema.Struct<{
                     readonly name: Schema.String;
                     readonly reported: Schema.Int;
@@ -205,7 +223,7 @@ export declare const treeRpc: {
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -228,6 +246,7 @@ export declare const treeRpc: {
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -235,6 +254,7 @@ export declare const treeRpc: {
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }, {
                 readonly rows: readonly {
@@ -244,7 +264,7 @@ export declare const treeRpc: {
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -267,6 +287,7 @@ export declare const treeRpc: {
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -274,6 +295,7 @@ export declare const treeRpc: {
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }> & Schema.Struct<{
                 readonly rows: Schema.$Array<Schema.Struct<{
@@ -282,8 +304,13 @@ export declare const treeRpc: {
                     readonly title: Schema.String;
                     /** A child of the panel's session is at depth 1. */
                     readonly depth: Schema.Int;
-                    /** `waiting` on a request to the person or a form it shows them; `gone` when OpenCode no longer knows it. */
-                    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "gone"]>;
+                    /**
+                     * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+                     * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+                     */
+                    readonly state: Schema.Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
+                    /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+                    readonly stalled: Schema.optionalKey<Schema.Number>;
                     /** How its last turn ended. */
                     readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
                     /** Set when courier_stop stopped it since its last prompt. */
@@ -324,6 +351,8 @@ export declare const treeRpc: {
                 }>>;
                 /** How many older sessions the listing left out, when it had more than `maxTotal`: the live ones come first, then the newest. */
                 readonly truncated: Schema.optionalKey<Schema.Int>;
+                /** Since when a courier message has waited in the panel's own session, when that session is stalled. */
+                readonly stalled: Schema.optionalKey<Schema.Number>;
             }>;
         };
         /** Stops `sessionID` and everything under it, as courier_stop called from `by`, which must be above it. */

package/dist/tree/rpc.js

@@ -15,6 +15,8 @@ const Summary = Schema.Struct({
     waiting: Count,
     /** Not running: done, or waiting for a message. */
     idle: Count,
+    /** Left a courier message waiting while idle, and did not take it once woken again; the session itself counts too. Absent at 0. */
+    stalled: Schema.optionalKey(Count),
     groups: Schema.Array(Group),
 });
 /** A request a session waits on until the person answers it: a permission request, its first question, or a form it shows. */
@@ -30,8 +32,13 @@ const Row = Schema.Struct({
     title: Schema.String,
     /** A child of the panel's session is at depth 1. */
     depth: Count,
-    /** `waiting` on a request to the person or a form it shows them; `gone` when OpenCode no longer knows it. */
-    state: Schema.Literals(["running", "waiting", "idle", "gone"]),
+    /**
+     * `waiting` on a request to the person or a form it shows them; `stalled` when a courier message waits in its inbox and
+     * waking it again did not start a turn; `gone` when OpenCode no longer knows it.
+     */
+    state: Schema.Literals(["running", "waiting", "idle", "stalled", "gone"]),
+    /** Since when its oldest message that did not wake it has waited, when it is stalled. */
+    stalled: Schema.optionalKey(Schema.Number),
     /** How its last turn ended. */
     outcome: Schema.optionalKey(Schema.Literals(["succeeded", "failed", "interrupted"])),
     /** Set when courier_stop stopped it since its last prompt. */
@@ -55,6 +62,8 @@ const Tree = Schema.Struct({
     rows: Schema.Array(Row),
     /** How many older sessions the listing left out, when it had more than `maxTotal`: the live ones come first, then the newest. */
     truncated: Schema.optionalKey(Count),
+    /** Since when a courier message has waited in the panel's own session, when that session is stalled. */
+    stalled: Schema.optionalKey(Schema.Number),
 });
 /** What a stop did to each session, deepest first, as courier_stop reports it. */
 const Stopped = Schema.Struct({

package/dist/tree/stop.js

@@ -4,6 +4,7 @@ import { cleanup } from "./cleanup.js";
 import { childStore } from "./store.js";
 import { subtree } from "./subtree.js";
 import { stoppedNotice } from "./text.js";
+import { forgetWakes } from "./wake.js";
 /** Rounds of looking again for sessions started while others were being stopped. */
 const ROUNDS = 3;
 /**
@@ -62,6 +63,7 @@ async function silence(ports, sessionID, cancelled) {
     catch (error) {
         log(`courier_stop: could not cancel the messages scheduled for ${sessionID}: ${String(error)}`);
     }
+    await forgetWakes(ports.courier, sessionID).catch((error) => log(`courier_stop: could not drop the wake watch of ${sessionID}: ${String(error)}`));
 }
 async function interrupt(ports, { entry, depth }) {
     const { sessionID, title } = entry;

package/dist/tree/store.d.ts

@@ -1,5 +1,5 @@
 import { type Storage } from "../platform/storage.js";
-import type { ChildStore, GroupStore } from "./ports.js";
+import type { ChildStore, GroupStore, WakeStore } from "./ports.js";
 /**
  * What the reverse index holds for a child: the sessions above it, its parent first and the top
  * session, which courier_spawn did not start, last; each is the parent of the one before it.
@@ -18,7 +18,10 @@ export declare const memberKey: (parentID: string, group: string, sessionID: str
 /** The key prefix of a parent's groups, and of one group's members. */
 export declare const groupsPrefix: (parentID: string) => string;
 export declare const groupPrefix: (parentID: string, group: string) => string;
+export declare const wakeKey: (sessionID: string, inboxID: string) => string;
 /** The `ChildStore` over the plugin's storage. */
 export declare function childStore(storage: Storage): ChildStore;
 /** The `GroupStore` over the plugin's storage. */
 export declare function groupStore(storage: Storage): GroupStore;
+/** The `WakeStore` over the plugin's storage. */
+export declare function wakeStore(storage: Storage): WakeStore;

package/dist/tree/store.js

@@ -42,6 +42,12 @@ export const memberKey = (parentID, group, sessionID) => `${GROUP_PREFIX}${paren
 /** The key prefix of a parent's groups, and of one group's members. */
 export const groupsPrefix = (parentID) => `${GROUP_PREFIX}${parentID}/`;
 export const groupPrefix = (parentID, group) => `${groupsPrefix(parentID)}${group}/`;
+/**
+ * The courier messages waiting in a session's inbox, each under `wake/<sessionID>/<inboxID>` until it is delivered, for
+ * the scheduler to wake a session whose wake was missed. docs/maintainers/architecture.md, § Storage.
+ */
+const WAKE_PREFIX = "wake/";
+export const wakeKey = (sessionID, inboxID) => `${WAKE_PREFIX}${sessionID}/${inboxID}`;
 function isReverse(value) {
     const ancestors = value?.ancestors;
     return Array.isArray(ancestors) && ancestors.length > 0 && ancestors.every((id) => typeof id === "string");
@@ -262,3 +268,48 @@ export function groupStore(storage) {
         },
     };
 }
+/** A watched message as stored under its key's session and inbox id; one that cannot be read is left out. */
+function readWake(sessionID, inboxID, value) {
+    const given = obj(value);
+    const at = num(given.at);
+    const text = str(given.text);
+    if (at === undefined || text === undefined || typeof given.running !== "boolean")
+        return undefined;
+    const optional = (field) => {
+        const time = num(given[field]);
+        return time === undefined ? {} : { [field]: time };
+    };
+    const description = str(given.description);
+    return {
+        sessionID,
+        inboxID,
+        at,
+        text,
+        ...(description !== undefined ? { description } : {}),
+        running: given.running,
+        ...optional("idleAt"),
+        ...optional("rewoken"),
+        ...optional("stalled"),
+    };
+}
+/** The `WakeStore` over the plugin's storage. */
+export function wakeStore(storage) {
+    const under = async (prefix) => {
+        const entries = await scanEntries(storage, prefix);
+        return entries.flatMap(({ key, value }) => {
+            const parts = `${prefix.slice(WAKE_PREFIX.length)}${key}`.split("/");
+            const wake = parts.length === 2 ? readWake(parts[0], parts[1], value) : undefined;
+            return wake ? [wake] : [];
+        });
+    };
+    return {
+        async put({ sessionID, inboxID, ...wake }) {
+            await storage.set(wakeKey(sessionID, inboxID), { ...wake });
+        },
+        of: (sessionID) => under(`${WAKE_PREFIX}${sessionID}/`),
+        all: () => under(WAKE_PREFIX),
+        async remove(sessionID, inboxID) {
+            await storage.remove(wakeKey(sessionID, inboxID));
+        },
+    };
+}

package/dist/tree/summary.d.ts

@@ -1,7 +1,7 @@
 import type { CourierPorts } from "./ports.js";
 import type { Summary } from "./rpc.js";
 /**
- * Every session started under a session, counted by what it is doing, and its open join groups, those of its own
- * children, with how far each has reported.
+ * Every session started under a session, counted by what it is doing (the session itself too, when it is stalled), and its
+ * open join groups, those of its own children, with how far each has reported.
  */
 export declare function summary(ports: CourierPorts, sessionID: string): Promise<Summary>;

package/dist/tree/summary.js

@@ -2,26 +2,35 @@ import { busy } from "./domain.js";
 import { groupStandings } from "./group.js";
 import { groupStore } from "./store.js";
 import { lookUp } from "./subtree.js";
-/** What a session is doing: waiting on a request it made or a form it shows, running, or idle; undefined when OpenCode no longer knows it. */
-function activity({ info, pending, forms }) {
+import { stalledAmong } from "./wake.js";
+/**
+ * What a session is doing: waiting on a request it made or a form it shows, stalled, running, or idle; undefined when
+ * OpenCode no longer knows it. A message waiting in its inbox makes a stalled session look busy.
+ */
+function activity({ info, pending, forms, entry }, stalled) {
     if (!info)
         return undefined;
     if (pending.length || forms.length)
         return "waiting";
+    if (stalled.has(entry.sessionID))
+        return "stalled";
     return busy(info.time) ? "running" : "idle";
 }
 /**
- * Every session started under a session, counted by what it is doing, and its open join groups, those of its own
- * children, with how far each has reported.
+ * Every session started under a session, counted by what it is doing (the session itself too, when it is stalled), and its
+ * open join groups, those of its own children, with how far each has reported.
  */
 export async function summary(ports, sessionID) {
     const [looked, standings] = await Promise.all([lookUp(ports, sessionID), groupStandings(groupStore(ports.storage), sessionID)]);
-    const activities = looked.map(activity);
+    const stalled = await stalledAmong(ports, [sessionID, ...looked.map((one) => one.entry.sessionID)]);
+    const activities = looked.map((one) => activity(one, stalled));
     const count = (kind) => activities.filter((item) => item === kind).length;
+    const stalls = count("stalled") + (stalled.has(sessionID) ? 1 : 0);
     return {
         running: count("running"),
         waiting: count("waiting"),
         idle: count("idle"),
+        ...(stalls ? { stalled: stalls } : {}),
         groups: standings.map(({ name, reported, members }) => ({ name, reported, members })),
     };
 }

package/dist/tree/text.js

@@ -47,7 +47,7 @@ function splitRule(parentID, depth, limits) {
         `You are at depth ${depth} of a session tree that goes at most ${limits.maxDepth} deep. Split your task or do it yourself:`,
         "- Split it when it has 2 or more independent parts, each substantial and touching separate files or areas: start one " +
             `session per part with courier_spawn, at most ${limits.maxChildren} of yours running at once and ${limits.maxTotal} in the whole tree.`,
-        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session.",
+        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole task.",
         `- Say which in one line of your reply: ${SPLIT_LINE}.`,
         "- If you split, you orchestrate: end your turn while they work, check and integrate each part yourself when it " +
             `reports (never hand that checking to another session), then send ${parentID} one combined report.`,

package/dist/tree/tui.d.ts

@@ -34,11 +34,15 @@ export declare function waitLine(wait: Wait): string;
 export declare function statusLine(row: Row): string;
 /** A leaf's activity: how long it has run, its last tool call and how long ago, and its cost. */
 export declare function activityLine(row: Row, now: number): string;
-/** The lines a row shows under its title: an orchestrator's bar, a paused session's requests, or else a live leaf's activity. */
+/** What a stalled session's row, or the panel of one, says of it: "a message waits in its inbox since 2m 05s, woken again in vain". */
+export declare function stalledLine(since: number, now: number): string;
+/** The lines a row shows under its title: an orchestrator's bar, a paused or stalled session's wait, or else a live leaf's activity. */
 export declare function detailLines(row: Row, rows: ReadonlyArray<Row>, now: number): string[];
+/** How often the footer and the panel ask again with no event: the scheduler flags a stalled session without one. */
+export declare const REREAD_MS = 15000;
 /**
  * Adds the tree's entry to the prompt's footer: what the sessions under the open session do, asked of the RPC after each
- * change; nothing on the home screen. Clicked while some wait on the person, it calls `onWaiting` with the open session.
+ * change and every `REREAD_MS`; nothing on the home screen. Clicked while some wait on the person, it calls `onWaiting`.
  */
 export declare function addTreeStatus(ctx: Context, onWaiting?: (sessionID: string) => void): () => void;
 /** The toast after a stop: how many sessions were interrupted, and how many scheduled messages were cancelled. */

package/dist/tree/wake.d.ts

@@ -0,0 +1,69 @@
+import type { GroupPorts, Wake, WatchPorts } from "./ports.js";
+/** How long a courier message may wait in an idle session's inbox before its wake counts as missed. */
+export declare const WAKE_MS = 30000;
+/** OpenCode's `session.inbox.enqueued`, with the item's payload, which carries the courier's metadata. */
+export interface Enqueued {
+    readonly created?: number;
+    readonly data: {
+        readonly sessionID: string;
+        readonly inboxID: string;
+        readonly item: {
+            readonly type: string;
+            readonly payload?: {
+                readonly text?: unknown;
+                readonly description?: unknown;
+                readonly metadata?: {
+                    readonly source?: unknown;
+                    readonly resume?: unknown;
+                };
+            };
+        };
+    };
+}
+/** OpenCode's `session.inbox.delivered` and `session.inbox.cancelled`. */
+export interface InboxSettled {
+    readonly data: {
+        readonly sessionID: string;
+        readonly inboxID: string;
+    };
+}
+/** OpenCode's `session.execution.*` events, which frame a session's busy period. */
+export interface Execution {
+    readonly created?: number;
+    readonly data: {
+        readonly sessionID: string;
+    };
+}
+/**
+ * Watches a courier message enqueued for a session until it is delivered, noting whether the session runs.
+ * Returns whether it is watched, which one sent with `resume: false` is not.
+ */
+export declare function watchWake(ports: WatchPorts, event: Enqueued): Promise<boolean>;
+/** Stops watching a message once it is delivered or cancelled. */
+export declare function settleWake(ports: Pick<WatchPorts, "storage">, event: InboxSettled): Promise<void>;
+/** A turn started in a session: the messages waiting there are its to take. */
+export declare function wakeStarted(ports: Pick<WatchPorts, "storage">, event: Execution): Promise<void>;
+/**
+ * A session's turn ended: a message it took is no longer watched, as its delivery may have been missed by this
+ * subscription; one still waiting is watched as waiting in an idle session from now.
+ */
+export declare function wakeEnded(ports: WatchPorts, event: Execution & {
+    readonly data: {
+        readonly reason?: string;
+    };
+}): Promise<void>;
+/** Forgets the messages watched in a session's inbox: it was deleted, or stopped, which nothing is to wake again. */
+export declare function forgetWakes(ports: Pick<WatchPorts, "storage">, sessionID: string): Promise<void>;
+/** The ports the scheduler's tick wakes sessions through: what every hub member's `later` ports have. */
+export type WakePorts = GroupPorts & {
+    readonly now: () => number;
+};
+/**
+ * Sends once more, under its inbox id, each courier message an idle session has left waiting for `WAKE_MS`, and flags
+ * stalled one still waiting `WAKE_MS` later; run by the scheduler's owner, `claimed` keeping a tick alongside off it.
+ */
+export declare function wakeMissed(ports: WakePorts, claimed: Set<string>): Promise<void>;
+/** Whether a message has waited in an idle session past `WAKE_MS`, and since a wake again, if one was sent; a stalled one is done. */
+export declare function missed(wake: Wake, now: number): boolean;
+/** The sessions among `sessionIDs` flagged stalled, each with when its oldest stalled message was enqueued. */
+export declare function stalledAmong(ports: Pick<WatchPorts, "storage">, sessionIDs: ReadonlyArray<string>): Promise<Map<string, number>>;

package/dist/tree/wake.js

@@ -0,0 +1,122 @@
+import { wakeStore } from "./store.js";
+/** How long a courier message may wait in an idle session's inbox before its wake counts as missed. */
+export const WAKE_MS = 30_000;
+/** Whether a session's stored messages end with the marker of an ended turn; one with none yet is taken to run. */
+const endsIdle = (messages) => messages.at(-1)?.type === "idle";
+/**
+ * Watches a courier message enqueued for a session until it is delivered, noting whether the session runs.
+ * Returns whether it is watched, which one sent with `resume: false` is not.
+ */
+export async function watchWake(ports, event) {
+    const { sessionID, inboxID, item } = event.data;
+    const payload = item.payload;
+    if (item.type !== "synthetic" || payload?.metadata?.source !== "courier" || typeof payload.text !== "string")
+        return false;
+    // Sent without a wake: it waits for the next turn, which nothing owes it.
+    if (payload.metadata.resume === false)
+        return false;
+    const at = event.created ?? ports.now();
+    // Read after the enqueue: a turn it started has stored messages since, and an unknown session is taken to run.
+    const idle = await ports.session.context({ sessionID }).then(endsIdle, () => false);
+    await wakeStore(ports.storage).put({
+        sessionID,
+        inboxID,
+        at,
+        text: payload.text,
+        ...(typeof payload.description === "string" ? { description: payload.description } : {}),
+        running: !idle,
+        ...(idle ? { idleAt: at } : {}),
+    });
+    return true;
+}
+/** Stops watching a message once it is delivered or cancelled. */
+export async function settleWake(ports, event) {
+    await wakeStore(ports.storage).remove(event.data.sessionID, event.data.inboxID);
+}
+/** A turn started in a session: the messages waiting there are its to take. */
+export async function wakeStarted(ports, event) {
+    const store = wakeStore(ports.storage);
+    const waiting = await store.of(event.data.sessionID);
+    await Promise.all(waiting.filter((wake) => !wake.running).map(({ idleAt: _, ...wake }) => store.put({ ...wake, running: true })));
+}
+/**
+ * A session's turn ended: a message it took is no longer watched, as its delivery may have been missed by this
+ * subscription; one still waiting is watched as waiting in an idle session from now.
+ */
+export async function wakeEnded(ports, event) {
+    if (event.data.reason === "shutdown")
+        return;
+    const { sessionID } = event.data;
+    const store = wakeStore(ports.storage);
+    const waiting = await store.of(sessionID);
+    if (!waiting.length)
+        return;
+    const at = event.created ?? ports.now();
+    const stored = new Set((await ports.session.context({ sessionID }).catch(() => [])).map((message) => message.id));
+    await Promise.all(waiting.map((wake) => (stored.has(wake.inboxID) ? store.remove(sessionID, wake.inboxID) : store.put({ ...wake, running: false, idleAt: at }))));
+}
+/** Forgets the messages watched in a session's inbox: it was deleted, or stopped, which nothing is to wake again. */
+export async function forgetWakes(ports, sessionID) {
+    const store = wakeStore(ports.storage);
+    await Promise.all((await store.of(sessionID)).map((wake) => store.remove(sessionID, wake.inboxID)));
+}
+/**
+ * Sends once more, under its inbox id, each courier message an idle session has left waiting for `WAKE_MS`, and flags
+ * stalled one still waiting `WAKE_MS` later; run by the scheduler's owner, `claimed` keeping a tick alongside off it.
+ */
+export async function wakeMissed(ports, claimed) {
+    const store = wakeStore(ports.storage);
+    const now = ports.now();
+    const due = (await store.all()).filter((wake) => missed(wake, now) && !claimed.has(claimOf(wake)));
+    for (const wake of due)
+        claimed.add(claimOf(wake));
+    await Promise.all(due.map((wake) => wakeAgain(ports, store, wake, now).finally(() => claimed.delete(claimOf(wake)))));
+}
+const claimOf = (wake) => `wake ${wake.sessionID} ${wake.inboxID}`;
+/** Whether a message has waited in an idle session past `WAKE_MS`, and since a wake again, if one was sent; a stalled one is done. */
+export function missed(wake, now) {
+    if (wake.running || wake.stalled !== undefined)
+        return false;
+    const since = Math.max(wake.idleAt ?? wake.at, wake.rewoken ?? 0);
+    return now - since >= WAKE_MS;
+}
+async function wakeAgain(ports, store, wake, now) {
+    try {
+        // Re-read: the message may have been delivered, or the session woken, since the scan.
+        const current = (await store.of(wake.sessionID)).find((one) => one.inboxID === wake.inboxID);
+        if (!current || !missed(current, now))
+            return;
+        if (current.rewoken !== undefined) {
+            ports.log(`courier wake: ${wake.sessionID} has not taken message ${wake.inboxID} since it was woken again; flagged stalled`);
+            return await store.put({ ...current, stalled: now });
+        }
+        // Noted before the send: the turn it starts may take the message, and drop the watch, before the send returns.
+        await store.put({ ...current, rewoken: now });
+        await ports.session.synthetic({
+            sessionID: wake.sessionID,
+            id: wake.inboxID,
+            text: wake.text,
+            ...(wake.description !== undefined ? { description: wake.description } : {}),
+            metadata: { source: "courier", wake: "again" },
+            delivery: "steer",
+        }).catch(async (error) => {
+            await store.put(current);
+            throw error;
+        });
+        ports.log(`courier wake: ${wake.sessionID} left message ${wake.inboxID} waiting while idle; woken again`);
+    }
+    catch (error) {
+        ports.log(`courier wake: could not wake ${wake.sessionID} again for ${wake.inboxID}: ${String(error)}`);
+    }
+}
+/** The sessions among `sessionIDs` flagged stalled, each with when its oldest stalled message was enqueued. */
+export async function stalledAmong(ports, sessionIDs) {
+    const wanted = new Set(sessionIDs);
+    const stalled = new Map();
+    for (const wake of await wakeStore(ports.storage).all()) {
+        if (wake.stalled === undefined || !wanted.has(wake.sessionID))
+            continue;
+        stalled.set(wake.sessionID, Math.min(stalled.get(wake.sessionID) ?? wake.at, wake.at));
+    }
+    return stalled;
+}