Delivery events queued while an agent's process was down are not push-delivered on its return

[Mearman]

Delivery queues are per-store in-memory maps and serialise() excludes them, so a restarted bridge receives synced room and DM history (readable via read_room / DM reads — nothing is lost) but gets no push delivery (onDelivery) for what arrived while it was down.

Resolution is a design decision, either direction acceptable if recorded here:

Implement replay: include pending delivery events in the synced state and apply them as local delivery when the owning agent re-registers. Design considerations: replay must not re-notify for events already consumed (the mesh-store's localDeliveryKeys dedup is per-process and cleared on restart, while bridges like pi carry their own LRU dedup over recent delivery events, so bridge-level dedup catches most replays), auto-markRead fires on delivery (replays would re-mark-read messages whose receipts already propagated), and a long-down agent can accumulate a large replay set (bound it, or drain per subscription).

Or decide replay is wrong by design: history sync already covers correctness and push replay would be noise; in that case the boundary gets documented in the README's delivery section rather than left implicit.

Recorded during the #14 persistent-identity work; spun out as its own item because the design call is independent of identity stability.

[Mearman]

Fixed in #30, and the design decision this issue asked for is: implement replay.

The deciding argument: for push bridges the missing wake-up is not an ergonomics gap, it is the "pi never wakes up" failure class from #14 in a different guise — a message that arrives during downtime sits correct-but-silent in history, and nothing ever wakes the agent to it. History sync covers correctness; replay covers the wake-up. Both matter.

How it works: every peer already replicated delivery events in its own queues (that machinery existed for drain bridges), so the queues simply travel in SerialisedState now, and applying a snapshot fires onDelivery for events targeting the receiving peer's own agent. A returning process replays exactly what accumulated while it was down; drain bridges drain the same merged queue.

The two design hazards the issue flagged, and how they landed:

• Re-notification: deduplicated two ways — messages the agent has already read are skipped (read receipts mutate the event between snapshots, so a structural key alone re-fires; this was a real bug the tests caught), and a bounded structural key set covers the other event types. An event fired locally is also removed from the local pending queue, so steady-state snapshots stop carrying what a peer already consumed.
• Unbounded replay: queues are capped per agent (oldest dropped first), and the stale-agent cleanup now purges queue entries with their agent — which also fixes a pre-existing leak where purged agents' queues grew forever.

End-to-end acceptance: a real TLS restart over a persisted identity receives the push for a message sent while it was down, plus unit coverage of replay, dedup, and the bound — all in pnpm test (20 suites-worth of tests, three clean consecutive rounds locally, green CI).

[github-actions]

🎉 This issue has been resolved in version 1.25.6 🎉

The release is available on:

• npm package (@latest dist-tag)
• v1.25.6
• GitHub release

Your semantic-release bot 📦🚀

[Mearman]

Recording an accepted design boundary for discoverability: replay dedup is airtight for room messages and DMs (the read-receipt guard), but non-message events evicted from the 50-entry structural-key LRU can re-fire if a peer's snapshot re-delivers them after more than 50 subsequent events — a bound of at most one duplicate push per event, and only for notification-shaped events (room_invite, member_joined, connection_request, ...). The bridges' own LRU dedup (pi keeps 100) is a further backstop. Accepted as bounded noise rather than growing the store's key set; noted so the occasional duplicate notification has a documented cause.

[Mearman]

Superseded by #33: the bounded re-fire boundary documented above is now closed exactly rather than bounded. Replay fires only for events with consumption evidence — room messages and DMs (readBy) and invites (the invited list) — so nothing without evidence ever replay-fires, transient notifications included. Pinned by tests for the invite pending/declined pair and transient merge-without-fire.