docs(stream): explain bounded delivery
Document queue limits, overflow recovery, and coalesced session wakes.
33 unmodified lines34353637383940414243444546474849505152535455565758596061626329 unmodified lines33 unmodified linesroutes: `GET /agents?session=<id>` (the tree), `GET /agents/stream` (batched events), `POST /sessions/:id/children`, `POST /sessions/:id/mail`.
The Go client decodes known agent events into `daemon.AgentEvent` before delivery to the view. Unknown event kinds are ignored. Malformed known events return a protocol error instead of supplying empty fields to the view. Tool progress uses the same typed value as the session stream.
## Stream overflow and refresh
The agents stream sends an initial empty batch after subscribing. Eachsubscriber retains at most 256 queued events or 1 MiB of encoded payload,plus one bounded batch being sent. Event payloads stay outside subscribermailboxes, and wake notifications are coalesced. Publication never waits fora client to read its socket.
When a subscriber exceeds either limit, the daemon discards queued deltas,sends `{"events":[{"type":"overflow"}]}`, and closes the stream. An event largerthan the byte limit also causes overflow. A socket that remains stalled mayclose before delivering the marker.
Overflow triggers a normal refresh. The CLIclears unfinished previews, reconnects, and reloads the authoritative treeafter subscribing. The refreshed tree removes missing agents and replacesnames, parent relationships, closed state, and running status. Replies froman older attachment cannot repopulate the view. Disconnecting releases thesubscriber's queue when its stream process stops, without waiting for anotherpublication. Drafts and pending action results survive recovery. Terminalstream failures remain visible; `ctrl+l` starts a fresh attachment.
## swarm overhead
kernel boots queue behind four slots. each boot owns only its session's composition,and each kernel's host callback captures only its routes, store handle, and session29 unmodified lines22 unmodified lines2324252627282930313233343552 unmodified lines22 unmodified linesA missing or different generation, or a sequence outside the replay window,returns a durable transcript reset. Empty keepalive batches carry the currentpair too.
Session subscribers receive coalesced wake notifications. Event payloads stayin the session's existing replay buffer; a successful frame acknowledges itscursor before another wake is issued. A subscriber's death removes its watchwithout requiring another event.
The CLI validates the whole batch before consuming it and saves both cursorvalues only after every callback succeeds. Initial attachment and a generationchange require a leading reset. Within one generation, the sequence cannotdecrease without a reset. A generation change with a reset is normal recovery.52 unmodified lines