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

package/dist/watch.js

@@ -6,7 +6,8 @@ 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';
+import { nextNoticeId, writePauseMarker } from './pause.js';
+import { HANDLE, ULID } from './request.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([
@@ -27,16 +28,35 @@ 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 NOTICES_PER_HOUR = 10;
+const NOTICE_RESERVE_PER_PEER = 3;
+const MAX_COALESCED_PAUSES = 999999;
+const MAX_PEER_CLOCK_SKEW_MS = 10 * 60_000;
 const MAX_OUTBOX = 50;
 const MAX_OUTBOX_TRIES = 8;
+const MAX_NOTICE_ATTEMPTS = 3;
 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}$/;
+const emptyNoticeRetry = () => ({ dispatchArrivals: '------', tries: 0, nextAttemptAt: 0, logged: false });
+const ZERO_ULID = '0'.repeat(26);
+const EPOCH = new Date(0).toISOString();
+const needsKind = (kind) => kind === 'new-message' ? 'message' : kind === 'new-approval' ? 'approval' : undefined;
+const emptyNeedsSlot = () => ({ threadId: ZERO_ULID, eventId: ZERO_ULID, count: '000000',
+    firstSeenAt: EPOCH, arrivalFirstSeenAt: EPOCH, ...emptyNoticeRetry() });
+const needsKey = (peer, kind) => `needs:${peer}:${kind}`;
+const emptyEpisode = () => ({ kind: '', eventId: ZERO_ULID, repeats: '000000', ...emptyNoticeRetry() });
+const incrementCount = (count) => String(Math.min(MAX_COALESCED_PAUSES, Number(count) + 1)).padStart(6, '0');
+const episodeKey = (key, slot) => `notice:${key}:${slot}`;
+function threadNoticeState() {
+    return { ourPaused: false, peerPaused: false, lastPeerNoticeId: '0'.repeat(26), lastNoticeSentAt: new Date(0).toISOString(),
+        ourMarkerId: '', episodes: [emptyEpisode(), emptyEpisode()], informPending: false, informText: '' };
+}
 export const WATCH_DEFAULTS = { debounceMs: 30_000, pollMs: 60_000, ticketSeconds: 25, wakeBudget: 12 };
 export function emptyWatchState() {
-    return { v: 1, pending: {}, woken: [], approvalsSeen: [], wakes: {}, paused: [], outbox: [], held: {}, peerPausedDay: {}, noticeLog: {} };
+    return { v: 1, pending: {}, woken: [], approvalsSeen: [], wakes: {}, paused: [], wakeRetries: {}, approvalRetries: {}, outbox: [], held: {}, threadNotices: {}, peerNotices: {}, noticeGlobalLog: [], noticeLog: {} };
 }
 /** Wake time: `debounce` after the latest message, but never later than twice `debounce` after the first. */
 export function wakeDueAt(pending, debounceMs) {
@@ -87,7 +107,6 @@ export class Watcher {
     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. */
@@ -124,7 +143,67 @@ 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);
+        // Discard the old per-peer-generation map; it was sized by untrusted ids.
+        delete this.state.peerPausedDay;
+        for (const key of [...Object.keys(this.state.wakes), ...this.state.paused]) {
+            const [peer, threadId] = key.split('/');
+            if (peer && threadId && SAFE_ID.test(peer) && SAFE_ID.test(threadId)) {
+                const record = this.state.threadNotices[key] ??= threadNoticeState();
+                record.ourPaused = this.state.paused.includes(key);
+            }
+        }
+        this.syncNoticePeers();
+        for (const record of Object.values(this.state.peerNotices))
+            for (const slot of Object.values(record))
+                slot.dispatchArrivals = '------';
+        // Upgrade the previous single-pending record while retaining its attempt/deadline metadata.
+        for (const [key, record] of Object.entries(this.state.threadNotices)) {
+            const old = record;
+            if (!record.episodes) {
+                record.episodes = [emptyEpisode(), emptyEpisode()];
+                for (const item of this.state.outbox) {
+                    if (item.kind !== 'notify' || `${item.notice.peer}/${item.notice.threadId}` !== key
+                        || (item.notice.kind !== 'paused' && item.notice.kind !== 'peer-paused')
+                        || item.id !== `${item.notice.kind}:${key}` || !item.notice.eventId)
+                        continue;
+                    this.queueEpisode(record, item.notice.kind, item.notice.eventId);
+                }
+                if (old.ourNoticePending)
+                    this.queueEpisode(record, 'paused', record.ourMarkerId);
+                if (old.peerNoticePending && old.peerNoticeId)
+                    this.queueEpisode(record, 'peer-paused', old.peerNoticeId);
+            }
+            record.episodes = record.episodes.map(episode => ({ ...emptyEpisode(), ...episode, dispatchArrivals: '------' }));
+            delete old.ourNoticePending;
+            delete old.peerNoticePending;
+            delete old.peerNoticeId;
+        }
+        this.state.outbox = this.state.outbox.filter(item => {
+            if (item.kind === 'inform')
+                return true;
+            const kind = needsKind(item.notice.kind);
+            if (kind) {
+                const slot = this.noticeSlot(item);
+                if (!slot || item.id !== needsKey(item.notice.peer, kind))
+                    return false;
+                this.rememberNotice(item);
+                return true;
+            }
+            const key = `${item.notice.peer}/${item.notice.threadId}`;
+            const record = this.state.threadNotices[key];
+            const slot = record?.episodes.findIndex(episode => episode.kind === item.notice.kind && episode.eventId === item.notice.eventId) ?? -1;
+            if (slot < 0 || (item.id !== `${item.notice.kind}:${key}` && item.id !== episodeKey(key, slot)))
+                return false;
+            item.id = episodeKey(key, slot);
+            item.notice.repeats ??= record.episodes[slot].repeats;
+            this.rememberNotice(item);
+            return true;
+        });
+        for (const item of [...this.state.outbox]) {
+            if ((item.tries ?? 0) >= (item.kind === 'notify' ? MAX_NOTICE_ATTEMPTS : MAX_OUTBOX_TRIES))
+                this.finishOutbox(item);
+        }
+        this.state.outbox = this.state.outbox.slice(-MAX_OUTBOX);
     }
     snapshot() {
         return structuredClone(this.state);
@@ -288,7 +367,7 @@ export class Watcher {
         // 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 [keys] = await Promise.all([listAll(peerKv, `${PREFIX}/to/${mailbox}/threads/`), this.syncPaused(), this.syncKnownThreads(peer)]);
         const receipts = (await getJson(selfKv, k.receipts(peer.handle)))?.value ?? { v: 1, threads: {} };
         receipts.threads ??= {};
         const delivered = [];
@@ -334,9 +413,11 @@ export class Watcher {
         }
         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: '' } });
+                this.syncNoticePeers();
+                for (const item of [...delivered].sort((a, b) => a.messageId.localeCompare(b.messageId))) {
+                    if (item.intent && item.notice !== 'thread-paused' && item.notice !== 'thread-resumed') {
+                        this.queueNeeds(peer.handle, 'message', item.threadId);
+                    }
                 }
             }
             for (const item of delivered) {
@@ -356,23 +437,53 @@ 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.
+            // Only our local listing establishes a known thread. The peer controls its own state, not allocation.
             for (const item of delivered) {
-                if (item.notice !== 'thread-paused' || item.intent !== 'inform')
+                if (item.intent !== 'inform' || (item.notice !== 'thread-paused' && item.notice !== 'thread-resumed'))
                     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" },
-                });
+                const record = this.state.threadNotices[`${peer.handle}/${item.threadId}`];
+                if (!record || !ULID.test(item.messageId) || item.messageId <= record.lastPeerNoticeId)
+                    continue;
+                let sentAt;
+                try {
+                    sentAt = decodeTime(item.messageId);
+                }
+                catch {
+                    continue;
+                } // ULID's high bits must fit 128 bits
+                if (sentAt > at + MAX_PEER_CLOCK_SKEW_MS)
+                    continue;
+                record.lastPeerNoticeId = item.messageId;
+                const paused = item.notice === 'thread-paused';
+                if (paused && !record.peerPaused)
+                    this.queueEpisode(record, 'peer-paused', item.messageId);
+                record.peerPaused = paused;
             }
+            this.fillOutbox();
         });
         await commitReceipts(selfKv, new Map([[peer.handle, delivered.map(({ threadId, messageId }) => ({ threadId, messageId }))]]));
         await this.mirrorThreads(peer, peerKv, keys);
     }
+    /** Only locally authored meta/messages/tasks, or a local wake/pause witness, establish a known thread. */
+    async syncKnownThreads(peer) {
+        const prefix = `${PREFIX}/to/${peer.handle}/threads/`;
+        const keys = await listAll(this.deps.selfKv, prefix);
+        const known = new Set();
+        for (const path of keys) {
+            const match = /^([^/]+)\/(?:meta\.json|(?:msg|task)\/[^/]+\.json)$/.exec(path.slice(prefix.length));
+            if (match && SAFE_ID.test(match[1]))
+                known.add(`${peer.handle}/${match[1]}`);
+        }
+        for (const key of Object.keys(this.state.wakes))
+            if (key.startsWith(`${peer.handle}/`))
+                known.add(key);
+        const missing = [...known].filter(key => !this.state.threadNotices[key]);
+        if (missing.length)
+            await this.mutate(() => {
+                for (const key of missing)
+                    this.state.threadNotices[key] ??= threadNoticeState();
+            });
+    }
     async mirrorCreate(key, value) {
         try {
             await putCreate(this.deps.selfKv, key, value);
@@ -481,9 +592,11 @@ export class Watcher {
         const at = this.now();
         await this.mutate(() => {
             this.state.approvalsSeen = [...new Set([...this.state.approvalsSeen, ...handled])].sort();
+            if (this.deps.notifyOnly)
+                this.syncNoticePeers();
             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: '' } });
+                    this.queueNeeds(peer, 'approval', threadId);
                     continue;
                 }
                 const key = `${peer}/${threadId}`;
@@ -493,6 +606,8 @@ export class Watcher {
                     entry.approvals.push(approval);
                 entry.lastSeenAt = at;
             }
+            if (this.deps.notifyOnly)
+                this.fillOutbox();
         });
     }
     /** Reads one new approval and its request; `skip` says why it should not wake anyone. */
@@ -525,16 +640,18 @@ export class Watcher {
         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.
+            // Switching to D mode converts the prior local backlog into the same fixed peer slots.
             if (Object.keys(this.state.pending).length)
                 await this.mutate(() => {
+                    this.syncNoticePeers();
                     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: '' } });
+                        for (const _message of pending.messages)
+                            this.queueNeeds(pending.peer, 'message', pending.threadId);
+                        for (const _approval of pending.approvals ?? [])
+                            this.queueNeeds(pending.peer, 'approval', pending.threadId);
                     }
                     this.state.pending = {};
+                    this.fillOutbox();
                 });
             await this.runOutbox();
             return;
@@ -546,7 +663,7 @@ export class Watcher {
                 continue;
             if (!force && wakeDueAt(pending, this.opts.debounceMs) > at)
                 continue;
-            if (!force && (this.retryAt.get(key) ?? 0) > at)
+            if (!force && !pending.approvals?.length && (this.retryAt.get(key) ?? 0) > at)
                 continue;
             this.waking.add(key);
             runs.push(this.wakeThread(key, pending, at).finally(() => this.waking.delete(key)));
@@ -566,7 +683,7 @@ export class Watcher {
         await this.syncPaused();
         // Messages that land while the wake runs stay pending for the next one, so wake exactly this snapshot.
         let messages = [...pending.messages];
-        const approvals = [...(pending.approvals ?? [])];
+        let 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) {
@@ -592,6 +709,13 @@ export class Watcher {
                     return;
             }
         }
+        // Owner decisions have their own retry clock. A failed message adapter cannot delay an approval.
+        if ((this.state.wakeRetries[key]?.nextAttemptAt ?? 0) > at)
+            messages = [];
+        if ((this.state.approvalRetries[key]?.nextAttemptAt ?? 0) > at)
+            approvals = [];
+        if (!messages.length && !approvals.length)
+            return;
         const woken = messages.map((m) => m.messageId);
         const approvedIds = approvals.map((a) => a.approvalId);
         const oldestSentAt = messages[0]?.sentAt ?? '';
@@ -607,6 +731,7 @@ export class Watcher {
             // 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(() => {
+                this.state.threadNotices[key] ??= threadNoticeState();
                 if (woken.length)
                     this.state.wakes[key] = [...this.recentWakes(key), this.now()];
             });
@@ -632,9 +757,14 @@ export class Watcher {
         }
         catch (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)));
+            let failures = 0;
+            await this.mutate(() => {
+                for (const retries of [...(woken.length ? [this.state.wakeRetries] : []), ...(approvedIds.length ? [this.state.approvalRetries] : [])]) {
+                    const count = (retries[key]?.failures ?? 0) + 1;
+                    retries[key] = { failures: count, nextAttemptAt: this.now() + Math.min(15 * 60_000, WAKE_RETRY_MS * 2 ** (count - 1)) };
+                    failures = Math.max(failures, count);
+                }
+            });
             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);
@@ -649,8 +779,11 @@ export class Watcher {
                     delete this.state.pending[key];
             }
             this.state.woken = [...this.state.woken, ...woken].slice(-WAKEN_MEMORY);
+            if (woken.length)
+                delete this.state.wakeRetries[key];
+            if (approvedIds.length)
+                delete this.state.approvalRetries[key];
         });
-        this.wakeFailures.delete(key);
         // Only now, with the wake recorded, is the retry hold-off cleared.
         this.retryAt.delete(key);
         this.deps.log('woke', {
@@ -662,8 +795,9 @@ export class Watcher {
     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 pauseId = await nextNoticeId(this.deps.selfKv, pending.peer, pending.threadId, this.now());
         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 });
+            const created = await writePauseMarker(this.deps.selfKv, { v: 1, peer: pending.peer, threadId: pending.threadId, by: 'budget', at, reason, informId: pauseId });
             this.pausedKeys.add(key);
             return created;
         });
@@ -677,8 +811,10 @@ export class Watcher {
         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 } });
+            const record = this.state.threadNotices[key] ??= threadNoticeState();
+            Object.assign(record, { ourPaused: true, ourMarkerId: pauseId, informPending: true, informText: text });
+            this.queueEpisode(record, 'paused', pauseId);
+            this.fillOutbox();
         });
         this.deps.log('paused', { peer: pending.peer, threadId: pending.threadId, by: 'budget', reason });
     }
@@ -694,29 +830,220 @@ export class Watcher {
             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;
+    /** Two episode values per known thread. Additional transitions coalesce, without allocating another slot. */
+    queueEpisode(record, kind, eventId) {
+        if (!ULID.test(eventId) || record.episodes.some(episode => episode.kind === kind && episode.eventId === eventId))
+            return;
+        const slot = record.episodes.find(episode => !episode.kind);
+        if (slot)
+            Object.assign(slot, emptyEpisode(), { kind, eventId });
+        else {
+            const last = record.episodes[1];
+            last.repeats = incrementCount(last.repeats);
+            if (last.dispatchArrivals !== '------')
+                last.dispatchArrivals = incrementCount(last.dispatchArrivals);
+        }
+    }
+    /** Only the paired handles in our local configuration allocate needs-you state. */
+    syncNoticePeers() {
+        const paired = new Set(this.deps.loadPeers().filter(peer => peer.status === 'paired' && HANDLE.test(peer.handle)).map(peer => peer.handle));
+        for (const peer of Object.keys(this.state.peerNotices))
+            if (!paired.has(peer))
+                delete this.state.peerNotices[peer];
+        if (this.deps.notifyOnly)
+            for (const peer of paired) {
+                if (!Object.hasOwn(this.state.peerNotices, peer))
+                    this.state.peerNotices[peer] = { message: emptyNeedsSlot(), approval: emptyNeedsSlot() };
             }
-            this.state.peerPausedDay[key] = day;
-            this.state.noticeLog[notice.peer] = [...recent, at];
+        for (const record of Object.values(this.state.peerNotices))
+            for (const kind of ['message', 'approval']) {
+                record[kind] = { ...emptyNeedsSlot(), ...record[kind] };
+            }
+    }
+    /** Bounded values only: a later delivery updates the same paired-peer slot. Called inside mutate. */
+    queueNeeds(peer, kind, threadId) {
+        const slot = this.state.peerNotices[peer]?.[kind];
+        if (!slot || !ULID.test(threadId))
+            return;
+        try {
+            decodeTime(threadId);
+        }
+        catch {
+            return;
+        }
+        const at = new Date(this.now()).toISOString();
+        if (slot.count === '000000') {
+            slot.eventId = ulid(this.now());
+            slot.firstSeenAt = at;
+        }
+        slot.threadId = threadId;
+        slot.count = incrementCount(slot.count);
+        if (slot.dispatchArrivals !== '------') {
+            if (slot.dispatchArrivals === '000000')
+                slot.arrivalFirstSeenAt = at;
+            slot.dispatchArrivals = incrementCount(slot.dispatchArrivals);
+        }
+    }
+    noticeSlot(item) {
+        const kind = needsKind(item.notice.kind);
+        if (kind) {
+            const slot = this.state.peerNotices[item.notice.peer]?.[kind];
+            return slot?.count !== '000000' && slot?.eventId === item.notice.eventId ? slot : undefined;
         }
+        return this.state.threadNotices[`${item.notice.peer}/${item.notice.threadId}`]?.episodes.find(episode => episode.kind === item.notice.kind && episode.eventId === item.notice.eventId);
+    }
+    rememberNotice(item) {
+        const episode = this.noticeSlot(item);
+        if (episode)
+            Object.assign(episode, { tries: item.tries ?? 0, nextAttemptAt: item.nextAttemptAt ?? 0, logged: item.logged ?? false });
+    }
+    /** Earliest rolling-hour retry under the global allowance and each paired peer's share. */
+    noticeRateDeadline(peer, now = this.now()) {
+        const recent = (this.state.noticeLog[peer] ?? []).filter(t => now - t < 3600_000);
+        const global = this.state.noticeGlobalLog.filter(t => now - t < 3600_000);
+        const peers = [...new Set([...this.deps.loadPeers().filter(peer => peer.status === 'paired').map(peer => peer.handle), peer])];
+        const share = Math.min(NOTICE_RESERVE_PER_PEER, Math.floor(NOTICES_PER_HOUR / peers.length));
+        const reservedForOthers = peers.filter(other => other !== peer).reduce((reserved, other) => reserved + Math.max(0, share - (this.state.noticeLog[other] ?? []).filter(t => now - t < 3600_000).length), 0);
+        if (recent.length < NOTICES_PER_PEER_PER_HOUR && global.length + reservedForOthers < NOTICES_PER_HOUR)
+            return 0;
+        return Math.max(recent.length >= NOTICES_PER_PEER_PER_HOUR ? Math.min(...recent) + 3600_000 : 0, global.length ? Math.min(...global) + 3600_000 : now + 3600_000);
+    }
+    /** -1 appends; a nonnegative index yields that place; undefined leaves the pending slot alone. */
+    admissionIndex(item) {
+        if (this.state.outbox.some(existing => existing.id === item.id))
+            return undefined;
+        if (this.state.outbox.length < MAX_OUTBOX)
+            return -1;
+        const now = this.now();
+        const eligible = item.kind === 'inform' || ((item.nextAttemptAt ?? 0) <= now && !this.noticeRateDeadline(item.notice.peer, now));
+        if (!eligible)
+            return undefined;
+        const deferred = this.state.outbox.findIndex(existing => existing.kind === 'notify' && !this.outboxBusy.has(existing.id)
+            && ((existing.nextAttemptAt ?? 0) > now || this.noticeRateDeadline(existing.notice.peer, now) > now));
+        if (deferred >= 0)
+            return deferred;
+        if (item.kind === 'notify') {
+            const counts = new Map();
+            for (const existing of this.state.outbox)
+                if (existing.kind === 'notify')
+                    counts.set(existing.notice.peer, (counts.get(existing.notice.peer) ?? 0) + 1);
+            const own = counts.get(item.notice.peer) ?? 0;
+            const overrepresented = this.state.outbox.findIndex(existing => existing.kind === 'notify'
+                && existing.notice.peer !== item.notice.peer && (counts.get(existing.notice.peer) ?? 0) > own + 1
+                && existing.notice.kind !== 'paused' && !existing.tries && !this.outboxBusy.has(existing.id));
+            if (overrepresented >= 0)
+                return overrepresented;
+        }
+        if (item.kind === 'inform' || item.notice.kind === 'paused') {
+            const unattempted = this.state.outbox.findIndex(existing => existing.kind === 'notify' && existing.notice.kind === 'peer-paused'
+                && !existing.tries && !this.outboxBusy.has(existing.id));
+            if (unattempted >= 0)
+                return unattempted;
+        }
+        return undefined;
+    }
+    /** Queue places can yield; the two fixed episode records retain all retry metadata. */
+    enqueue(item) {
+        const index = this.admissionIndex(item);
+        if (index === undefined)
+            return;
+        if (index >= 0)
+            this.state.outbox.splice(index, 1);
         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' });
+    }
+    *outboxCandidates() {
+        for (const [key, record] of Object.entries(this.state.threadNotices)) {
+            const [peer, threadId] = key.split('/');
+            if (record.informPending)
+                yield { id: `inform:${key}`, kind: 'inform', peer, threadId, pauseId: record.ourMarkerId, text: record.informText };
+        }
+        for (const kind of ['paused', 'peer-paused']) {
+            for (const [key, record] of Object.entries(this.state.threadNotices)) {
+                const [peer, threadId] = key.split('/');
+                for (const [slot, episode] of record.episodes.entries()) {
+                    if (episode.kind === kind)
+                        yield { id: episodeKey(key, slot), kind: 'notify',
+                            tries: episode.tries, nextAttemptAt: episode.nextAttemptAt, logged: episode.logged, notice: {
+                                kind, peer, threadId, eventId: episode.eventId, repeats: episode.repeats,
+                                detail: kind === 'paused' ? 'thread paused on this side' : "the peer's watcher reported the thread paused",
+                            } };
+                }
+            }
         }
+        for (const [peer, record] of Object.entries(this.state.peerNotices)) {
+            for (const kind of ['approval', 'message']) {
+                const slot = record[kind];
+                if (slot.count !== '000000')
+                    yield { id: needsKey(peer, kind), kind: 'notify',
+                        tries: slot.tries, nextAttemptAt: slot.nextAttemptAt, logged: slot.logged, notice: {
+                            kind: kind === 'message' ? 'new-message' : 'new-approval', peer, threadId: slot.threadId,
+                            eventId: slot.eventId, count: slot.count, detail: '',
+                        } };
+            }
+        }
+    }
+    /** Admit local work first, allowing eligible peers to pass deferred entries in a full queue. */
+    fillOutbox() {
+        for (const item of this.fairOutbox([...this.outboxCandidates()]))
+            this.enqueue(item);
+    }
+    fairOutbox(items) {
+        const ordered = [];
+        for (const priority of ['inform', 'paused', 'other']) {
+            const peers = new Map();
+            for (const item of items) {
+                const group = item.kind === 'inform' ? 'inform' : item.notice.kind === 'paused' ? 'paused' : 'other';
+                if (group !== priority)
+                    continue;
+                const peer = item.kind === 'inform' ? item.peer : item.notice.peer;
+                if (!peers.has(peer))
+                    peers.set(peer, []);
+                peers.get(peer).push(item);
+            }
+            while (peers.size)
+                for (const [peer, queue] of peers) {
+                    ordered.push(queue.shift());
+                    if (!queue.length)
+                        peers.delete(peer);
+                }
+        }
+        return ordered;
+    }
+    /** Completion matches both the fixed slot and episode ULID; another queued episode is independent. */
+    finishOutbox(item, delivered = false) {
+        const peer = item.kind === 'inform' ? item.peer : item.notice.peer;
+        const threadId = item.kind === 'inform' ? item.threadId : item.notice.threadId;
+        const record = this.state.threadNotices[`${peer}/${threadId}`];
+        if (item.kind === 'notify' && needsKind(item.notice.kind)) {
+            const slot = this.noticeSlot(item);
+            if (slot) {
+                const arrivals = slot.dispatchArrivals === '------' ? '000000' : slot.dispatchArrivals;
+                if (delivered && arrivals !== '000000')
+                    Object.assign(slot, emptyNeedsSlot(), {
+                        threadId: slot.threadId, eventId: ulid(this.now()), count: arrivals, firstSeenAt: slot.arrivalFirstSeenAt,
+                    });
+                else
+                    Object.assign(slot, emptyNeedsSlot());
+            }
+        }
+        else if (record) {
+            if (item.kind === 'inform' && item.pauseId === record.ourMarkerId)
+                record.informPending = false;
+            if (item.kind === 'notify') {
+                record.lastNoticeSentAt = new Date(this.now()).toISOString();
+                const slot = record.episodes.find(episode => episode.kind === item.notice.kind && episode.eventId === item.notice.eventId);
+                if (slot) {
+                    const arrivedDuringDelivery = slot.dispatchArrivals === '------' ? 0 : Number(slot.dispatchArrivals);
+                    if (delivered && arrivedDuringDelivery > 0)
+                        Object.assign(slot, emptyEpisode(), {
+                            kind: slot.kind, eventId: slot.eventId, repeats: String(arrivedDuringDelivery - 1).padStart(6, '0'),
+                        });
+                    else
+                        Object.assign(slot, emptyEpisode());
+                }
+            }
+        }
+        this.state.outbox = this.state.outbox.filter(o => o.id !== item.id);
     }
     /**
      * Markers under me/state/paused/ are the truth. A marker that disappeared means the human resumed: the budget starts
@@ -744,7 +1071,10 @@ export class Watcher {
                     const backlog = {};
                     await this.mutate(() => {
                         for (const key of resumed) {
+                            if (this.state.threadNotices[key])
+                                this.state.threadNotices[key].ourPaused = false;
                             delete this.state.wakes[key];
+                            delete this.state.wakeRetries[key];
                             const held = this.state.held[key];
                             if (held?.messages.length) {
                                 backlog[key] = held.messages.length;
@@ -756,6 +1086,10 @@ export class Watcher {
                             }
                             delete this.state.held[key];
                         }
+                        for (const key of added) {
+                            const record = this.state.threadNotices[key] ??= threadNoticeState();
+                            record.ourPaused = true;
+                        }
                         this.state.paused = [...new Set([...this.state.paused.filter((key) => !resumed.includes(key)), ...added])].sort();
                     });
                     for (const key of resumed)
@@ -770,60 +1104,119 @@ export class Watcher {
     /** 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.approvalRetries).filter(key => !this.state.pending[key]?.approvals?.length))
+            .concat(Object.keys(this.state.wakeRetries).filter(key => !this.state.pending[key]))
             .concat(Object.keys(this.state.noticeLog).filter((peer) => !this.state.noticeLog[peer].some((t) => at - t < 3600_000)));
-        if (!stale.length)
+        if (!stale.length && !this.state.noticeGlobalLog.some(t => at - t >= 3600_000))
             return;
         await this.mutate(() => {
+            for (const key of Object.keys(this.state.wakeRetries))
+                if (!this.state.pending[key])
+                    delete this.state.wakeRetries[key];
             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 key of Object.keys(this.state.approvalRetries))
+                if (!this.state.pending[key]?.approvals?.length)
+                    delete this.state.approvalRetries[key];
+            this.state.noticeGlobalLog = this.state.noticeGlobalLog.filter(t => at - t < 3600_000);
             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. */
+    /** Informs and notifications queued in state; failures back off (1, 2, 4 ... 15 minutes) and give up after 3 notification attempts or 8 inform failures. */
     async runOutbox() {
         const at = this.now();
+        const refill = [...this.outboxCandidates()].some(item => this.admissionIndex(item) !== undefined);
+        if (refill)
+            await this.mutate(() => this.fillOutbox());
         const runs = [];
-        for (const item of [...this.state.outbox]) {
+        const items = this.fairOutbox([...this.state.outbox]);
+        for (const item of items) {
             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);
+                        await this.deps.postInform?.(item.peer, item.threadId, item.text, item.pauseId);
                     else {
                         const { notice } = item;
+                        let reserved = false;
+                        await this.mutate(() => {
+                            const stored = this.state.outbox.find(o => o.id === item.id);
+                            if (stored?.kind !== 'notify')
+                                return;
+                            const now = this.now();
+                            const recent = (this.state.noticeLog[notice.peer] ?? []).filter(t => now - t < 3600_000);
+                            if ((stored.tries ?? 0) >= MAX_NOTICE_ATTEMPTS) {
+                                this.finishOutbox(item);
+                                return;
+                            }
+                            const deadline = this.noticeRateDeadline(notice.peer, now);
+                            if (deadline) {
+                                stored.nextAttemptAt = deadline;
+                                this.rememberNotice(stored);
+                                this.deps.log('notice-rate-cap', { peer: notice.peer, id: item.id });
+                                return;
+                            }
+                            const episode = this.noticeSlot(stored);
+                            if (episode) {
+                                if ('repeats' in episode)
+                                    item.notice.repeats = stored.notice.repeats = episode.repeats;
+                                else {
+                                    item.notice.threadId = stored.notice.threadId = episode.threadId;
+                                    item.notice.count = stored.notice.count = episode.count;
+                                    episode.arrivalFirstSeenAt = EPOCH;
+                                }
+                                episode.dispatchArrivals = '000000';
+                            }
+                            this.state.noticeGlobalLog = [...this.state.noticeGlobalLog.filter(t => now - t < 3600_000), now];
+                            item.tries = stored.tries = (stored.tries ?? 0) + 1;
+                            this.rememberNotice(stored);
+                            this.state.noticeLog[notice.peer] = [...recent, now];
+                            reserved = true; // persisted BEFORE any channel operation, even one that delivers then fails
+                        });
+                        if (!reserved)
+                            return;
                         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.mutate(() => {
+                                const stored = this.state.outbox.find(o => o.id === item.id);
+                                if (stored?.kind === 'notify') {
+                                    stored.logged = true;
+                                    this.rememberNotice(stored);
+                                }
+                            });
                         }
                         await this.deps.notify?.(notice);
                     }
-                    await this.mutate(() => { this.state.outbox = this.state.outbox.filter((o) => o.id !== item.id); });
+                    await this.mutate(() => this.finishOutbox(item, true));
                 }
                 catch (error) {
-                    const tries = (item.tries ?? 0) + 1;
+                    const tries = item.kind === 'notify' ? (item.tries ?? 1) : (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) {
+                    if (tries >= (item.kind === 'notify' ? MAX_NOTICE_ATTEMPTS : 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); });
+                        await this.mutate(() => this.finishOutbox(item));
                     }
                     else {
-                        await this.mutate(() => { const stored = this.state.outbox.find((o) => o.id === item.id); if (stored) {
+                        await this.mutate(() => {
+                            const stored = this.state.outbox.find(o => o.id === item.id);
+                            if (!stored)
+                                return;
                             stored.tries = tries;
-                            stored.nextAttemptAt = at + Math.min(15 * 60_000, WAKE_RETRY_MS * 2 ** (tries - 1));
-                        } });
+                            stored.nextAttemptAt = this.now() + Math.min(15 * 60_000, WAKE_RETRY_MS * 2 ** (tries - 1));
+                            if (stored.kind === 'notify') {
+                                this.rememberNotice(stored);
+                                const episode = this.noticeSlot(stored);
+                                if (episode)
+                                    episode.dispatchArrivals = '------';
+                            }
+                        });
                     }
                 }
                 finally {
@@ -835,6 +1228,16 @@ export class Watcher {
     }
     // ---------- run loop ----------
     async pollOnce(via) {
+        if (this.deps.notifyOnly) {
+            const paired = this.deps.loadPeers().filter(peer => peer.status === 'paired' && HANDLE.test(peer.handle)).map(peer => peer.handle);
+            if (paired.some(peer => !Object.hasOwn(this.state.peerNotices, peer))
+                || Object.keys(this.state.peerNotices).some(peer => !paired.includes(peer))) {
+                await this.mutate(() => {
+                    this.syncNoticePeers();
+                    this.state.outbox = this.state.outbox.filter(item => item.kind !== 'notify' || !needsKind(item.notice.kind) || paired.includes(item.notice.peer));
+                });
+            }
+        }
         await this.syncPaused();
         await this.pruneState();
         await Promise.all(this.deps.loadPeers().map((peer) => this.sync(peer, via)));