@tinycloud/courier 0.2.0-beta.36 → 0.2.0-beta.38

package/dist/watch.d.ts

@@ -2,6 +2,7 @@ import type { HookSubscription } from '@tinycloud/node-sdk';
 import type { StoredPeer } from './profile.js';
 import { type KV } from './inbox.js';
 import type { WakeApproval, WakeMessage, Waker, WatchLog } from './wake.js';
+import { type Notice, type Notifier } from './notify.js';
 export interface PendingWake {
     peer: string;
     threadId: string;
@@ -19,11 +20,48 @@ export interface WatchState {
     /** Recently woken message ids, so a receipt write that failed cannot cause a second wake. */
     woken: string[];
     approvalsSeen: string[];
+    /** Message wake attempts today (UTC), per `<peer>/<threadId>`, as epoch ms (approval wakes do not count). */
+    wakes: Record<string, number[]>;
+    /** Threads this watcher has seen paused; a marker that vanishes from this list means the human resumed it. */
+    paused: string[];
+    /** Posts and notifications that must happen exactly-ish once and survive a restart (retried until they succeed). */
+    outbox: OutboxItem[];
+    held: Record<string, HeldBacklog>;
+    /** UTC day of the last notification per kind/peer/thread: one of each kind per day. */
+    peerPausedDay: Record<string, number>;
+    /** Times of recent notifications per peer, for the shared per-hour cap. */
+    noticeLog: Record<string, number[]>;
+}
+/** `tries` counts failed attempts; an item that keeps failing is dropped (see `MAX_OUTBOX_TRIES`). */
+export type OutboxItem = {
+    id: string;
+    kind: 'inform';
+    peer: string;
+    threadId: string;
+    text: string;
+    tries?: number;
+    nextAttemptAt?: number;
+} | {
+    id: string;
+    kind: 'notify';
+    notice: Notice;
+    tries?: number;
+    nextAttemptAt?: number;
+    logged?: boolean;
+};
+/** Messages that arrived while a thread was paused; they wake the agent once, together, after `courier resume`. */
+export interface HeldBacklog {
+    peer: string;
+    threadId: string;
+    subject: string;
+    messages: WakeMessage[];
 }
 export interface WatchOptions {
     debounceMs: number;
     pollMs: number;
     ticketSeconds: number;
+    /** Spec §8: at most this many wakes per side per thread per 24 h, then the thread pauses. */
+    wakeBudget: number;
 }
 export declare const WATCH_DEFAULTS: WatchOptions;
 interface HookEventLike {
@@ -48,6 +86,14 @@ export interface WatchDeps {
     kvFor(peer: StoredPeer): Promise<KV>;
     wake: Waker;
     log: WatchLog;
+    /** Posts the `thread-paused` inform to a peer (own space, `to/<peer>/threads/<id>/msg/`). Default: nothing. */
+    postInform?(peer: string, threadId: string, text: string): Promise<void>;
+    /** Tells this side's human without a model (desktop notification or operator command). Default: log only. */
+    notify?: Notifier;
+    /** Local bounded notification log; omitted by library callers that want no disk output. */
+    notificationHome?: string;
+    /** D mode: mirror/receipt and notify the human, never invoke the wake adapter or spend its budget. */
+    notifyOnly?: boolean;
     /**
      * Who this watcher is, for wake claims. `profileId` is stable for this profile on this machine (a restart keeps it,
      * a second profile or machine differs); `pid` and `isAlive` tell a restarted watcher its predecessor is dead.
@@ -71,6 +117,12 @@ export declare class Watcher {
     private readonly retryAt;
     private readonly waking;
     private approvalsRunning;
+    /** Thread keys currently paused: markers under me/state/paused/ plus those this watcher just wrote. */
+    private pausedKeys;
+    /** Serialises everything that reads or writes pause markers, so a stale listing cannot drop a pause just written. */
+    private pausedLock;
+    private readonly wakeFailures;
+    private readonly outboxBusy;
     private approvalsAgain;
     /** Unique to this run: a claim with this id is this process's own. */
     private readonly runId;
@@ -137,7 +189,25 @@ export declare class Watcher {
     private approvalWake;
     /** Wake every thread whose debounce has elapsed (`force`: all of them now). Threads wake in parallel, one wake per thread at a time. */
     tick(force?: boolean): Promise<void>;
+    /** Spec §8: the budget is per side, per thread, per day. A day is the UTC calendar day, so it is easy to state and to check. */
+    private recentWakes;
     private wakeThread;
+    /** Budget reached: pause this side's wakes for the thread, tell the peer (inform), tell this side's human. */
+    private pauseThread;
+    private exclusive;
+    /** Called inside `mutate`: parks a message that arrived while its thread is paused (bounded). */
+    private hold;
+    /** Called inside `mutate`: queues an inform or notification; the outbox is bounded, the oldest item goes first. */
+    private enqueue;
+    /**
+     * Markers under me/state/paused/ are the truth. A marker that disappeared means the human resumed: the budget starts
+     * over and what arrived meanwhile wakes the agent once. Serialised, so overlapping calls never apply a stale listing.
+     */
+    syncPaused(): Promise<void>;
+    /** State that only matters for a day or an hour is dropped, so it cannot grow without bound. */
+    private pruneState;
+    /** Informs and notifications queued in state; failures back off (1, 2, 4 ... 15 minutes) and give up after MAX_OUTBOX_TRIES. */
+    private runOutbox;
     pollOnce(via: Via): Promise<void>;
     /**
      * Runs until `signal` aborts. With `once`, does one catch-up and wakes everything immediately. Throws

package/dist/watch.js

@@ -5,6 +5,8 @@ import { k, PREFIX } from './keys.js';
 import { isRecord, messageView, oneLine, taskView } from './a2a.js';
 import { commitReceipts, selectUndelivered } from './inbox.js';
 import { del, getJson, listAll, putCreate, putMatch, putOverwrite } from './store.js';
+import { appendNotice } from './notify.js';
+import { writePauseMarker } from './pause.js';
 /** Spec §8. inform and receipts never wake; a message with no valid intent is delivered but never wakes. */
 const WAKE_INTENTS = new Set(['request', 'ask', 'answer', 'update']);
 const TERMINAL_TASK_STATES = new Set([
@@ -23,13 +25,18 @@ const FOREIGN_CLAIM_LEASE_MS = 45 * 60_000;
 /** A thread another watcher is waking is looked at again after this. */
 const CLAIM_SKIP_MS = 30_000;
 const DAY_MS = 24 * 3600 * 1000;
+/** A peer can make this side's watcher notify its human at most this often per hour, and the outbox never grows past `MAX_OUTBOX`. */
+const NOTICES_PER_PEER_PER_HOUR = 10;
+const MAX_OUTBOX = 50;
+const MAX_OUTBOX_TRIES = 8;
+const MAX_HELD_PER_THREAD = 100;
 /** The subject is peer-controlled text that reaches state, prompts and environments: one line, control characters removed, capped. */
 const MAX_SUBJECT = 200;
 /** Thread and message ids come from key names the peer controls; they reach prompts and argv, so only ULID-like ids pass. */
 const SAFE_ID = /^[0-9A-Za-z_-]{1,64}$/;
-export const WATCH_DEFAULTS = { debounceMs: 30_000, pollMs: 60_000, ticketSeconds: 25 };
+export const WATCH_DEFAULTS = { debounceMs: 30_000, pollMs: 60_000, ticketSeconds: 25, wakeBudget: 12 };
 export function emptyWatchState() {
-    return { v: 1, pending: {}, woken: [], approvalsSeen: [] };
+    return { v: 1, pending: {}, woken: [], approvalsSeen: [], wakes: {}, paused: [], outbox: [], held: {}, peerPausedDay: {}, noticeLog: {} };
 }
 /** Wake time: `debounce` after the latest message, but never later than twice `debounce` after the first. */
 export function wakeDueAt(pending, debounceMs) {
@@ -76,6 +83,12 @@ export class Watcher {
     retryAt = new Map();
     waking = new Set();
     approvalsRunning = false;
+    /** Thread keys currently paused: markers under me/state/paused/ plus those this watcher just wrote. */
+    pausedKeys = new Set();
+    /** Serialises everything that reads or writes pause markers, so a stale listing cannot drop a pause just written. */
+    pausedLock = Promise.resolve();
+    wakeFailures = new Map();
+    outboxBusy = new Set();
     approvalsAgain = false;
     /** Unique to this run: a claim with this id is this process's own. */
     runId = ulid();
@@ -111,6 +124,7 @@ export class Watcher {
         this.state = isRecord(value) && value.v === 1
             ? { ...emptyWatchState(), ...value }
             : emptyWatchState();
+        this.state.outbox = this.state.outbox.slice(-MAX_OUTBOX).filter(item => (item.tries ?? 0) < MAX_OUTBOX_TRIES);
     }
     snapshot() {
         return structuredClone(this.state);
@@ -271,7 +285,10 @@ export class Watcher {
         const { selfKv, log } = this.deps;
         const mailbox = peer.theirHandleForMe;
         const peerKv = await this.deps.kvFor(peer);
-        const keys = await listAll(peerKv, `${PREFIX}/to/${mailbox}/threads/`);
+        // Pause markers are read with every listing, so a `courier resume` or `courier pause` takes effect on the very
+        // next message instead of at the next poll (a message delivered while the watcher still thought the thread was
+        // paused would never wake anyone).
+        const [keys] = await Promise.all([listAll(peerKv, `${PREFIX}/to/${mailbox}/threads/`), this.syncPaused()]);
         const receipts = (await getJson(selfKv, k.receipts(peer.handle)))?.value ?? { v: 1, threads: {} };
         receipts.threads ??= {};
         const delivered = [];
@@ -288,7 +305,8 @@ export class Watcher {
                 if (!isRecord(value) || value.messageId !== selected.messageId || value.contextId !== selected.threadId)
                     continue;
                 await this.mirrorCreate(k.mirrorMsg(peer.handle, selected.threadId, selected.messageId), value);
-                delivered.push({ threadId: selected.threadId, messageId: selected.messageId, intent: messageView(value).intent });
+                const view = messageView(value);
+                delivered.push({ threadId: selected.threadId, messageId: selected.messageId, intent: view.intent, notice: view.notice });
             }
             catch (error) {
                 // Not delivered, so no receipt: this message is retried on the next sync; the others go ahead.
@@ -309,15 +327,27 @@ export class Watcher {
             const sentAt = sentAtOf(item.messageId);
             log('delivered', {
                 via, peer: peer.handle, threadId: item.threadId, messageId: item.messageId, intent: item.intent ?? null,
-                wakes: Boolean(item.intent && WAKE_INTENTS.has(item.intent)),
+                wakes: !this.deps.notifyOnly && Boolean(item.intent && WAKE_INTENTS.has(item.intent)) && !this.pausedKeys.has(`${peer.handle}/${item.threadId}`),
+                ...(this.pausedKeys.has(`${peer.handle}/${item.threadId}`) ? { paused: true } : {}),
                 sentAt, latencyMs: sentAt ? at - Date.parse(sentAt) : null,
             });
         }
         await this.mutate(() => {
+            if (this.deps.notifyOnly) {
+                for (const threadId of new Set(delivered.filter(item => item.intent && item.notice !== 'thread-paused').map(item => item.threadId))) {
+                    const first = delivered.find(item => item.threadId === threadId);
+                    this.enqueue({ id: `message:${peer.handle}/${threadId}:${first.messageId}`, kind: 'notify', notice: { kind: 'new-message', peer: peer.handle, threadId, eventId: first.messageId, detail: '' } });
+                }
+            }
             for (const item of delivered) {
-                if (!item.intent || !WAKE_INTENTS.has(item.intent) || this.state.woken.includes(item.messageId))
+                if (this.deps.notifyOnly || !item.intent || !WAKE_INTENTS.has(item.intent) || this.state.woken.includes(item.messageId))
                     continue;
                 const key = `${peer.handle}/${item.threadId}`;
+                if (this.pausedKeys.has(key)) {
+                    // Delivered and mirrored, but a paused thread never wakes: the message waits for `courier resume`.
+                    this.hold(key, peer.handle, item.threadId, subjects.get(item.threadId), { messageId: item.messageId, intent: item.intent, sentAt: sentAtOf(item.messageId) });
+                    continue;
+                }
                 const entry = this.state.pending[key] ??= {
                     peer: peer.handle, threadId: item.threadId, subject: subjects.get(item.threadId), messages: [], firstSeenAt: at, lastSeenAt: at,
                 };
@@ -326,6 +356,19 @@ export class Watcher {
                 entry.messages.push({ messageId: item.messageId, intent: item.intent, sentAt: sentAtOf(item.messageId) });
                 entry.lastSeenAt = at;
             }
+            // The peer's watcher paused the thread: tell this side's human (their agent is not coming back until resumed).
+            // Only a paired peer's `inform` carrying the notice counts, once per thread per UTC day, at most
+            // NOTICES_PER_PEER_PER_HOUR per peer: a peer cannot turn this into a stream of notifications or agent runs.
+            for (const item of delivered) {
+                if (item.notice !== 'thread-paused' || item.intent !== 'inform')
+                    continue;
+                const key = `${peer.handle}/${item.threadId}`;
+                const day = Math.floor(at / DAY_MS);
+                this.enqueue({
+                    id: `peer-paused:${key}:${day}`, kind: 'notify',
+                    notice: { kind: 'peer-paused', peer: peer.handle, threadId: item.threadId, detail: "the peer's watcher reported the thread paused" },
+                });
+            }
         });
         await commitReceipts(selfKv, new Map([[peer.handle, delivered.map(({ threadId, messageId }) => ({ threadId, messageId }))]]));
         await this.mirrorThreads(peer, peerKv, keys);
@@ -421,7 +464,7 @@ export class Watcher {
                 const found = await this.approvalWake(id);
                 if ('wake' in found) {
                     wakes.push(found.wake);
-                    log('approval-seen', { via, approvalId: id, wakes: true, decision: found.wake.approval.decision });
+                    log('approval-seen', { via, approvalId: id, wakes: !this.deps.notifyOnly, notifies: Boolean(this.deps.notifyOnly), decision: found.wake.approval.decision });
                 }
                 else {
                     log('approval-seen', { via, approvalId: id, wakes: false, reason: found.skip });
@@ -439,6 +482,10 @@ export class Watcher {
         await this.mutate(() => {
             this.state.approvalsSeen = [...new Set([...this.state.approvalsSeen, ...handled])].sort();
             for (const { approval, peer, threadId, subject } of wakes) {
+                if (this.deps.notifyOnly) {
+                    this.enqueue({ id: `approval:${approval.approvalId}`, kind: 'notify', notice: { kind: 'new-approval', peer, threadId, eventId: approval.approvalId, detail: '' } });
+                    continue;
+                }
                 const key = `${peer}/${threadId}`;
                 const entry = this.state.pending[key] ??= { peer, threadId, subject, messages: [], firstSeenAt: at, lastSeenAt: at };
                 entry.approvals ??= [];
@@ -477,6 +524,21 @@ export class Watcher {
     async tick(force = false) {
         if (this.fatalError || this.stopping)
             return;
+        if (this.deps.notifyOnly) {
+            // A watcher switched from auto-wake to D may have a pending backlog from its previous run.
+            if (Object.keys(this.state.pending).length)
+                await this.mutate(() => {
+                    for (const pending of Object.values(this.state.pending)) {
+                        if (pending.messages.length)
+                            this.enqueue({ id: `message:${pending.peer}/${pending.threadId}:${pending.messages[0].messageId}`, kind: 'notify', notice: { kind: 'new-message', peer: pending.peer, threadId: pending.threadId, eventId: pending.messages[0].messageId, detail: '' } });
+                        for (const approval of pending.approvals ?? [])
+                            this.enqueue({ id: `approval:${approval.approvalId}`, kind: 'notify', notice: { kind: 'new-approval', peer: pending.peer, threadId: pending.threadId, eventId: approval.approvalId, detail: '' } });
+                    }
+                    this.state.pending = {};
+                });
+            await this.runOutbox();
+            return;
+        }
         const at = this.now();
         const runs = [];
         for (const [key, pending] of Object.entries(this.state.pending)) {
@@ -489,14 +551,47 @@ export class Watcher {
             this.waking.add(key);
             runs.push(this.wakeThread(key, pending, at).finally(() => this.waking.delete(key)));
         }
+        runs.push(this.runOutbox());
         await Promise.all(runs);
     }
+    /** Spec §8: the budget is per side, per thread, per day. A day is the UTC calendar day, so it is easy to state and to check. */
+    recentWakes(key) {
+        const today = Math.floor(this.now() / DAY_MS);
+        return (this.state.wakes[key] ?? []).filter((at) => Math.floor(at / DAY_MS) === today);
+    }
     async wakeThread(key, pending, at) {
         if (this.stopping)
             return; // told to stop: claim nothing, start nothing
+        // A `courier pause` written since the last listing must stop a wake that is already queued.
+        await this.syncPaused();
         // Messages that land while the wake runs stay pending for the next one, so wake exactly this snapshot.
-        const messages = [...pending.messages];
+        let messages = [...pending.messages];
         const approvals = [...(pending.approvals ?? [])];
+        // Spec §8: the loop stops here. A paused thread, or one over budget, wakes nobody for messages (approvals are
+        // a human decision, not a loop, and always wake).
+        if (messages.length) {
+            const used = this.recentWakes(key).length;
+            if (!this.pausedKeys.has(key) && used >= this.opts.wakeBudget)
+                await this.pauseThread(key, pending, used);
+            if (this.pausedKeys.has(key)) {
+                // Moved to the held backlog: they wake once, together, after `courier resume`.
+                const held = messages;
+                const heldIds = held.map((m) => m.messageId);
+                messages = [];
+                await this.mutate(() => {
+                    for (const message of held)
+                        this.hold(key, pending.peer, pending.threadId, pending.subject, message);
+                    const current = this.state.pending[key];
+                    if (!current)
+                        return;
+                    current.messages = current.messages.filter((m) => !heldIds.includes(m.messageId));
+                    if (!current.messages.length && !(current.approvals ?? []).length)
+                        delete this.state.pending[key];
+                });
+                if (!approvals.length)
+                    return;
+            }
+        }
         const woken = messages.map((m) => m.messageId);
         const approvedIds = approvals.map((a) => a.approvalId);
         const oldestSentAt = messages[0]?.sentAt ?? '';
@@ -509,7 +604,12 @@ export class Watcher {
             return;
         }
         try {
-            await this.mutate(() => { });
+            // The attempt is counted against the budget BEFORE the adapter runs, and whether it then succeeds, fails or
+            // times out: an adapter that always throws must not be retried forever. (A crash mid-wake counts too.)
+            await this.mutate(() => {
+                if (woken.length)
+                    this.state.wakes[key] = [...this.recentWakes(key), this.now()];
+            });
         }
         catch (error) {
             await this.releaseClaim(pending.peer, pending.threadId, claimId);
@@ -531,8 +631,11 @@ export class Watcher {
             await this.deps.wake({ peer: pending.peer, threadId: pending.threadId, subject: pending.subject, messages, approvals });
         }
         catch (error) {
-            this.retryAt.set(key, at + WAKE_RETRY_MS);
-            this.deps.log('wake-error', { peer: pending.peer, threadId: pending.threadId, ...errInfo(error) });
+            // Failures back off: 1, 2, 4, ... minutes, at most 15.
+            const failures = (this.wakeFailures.get(key) ?? 0) + 1;
+            this.wakeFailures.set(key, failures);
+            this.retryAt.set(key, at + Math.min(15 * 60_000, WAKE_RETRY_MS * 2 ** (failures - 1)));
+            this.deps.log('wake-error', { peer: pending.peer, threadId: pending.threadId, failures, ...errInfo(error) });
             // The attempt failed, so the thread is not being woken: release the claim (a restart must not wait for it).
             await this.releaseClaim(pending.peer, pending.threadId, claimId);
             return;
@@ -547,6 +650,7 @@ export class Watcher {
             }
             this.state.woken = [...this.state.woken, ...woken].slice(-WAKEN_MEMORY);
         });
+        this.wakeFailures.delete(key);
         // Only now, with the wake recorded, is the retry hold-off cleared.
         this.retryAt.delete(key);
         this.deps.log('woke', {
@@ -554,8 +658,185 @@ export class Watcher {
             runMs: this.now() - startedAt,
         });
     }
+    /** Budget reached: pause this side's wakes for the thread, tell the peer (inform), tell this side's human. */
+    async pauseThread(key, pending, used) {
+        const reason = `wake budget reached (${used} wakes today, UTC; limit ${this.opts.wakeBudget ?? WATCH_DEFAULTS.wakeBudget} per thread per day)`;
+        const at = new Date(this.now()).toISOString();
+        const wrote = await this.exclusive(async () => {
+            const created = await writePauseMarker(this.deps.selfKv, { v: 1, peer: pending.peer, threadId: pending.threadId, by: 'budget', at, reason });
+            this.pausedKeys.add(key);
+            return created;
+        });
+        // The marker already existed (a human pause, or another run): the peer and the human were told then.
+        if (!wrote) {
+            this.deps.log('paused', { peer: pending.peer, threadId: pending.threadId, by: 'marker-existing' });
+            return;
+        }
+        const text = `Thread paused on this side: ${reason}. Its agent will not be woken for this thread until its owner resumes it. ` +
+            'This is an automatic stop for reply loops, not a refusal; messages you send are still stored and mirrored.';
+        await this.mutate(() => {
+            if (!this.state.paused.includes(key))
+                this.state.paused.push(key);
+            this.enqueue({ id: `inform:${key}:${at}`, kind: 'inform', peer: pending.peer, threadId: pending.threadId, text });
+            this.enqueue({ id: `paused:${key}:${at}`, kind: 'notify', notice: { kind: 'paused', peer: pending.peer, threadId: pending.threadId, detail: reason } });
+        });
+        this.deps.log('paused', { peer: pending.peer, threadId: pending.threadId, by: 'budget', reason });
+    }
+    exclusive(fn) {
+        const run = this.pausedLock.then(fn, fn);
+        this.pausedLock = run.catch(() => undefined);
+        return run;
+    }
+    /** Called inside `mutate`: parks a message that arrived while its thread is paused (bounded). */
+    hold(key, peer, threadId, subject, message) {
+        const entry = this.state.held[key] ??= { peer, threadId, subject, messages: [] };
+        if (entry.messages.some((m) => m.messageId === message.messageId))
+            return;
+        entry.messages = [...entry.messages, message].slice(-MAX_HELD_PER_THREAD);
+    }
+    /** Called inside `mutate`: queues an inform or notification; the outbox is bounded, the oldest item goes first. */
+    enqueue(item) {
+        if (item.kind === 'notify') {
+            const { notice } = item;
+            const at = this.now();
+            const day = Math.floor(at / DAY_MS);
+            const reference = notice.eventId && SAFE_ID.test(notice.eventId) ? `:${notice.eventId}` : '';
+            const key = `${notice.kind}:${notice.peer}/${notice.threadId}${reference}`;
+            if (this.state.peerPausedDay[key] === day)
+                return;
+            const recent = (this.state.noticeLog[notice.peer] ?? []).filter(t => at - t < 3600_000);
+            if (recent.length >= NOTICES_PER_PEER_PER_HOUR) {
+                this.deps.log('notice-dropped', { peer: notice.peer, reason: 'peer-rate-cap' });
+                return;
+            }
+            this.state.peerPausedDay[key] = day;
+            this.state.noticeLog[notice.peer] = [...recent, at];
+        }
+        this.state.outbox.push(item);
+        while (this.state.outbox.length > MAX_OUTBOX) {
+            const dropped = this.state.outbox.shift();
+            this.deps.log('outbox-dropped', { id: dropped.id, reason: 'full' });
+        }
+    }
+    /**
+     * Markers under me/state/paused/ are the truth. A marker that disappeared means the human resumed: the budget starts
+     * over and what arrived meanwhile wakes the agent once. Serialised, so overlapping calls never apply a stale listing.
+     */
+    syncPaused() {
+        return this.exclusive(async () => {
+            try {
+                const keys = await listAll(this.deps.selfKv, k.pausedPrefix);
+                const listed = new Set();
+                for (const key of keys) {
+                    const match = /\/paused\/([^/]+)\/([^/]+)\.json$/.exec(key);
+                    if (match && SAFE_ID.test(match[1]) && SAFE_ID.test(match[2]))
+                        listed.add(`${match[1]}/${match[2]}`);
+                }
+                const before = this.pausedKeys;
+                const resumed = this.state.paused.filter((key) => !listed.has(key));
+                const added = [...listed].filter((key) => !this.state.paused.includes(key));
+                this.pausedKeys = listed;
+                for (const key of added)
+                    if (!before.has(key))
+                        this.deps.log('paused', { thread: key, by: 'marker' });
+                if (resumed.length || added.length) {
+                    const at = this.now();
+                    const backlog = {};
+                    await this.mutate(() => {
+                        for (const key of resumed) {
+                            delete this.state.wakes[key];
+                            const held = this.state.held[key];
+                            if (held?.messages.length) {
+                                backlog[key] = held.messages.length;
+                                const entry = this.state.pending[key] ??= { peer: held.peer, threadId: held.threadId, subject: held.subject, messages: [], firstSeenAt: at, lastSeenAt: at };
+                                for (const message of held.messages)
+                                    if (!entry.messages.some((m) => m.messageId === message.messageId))
+                                        entry.messages.push(message);
+                                entry.lastSeenAt = at;
+                            }
+                            delete this.state.held[key];
+                        }
+                        this.state.paused = [...new Set([...this.state.paused.filter((key) => !resumed.includes(key)), ...added])].sort();
+                    });
+                    for (const key of resumed)
+                        this.deps.log('resumed', { thread: key, backlog: backlog[key] ?? 0 });
+                }
+            }
+            catch (error) {
+                this.deps.log('sync-error', { source: 'paused', ...errInfo(error) });
+            }
+        });
+    }
+    /** State that only matters for a day or an hour is dropped, so it cannot grow without bound. */
+    async pruneState() {
+        const at = this.now();
+        const today = Math.floor(at / DAY_MS);
+        const stale = Object.keys(this.state.wakes).filter((key) => !this.recentWakes(key).length)
+            .concat(Object.keys(this.state.peerPausedDay).filter((key) => today - this.state.peerPausedDay[key] > 7))
+            .concat(Object.keys(this.state.noticeLog).filter((peer) => !this.state.noticeLog[peer].some((t) => at - t < 3600_000)));
+        if (!stale.length)
+            return;
+        await this.mutate(() => {
+            for (const key of Object.keys(this.state.wakes))
+                if (!this.recentWakes(key).length)
+                    delete this.state.wakes[key];
+            for (const key of Object.keys(this.state.peerPausedDay))
+                if (today - this.state.peerPausedDay[key] > 7)
+                    delete this.state.peerPausedDay[key];
+            for (const peer of Object.keys(this.state.noticeLog))
+                if (!this.state.noticeLog[peer].some((t) => at - t < 3600_000))
+                    delete this.state.noticeLog[peer];
+        });
+    }
+    /** Informs and notifications queued in state; failures back off (1, 2, 4 ... 15 minutes) and give up after MAX_OUTBOX_TRIES. */
+    async runOutbox() {
+        const at = this.now();
+        const runs = [];
+        for (const item of [...this.state.outbox]) {
+            if (this.outboxBusy.has(item.id) || (item.nextAttemptAt ?? 0) > at)
+                continue;
+            this.outboxBusy.add(item.id);
+            runs.push((async () => {
+                try {
+                    if (item.kind === 'inform')
+                        await this.deps.postInform?.(item.peer, item.threadId, item.text);
+                    else {
+                        const { notice } = item;
+                        this.deps.log('notify', { kind: notice.kind, peer: notice.peer, threadId: notice.threadId, detail: notice.detail });
+                        if (!item.logged && this.deps.notificationHome) {
+                            appendNotice(this.deps.notificationHome, notice);
+                            await this.mutate(() => { const stored = this.state.outbox.find(o => o.id === item.id); if (stored?.kind === 'notify')
+                                stored.logged = true; });
+                        }
+                        await this.deps.notify?.(notice);
+                    }
+                    await this.mutate(() => { this.state.outbox = this.state.outbox.filter((o) => o.id !== item.id); });
+                }
+                catch (error) {
+                    const tries = (item.tries ?? 0) + 1;
+                    this.deps.log(item.kind === 'inform' ? 'inform-error' : 'notify-error', { id: item.id, tries, ...errInfo(error) });
+                    if (tries >= MAX_OUTBOX_TRIES) {
+                        this.deps.log('outbox-dropped', { id: item.id, reason: 'too-many-failures' });
+                        await this.mutate(() => { this.state.outbox = this.state.outbox.filter((o) => o.id !== item.id); });
+                    }
+                    else {
+                        await this.mutate(() => { const stored = this.state.outbox.find((o) => o.id === item.id); if (stored) {
+                            stored.tries = tries;
+                            stored.nextAttemptAt = at + Math.min(15 * 60_000, WAKE_RETRY_MS * 2 ** (tries - 1));
+                        } });
+                    }
+                }
+                finally {
+                    this.outboxBusy.delete(item.id);
+                }
+            })());
+        }
+        await Promise.all(runs);
+    }
     // ---------- run loop ----------
     async pollOnce(via) {
+        await this.syncPaused();
+        await this.pruneState();
         await Promise.all(this.deps.loadPeers().map((peer) => this.sync(peer, via)));
         await this.syncApprovals(via);
     }