docs(dashboard): document the ST4TS hive-wide stats tab

Adds the ST4TS tab to the strip list + a section covering the swarm
rollup, the /api/stats-hive endpoint shape, the read-only/skip-missing
aggregation, pull-on-activation, and the labelled cost estimate. Ships
with the feature (this branch / PR).
This commit is contained in:
iris 2026-06-05 22:44:20 +02:00 committed by mara
commit a8a30dd39b

View file

@ -14,7 +14,8 @@ swap.
**Chrome header** (fixed, overlays the active tab pane):
- **Tab strip**: `◆ SW4RM ◆`, `◆ Y3R C4LL ◆`, `◆ SYST3M ◆`,
`◆ P3RM1SS10NS ◆`, `◆ SCH3DUL3S ◆`, `◆ P33RS ◆` (hidden when `swarm.peers` is empty),
`◆ P3RM1SS10NS ◆`, `◆ SCH3DUL3S ◆`, `◆ ST4TS ◆`,
`◆ P33RS ◆` (hidden when `swarm.peers` is empty),
`◆ M4TR1X ◆ →` (optional page link, see below), `◆ FL0W ◆ →`
(page link), and `◆ S3TT1NGS ◆`. Count pills on SW4RM (container
count), Y3R C4LL (pending approvals + questions), and SCH3DUL3S
@ -282,6 +283,36 @@ attribute; a shared 1s ticker rewrites it in-place — showing
`overdue X ago` once the deadline passes — without triggering a
full re-render of the list.
## ST4TS tab
Hive-wide turn statistics, aggregated across every agent's
`hyperhive-turn-stats.sqlite` for the selected window. Distinct from
each agent's own `/stats` page (which carries the per-agent trend
charts): ST4TS is the swarm-level rollup.
- **Window selector** (`1h``30d`) re-fetches on change.
- **Summary chips**: active agents, turns, total/input/output/cache-read
tokens, and a labelled **est cost**.
- **Busiest agents** table — one row per agent (most turns first):
turns, input / output / cache-read tokens, est cost.
- **Model mix** — turns per model across the swarm, as CSS bars.
Backed by `GET /api/stats-hive?window=<w>` in `hive-c0re`
(`hive_stats.rs`): for every name from
`Coordinator::kept_state_names()` it opens
`agent_harness_dir(name)/hyperhive-turn-stats.sqlite` read-only (with a
500 ms `busy_timeout`, since `turn_stats` is rollback-journal) and rolls
the rows up — missing / unreadable / zero-turn dbs are skipped so one
bad db never fails the endpoint. This is a **pull** surface (no SSE):
the data is fetched on tab activation and on window change. Rendered
with plain tables + CSS bars — the dashboard bundle ships no chart
library.
The cost figure is a deliberately rough estimate from an approximate
per-model price table (`est_cost_usd`); it drifts with list pricing and
is labelled accordingly. (A follow-up can move the table to a nix
option so it's operator-tunable.)
## P33RS tab
Peer hives in this swarm. The tab is hidden when the