Realtime SSE

Each repository and branch room has a text/event-stream endpoint at its /events suffix. Authenticate with the normal bearer header.

Resume contract

The durable message cursor appears as the SSE id. Reconnect by sending it in Last-Event-ID. A cursor query parameter is also accepted by the API, but header-based resume avoids putting cursor material in loggable URLs. Do not send both forms with conflicting values.

curl --no-buffer --fail-with-body \
  --header 'Accept: text/event-stream' \
  --header 'Authorization: Bearer <REDACTED_CHAT_BEARER>' \
  --header 'Last-Event-ID: <OPAQUE_MESSAGE_CURSOR>' \
  'https://<CHAT_API_HOST>/v1/repositories/<REPOSITORY_ULID>/room/events'

Event	id	Meaning
message	Durable cursor	data is the REST MessageResponse; persist the cursor only after processing succeeds
heartbeat	none	Liveness signal with server time; never advances resume state
handoff	none	Planned server rotation; reconnect from the last durable message cursor
reauthorize	none	Access changed or authorization could not be confirmed; refresh/re-evaluate before reconnecting

Failure and recovery

Streams close before the current grant expires and core authorization is periodically rechecked. On permission loss or authorization outage, the server sends reauthorize and closes. A healthy stream sends handoff with reason stream_rotation before its planned server-side rotation; reconnect using the same cursor contract. Lag, replay overflow, source reset, shutdown, and handoff failure close without inventing a cursor.

Use bounded exponential backoff with jitter. Resume only from the last fully processed message ID. If no cursor was processed, reconnect without one and allow durable replay. Never infer success from a heartbeat and never skip forward after a terminal transport error.

Listener-first handoff, durable replay, overlap suppression, and a snapshot high-water barrier ensure total order across reconnect and multi-instance delivery. Consumers still must be idempotent because a reconnect can replay the last processed event when local cursor persistence races a crash.