feat(api): GET /api/{claims,remittances,activity}/stream + unsubscribe

Adds three live-tail streaming endpoints that emit an NDJSON snapshot
then forward new event-bus events as they arrive, with a 15s idle
heartbeat (overridable via CYCLONE_TAIL_HEARTBEAT_S for tests).

Each endpoint:
  1. yields a snapshot of existing rows as {"type":"item","data":<row>}
  2. terminates the snapshot with {"type":"snapshot_end","data":{"count":N}}
  3. subscribes to its event kind and forwards each new event as an
     {"type":"item","data":<event>} line
  4. emits a {"type":"heartbeat","data":{"ts":<iso>}} line every
     CYCLONE_TAIL_HEARTBEAT_S seconds when idle
  5. checks request.is_disconnected() before each yield and unsubscribes
     from the bus on cleanup so a closed stream releases its queue

The shared tail loop lives in api._tail_events, which polls
bus.subscribe_raw()'s queue directly instead of using the bus's
async-iterator wrapper — wait_for on an async generator cancels the
inner future on timeout, which poisons subsequent __anext__ calls with
StopAsyncIteration. Queue.get() is idempotent under cancellation, so
heartbeats don't break the subscription.

EventBus gains an unsubscribe(queue, kinds) method (idempotent) so
the tail loop can release its queue in a try/finally. The disconnect
test asserts the subscriber list is empty after the body iterator is
closed, validating no queue leak per open stream.

Tests in test_api_stream_live.py: 8 tests covering snapshot shape,
post-snapshot publish, heartbeat timing, multi-item snapshots, and
client disconnect cleanup. Plus 2 tests in test_pubsub.py for the
new unsubscribe method.

backend/src/cyclone/api.py

@@ -15,8 +15,10 @@ plus GET/POST with any header.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
+import os
 import uuid
 from contextlib import asynccontextmanager
 from typing import Any, AsyncIterator
@@ -738,6 +740,123 @@ def list_claims(
     }
 
 
+# --------------------------------------------------------------------------- #
+# Live-tail NDJSON streaming endpoints (Phase 3 — SP5)
+# --------------------------------------------------------------------------- #
+
+
+def _heartbeat_seconds() -> float:
+    """Return the configured tail heartbeat interval.
+
+    Read from ``CYCLONE_TAIL_HEARTBEAT_S`` at call time so tests can
+    monkeypatch the env var without reloading the module. Defaults to
+    15s (the production cadence); tests override to a small value (e.g.
+    0.2s) to keep their runtime bounded.
+    """
+    raw = os.environ.get("CYCLONE_TAIL_HEARTBEAT_S", "15")
+    try:
+        v = float(raw)
+    except ValueError:
+        return 15.0
+    return v if v > 0 else 15.0
+
+
+async def _tail_events(
+    request: Request, bus: EventBus, kinds: list[str]
+) -> AsyncIterator[bytes]:
+    """Forward subscribed events as ``item`` lines with periodic heartbeats.
+
+    Polls the underlying ``asyncio.Queue`` directly (via
+    :meth:`EventBus.subscribe_raw`) instead of awaiting the bus's
+    async-iterator wrapper. ``asyncio.wait_for`` cancels the inner
+    future on timeout, which would otherwise terminate the bus
+    iterator at its ``await`` point and break subsequent
+    ``__anext__`` calls with ``StopAsyncIteration``. Polling
+    ``queue.get()`` is idempotent under cancellation, so heartbeats
+    don't poison the subscription.
+
+    A ``try/finally`` unsubscribes the queue from the bus when the
+    caller disconnects or the generator is garbage collected —
+    otherwise the bus would leak one queue per open stream.
+    """
+    hb_s = _heartbeat_seconds()
+    queue, _sub = bus.subscribe_raw(kinds)
+    try:
+        while True:
+            if await request.is_disconnected():
+                return
+            get_task = asyncio.ensure_future(queue.get())
+            sleep_task = asyncio.ensure_future(asyncio.sleep(hb_s))
+            try:
+                done, pending = await asyncio.wait(
+                    {get_task, sleep_task},
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+            except BaseException:
+                get_task.cancel()
+                sleep_task.cancel()
+                raise
+            for t in pending:
+                t.cancel()
+            if get_task in done:
+                event = get_task.result()
+                yield _ndjson_line({"type": "item", "data": event})
+            else:
+                yield _ndjson_line({
+                    "type": "heartbeat",
+                    "data": {"ts": utcnow().isoformat().replace("+00:00", "Z")},
+                })
+    finally:
+        bus.unsubscribe(queue, kinds)
+
+
+@app.get("/api/claims/stream")
+async def claims_stream(
+    request: Request,
+    status: str | None = Query(None),
+    provider_npi: str | None = Query(None),
+    payer: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+    sort: str | None = Query(None),
+    order: str = Query("desc"),
+    limit: int = Query(100, ge=1, le=1000),
+) -> StreamingResponse:
+    """Stream Claims as NDJSON: snapshot first, then live events.
+
+    Wire format:
+      * ``{"type":"item","data":<claim>}`` per snapshot row, then per
+        new ``claim_written`` event
+      * ``{"type":"snapshot_end","data":{"count":N}}`` after the snapshot
+      * ``{"type":"heartbeat","data":{"ts":<iso>}}`` every
+        ``CYCLONE_TAIL_HEARTBEAT_S`` seconds when idle
+
+    Query params mirror :func:`list_claims` so a frontend can swap a
+    one-shot fetch for a tail with no URL surgery.
+
+    NOTE: registered before ``/api/claims/{claim_id}`` so the literal
+    ``stream`` path segment doesn't get matched as a claim id.
+    """
+    bus: EventBus = request.app.state.event_bus
+
+    async def gen() -> AsyncIterator[bytes]:
+        # 1. Snapshot (eager — iter_claims returns a list already).
+        rows = store.iter_claims(
+            status=status, provider_npi=provider_npi, payer=payer,
+            date_from=date_from, date_to=date_to,
+            sort=sort or "-submission_date", order=order, limit=limit,
+        )
+        for row in rows:
+            yield _ndjson_line({"type": "item", "data": row})
+        yield _ndjson_line({"type": "snapshot_end", "data": {"count": len(rows)}})
+
+        # 2. Subscribe + heartbeats.
+        async for chunk in _tail_events(request, bus, ["claim_written"]):
+            yield chunk
+
+    return StreamingResponse(gen(), media_type="application/x-ndjson")
+
+
 @app.get("/api/claims/{claim_id}")
 def get_claim_detail_endpoint(claim_id: str) -> dict:
     """Return one claim with full drawer context (SP4).
@@ -891,6 +1010,45 @@ def list_remittances(
     }
 
 
+@app.get("/api/remittances/stream")
+async def remittances_stream(
+    request: Request,
+    payer: str | None = Query(None),
+    claim_id: str | None = Query(None),
+    date_from: str | None = Query(None),
+    date_to: str | None = Query(None),
+    sort: str | None = Query(None),
+    order: str = Query("desc"),
+    limit: int = Query(100, ge=1, le=1000),
+) -> StreamingResponse:
+    """Stream Remittances as NDJSON: snapshot first, then live events.
+
+    Subscribes to ``remittance_written``. Default sort is
+    ``-received_date`` (newest-first), matching the list endpoint's
+    most common sort.
+
+    NOTE: registered before ``/api/remittances/{remittance_id}`` so
+    the literal ``stream`` path segment doesn't get matched as a
+    remittance id.
+    """
+    bus: EventBus = request.app.state.event_bus
+
+    async def gen() -> AsyncIterator[bytes]:
+        rows = store.iter_remittances(
+            payer=payer, claim_id=claim_id,
+            date_from=date_from, date_to=date_to,
+            sort=sort or "-received_date", order=order, limit=limit,
+        )
+        for row in rows:
+            yield _ndjson_line({"type": "item", "data": row})
+        yield _ndjson_line({"type": "snapshot_end", "data": {"count": len(rows)}})
+
+        async for chunk in _tail_events(request, bus, ["remittance_written"]):
+            yield chunk
+
+    return StreamingResponse(gen(), media_type="application/x-ndjson")
+
+
 @app.get("/api/remittances/{remittance_id}")
 def get_remittance(remittance_id: str) -> dict:
     """Return one remittance with its labeled CAS ``adjustments`` array.
@@ -965,6 +1123,43 @@ def list_activity(
     }
 
 
+@app.get("/api/activity/stream")
+async def activity_stream(
+    request: Request,
+    kind: str | None = Query(None),
+    since: str | None = Query(None),
+    limit: int = Query(50, ge=1, le=500),
+) -> StreamingResponse:
+    """Stream Activity events as NDJSON: snapshot first, then live events.
+
+    Subscribes to ``activity_recorded``. Default ``limit`` is 50
+    (smaller than the list endpoint's 200) because activity is
+    high-volume — callers usually want the most recent handful, not a
+    full replay.
+    """
+    bus: EventBus = request.app.state.event_bus
+
+    async def gen() -> AsyncIterator[bytes]:
+        # Snapshot reuses the same in-memory filter as ``list_activity``
+        # so the two endpoints are interchangeable for the snapshot
+        # half.
+        events = store.recent_activity(limit=limit)
+        if kind is not None:
+            events = [e for e in events if e["kind"] == kind]
+        if since is not None:
+            events = [e for e in events if e["timestamp"] >= since]
+        for ev in events:
+            yield _ndjson_line({"type": "item", "data": ev})
+        yield _ndjson_line({
+            "type": "snapshot_end", "data": {"count": len(events)},
+        })
+
+        async for chunk in _tail_events(request, bus, ["activity_recorded"]):
+            yield chunk
+
+    return StreamingResponse(gen(), media_type="application/x-ndjson")
+
+
 # --------------------------------------------------------------------------- #
 # 999 ACKs (read views)
 # --------------------------------------------------------------------------- #

backend/src/cyclone/pubsub.py

@@ -52,6 +52,49 @@ class EventBus:
             self._subscribers.setdefault(kind, []).append(queue)
         return self._iterator(queue)
 
+    def subscribe_raw(
+        self, kinds: list[str]
+    ) -> tuple[asyncio.Queue[dict], AsyncIterator[dict]]:
+        """Like :meth:`subscribe` but also returns the underlying queue.
+
+        Most consumers should use :meth:`subscribe`. The live-tail
+        endpoints use ``subscribe_raw`` so they can race
+        ``queue.get()`` against a heartbeat sleep without poisoning
+        the subscription iterator: ``asyncio.wait_for`` cancels the
+        inner future on timeout, which terminates an async generator
+        at its ``await`` point and breaks all subsequent
+        ``__anext__`` calls. Polling ``queue.get()`` directly avoids
+        that because ``Queue.get`` is idempotent under cancellation.
+
+        Callers MUST pair this with :meth:`unsubscribe` in a
+        ``try/finally`` to release the queue when the consumer
+        disconnects — otherwise the bus leaks a queue per stream.
+        """
+        queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=self._max_queue_size)
+        for kind in kinds:
+            self._subscribers.setdefault(kind, []).append(queue)
+        return queue, self._iterator(queue)
+
+    def unsubscribe(
+        self, queue: asyncio.Queue[dict], kinds: list[str]
+    ) -> None:
+        """Remove ``queue`` from each kind's subscriber list.
+
+        Idempotent: missing entries are silently ignored so callers
+        can run the cleanup in a ``finally`` without worrying about
+        double-unsubscribe on disconnect-then-GeneratorExit.
+        """
+        for kind in kinds:
+            subs = self._subscribers.get(kind)
+            if not subs:
+                continue
+            try:
+                subs.remove(queue)
+            except ValueError:
+                pass
+            if not subs:
+                self._subscribers.pop(kind, None)
+
     async def _iterator(self, queue: asyncio.Queue[dict]) -> AsyncIterator[dict]:
         while True:
             yield await queue.get()