docs(architecture): record the structured session events design [skip-ci]

[RonenMars]

The streamer drives each agent as a terminal application and recovers its state by parsing what that terminal painted, so every state we publish is the lossy inverse of something the vendor already computes.
This records the design for consuming the providers' structured streams instead, and the evidence behind it.

Doc only — no code change.

What it contains

The problem stated at the level that actually explains the bug class, with the six subsystems across the streamer and mobile that exist only to undo rendering.
The measured fragility from four live turns captured off a running streamer on 2026-08-12: randomized turn verbs, torn mid-repaint frames, absolute CSI H repaint targets, and a Codex busy state that never clears under Claude's rules.
What both providers expose instead, verified against the installed binaries rather than from documentation alone.
The normalized event model, where each of the three repos lands, and the five costs — including the one that is a product decision rather than a technical one.

Verified, not asserted

codex app-server generate-json-schema --out <dir> against codex-cli 0.147.0 emits 39 schema files and 191 definitions, including TurnStartedNotification, TurnCompletedNotification, ReasoningTextDeltaNotification, AgentMessageDeltaNotification and TurnStatus = "completed" | "interrupted" | "failed" | "inProgress", with threadId and turnId on every delta.
Claude Code hooks fire once per turn against the interactive CLI, so turn boundaries cost no architectural change, while intra-turn phase requires --print, which this server never passes.

Known limits

The doc records a screen-scraped approximation that was built and withdrawn on 2026-08-12, with the measurement that killed it: it read the rendered grid tail, which only works while the grid is shorter than roughly 46 rows, and the client seeds that grid with the replayed transcript first.
Against real captures it produced the full phase timeline at seeds of 0/20/35 lines and no transitions at all at 41/45/60/100.
It is written down so the approach is not re-attempted without that constraint in hand.

Reference

Streamer half: #535
Mobile half: RonenMars/threadbase-mobile#649
Scanner half: RonenMars/threadbase-scanner#64