Document integrations in the user guide

Adds an Integrations section covering incoming webhooks, outgoing event
subscriptions (including verifying the signature and the best-effort
delivery limits), and bots with API tokens. Nothing in the guide
mentioned any of these; the only write-up was the developer README.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

USER_GUIDE.md

@@ -17,6 +17,7 @@ attachments, notifications, and personalizing your account.
 - [Presence and notifications](#presence-and-notifications)
 - [Your profile](#your-profile)
 - [Room details](#room-details)
+- [Integrations](#integrations)
 - [Active sessions](#active-sessions)
 - [Staying up to date](#staying-up-to-date)
 
@@ -68,6 +69,11 @@ new message, or if you message them again yourself.
 Type in the message box at the bottom of a room and press **Enter** to
 send. Use **Shift+Enter** to add a line break without sending.
 
+Each message shows when it was sent, in your local time. Messages from today
+show just the time; older ones add the day — "Yesterday 4:04 PM", a weekday
+like "Mon 4:04 PM" for the past week, then the date ("Oct 2, 4:04 PM", with
+the year if it's not this one). Hover a time to see the full date.
+
 ## Formatting
 
 Messages support Markdown. Prefer buttons to typing the syntax? Click the
@@ -128,7 +134,9 @@ you'll see an error before it uploads.
 Hover over a message and click the 🙂 icon in its action row to react
 with an emoji. Reactions from everyone appear as small pills under the
 message with a count; click an existing pill to add or remove your own
-reaction to it. Hovering a pill shows who reacted.
+reaction to it. Hovering a pill shows who reacted. Once a message has
+reactions, a small **+🙂** button at the end of the row of pills lets you
+add a different emoji without going back to the action row.
 
 Anyone can add a custom emoji: open the emoji picker (the 🙂 button, either
 in the composer or on a message) and click **+ Add** in the **Custom**
@@ -202,8 +210,135 @@ you can:
 - Leave the room — unless you're the owner, in which case ownership has
   to be transferred to someone else first
 
-Room admins and owners see additional management options here that
-aren't covered in this guide.
+Room admins and owners see additional management options here, including
+**Integrations** (see [Integrations](#integrations)).
+
+## Integrations
+
+DS Chat can exchange messages with other tools, three ways. The first two
+are set up by a room's admins or owners; the third by a site admin.
+
+| You want to… | Use |
+| --- | --- |
+| Post into a room from a script, CI job, or another service | [Incoming webhook](#incoming-webhooks) |
+| Get notified elsewhere when a room's messages change | [Outgoing event subscription](#outgoing-event-subscriptions) |
+| Have a program read and write messages as its own account | [Bot](#bots) |
+
+Links in messages already get a preview card on their own, and Web Push
+and email notifications work without any setup — see
+[Presence and notifications](#presence-and-notifications).
+
+### Incoming webhooks
+
+An incoming webhook is a private URL that posts into one room.
+
+1. Open the room's details panel (the info icon in the header) and expand
+   **Integrations**. You need to be an admin or the owner of the room.
+2. Under **Incoming webhooks**, add an optional description (such as
+   "Deploy notices") and create it. The full URL is listed there whenever
+   you need to copy it again.
+3. Send a `POST` with a JSON body to that URL:
+
+```bash
+curl -X POST "https://chat.example.com/api/webhooks/incoming/<token>" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Deploy finished: **v2026.10.22** is live"}'
+```
+
+The message appears in the room right away, formatted like any other
+(markdown works), attributed to whoever created the webhook, and it
+notifies members the same way a typed message would. A successful post
+returns `204`; an unknown or revoked URL returns `404`, and an archived
+room returns `403`.
+
+**Treat the URL like a password.** There's no other authentication: anyone
+who has it can post into the room. If it leaks, click **Revoke** next to
+it in the same panel and create a new one.
+
+### Outgoing event subscriptions
+
+An outgoing subscription sends DS Chat's events to a URL you control.
+
+1. In the same **Integrations** panel, under **Outgoing event
+   subscriptions**, enter the URL and tick the events you want:
+   `message.created` (a new message) and/or `message.updated` (an edit).
+2. Click **Add**. A **signing secret** appears once — copy it now, it
+   won't be shown again.
+
+Each event arrives as a `POST` with a JSON body:
+
+```json
+{
+  "event": "message.created",
+  "data": { "id": "…", "room_id": "…", "username": "alice", "content": "hello", "…": "…" }
+}
+```
+
+To let you confirm a request really came from DS Chat, each one carries an
+`X-DS-Chat-Signature: sha256=<hex>` header: the HMAC-SHA256 of the raw
+request body, keyed with your signing secret. For example, in Python:
+
+```python
+import hashlib, hmac
+
+expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+valid = hmac.compare_digest(expected, request_signature_header)
+```
+
+Things to know:
+
+- **Delivery is best-effort.** Each event is tried once with a short
+  timeout; if your endpoint is down or slow, that event is dropped and
+  not retried. Don't rely on it as your only record of a conversation.
+- **Only message creation and edits** are sent. Deletions, reactions,
+  and joins don't generate events.
+- **The URL must be publicly reachable.** Addresses that point to
+  private or internal networks (localhost, `192.168.x.x`, and so on) are
+  rejected when you add the subscription.
+- **Revoke** removes a subscription immediately.
+
+### Bots
+
+A bot is an account for a program rather than a person. It signs in with
+an API token instead of a password and uses the same interface as the
+app itself, so it can read and write messages in real time.
+
+Only **site admins** create bots: open the admin page, choose the **Bots**
+tab, and click **Create bot**, then **Issue token** and pick what the
+token may do:
+
+- `read:messages` — read a room's message history
+- `write:messages` — send, edit, and delete messages
+- `manage:rooms` — recognized, but doesn't grant anything beyond what the
+  bot's room role already allows
+
+The token is shown once — copy it then. You can revoke it from the same
+tab at any time.
+
+A bot is held to the same rules as any member: it can only see and post
+in rooms it belongs to, and its room role limits what it can do there.
+The token can narrow that further, never widen it.
+
+The bot connects to the WebSocket at `/ws/chat`, sending
+`Authorization: Bearer <token>` with the connection, and then speaks
+simple JSON messages:
+
+```json
+{"type": "join", "room_id": "<room id>"}
+{"type": "message", "room_id": "<room id>", "content": "Hello from a bot"}
+{"type": "edit", "room_id": "<room id>", "message_id": "<id>", "content": "Fixed"}
+```
+
+Messages from the room arrive on the same connection as they happen. The
+same bearer token also works for the regular `/api/` endpoints, such as
+fetching a room's history.
+
+The server sends a `{"type": "ping"}` every 30 seconds to check a
+connection is alive; a bot may ignore it, since bot connections are never
+dropped for staying silent.
+
+There is currently **no rate limiting** on bots (or anyone else), so keep
+automation polite.
 
 ## Staying up to date
 

backend/README.md

@@ -289,17 +289,26 @@ instance and running many behave identically:
   to `room:*`; each message it receives is handed to its own local
   `ConnectionManager.broadcast()`. One instance just talks to itself
   through Redis, so there's no separate single-instance code path.
-- `app/ws/presence.py` (`Presence`) — a Redis hash per room
-  (`presence:{room_id}`, field = user ID, value = connection refcount) is
-  the cross-instance answer to "is this member connected *anywhere* right
-  now," which is what the Phase 4 offline-push check uses instead of the
-  local `ConnectionManager`. Refcounted so a user connected from two tabs
-  (or two instances) isn't marked offline until every connection closes.
+- `app/ws/presence.py` (`Presence`) — a Redis sorted set per room
+  (`presence:v2:room:{id}`, one member per *connection*, `<user_id>:<conn_id>`,
+  score = expiry time) is the cross-instance answer to "is this member
+  connected *anywhere* right now," which is what the Phase 4 offline-push
+  check uses instead of the local `ConnectionManager`. A user is connected
+  while any of their entries is unexpired, so two tabs (or two instances)
+  don't mark them offline until every connection is gone. `GlobalPresence`
+  (`presence:v2:global`) and `FocusPresence` (`presence:v2:unfocused`) use the
+  same store, `app/ws/expiring_presence.py` (`ExpiringPresenceSet`).
 
-Known limitation: `Presence` has no heartbeat/TTL, so a hard process crash
-(not a clean disconnect) leaks that connection's increment forever — same
-category of simplification as the "no server-side session revocation" note
-below.
+Presence entries expire (#77) so nothing can be stuck online. A connection
+renews its entries (90s TTL) whenever the client sends a frame — the frontend
+answers the server's 30s `ping` with a `pong`, which is exactly that — and
+the server closes a human client's socket (code 4408) after 90s of silence.
+Bot (API-token) connections don't speak the heartbeat, so the server renews
+their entries itself while their handler is alive. An expiry has no
+disconnect event to announce it, so `app/ws/presence_sweeper.py` runs on every
+worker (a Redis lock makes it one sweep per 15s overall), prunes expired
+entries, and broadcasts the offline transition. The pre-#77 `presence:*`
+refcount hashes are deleted at startup.
 
 ## Push notifications (Phase 4)
 

backend/app/main.py

@@ -1,5 +1,6 @@
 import asyncio
 import contextlib
+import logging
 import pathlib
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
@@ -11,6 +12,7 @@ from redis.asyncio import Redis
 from starlette.middleware.sessions import SessionMiddleware
 
 from app.config import settings
+from app.database import async_session_factory
 from app.routers import (
     admin,
     auth,
@@ -31,6 +33,9 @@ from app.ws.connection_manager import ConnectionManager
 from app.ws.focus_presence import FocusPresence
 from app.ws.global_presence import GlobalPresence
 from app.ws.presence import Presence
+from app.ws.presence_sweeper import purge_legacy_presence, run_presence_sweeper
+
+logger = logging.getLogger(__name__)
 
 # backend/app/main.py -> backend/ -> repo root -- matches both the local
 # monorepo layout and the production layout (/srv/ds-chat/backend,
@@ -65,11 +70,23 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     # restarts on failure instead.
     listener_task = asyncio.create_task(app.state.broadcaster.run_forever())
 
+    # #77: presence entries now expire, and an expiry has no disconnect event
+    # to announce it -- this loop is what notices. The purge clears the old
+    # refcount hashes (and the counts that had leaked into them); it's
+    # best-effort, since Redis being down at startup shouldn't stop the app.
+    try:
+        await purge_legacy_presence(app.state.redis)
+    except Exception:
+        logger.warning("Could not purge legacy presence keys", exc_info=True)
+    sweeper_task = asyncio.create_task(run_presence_sweeper(app))
+
     yield
 
-    listener_task.cancel()
-    with contextlib.suppress(asyncio.CancelledError):
-        await listener_task
+    for task in (sweeper_task, listener_task):
+        task.cancel()
+    for task in (sweeper_task, listener_task):
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
     await app.state.redis.aclose()
 
 
@@ -85,6 +102,7 @@ def create_app() -> FastAPI:
     )
 
     app.state.connection_manager = ConnectionManager()
+    app.state.session_factory = async_session_factory
     app.state.redis = Redis.from_url(settings.redis_url, decode_responses=True)
     app.state.presence = Presence(app.state.redis)
     app.state.global_presence = GlobalPresence(app.state.redis)

backend/app/ws/chat.py

@@ -1,4 +1,7 @@
 import asyncio
+import contextlib
+import logging
+import time
 import uuid
 
 from fastapi import APIRouter, Depends, WebSocket, WebSocketDisconnect
@@ -28,6 +31,8 @@ from app.services.message_service import (
 from app.services.room_service import mark_room_read
 from app.services.session_service import resolve_session
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter(tags=["ws"])
 
 WS_UNAUTHENTICATED = 4401
@@ -44,6 +49,22 @@ WS_UNAUTHENTICATED = 4401
 # itself actually recovering).
 WS_PING_INTERVAL_SECONDS = 30
 
+# #77: a human client that has sent nothing -- not even the "pong" to the ping
+# above -- for this long is treated as gone and disconnected, so its presence
+# stops being renewed and cleanup runs. Needed on top of the transport's own
+# keepalive: a browser answers *protocol-level* pings from its network layer
+# even while the page's JavaScript is frozen (a suspended or discarded tab,
+# a sleeping laptop that keeps its network up), so the connection looks
+# healthy forever while nobody is actually there. Only the page itself can
+# send the app-level "pong". The frontend reconnects on any non-4401 close.
+WS_DEAD_AFTER_SECONDS = 90
+WS_HEARTBEAT_TIMEOUT = 4408
+
+# Presence entries (see ExpiringPresenceSet) are renewed on incoming frames,
+# at most this often -- a chatty client shouldn't turn every message into
+# several extra Redis writes.
+PRESENCE_REFRESH_MIN_INTERVAL_SECONDS = 10
+
 
 class ClientEnvelope(BaseModel):
     type: str
@@ -74,6 +95,21 @@ def _missing_scope(api_token: ApiToken | None, scope: str) -> bool:
     return api_token is not None and scope not in api_token.scopes
 
 
+async def _broadcast_offline(db: AsyncSession, broadcaster, user_id: uuid.UUID) -> None:
+    await broadcast_member_updated(db, broadcaster, user_id)
+    await broadcast_dm_presence_update(db, broadcaster, user_id, online=False)
+
+
+async def _best_effort(label: str, awaitable):
+    # Disconnect cleanup is several independent Redis/DB steps; one failing
+    # must not skip the ones after it.
+    try:
+        return await awaitable
+    except Exception:
+        logger.warning("Presence cleanup step failed: %s", label, exc_info=True)
+        return None
+
+
 @router.websocket("/ws/chat")
 async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)) -> None:
     api_token: ApiToken | None = None
@@ -114,13 +150,19 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
     # refcount if the socket closes while still blurred -- mirroring how
     # joined_rooms tracks per-connection room membership for its own cleanup.
     is_blurred = False
+    # Identifies this connection's own presence entries (#77) -- see
+    # ExpiringPresenceSet -- so one connection ending can't affect another
+    # belonging to the same user, and a dead one can simply stop renewing.
+    conn_id = uuid.uuid4().hex
+    last_frame_at = time.monotonic()
+    last_presence_refresh = last_frame_at
     manager.register_user(user.id, websocket)
     # Only broadcast on a genuine offline->online transition (this user's
     # first open connection), not for every extra tab -- broadcast_member_
     # updated tells every room this user's in to refresh, which would be
     # wasted churn on a transition that didn't actually change anything
     # visible.
-    if await global_presence.connect(user.id):
+    if await global_presence.connect(user.id, conn_id):
         await broadcast_member_updated(db, broadcaster, user.id)
         await broadcast_dm_presence_update(db, broadcaster, user.id, online=True)
     # This session is shared for the connection's entire lifetime (which can
@@ -135,6 +177,18 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
     # waiting for the next one.
     await db.commit()
 
+    async def refresh_presence() -> None:
+        # Renews every presence entry this connection holds. If the global
+        # one had already lapsed (a long stall) this is also the moment the
+        # user comes back online, and has to be announced like a fresh connect.
+        if await global_presence.refresh(user.id, conn_id):
+            await broadcast_member_updated(db, broadcaster, user.id)
+            await broadcast_dm_presence_update(db, broadcaster, user.id, online=True)
+        for room_id in joined_rooms:
+            await presence.refresh(room_id, user.id, conn_id)
+        if is_blurred:
+            await focus_presence.refresh(user.id, conn_id)
+
     try:
         while True:
             try:
@@ -147,9 +201,30 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
                 # send (raising, caught below same as any other disconnect);
                 # a merely quiet one just gets proded and the loop continues
                 # waiting.
+                if api_token is None and time.monotonic() - last_frame_at >= WS_DEAD_AFTER_SECONDS:
+                    # Gone (see WS_DEAD_AFTER_SECONDS). The socket may be too
+                    # dead to even take a close frame; either way, leaving the
+                    # loop runs the normal cleanup below.
+                    with contextlib.suppress(Exception):
+                        await websocket.close(code=WS_HEARTBEAT_TIMEOUT)
+                    break
+                if api_token is not None:
+                    # A bot isn't expected to speak our app-level heartbeat
+                    # (it may just ignore the ping), so it can't be dropped
+                    # for not answering and its presence can't depend on
+                    # answers. While the handler is alive the transport's own
+                    # keepalive is what vouches for it -- a dead bot socket
+                    # ends this handler, and cleanup does the rest.
+                    await refresh_presence()
+                    last_presence_refresh = time.monotonic()
+                    await db.commit()
                 await websocket.send_json({"type": "ping"})
                 continue
+            last_frame_at = time.monotonic()
             try:
+                if last_frame_at - last_presence_refresh >= PRESENCE_REFRESH_MIN_INTERVAL_SECONDS:
+                    await refresh_presence()
+                    last_presence_refresh = last_frame_at
                 try:
                     envelope = ClientEnvelope.model_validate(raw)
                 except ValidationError:
@@ -166,7 +241,7 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
                         )
                         continue
                     manager.join(envelope.room_id, websocket)
-                    await presence.join(envelope.room_id, user.id)
+                    await presence.join(envelope.room_id, user.id, conn_id)
                     joined_rooms.add(envelope.room_id)
                     await websocket.send_json({"type": "joined", "room_id": str(envelope.room_id)})
 
@@ -183,7 +258,7 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
                         await websocket.send_json({"type": "error", "detail": "room_id required"})
                         continue
                     manager.leave(envelope.room_id, websocket)
-                    await presence.leave(envelope.room_id, user.id)
+                    await presence.leave(envelope.room_id, user.id, conn_id)
                     joined_rooms.discard(envelope.room_id)
 
                 elif envelope.type == "focus":
@@ -198,11 +273,11 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
                         continue
                     if envelope.focused:
                         if is_blurred:
-                            await focus_presence.mark_focused(user.id)
+                            await focus_presence.mark_focused(user.id, conn_id)
                             is_blurred = False
                     else:
                         if not is_blurred:
-                            await focus_presence.mark_blurred(user.id)
+                            await focus_presence.mark_blurred(user.id, conn_id)
                             is_blurred = True
 
                 elif envelope.type == "message":
@@ -396,9 +471,11 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
         manager.leave_all(websocket)
         manager.unregister_user(user.id, websocket)
         for room_id in joined_rooms:
-            await presence.leave(room_id, user.id)
+            await _best_effort("room presence", presence.leave(room_id, user.id, conn_id))
         if is_blurred:
-            await focus_presence.mark_focused(user.id)
-        if await global_presence.disconnect(user.id):
-            await broadcast_member_updated(db, broadcaster, user.id)
-            await broadcast_dm_presence_update(db, broadcaster, user.id, online=False)
+            await _best_effort("focus presence", focus_presence.mark_focused(user.id, conn_id))
+        if await _best_effort("global presence", global_presence.disconnect(user.id, conn_id)):
+            await _best_effort(
+                "offline broadcast",
+                _broadcast_offline(db, broadcaster, user.id),
+            )

backend/app/ws/expiring_presence.py

@@ -0,0 +1,103 @@
+import time
+import uuid
+from collections.abc import Callable
+
+from redis.asyncio import Redis
+
+# #77: an entry that isn't renewed for this long stops counting. Chosen as 3x
+# the app-level ping interval (chat.py's WS_PING_INTERVAL_SECONDS): a healthy
+# connection renews roughly every ping, so two missed beats are tolerated
+# before someone flips offline.
+PRESENCE_TTL_SECONDS = 90
+
+
+def _text(value: str | bytes) -> str:
+    return value.decode() if isinstance(value, bytes) else value
+
+
+def _user_part(member: str) -> str:
+    return member.split(":", 1)[0]
+
+
+class ExpiringPresenceSet:
+    """"Which users have at least one live connection" for one Redis key,
+    where every connection is its own entry with its own expiry.
+
+    This replaced per-user refcounts (#77): a refcount only goes down when a
+    connection's cleanup code actually runs, so any connection that ended
+    without it -- a server crash or reboot, a process killed mid-restart, a
+    client that vanished without the server ever noticing -- left a +1 that
+    nothing could ever subtract, showing that person online forever (and in
+    the per-room case, suppressing their push notifications). Here a dead
+    connection simply stops being renewed and ages out on its own, so there
+    is no state that can leak.
+
+    One sorted set per key: member `<user_id>:<connection_id>`, score = the
+    moment it expires. "Live" means score > now. Scans are O(connections) --
+    fine for a self-hosted team chat; only the global key grows with the
+    whole server rather than one room.
+    """
+
+    def __init__(
+        self,
+        redis: Redis,
+        ttl_seconds: float = PRESENCE_TTL_SECONDS,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self._redis = redis
+        self._ttl = ttl_seconds
+        self._clock = clock
+
+    @staticmethod
+    def _member(user_id: uuid.UUID, conn_id: str) -> str:
+        return f"{user_id}:{conn_id}"
+
+    async def _live_members(self, key: str) -> list[str]:
+        members = await self._redis.zrangebyscore(key, f"({self._clock()}", "+inf")
+        return [_text(m) for m in members]
+
+    async def add(self, key: str, user_id: uuid.UUID, conn_id: str) -> bool:
+        """Creates or renews this connection's entry. Returns True iff the
+        user had no live entry beforehand -- a genuine offline->online
+        transition worth telling anyone about. Renewing an entry that's still
+        live (the common case, every heartbeat) is a single cheap write."""
+        member = self._member(user_id, conn_id)
+        now = self._clock()
+        score = await self._redis.zscore(key, member)
+        came_online = False
+        if score is None or score <= now:
+            came_online = not await self.is_live(key, user_id)
+        await self._redis.zadd(key, {member: now + self._ttl})
+        # Lets a key nobody renews any more (an idle room) disappear on its
+        # own instead of sitting there holding only expired entries.
+        await self._redis.expire(key, int(self._ttl * 2))
+        return came_online
+
+    async def remove(self, key: str, user_id: uuid.UUID, conn_id: str) -> bool:
+        """Drops this connection's entry. Returns True iff that left the user
+        with no live entry -- a genuine online->offline transition. False if
+        the entry was already gone: whoever removed it (see prune) already
+        reported the transition, and reporting it twice would be noise."""
+        removed = await self._redis.zrem(key, self._member(user_id, conn_id))
+        if not removed:
+            return False
+        return not await self.is_live(key, user_id)
+
+    async def is_live(self, key: str, user_id: uuid.UUID) -> bool:
+        prefix = f"{user_id}:"
+        return any(m.startswith(prefix) for m in await self._live_members(key))
+
+    async def live_user_ids(self, key: str) -> set[uuid.UUID]:
+        return {uuid.UUID(_user_part(m)) for m in await self._live_members(key)}
+
+    async def prune(self, key: str) -> set[uuid.UUID]:
+        """Deletes expired entries. Returns the users whose last live entry
+        was among them -- the offline transitions nobody was told about,
+        since an expiry has no disconnect event to hang a broadcast on."""
+        now = self._clock()
+        expired = [_text(m) for m in await self._redis.zrangebyscore(key, "-inf", now)]
+        if not expired:
+            return set()
+        await self._redis.zremrangebyscore(key, "-inf", now)
+        gone = {_user_part(m) for m in expired} - {_user_part(m) for m in await self._live_members(key)}
+        return {uuid.UUID(u) for u in gone}

backend/app/ws/focus_presence.py

@@ -2,44 +2,45 @@ import uuid
 
 from redis.asyncio import Redis
 
+from app.ws.expiring_presence import ExpiringPresenceSet
+
 
 class FocusPresence:
     """Cross-instance "is this desktop-mode user's window currently
     unfocused," used only to widen desktop_notification/push eligibility
-    beyond plain room-connection state (#59). A Redis hash (field =
-    user_id, value = refcount of that user's currently-blurred desktop
-    connections), parallel to Presence/GlobalPresence.
+    beyond plain room-connection state (#59). One expiring entry per
+    currently-blurred desktop connection (see ExpiringPresenceSet),
+    parallel to Presence/GlobalPresence.
 
-    Absence from this hash is the default and means "focused." That default
+    Absence from the set is the default and means "focused." That default
     is also exactly right for every browser-tab connection: only the
     desktop client ever sends focus/blur frames at all (see chat.py's
     "focus" envelope handling), so a browser user never appears here --
     their attention is already fully captured by Presence's room-connection
     state, which stays visibility-gated with no separate focus signal.
 
-    Refcounted for the same multi-connection reason as Presence/
-    GlobalPresence, with the same known simplification: two desktop windows
-    for one user, one focused and one blurred, count as "unfocused" here
-    (refcount > 0) even though the user does have attention somewhere. That
-    errs toward notifying rather than silently missing one, which is the
-    safer failure mode for a notification.
+    Same known simplification as before: two desktop windows for one user,
+    one focused and one blurred, count as "unfocused" (any live blurred
+    entry) even though the user does have attention somewhere. That errs
+    toward notifying rather than silently missing one, which is the safer
+    failure mode for a notification. Entries expire (#77) -- a desktop
+    window that died while blurred used to leave its user "unfocused"
+    forever.
     """
 
-    def __init__(self, redis: Redis) -> None:
-        self._redis = redis
+    KEY = "presence:v2:unfocused"
 
-    def _key(self) -> str:
-        return "presence:unfocused"
+    def __init__(self, redis: Redis, store: ExpiringPresenceSet | None = None) -> None:
+        self._store = store or ExpiringPresenceSet(redis)
 
-    async def mark_blurred(self, user_id: uuid.UUID) -> None:
-        await self._redis.hincrby(self._key(), str(user_id), 1)
+    async def mark_blurred(self, user_id: uuid.UUID, conn_id: str) -> None:
+        await self._store.add(self.KEY, user_id, conn_id)
 
-    async def mark_focused(self, user_id: uuid.UUID) -> None:
-        key = self._key()
-        field = str(user_id)
-        remaining = await self._redis.hincrby(key, field, -1)
-        if remaining <= 0:
-            await self._redis.hdel(key, field)
+    async def mark_focused(self, user_id: uuid.UUID, conn_id: str) -> None:
+        await self._store.remove(self.KEY, user_id, conn_id)
+
+    async def refresh(self, user_id: uuid.UUID, conn_id: str) -> None:
+        await self._store.add(self.KEY, user_id, conn_id)
 
     async def is_unfocused(self, user_id: uuid.UUID) -> bool:
-        return await self._redis.hexists(self._key(), str(user_id))
+        return await self._store.is_live(self.KEY, user_id)

backend/app/ws/global_presence.py

@@ -2,50 +2,55 @@ import uuid
 
 from redis.asyncio import Redis
 
+from app.ws.expiring_presence import ExpiringPresenceSet
+
 
 class GlobalPresence:
     """Cross-instance "does this user have the app open at all right now,"
     independent of which (if any) room they currently have open -- backing
     the online/offline presence dot shown wherever a user's avatar renders.
-    A single Redis hash (field = user_id, value = connection refcount),
-    parallel to but separate from Presence's per-room hashes.
 
-    Refcounted for the same reason as Presence: multiple tabs/instances for
-    one user shouldn't flip them offline until the last connection closes.
+    Each connection has its own expiring entry (see ExpiringPresenceSet), so
+    a user with several tabs/devices stays online until the last one goes,
+    and a connection that dies without cleaning up ages out instead of
+    leaving them online forever (#77). The key is versioned (`v2`) because
+    the old refcount hash lives at `presence:global` and its leaked counts
+    must not be read as live entries.
     """
 
-    def __init__(self, redis: Redis) -> None:
-        self._redis = redis
+    KEY = "presence:v2:global"
 
-    def _key(self) -> str:
-        return "presence:global"
+    def __init__(self, redis: Redis, store: ExpiringPresenceSet | None = None) -> None:
+        self._store = store or ExpiringPresenceSet(redis)
 
-    async def connect(self, user_id: uuid.UUID) -> bool:
-        """Returns True iff this was the user's first open connection --
-        a genuine offline->online transition worth telling anyone about."""
-        count = await self._redis.hincrby(self._key(), str(user_id), 1)
-        return count == 1
+    async def connect(self, user_id: uuid.UUID, conn_id: str) -> bool:
+        """Returns True iff this made the user newly online -- a genuine
+        offline->online transition worth telling anyone about."""
+        return await self._store.add(self.KEY, user_id, conn_id)
 
-    async def disconnect(self, user_id: uuid.UUID) -> bool:
-        """Returns True iff this was the user's last open connection -- a
+    async def refresh(self, user_id: uuid.UUID, conn_id: str) -> bool:
+        """Heartbeat. Same as connect() on purpose: a connection whose entry
+        had already expired (a long stall) comes back online here, and the
+        caller needs to announce that exactly like a fresh connect."""
+        return await self._store.add(self.KEY, user_id, conn_id)
+
+    async def disconnect(self, user_id: uuid.UUID, conn_id: str) -> bool:
+        """Returns True iff that was the user's last live connection -- a
         genuine online->offline transition."""
-        key = self._key()
-        field = str(user_id)
-        remaining = await self._redis.hincrby(key, field, -1)
-        if remaining <= 0:
-            await self._redis.hdel(key, field)
-            return True
-        return False
+        return await self._store.remove(self.KEY, user_id, conn_id)
+
+    async def sweep(self) -> set[uuid.UUID]:
+        """Drops expired entries and returns the users that went offline as a
+        result -- the transitions no disconnect ever reported."""
+        return await self._store.prune(self.KEY)
 
     async def is_online(self, user_id: uuid.UUID) -> bool:
-        return await self._redis.hexists(self._key(), str(user_id))
+        return await self._store.is_live(self.KEY, user_id)
 
     async def online_user_ids(self, user_ids: list[uuid.UUID]) -> set[uuid.UUID]:
         if not user_ids:
             return set()
-        values = await self._redis.hmget(self._key(), [str(u) for u in user_ids])
-        return {uid for uid, v in zip(user_ids, values) if v is not None}
+        return set(user_ids) & await self._store.live_user_ids(self.KEY)
 
     async def all_online_user_ids(self) -> set[uuid.UUID]:
-        fields = await self._redis.hkeys(self._key())
-        return {uuid.UUID(f) for f in fields}
+        return await self._store.live_user_ids(self.KEY)

backend/app/ws/presence.py

@@ -2,38 +2,40 @@ import uuid
 
 from redis.asyncio import Redis
 
+from app.ws.expiring_presence import ExpiringPresenceSet
+
 
 class Presence:
-    """Cross-instance "who's connected to this room," backed by a Redis hash
-    per room (field = user_id, value = connection refcount).
+    """Cross-instance "who's connected to this room," one expiring set per
+    room (see ExpiringPresenceSet).
 
-    Refcounted rather than a plain set so a user with two connections to the
-    same room -- two tabs, or one per app instance -- doesn't get marked
-    offline when only one of those connections closes.
-
-    Known limitation: a hard crash (not a clean disconnect) leaks that
-    connection's increment forever, since there's no heartbeat/TTL here to
-    reclaim it -- out of scope for this phase, same category of
-    simplification as the "no server-side session revocation" note in the
-    README.
+    This is what the offline-push check reads, so a leaked entry used to mean
+    a user who'd gone away was still treated as "watching the room" and never
+    got a push notification (#77). Entries now expire unless the connection
+    keeps renewing them, so that can't outlive a dead connection by more than
+    the TTL. Keys are versioned (`v2`) so the old refcount hashes
+    (`presence:{room_id}`), with whatever they leaked, are never read.
     """
 
-    def __init__(self, redis: Redis) -> None:
-        self._redis = redis
+    def __init__(self, redis: Redis, store: ExpiringPresenceSet | None = None) -> None:
+        self._store = store or ExpiringPresenceSet(redis)
 
     def _key(self, room_id: uuid.UUID) -> str:
-        return f"presence:{room_id}"
+        return f"presence:v2:room:{room_id}"
 
-    async def join(self, room_id: uuid.UUID, user_id: uuid.UUID) -> None:
-        await self._redis.hincrby(self._key(room_id), str(user_id), 1)
-
-    async def leave(self, room_id: uuid.UUID, user_id: uuid.UUID) -> None:
+    async def join(self, room_id: uuid.UUID, user_id: uuid.UUID, conn_id: str) -> None:
         key = self._key(room_id)
-        field = str(user_id)
-        remaining = await self._redis.hincrby(key, field, -1)
-        if remaining <= 0:
-            await self._redis.hdel(key, field)
+        # Per-room offline transitions aren't broadcast anywhere, so unlike
+        # the global key there's nothing to lose by pruning here -- it just
+        # keeps a busy room's set from accumulating expired entries.
+        await self._store.prune(key)
+        await self._store.add(key, user_id, conn_id)
+
+    async def refresh(self, room_id: uuid.UUID, user_id: uuid.UUID, conn_id: str) -> None:
+        await self._store.add(self._key(room_id), user_id, conn_id)
+
+    async def leave(self, room_id: uuid.UUID, user_id: uuid.UUID, conn_id: str) -> None:
+        await self._store.remove(self._key(room_id), user_id, conn_id)
 
     async def connected_user_ids(self, room_id: uuid.UUID) -> set[uuid.UUID]:
-        fields = await self._redis.hkeys(self._key(room_id))
-        return {uuid.UUID(f) for f in fields}
+        return await self._store.live_user_ids(self._key(room_id))

backend/app/ws/presence_sweeper.py

@@ -0,0 +1,83 @@
+import asyncio
+import logging
+import uuid
+from collections.abc import Callable
+
+from redis.asyncio import Redis
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.message_events import broadcast_dm_presence_update, broadcast_member_updated
+from app.ws.broadcaster import Broadcaster
+from app.ws.global_presence import GlobalPresence
+
+logger = logging.getLogger(__name__)
+
+PRESENCE_SWEEP_INTERVAL_SECONDS = 15
+SWEEP_LOCK_KEY = "presence:v2:sweeper-lock"
+
+
+async def sweep_once(
+    redis: Redis,
+    global_presence: GlobalPresence,
+    broadcaster: Broadcaster,
+    session_factory: Callable[[], AsyncSession],
+    lock_seconds: int | None = max(1, PRESENCE_SWEEP_INTERVAL_SECONDS - 1),
+) -> set[uuid.UUID]:
+    """Expires dead connections' presence entries and tells everyone about
+    the users that went offline as a result.
+
+    A clean disconnect broadcasts its own offline transition (chat.py), but a
+    connection that just stops being renewed has no such event -- this is the
+    only thing that notices. Every app worker runs this loop; the Redis lock
+    makes it one sweep per interval across the whole deployment rather than
+    N workers each doing (and broadcasting) the same thing. `lock_seconds=None`
+    skips the lock (tests).
+    """
+    if lock_seconds is not None and not await redis.set(SWEEP_LOCK_KEY, "1", nx=True, ex=lock_seconds):
+        return set()
+    went_offline = await global_presence.sweep()
+    for user_id in went_offline:
+        # One user's failed broadcast must not cost everyone after them
+        # theirs -- their entry is already gone, so this is the only chance.
+        try:
+            async with session_factory() as db:
+                await broadcast_member_updated(db, broadcaster, user_id)
+                await broadcast_dm_presence_update(db, broadcaster, user_id, online=False)
+        except Exception:
+            logger.error("Failed to broadcast offline for %s", user_id, exc_info=True)
+    return went_offline
+
+
+async def run_presence_sweeper(app, interval: float = PRESENCE_SWEEP_INTERVAL_SECONDS) -> None:
+    # Same lesson as Broadcaster.run_forever (#76): a background task that
+    # dies on its first error does so silently, and here that would quietly
+    # bring the stuck-online bug back.
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            await sweep_once(
+                app.state.redis,
+                app.state.global_presence,
+                app.state.broadcaster,
+                app.state.session_factory,
+                lock_seconds=max(1, int(interval) - 1),
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.error("Presence sweep failed", exc_info=True)
+
+
+async def purge_legacy_presence(redis: Redis) -> int:
+    """Deletes the old refcount hashes (`presence:global`, `presence:unfocused`,
+    `presence:{room_id}`). Nothing reads them any more -- the live data is
+    under `presence:v2:` -- and they hold whatever counts leaked before #77,
+    so there's nothing worth keeping. Safe to run on every startup."""
+    deleted = 0
+    async for key in redis.scan_iter("presence:*"):
+        name = key.decode() if isinstance(key, bytes) else key
+        if name.startswith("presence:v2:"):
+            continue
+        await redis.delete(name)
+        deleted += 1
+    return deleted

backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ds-chat"
-version = "2026.10.2"
+version = "2026.10.22"
 description = "DS Chat backend service"
 license = { text = "AGPL-3.0-or-later" }
 requires-python = ">=3.11"

backend/tests/test_expiring_presence.py

@@ -0,0 +1,155 @@
+import os
+import time
+import uuid
+
+import pytest_asyncio
+from redis.asyncio import Redis
+
+from app.ws.expiring_presence import ExpiringPresenceSet
+
+
+class Clock:
+    def __init__(self) -> None:
+        self.now = time.time()
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+@pytest_asyncio.fixture
+async def redis_client():
+    client = Redis.from_url(os.environ["REDIS_URL"], decode_responses=True)
+    yield client
+    await client.aclose()
+
+
+@pytest_asyncio.fixture
+async def setup(redis_client):
+    clock = Clock()
+    store = ExpiringPresenceSet(redis_client, ttl_seconds=90, clock=clock)
+    key = f"presence:v2:test:{uuid.uuid4()}"
+    yield store, clock, key
+    await redis_client.delete(key)
+
+
+async def test_first_connection_is_a_transition_and_a_second_is_not(setup):
+    store, _, key = setup
+    user = uuid.uuid4()
+    assert await store.add(key, user, "tab1") is True
+    assert await store.add(key, user, "tab2") is False
+    assert await store.live_user_ids(key) == {user}
+
+
+async def test_renewing_a_live_entry_is_not_a_transition(setup):
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    clock.advance(30)
+    assert await store.add(key, user, "tab1") is False
+
+
+async def test_entry_stops_counting_after_the_ttl(setup):
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    clock.advance(89)
+    assert await store.is_live(key, user) is True
+    clock.advance(2)
+    assert await store.is_live(key, user) is False
+    assert await store.live_user_ids(key) == set()
+
+
+async def test_renewal_keeps_a_connection_alive_past_the_original_expiry(setup):
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    for _ in range(5):
+        clock.advance(60)
+        await store.add(key, user, "tab1")
+    assert await store.is_live(key, user) is True
+
+
+async def test_coming_back_after_expiry_is_a_transition_again(setup):
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    clock.advance(200)
+    assert await store.add(key, user, "tab1") is True
+
+
+async def test_one_live_connection_keeps_the_user_online_when_another_expires(setup):
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "old-tab")
+    clock.advance(60)
+    await store.add(key, user, "new-tab")
+    clock.advance(60)  # old-tab is now 120s stale, new-tab 60s
+    assert await store.is_live(key, user) is True
+
+
+async def test_remove_reports_only_the_last_connection_leaving(setup):
+    store, _, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    await store.add(key, user, "tab2")
+    assert await store.remove(key, user, "tab1") is False
+    assert await store.remove(key, user, "tab2") is True
+
+
+async def test_remove_of_an_entry_that_is_already_gone_reports_nothing(setup):
+    # Whoever removed it first (e.g. prune) already reported the transition.
+    store, _, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    await store.remove(key, user, "tab1")
+    assert await store.remove(key, user, "tab1") is False
+
+
+async def test_remove_of_an_expired_but_unpruned_entry_still_reports_offline(setup):
+    # Nobody has been told this user went offline yet (no prune has run), so
+    # their eventual clean close is the one place left to report it.
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    clock.advance(200)
+    assert await store.remove(key, user, "tab1") is True
+
+
+async def test_users_are_independent(setup):
+    store, _, key = setup
+    alice, bob = uuid.uuid4(), uuid.uuid4()
+    await store.add(key, alice, "a")
+    await store.add(key, bob, "b")
+    await store.remove(key, alice, "a")
+    assert await store.live_user_ids(key) == {bob}
+
+
+async def test_prune_reports_users_who_lost_their_last_live_entry(setup):
+    store, clock, key = setup
+    gone, still_here = uuid.uuid4(), uuid.uuid4()
+    await store.add(key, gone, "tab1")
+    await store.add(key, still_here, "old")
+    clock.advance(60)
+    await store.add(key, still_here, "new")
+    clock.advance(40)  # gone/tab1 and still_here/old are expired; still_here/new is not
+    assert await store.prune(key) == {gone}
+
+
+async def test_prune_is_idempotent_and_removes_what_it_reports(setup):
+    store, clock, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    clock.advance(200)
+    assert await store.prune(key) == {user}
+    assert await store.prune(key) == set()
+
+
+async def test_prune_with_nothing_expired_does_nothing(setup):
+    store, _, key = setup
+    user = uuid.uuid4()
+    await store.add(key, user, "tab1")
+    assert await store.prune(key) == set()
+    assert await store.is_live(key, user) is True

backend/tests/test_presence.py

@@ -130,3 +130,108 @@ def test_online_users_endpoint_respects_appear_offline(ws_client):
 
     online = ws_client.get("/api/users/online").json()
     assert alice["id"] not in online
+
+
+# --- #77: liveness -----------------------------------------------------------
+# A connection that stops answering the app-level heartbeat is dropped by the
+# server, and a connection that does answer keeps its presence entry renewed.
+# Timings are shrunk so nothing here waits on the real 30s/90s values.
+
+
+def _fast_heartbeat(monkeypatch):
+    monkeypatch.setattr("app.ws.chat.WS_PING_INTERVAL_SECONDS", 0.05)
+    monkeypatch.setattr("app.ws.chat.WS_DEAD_AFTER_SECONDS", 0.2)
+    monkeypatch.setattr("app.ws.chat.PRESENCE_REFRESH_MIN_INTERVAL_SECONDS", 0)
+
+
+def test_unresponsive_client_is_disconnected_by_the_server(ws_client, monkeypatch):
+    # The frozen-page / sleeping-laptop case: the transport stays open (the
+    # browser answers protocol pings itself) but the page never replies to
+    # the app-level ping.
+    from starlette.websockets import WebSocketDisconnect
+
+    _fast_heartbeat(monkeypatch)
+    _register_ws(ws_client, _unique("alice"))
+
+    with ws_client.websocket_connect("/ws/chat") as ws:
+        pings = 0
+        try:
+            while True:
+                assert ws.receive_json() == {"type": "ping"}
+                pings += 1
+                assert pings < 100, "server never gave up on a silent client"
+        except WebSocketDisconnect as exc:
+            assert exc.code == 4408
+        assert pings >= 2
+
+
+def test_client_that_answers_pings_is_not_disconnected(ws_client, monkeypatch):
+    _fast_heartbeat(monkeypatch)
+    _register_ws(ws_client, _unique("alice"))
+    room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
+
+    with ws_client.websocket_connect("/ws/chat") as ws:
+        # Far longer than WS_DEAD_AFTER_SECONDS in total.
+        for _ in range(12):
+            assert ws.receive_json() == {"type": "ping"}
+            ws.send_json({"type": "pong"})
+        ws.send_json({"type": "join", "room_id": room["id"]})
+        while (msg := ws.receive_json())["type"] == "ping":
+            pass
+        assert msg == {"type": "joined", "room_id": room["id"]}
+
+
+def test_bot_connection_is_not_dropped_for_ignoring_pings(ws_client_factory, monkeypatch):
+    # API-token clients aren't expected to speak the app heartbeat.
+    _fast_heartbeat(monkeypatch)
+    ws_client = ws_client_factory()
+    admin = _register_ws(ws_client, _unique("admin"))
+
+    async def _promote():
+        from app.models import User
+
+        async with ws_client.session_factory() as session:
+            user = await session.get(User, uuid.UUID(admin["id"]))
+            user.is_site_admin = True
+            await session.commit()
+
+    ws_client.portal.call(_promote)
+    room = ws_client.post("/api/rooms", json={"name": _unique("general")}).json()
+    bot = ws_client.post("/api/admin/bots", json={"username": _unique("bot")}).json()
+    token = ws_client.post(
+        f"/api/admin/bots/{bot['id']}/tokens", json={"scopes": ["read:messages", "write:messages"]}
+    ).json()["token"]
+    ws_client.post(f"/api/rooms/{room['id']}/join", headers={"Authorization": f"Bearer {token}"})
+
+    with ws_client.websocket_connect("/ws/chat", headers={"Authorization": f"Bearer {token}"}) as ws:
+        for _ in range(8):  # ~0.4s of silence, twice WS_DEAD_AFTER_SECONDS
+            assert ws.receive_json() == {"type": "ping"}
+        ws.send_json({"type": "join", "room_id": room["id"]})
+        while (msg := ws.receive_json())["type"] == "ping":
+            pass
+        assert msg["type"] == "joined"
+
+
+def test_presence_entry_is_renewed_while_the_client_answers(ws_client, monkeypatch):
+    import time
+
+    _fast_heartbeat(monkeypatch)
+    alice = _register_ws(ws_client, _unique("alice"))
+
+    async def _scores():
+        redis = ws_client.app.state.redis
+        return await redis.zrange("presence:v2:global", 0, -1, withscores=True)
+
+    with ws_client.websocket_connect("/ws/chat") as ws:
+        # Wait for the first ping so the connect-time entry exists.
+        assert ws.receive_json() == {"type": "ping"}
+        first = [s for m, s in ws_client.portal.call(_scores) if m.startswith(alice["id"])]
+        assert len(first) == 1
+
+        time.sleep(0.1)
+        ws.send_json({"type": "pong"})
+        # Any later frame arriving back proves the pong was processed.
+        while ws.receive_json()["type"] != "ping":
+            pass
+        second = [s for m, s in ws_client.portal.call(_scores) if m.startswith(alice["id"])]
+        assert second and second[0] > first[0]

backend/tests/test_presence_sweeper.py

@@ -0,0 +1,188 @@
+import os
+import time
+import uuid
+
+import pytest_asyncio
+from redis.asyncio import Redis
+
+from app.schemas.room import RoomCreate
+from app.schemas.user import UserCreate
+from app.services.auth_service import register_user
+from app.services.room_service import create_room, find_or_create_dm
+from app.ws.expiring_presence import ExpiringPresenceSet
+from app.ws.global_presence import GlobalPresence
+from app.ws.presence_sweeper import SWEEP_LOCK_KEY, purge_legacy_presence, sweep_once
+
+
+class Clock:
+    def __init__(self) -> None:
+        self.now = time.time()
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+class FakeBroadcaster:
+    def __init__(self) -> None:
+        self.room_events: list[tuple[uuid.UUID, dict]] = []
+        self.user_events: list[tuple[uuid.UUID, dict]] = []
+
+    async def publish(self, room_id, payload):
+        self.room_events.append((room_id, payload))
+
+    async def publish_to_user(self, user_id, payload):
+        self.user_events.append((user_id, payload))
+
+
+@pytest_asyncio.fixture
+async def redis_client():
+    client = Redis.from_url(os.environ["REDIS_URL"], decode_responses=True)
+    await client.delete(GlobalPresence.KEY, SWEEP_LOCK_KEY)
+    yield client
+    await client.delete(GlobalPresence.KEY, SWEEP_LOCK_KEY)
+    await client.aclose()
+
+
+@pytest_asyncio.fixture
+async def world(redis_client, db_session):
+    clock = Clock()
+    presence = GlobalPresence(redis_client, ExpiringPresenceSet(redis_client, ttl_seconds=90, clock=clock))
+    broadcaster = FakeBroadcaster()
+
+    class _Factory:
+        def __call__(self):
+            return self
+
+        async def __aenter__(self):
+            return db_session
+
+        async def __aexit__(self, *exc):
+            return False
+
+    async def make_user(prefix: str):
+        name = f"{prefix}-{uuid.uuid4().hex[:8]}"
+        return await register_user(
+            db_session, UserCreate(username=name, email=f"{name}@example.com", password="password123")
+        )
+
+    async def sweep(**kwargs):
+        return await sweep_once(redis_client, presence, broadcaster, _Factory(), **kwargs)
+
+    return clock, presence, broadcaster, make_user, sweep
+
+
+async def test_sweep_announces_a_user_whose_connection_expired(world, db_session):
+    clock, presence, broadcaster, make_user, sweep = world
+    alice, bob = await make_user("alice"), await make_user("bob")
+    room = await create_room(db_session, alice.id, RoomCreate(name=f"r-{uuid.uuid4().hex[:8]}"))
+    dm = await find_or_create_dm(db_session, alice.id, bob.id)
+
+    await presence.connect(alice.id, "tab1")
+    clock.advance(200)
+
+    assert await sweep(lock_seconds=None) == {alice.id}
+
+    room_ids = {rid for rid, p in broadcaster.room_events if p["type"] == "member_updated"}
+    assert {room.id, dm.id} <= room_ids
+    assert (bob.id, {"type": "dm_presence_update", "user_id": str(alice.id), "status": "offline"}) in (
+        broadcaster.user_events
+    )
+    assert await presence.is_online(alice.id) is False
+
+
+async def test_sweep_announces_each_expiry_only_once(world, db_session):
+    clock, presence, broadcaster, make_user, sweep = world
+    alice = await make_user("alice")
+    await create_room(db_session, alice.id, RoomCreate(name=f"r-{uuid.uuid4().hex[:8]}"))
+    await presence.connect(alice.id, "tab1")
+    clock.advance(200)
+
+    await sweep(lock_seconds=None)
+    sent = len(broadcaster.room_events)
+    assert sent > 0
+    assert await sweep(lock_seconds=None) == set()
+    assert len(broadcaster.room_events) == sent
+
+
+async def test_sweep_stays_quiet_while_the_user_has_another_live_connection(world, db_session):
+    clock, presence, broadcaster, make_user, sweep = world
+    alice = await make_user("alice")
+    await create_room(db_session, alice.id, RoomCreate(name=f"r-{uuid.uuid4().hex[:8]}"))
+    await presence.connect(alice.id, "old-tab")
+    clock.advance(60)
+    await presence.connect(alice.id, "new-tab")
+    clock.advance(60)
+
+    assert await sweep(lock_seconds=None) == set()
+    assert broadcaster.room_events == []
+    assert await presence.is_online(alice.id) is True
+
+
+async def test_sweep_leaves_healthy_connections_alone(world, db_session):
+    clock, presence, broadcaster, make_user, sweep = world
+    alice = await make_user("alice")
+    await presence.connect(alice.id, "tab1")
+    clock.advance(30)
+    assert await sweep(lock_seconds=None) == set()
+    assert broadcaster.room_events == []
+
+
+async def test_only_one_sweeper_runs_per_interval(world, db_session, redis_client):
+    clock, presence, broadcaster, make_user, sweep = world
+    alice = await make_user("alice")
+    await presence.connect(alice.id, "tab1")
+    clock.advance(200)
+
+    # Another worker holds the lock: this one must not sweep (or broadcast).
+    await redis_client.set(SWEEP_LOCK_KEY, "1", ex=14)
+    assert await sweep(lock_seconds=14) == set()
+    assert await redis_client.zcard(GlobalPresence.KEY) == 1
+
+    await redis_client.delete(SWEEP_LOCK_KEY)
+    assert await sweep(lock_seconds=14) == {alice.id}
+    # And the lock is now held, so an immediate second attempt does nothing.
+    assert await sweep(lock_seconds=14) == set()
+
+
+async def test_one_failed_broadcast_does_not_stop_the_rest(world, db_session):
+    clock, presence, broadcaster, make_user, sweep = world
+    alice, bob = await make_user("alice"), await make_user("bob")
+    room = await create_room(db_session, alice.id, RoomCreate(name=f"r-{uuid.uuid4().hex[:8]}"))
+    other = await create_room(db_session, bob.id, RoomCreate(name=f"r-{uuid.uuid4().hex[:8]}"))
+    await presence.connect(alice.id, "a")
+    await presence.connect(bob.id, "b")
+    clock.advance(200)
+
+    real_publish = broadcaster.publish
+    failed = []
+
+    async def flaky_publish(room_id, payload):
+        if room_id == room.id:
+            failed.append(room_id)
+            raise RuntimeError("redis hiccup")
+        await real_publish(room_id, payload)
+
+    broadcaster.publish = flaky_publish
+
+    assert await sweep(lock_seconds=None) == {alice.id, bob.id}
+    assert failed == [room.id]
+    assert other.id in {rid for rid, _ in broadcaster.room_events}
+
+
+async def test_purge_removes_legacy_keys_but_keeps_v2(redis_client):
+    legacy = ["presence:global", "presence:unfocused", f"presence:{uuid.uuid4()}"]
+    current = f"presence:v2:test:{uuid.uuid4()}"
+    for key in legacy:
+        await redis_client.hset(key, "someone", 3)
+    await redis_client.zadd(current, {"x:y": time.time() + 90})
+
+    try:
+        assert await purge_legacy_presence(redis_client) >= len(legacy)
+        for key in legacy:
+            assert await redis_client.exists(key) == 0
+        assert await redis_client.exists(current) == 1
+    finally:
+        await redis_client.delete(current, *legacy)

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "2026.10.2",
+  "version": "2026.10.22",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "scripts": {

frontend/src/components/MessageList.css

@@ -40,12 +40,17 @@
 }
 
 .message-author {
+  /* Lets a very long display name shrink/wrap instead of pushing the
+     (now longer, e.g. "Yesterday 4:04 PM") timestamp out of the row. */
+  min-width: 0;
   font-size: 0.86rem;
   font-weight: 700;
   color: var(--ds-text);
 }
 
 .message-time {
+  flex: none;
+  white-space: nowrap;
   font-size: 0.68rem;
   color: var(--ds-muted);
   font-family: var(--mono);
@@ -386,6 +391,7 @@
 }
 
 .message-reaction-pills {
+  position: relative;
   display: flex;
   flex-wrap: wrap;
   gap: 4px;
@@ -425,3 +431,24 @@
   width: 100%;
   resize: vertical;
 }
+
+/* The picker anchors to the row of pills, not to this button: the button's
+   position moves right with every added reaction, and a picker hanging
+   off it ran past the edge of a phone screen. (No `position` here on
+   purpose -- .message-reaction-wrap's relative would re-anchor it.) */
+.message-reaction-add-wrap {
+  display: contents;
+}
+
+/* #78: always visible once a message has reactions, so adding to the pile
+   doesn't need the hover-row button. Same shape as the pills it sits
+   beside, kept quieter so it doesn't read as another reaction. */
+.message-reaction-add {
+  gap: 2px;
+  opacity: 0.8;
+}
+
+.message-reaction-add:hover,
+.message-reaction-add:focus-visible {
+  opacity: 1;
+}

frontend/src/components/MessageList.test.tsx

@@ -0,0 +1,122 @@
+import { cleanup, fireEvent, render, screen, within } from '@testing-library/react'
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import type { Message } from '../types'
+import { MessageList } from './MessageList'
+
+vi.mock('../context/AuthContext', () => ({
+  useAuth: () => ({ user: { id: 'u1', username: 'alice', emoji_scale: 'normal' } }),
+}))
+vi.mock('../context/CustomEmojiContext', () => ({
+  useCustomEmoji: () => ({ byShortcode: new Map(), list: [], refresh: () => {} }),
+}))
+
+beforeAll(() => {
+  // jsdom doesn't implement it; MessageList scrolls to the bottom on mount.
+  Element.prototype.scrollIntoView = () => {}
+})
+
+afterEach(cleanup)
+
+function message(overrides: Partial<Message>): Message {
+  return {
+    id: 'm1',
+    room_id: 'r1',
+    user_id: 'u2',
+    username: 'bob',
+    content: 'hello',
+    image_id: null,
+    file: null,
+    link_preview: null,
+    reactions: [],
+    created_at: '2026-10-20T16:46:00Z',
+    edited_at: null,
+    deleted_at: null,
+    ...overrides,
+  }
+}
+
+function renderList(messages: Message[], onReact = vi.fn()) {
+  render(
+    <MessageList
+      roomId="r1"
+      messages={messages}
+      members={[]}
+      myRooms={new Map()}
+      onEdit={() => {}}
+      onReact={onReact}
+      onDelete={() => {}}
+    />,
+  )
+  return onReact
+}
+
+const reacted = [{ emoji: '🎉', count: 1, user_ids: ['u2'] }]
+
+describe('MessageList add-reaction button (#78)', () => {
+  it('shows one in the reaction row only when the message already has reactions', () => {
+    renderList([
+      message({ id: 'm1', content: 'with', reactions: reacted }),
+      message({ id: 'm2', content: 'without', reactions: [] }),
+    ])
+    const pills = document.querySelectorAll('.message-reaction-pills')
+    expect(pills).toHaveLength(1)
+    expect(within(pills[0] as HTMLElement).getByRole('button', { name: 'Add reaction' })).toBeTruthy()
+  })
+
+  it('keeps the hover-row button on every message', () => {
+    renderList([
+      message({ id: 'm1', reactions: reacted }),
+      message({ id: 'm2', content: 'plain', reactions: [] }),
+    ])
+    // Two on the reacted message (row + pills), one on the plain one.
+    expect(screen.getAllByRole('button', { name: 'Add reaction' })).toHaveLength(3)
+  })
+
+  it('opens the picker next to the pills and reacts with the pick', () => {
+    const onReact = renderList([message({ reactions: reacted })])
+    const pillsAdd = within(document.querySelector('.message-reaction-pills') as HTMLElement).getByRole(
+      'button',
+      { name: 'Add reaction' },
+    )
+    fireEvent.click(pillsAdd)
+
+    const pickers = document.querySelectorAll('.emoji-picker')
+    expect(pickers).toHaveLength(1)
+    expect(document.querySelector('.message-reaction-pills .emoji-picker')).not.toBeNull()
+
+    fireEvent.click(within(pickers[0] as HTMLElement).getAllByRole('menuitem')[0])
+    expect(onReact).toHaveBeenCalledTimes(1)
+    expect(onReact.mock.calls[0][0]).toBe('m1')
+    expect(document.querySelector('.emoji-picker')).toBeNull()
+  })
+
+  it('opens only one picker at a time, in whichever place was used last', () => {
+    renderList([message({ reactions: reacted })])
+    const [rowButton, pillsButton] = [
+      document.querySelector('.message-row-actions .message-reaction-trigger') as HTMLElement,
+      document.querySelector('.message-reaction-pills .message-reaction-add') as HTMLElement,
+    ]
+
+    fireEvent.click(pillsButton)
+    expect(document.querySelectorAll('.emoji-picker')).toHaveLength(1)
+
+    fireEvent.click(rowButton)
+    expect(document.querySelectorAll('.emoji-picker')).toHaveLength(1)
+    expect(document.querySelector('.message-row-actions .emoji-picker')).not.toBeNull()
+    expect(document.querySelector('.message-reaction-pills .emoji-picker')).toBeNull()
+  })
+
+  it('clicking the same button again closes its picker', () => {
+    renderList([message({ reactions: reacted })])
+    const pillsButton = document.querySelector('.message-reaction-pills .message-reaction-add') as HTMLElement
+    fireEvent.click(pillsButton)
+    expect(document.querySelector('.emoji-picker')).not.toBeNull()
+    fireEvent.click(pillsButton)
+    expect(document.querySelector('.emoji-picker')).toBeNull()
+  })
+
+  it('is not offered on a deleted message', () => {
+    renderList([message({ content: null, deleted_at: '2026-10-21T10:00:00Z', reactions: [] })])
+    expect(screen.queryByRole('button', { name: 'Add reaction' })).toBeNull()
+  })
+})

frontend/src/components/MessageList.tsx

@@ -1,9 +1,11 @@
-import type { CSSProperties } from 'react'
+import type { CSSProperties, MouseEvent as ReactMouseEvent } from 'react'
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { getRoomFileUrl, getRoomImageUrl } from '../api/rooms'
 import { useAuth } from '../context/AuthContext'
+import { useLocalDay } from '../hooks/useLocalDay'
 import { formatFileSize } from '../lib/fileSize'
-import { avatarUrlFor, displayNameFor, senderColorIndex, statusFor } from '../lib/messageGrouping'
+import { formatMessageTime, formatMessageTimeTitle } from '../lib/formatMessageTime'
+import { avatarUrlFor, displayNameFor, isGroupStart, senderColorIndex, statusFor } from '../lib/messageGrouping'
 import type { ChatMessageEnvelope, Message, MessageFileInfo, RoomMember } from '../types'
 import { EMOJI_PICKER_MAX_HEIGHT, EmojiPicker } from './EmojiPicker'
 import { FilePreviewModal, getPreviewKind } from './FilePreviewModal'
@@ -69,13 +71,6 @@ function FileAttachmentCard({ file, roomId, onPreview }: FileAttachmentCardProps
 // trigger a download the moment the browser tries to fetch it).
 const PLAYABLE_VIDEO_CONTENT_TYPES = new Set(['video/mp4', 'video/webm', 'video/ogg'])
 
-// #73: Slack's own threshold for the same "still grouped, but it's been a
-// while" call -- past this gap a same-sender message starts a new group
-// (its own avatar/name/timestamp) even with nobody else posting in
-// between, so a message sent minutes later doesn't hide under a stale
-// timestamp from the start of the run.
-const GROUP_BREAK_MS = 5 * 60 * 1000
-
 interface VideoAttachmentProps {
   file: MessageFileInfo
   roomId: string
@@ -134,6 +129,7 @@ export function MessageList({
   onDelete,
 }: MessageListProps) {
   const { user } = useAuth()
+  const now = useLocalDay()
   // #71: same viewer preference MessageContent applies to in-text emoji,
   // looked up separately here since a reaction pill isn't a descendant of
   // that component's wrapper div (see EmojiGlyph's own comment).
@@ -150,6 +146,10 @@ export function MessageList({
   const [lightboxSrc, setLightboxSrc] = useState<string | null>(null)
   const [videoLightbox, setVideoLightbox] = useState<{ src: string; filename: string } | null>(null)
   const [reactingId, setReactingId] = useState<string | null>(null)
+  // #78: a message has two buttons that open the same picker (the hover-row
+  // one and the one at the end of its reaction pills); this says which one
+  // the picker belongs to, so it renders next to the button that was used.
+  const [reactingFrom, setReactingFrom] = useState<'row' | 'pills'>('row')
   const [reactionPlacement, setReactionPlacement] = useState<'above' | 'below'>('below')
   const [previewFile, setPreviewFile] = useState<MessageFileInfo | null>(null)
   const memberUsernames = useMemo(() => new Set(members.map((m) => m.username)), [members])
@@ -159,6 +159,25 @@ export function MessageList({
     return member?.display_name || member?.username || 'someone'
   }
 
+  function toggleReactionPicker(
+    e: ReactMouseEvent<HTMLButtonElement>,
+    messageId: string,
+    from: 'row' | 'pills',
+  ) {
+    if (reactingId === messageId && reactingFrom === from) {
+      setReactingId(null)
+      return
+    }
+    // Flip upward when the picker wouldn't fit below the trigger -- a
+    // message near the bottom of the scrolled list otherwise opens a
+    // picker that runs off-screen and can't be used.
+    const rect = e.currentTarget.getBoundingClientRect()
+    const spaceBelow = window.innerHeight - rect.bottom
+    setReactionPlacement(spaceBelow < EMOJI_PICKER_MAX_HEIGHT ? 'above' : 'below')
+    setReactingFrom(from)
+    setReactingId(messageId)
+  }
+
   useEffect(() => {
     pinnedToBottomRef.current = true
     bottomRef.current?.scrollIntoView({ block: 'end' })
@@ -218,19 +237,15 @@ export function MessageList({
         // consecutive messages from the same sender only repeat the
         // avatar/name/timestamp header on the first one in the run --
         // applies uniformly, including to your own messages. Also breaks on
-        // a long gap (see GROUP_BREAK_MS) so a message sent well after the
-        // rest of the run still gets its own visible timestamp.
-        const isGroupStart =
-          !prev ||
-          prev.user_id !== msg.user_id ||
-          new Date(msg.created_at).getTime() - new Date(prev.created_at).getTime() > GROUP_BREAK_MS
+        // a long gap or a new calendar day -- see isGroupStart.
+        const groupStart = isGroupStart(prev, msg)
         const editing = editingId === msg.id
         const deleted = !!msg.deleted_at
 
         return (
-          <div key={msg.id} className={`message-row${isGroupStart ? ' message-row-start' : ''}`}>
+          <div key={msg.id} className={`message-row${groupStart ? ' message-row-start' : ''}`}>
             <div className="message-avatar-slot">
-              {isGroupStart && (
+              {groupStart && (
                 <UserAvatar
                   username={msg.username}
                   colorIndex={senderColorIndex(msg.username, members)}
@@ -240,11 +255,11 @@ export function MessageList({
               )}
             </div>
             <div className="message-content">
-              {isGroupStart && (
+              {groupStart && (
                 <div className="message-header">
                   <span className="message-author">{displayNameFor(msg.username, members)}</span>
-                  <span className="message-time">
-                    {new Date(msg.created_at).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}
+                  <span className="message-time" title={formatMessageTimeTitle(msg.created_at)}>
+                    {formatMessageTime(msg.created_at, now)}
                   </span>
                 </div>
               )}
@@ -329,6 +344,28 @@ export function MessageList({
                           </button>
                         )
                       })}
+                      <div className="message-reaction-add-wrap">
+                        <button
+                          type="button"
+                          className="message-reaction-pill message-reaction-add"
+                          onClick={(e) => toggleReactionPicker(e, msg.id, 'pills')}
+                          aria-label="Add reaction"
+                        >
+                          <span aria-hidden="true">+</span>
+                          <span aria-hidden="true">🙂</span>
+                        </button>
+                        {reactingId === msg.id && reactingFrom === 'pills' && (
+                          <EmojiPicker
+                            onPick={(emoji) => {
+                              onReact(msg.id, emoji)
+                              setReactingId(null)
+                            }}
+                            onClose={() => setReactingId(null)}
+                            placement={reactionPlacement}
+                            align="left"
+                          />
+                        )}
+                      </div>
                     </div>
                   )}
                 </>
@@ -340,25 +377,12 @@ export function MessageList({
                   <button
                     type="button"
                     className="message-reaction-trigger"
-                    onClick={(e) => {
-                      if (reactingId === msg.id) {
-                        setReactingId(null)
-                        return
-                      }
-                      // Flip upward when the picker wouldn't fit below the
-                      // trigger -- a message near the bottom of the
-                      // scrolled list otherwise opens a picker that runs
-                      // off-screen and can't be used.
-                      const rect = e.currentTarget.getBoundingClientRect()
-                      const spaceBelow = window.innerHeight - rect.bottom
-                      setReactionPlacement(spaceBelow < EMOJI_PICKER_MAX_HEIGHT ? 'above' : 'below')
-                      setReactingId(msg.id)
-                    }}
+                    onClick={(e) => toggleReactionPicker(e, msg.id, 'row')}
                     aria-label="Add reaction"
                   >
                     🙂
                   </button>
-                  {reactingId === msg.id && (
+                  {reactingId === msg.id && reactingFrom === 'row' && (
                     <EmojiPicker
                       onPick={(emoji) => {
                         onReact(msg.id, emoji)

frontend/src/hooks/useLocalDay.test.ts

@@ -0,0 +1,67 @@
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useLocalDay } from './useLocalDay'
+
+function setVisibility(state: 'visible' | 'hidden') {
+  Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => state })
+}
+
+describe('useLocalDay', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    setVisibility('visible')
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    // Remove the own-property override so jsdom's real getter shows through again.
+    delete (document as unknown as Record<string, unknown>).visibilityState
+  })
+
+  it('rolls over to the next day when local midnight passes', () => {
+    vi.setSystemTime(new Date(2026, 9, 9, 23, 59, 30))
+    const { result } = renderHook(() => useLocalDay())
+    expect(result.current.getDate()).toBe(9)
+
+    act(() => {
+      vi.advanceTimersByTime(60_000)
+    })
+    expect(result.current.getDate()).toBe(10)
+  })
+
+  it('refreshes when the tab becomes visible after the clock moved a day (e.g. a sleeping laptop)', () => {
+    vi.setSystemTime(new Date(2026, 9, 9, 12, 0))
+    const { result } = renderHook(() => useLocalDay())
+
+    // The clock jumps without any timer firing in between.
+    vi.setSystemTime(new Date(2026, 9, 10, 12, 0))
+    act(() => {
+      document.dispatchEvent(new Event('visibilitychange'))
+    })
+    expect(result.current.getDate()).toBe(10)
+  })
+
+  it('keeps the same value (no rerender) when visibility changes on the same day', () => {
+    vi.setSystemTime(new Date(2026, 9, 9, 12, 0))
+    const { result } = renderHook(() => useLocalDay())
+    const first = result.current
+
+    vi.setSystemTime(new Date(2026, 9, 9, 18, 0))
+    act(() => {
+      document.dispatchEvent(new Event('visibilitychange'))
+    })
+    expect(result.current).toBe(first)
+  })
+
+  it('ignores visibility changes while the tab is hidden', () => {
+    vi.setSystemTime(new Date(2026, 9, 9, 12, 0))
+    const { result } = renderHook(() => useLocalDay())
+
+    setVisibility('hidden')
+    vi.setSystemTime(new Date(2026, 9, 10, 12, 0))
+    act(() => {
+      document.dispatchEvent(new Event('visibilitychange'))
+    })
+    expect(result.current.getDate()).toBe(9)
+  })
+})

frontend/src/hooks/useLocalDay.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react'
+import { isSameLocalDay } from '../lib/formatMessageTime'
+
+function msUntilNextLocalMidnight(now: Date): number {
+  // One second past, so the timer never lands a hair before midnight.
+  const next = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1, 0, 0, 1)
+  return next.getTime() - now.getTime()
+}
+
+// A `now` that only changes when the local calendar day does -- at midnight,
+// and when a tab becomes visible again (a laptop that slept through
+// midnight). Without it, a tab left open overnight keeps showing yesterday's
+// messages as a bare "4:04 PM" until something unrelated rerenders the list.
+export function useLocalDay(): Date {
+  const [now, setNow] = useState(() => new Date())
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout>
+
+    function refresh() {
+      const current = new Date()
+      // Same state object when the day hasn't changed, so no rerender.
+      setNow((prev) => (isSameLocalDay(prev, current) ? prev : current))
+    }
+
+    function schedule() {
+      timer = setTimeout(() => {
+        refresh()
+        schedule()
+      }, msUntilNextLocalMidnight(new Date()))
+    }
+
+    function handleVisibilityChange() {
+      if (document.visibilityState === 'visible') refresh()
+    }
+
+    schedule()
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => {
+      clearTimeout(timer)
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+    }
+  }, [])
+
+  return now
+}

frontend/src/lib/formatMessageTime.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { formatMessageTime, formatMessageTimeTitle, isSameLocalDay } from './formatMessageTime'
+
+// Local-time constructors throughout, and expected text built with the same
+// locale calls the code uses -- so these hold in any timezone and any ICU
+// locale instead of hardcoding "3:00 PM".
+const NOW = new Date(2026, 9, 9, 15, 0) // Fri Oct 9 2026, 3:00 PM local
+
+const iso = (d: Date) => d.toISOString()
+const timeText = (d: Date) => d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+const weekday = (d: Date) => d.toLocaleDateString([], { weekday: 'short' })
+
+describe('formatMessageTime', () => {
+  it('shows just the time for a message sent today', () => {
+    const morning = new Date(2026, 9, 9, 8, 5)
+    expect(formatMessageTime(iso(morning), NOW)).toBe(timeText(morning))
+  })
+
+  it('prefixes "Yesterday" for yesterday', () => {
+    const d = new Date(2026, 9, 8, 23, 59)
+    expect(formatMessageTime(iso(d), NOW)).toBe(`Yesterday ${timeText(d)}`)
+  })
+
+  it('treats 11:59 PM vs 12:03 AM as different days despite being minutes apart', () => {
+    const justBeforeMidnight = new Date(2026, 9, 8, 23, 59)
+    const justAfterMidnight = new Date(2026, 9, 9, 0, 3)
+    expect(formatMessageTime(iso(justBeforeMidnight), justAfterMidnight)).toBe(
+      `Yesterday ${timeText(justBeforeMidnight)}`,
+    )
+    expect(formatMessageTime(iso(justAfterMidnight), justAfterMidnight)).toBe(timeText(justAfterMidnight))
+  })
+
+  it('uses the short weekday for 2 to 6 days ago', () => {
+    const twoDays = new Date(2026, 9, 7, 12, 0)
+    const sixDays = new Date(2026, 9, 3, 12, 0)
+    expect(formatMessageTime(iso(twoDays), NOW)).toBe(`${weekday(twoDays)} ${timeText(twoDays)}`)
+    expect(formatMessageTime(iso(sixDays), NOW)).toBe(`${weekday(sixDays)} ${timeText(sixDays)}`)
+  })
+
+  it('switches to a month and day at 7 days, without the year when it is this year', () => {
+    const d = new Date(2026, 9, 2, 12, 0)
+    const label = formatMessageTime(iso(d), NOW)
+    expect(label).toBe(`${d.toLocaleDateString([], { month: 'short', day: 'numeric' })}, ${timeText(d)}`)
+    expect(label).not.toContain('2026')
+  })
+
+  it('adds the year for a message from a different year', () => {
+    const d = new Date(2025, 11, 25, 9, 30)
+    const label = formatMessageTime(iso(d), NOW)
+    expect(label).toBe(
+      `${d.toLocaleDateString([], { month: 'short', day: 'numeric', year: 'numeric' })}, ${timeText(d)}`,
+    )
+    expect(label).toContain('2025')
+  })
+
+  it('counts Dec 31 -> Jan 1 as yesterday', () => {
+    const d = new Date(2026, 11, 31, 22, 0)
+    expect(formatMessageTime(iso(d), new Date(2027, 0, 1, 10, 0))).toBe(`Yesterday ${timeText(d)}`)
+  })
+
+  it('treats a slightly-future timestamp (clock skew) as today', () => {
+    const tomorrow = new Date(2026, 9, 10, 9, 0)
+    expect(formatMessageTime(iso(tomorrow), NOW)).toBe(timeText(tomorrow))
+  })
+})
+
+describe('formatMessageTimeTitle', () => {
+  it('includes the full date, with the year', () => {
+    expect(formatMessageTimeTitle(iso(new Date(2026, 9, 2, 16, 4)))).toContain('2026')
+  })
+})
+
+describe('isSameLocalDay', () => {
+  it('is false across midnight and true within a day', () => {
+    expect(isSameLocalDay(new Date(2026, 9, 8, 23, 59), new Date(2026, 9, 9, 0, 1))).toBe(false)
+    expect(isSameLocalDay(new Date(2026, 9, 9, 0, 1), new Date(2026, 9, 9, 23, 59))).toBe(true)
+  })
+
+  it('accepts ISO strings as well as Dates', () => {
+    expect(isSameLocalDay(iso(new Date(2026, 9, 9, 8, 0)), new Date(2026, 9, 9, 20, 0))).toBe(true)
+  })
+})

frontend/src/lib/formatMessageTime.ts

@@ -0,0 +1,44 @@
+// "Today" is the viewer's local calendar day, so everything here goes through
+// local-time getters, never UTC.
+type DateLike = Date | string
+
+function toDate(d: DateLike): Date {
+  return d instanceof Date ? d : new Date(d)
+}
+
+// A calendar-day number, not elapsed milliseconds: built from the local
+// y/m/d via Date.UTC so a 23- or 25-hour DST day still counts as one day,
+// and 11:58 PM vs 12:01 AM (3 minutes apart) correctly counts as 1 day apart.
+function dayNumber(d: Date): number {
+  return Math.floor(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / 86_400_000)
+}
+
+export function isSameLocalDay(a: DateLike, b: DateLike): boolean {
+  return dayNumber(toDate(a)) === dayNumber(toDate(b))
+}
+
+// A bare "4:04 PM" gives no way to tell today's message from one sent last
+// week. Today stays time-only; anything older gains just enough date to
+// place it.
+export function formatMessageTime(iso: string, now: Date = new Date()): string {
+  const sent = new Date(iso)
+  const time = sent.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+  // <= 0 also covers a timestamp slightly in the future (clock skew between
+  // server and this device) -- better shown as today than as a negative age.
+  const daysAgo = dayNumber(now) - dayNumber(sent)
+  if (daysAgo <= 0) return time
+  if (daysAgo === 1) return `Yesterday ${time}`
+  // Under 7 so the weekday is never the same as today's (7 days ago would be).
+  if (daysAgo < 7) return `${sent.toLocaleDateString([], { weekday: 'short' })} ${time}`
+  const date = sent.toLocaleDateString([], {
+    month: 'short',
+    day: 'numeric',
+    year: sent.getFullYear() === now.getFullYear() ? undefined : 'numeric',
+  })
+  return `${date}, ${time}`
+}
+
+// Hover text: the one place the full, unambiguous date is always available.
+export function formatMessageTimeTitle(iso: string): string {
+  return new Date(iso).toLocaleString([], { dateStyle: 'full', timeStyle: 'short' })
+}

frontend/src/lib/messageGrouping.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { GROUP_BREAK_MS, isGroupStart } from './messageGrouping'
+
+const msg = (user: string, d: Date) => ({ user_id: user, created_at: d.toISOString() })
+
+describe('isGroupStart', () => {
+  const t = new Date(2026, 9, 9, 10, 0, 0)
+  const later = (ms: number) => new Date(t.getTime() + ms)
+
+  it('starts a group for the first message', () => {
+    expect(isGroupStart(undefined, msg('a', t))).toBe(true)
+  })
+
+  it('starts a group when the sender changes', () => {
+    expect(isGroupStart(msg('a', t), msg('b', later(1000)))).toBe(true)
+  })
+
+  it('keeps the same sender grouped within the break window', () => {
+    expect(isGroupStart(msg('a', t), msg('a', later(60_000)))).toBe(false)
+  })
+
+  it('groups at exactly the break threshold and splits just past it', () => {
+    expect(isGroupStart(msg('a', t), msg('a', later(GROUP_BREAK_MS)))).toBe(false)
+    expect(isGroupStart(msg('a', t), msg('a', later(GROUP_BREAK_MS + 1000)))).toBe(true)
+  })
+
+  it('measures the gap from the previous message, not the first in the run', () => {
+    const fourMin = 4 * 60_000
+    expect(isGroupStart(msg('a', later(fourMin)), msg('a', later(2 * fourMin)))).toBe(false)
+    expect(isGroupStart(msg('a', later(2 * fourMin)), msg('a', later(3 * fourMin)))).toBe(false)
+  })
+
+  it('starts a new group when the same sender crosses midnight, even a few minutes apart', () => {
+    const before = new Date(2026, 9, 8, 23, 58)
+    const after = new Date(2026, 9, 9, 0, 1)
+    expect(after.getTime() - before.getTime()).toBeLessThan(GROUP_BREAK_MS)
+    expect(isGroupStart(msg('a', before), msg('a', after))).toBe(true)
+  })
+})

frontend/src/lib/messageGrouping.ts

@@ -1,7 +1,31 @@
 import { getUserAvatarUrl } from '../api/users'
 import { hashIndex } from './avatar'
+import { isSameLocalDay } from './formatMessageTime'
 import type { RoomMember } from '../types'
 
+// #73: Slack's own threshold for the same "still grouped, but it's been a
+// while" call -- past this gap a same-sender message starts a new group
+// (its own avatar/name/timestamp) even with nobody else posting in
+// between, so a message sent minutes later doesn't hide under a stale
+// timestamp from the start of the run.
+export const GROUP_BREAK_MS = 5 * 60 * 1000
+
+interface Groupable {
+  user_id: string
+  created_at: string
+}
+
+// Whether `msg` gets its own avatar/name/timestamp header, vs. continuing
+// `prev`'s group. A new calendar day always breaks the group: now that
+// timestamps can carry a date, a same-sender run that crosses midnight
+// (11:58 PM, then 12:01 AM) would otherwise leave the later message under a
+// header showing the wrong day.
+export function isGroupStart(prev: Groupable | undefined, msg: Groupable): boolean {
+  if (!prev || prev.user_id !== msg.user_id) return true
+  if (new Date(msg.created_at).getTime() - new Date(prev.created_at).getTime() > GROUP_BREAK_MS) return true
+  return !isSameLocalDay(prev.created_at, msg.created_at)
+}
+
 export function senderColorIndex(username: string, members: RoomMember[]): number {
   const idx = members.findIndex((m) => m.username === username)
   if (idx >= 0) return idx