docs: address argus nits — latency note in collect_unread, unread_count retention rationale

hive-matrix-mcp/src/handlers.rs

@@ -346,9 +346,13 @@ pub async fn read_room(client: &Client, room_ref: &str, limit: Option<usize>) ->
 
 /// Return the number of joined rooms with at least one unread
 /// notification according to the server-side push notification counts
-/// cached by the matrix-sdk client. Used by the harness to surface
-/// unread matrix activity in `get_loose_ends` without exposing
-/// message content.
+/// cached by the matrix-sdk client.
+///
+/// The harness uses [`unread_summary`] (richer, with per-room body
+/// snippets) rather than this endpoint. `unread_count` is kept as a
+/// lightweight public endpoint for callers that only need the count
+/// and want to avoid the `/messages` network round-trips that
+/// [`collect_unread`] issues for count==1 rooms.
 #[must_use]
 pub fn unread_count(client: &Client) -> DaemonResponse {
     let rooms = client
@@ -364,6 +368,13 @@ pub fn unread_count(client: &Client) -> DaemonResponse {
 /// one unread notification the last message body is fetched via the
 /// `/messages` endpoint (best-effort; failures leave `last_body` as
 /// `None`). Rooms with zero unreads are omitted.
+///
+/// **Latency note**: each count==1 room triggers a live `/messages`
+/// network request to the matrix homeserver to retrieve the message
+/// body. This adds per-room round-trip latency to `get_loose_ends`
+/// and the wake-signal path. Acceptable in practice (rooms with
+/// unread are few; request is best-effort), but worth bearing in
+/// mind if latency becomes a concern.
 #[must_use]
 pub async fn collect_unread(client: &Client) -> Vec<crate::protocol::RoomUnread> {
     use crate::protocol::RoomUnread;