docs(dashboard): document memory/disk pressure banner and /api/status resource blocks (NS-656)

Covers the advisory memory and disk blocks added to GET /api/status in
#84965 (thresholds, staleness handling, fail-safe degradation) and the
dashboard resource-pressure banner (trigger precedence, boot-scoped
dismissals).
This commit is contained in:
Teknium
2026-08-13 20:32:52 -07:00
parent 9c15f0191c
commit 44bdcf3a30
@@ -105,6 +105,26 @@ The landing page shows a live overview of your installation:
The status page auto-refreshes every 5 seconds.
#### Resource pressure banner
When the host is running low on memory or disk, a banner appears at the top of
the dashboard (fed by the same status poll — no extra requests):
- **"Your agent is almost out of memory and may restart"** — system available
memory has dropped to *elevated* (< 128 MiB or < 15%) or *critical*
(< 64 MiB or < 5%) levels, as sampled by the gateway's 30-second heartbeat.
- **"Your agent restarted unexpectedly, most likely because it ran out of
memory"** — the lifecycle ledger recorded an unclean exit under memory
pressure on the previous boot (a suspected OOM kill).
- **Disk warnings** — the volume holding `~/.hermes` is nearly full
(*elevated* below 512 MB free, *critical* below 256 MB free).
Only the most severe active warning shows at a time (disk critical > memory
critical > OOM restart > disk elevated > memory elevated). Dismissals are
scoped to the current gateway boot: dismissing a warning surfaces the next
active one, a gateway restart or an escalation (elevated → critical) re-opens
it, and a stale heartbeat renders nothing rather than a spurious alert.
### Chat
The **Chat** tab embeds the full Hermes TUI (the same interface you get from `hermes --tui`) directly in the browser. Everything you can do in the terminal TUI — slash commands, model picker, tool-call cards, markdown streaming, clarify/sudo/approval prompts, skin theming — works identically here, because the dashboard is running the real TUI binary and rendering its ANSI output through [xterm.js](https://xtermjs.org/) with its WebGL renderer for pixel-perfect cell layout.
@@ -415,6 +435,29 @@ a chat under the selected profile.
Returns agent version, gateway status, platform states, and active session count.
The response also carries two advisory resource blocks (they never affect the
`components`/`overall` health verdict):
- **`memory`** — distilled from the gateway's 30-second heartbeat and the
lifecycle ledger. Fields: `pressure` (`ok` / `elevated` / `critical` /
`unknown`), `gateway_rss_mb`, `system_total_mb`, `system_available_mb`,
`swap_used_mb`, `sampled_at`, `boot_id`, `last_boot_unclean`,
`last_boot_suspected_oom`. Pressure is `elevated` below 128 MiB (or 15%) of
available system memory and `critical` below 64 MiB (or 5%) — the same
levels at which a subsequent unclean exit would be flagged as a suspected
OOM kill. Heartbeats older than 150 seconds (or future-dated) keep their
numbers but degrade `pressure` to `unknown`, so a dead gateway's last
sample can't masquerade as a live reading.
- **`disk`** — a live `shutil.disk_usage()` sample of the volume holding
`~/.hermes`. Fields: `pressure`, `free_mb`, `total_mb`, `used_percent`,
`sampled_at`. Pressure is `elevated` below 512 MB free (or ≥85% used with
under 4 GB headroom) and `critical` below 256 MB free (or ≥95% used with
under 1 GB headroom).
Both collectors are fail-safe: any sampling error degrades the block to
`{"pressure": "unknown"}` instead of failing the status endpoint. The numbers
are coarse (whole MB, whole-percent) since `/api/status` is public.
### GET /api/sessions
Returns the 20 most recent sessions with metadata (model, token counts, timestamps, preview).