From 04e67aaa034676c1bef13e0e7876787a2b24d987 Mon Sep 17 00:00:00 2001
From: lexis <lexis@hyperhive>
Date: Tue, 26 May 2026 00:07:00 +0200
Subject: [PATCH] docs: add running field to get_agent_meta, document
 stopped-container display (follow-up to #433)

---
 docs/turn-loop.md | 11 ++++++++---
 docs/web-ui.md    | 50 +++++++++++++++++++++++++++++------------------
 2 files changed, 39 insertions(+), 22 deletions(-)

diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index db0aca0e..d137c673 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -227,12 +227,17 @@ it as a stdio child via `--mcp-config`. The hyperhive socket name is
   `{state_dir}/hyperhive-status`; survives harness restarts. Pass
   an empty string to clear.
 - `get_agent_meta(name?)` — fetch identity + status metadata for
-  an agent: `{ name, role, hyperhive_rev, status_text,
+  an agent: `{ name, role, hyperhive_rev, running, status_text,
   status_set_at }`. Pass `name` to query a peer (e.g. check
   whether a sub-agent is idle before sending it work). Omit
   `name` to get your own identity stamp — replaces the previous
-  `whoami` tool. Status fields are `None` when the target has
-  never called `set_status` or has cleared it.
+  `whoami` tool. `running` is `true` when the container is up.
+  When `running` is `false` the host clears live-only sentinel
+  fields (`status_text`, `status_set_at`, `needs_login`,
+  `rate_limited`, `ctx_tokens`) before serving the response, so
+  stale on-disk state never reaches the caller. Status fields are
+  also `None` when the target has never called `set_status` or
+  has cleared it.
 - `request_next_turn()` — ask the harness to start another turn
   immediately after this one ends, even if the inbox is empty. Use for
   multi-turn tasks (long builds, sequential steps) where you want to
diff --git a/docs/web-ui.md b/docs/web-ui.md
index 78f55e7f..a54d2de9 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -254,25 +254,37 @@ guess from container state.
   the single source of truth. The frontend resolves each
   `AgentLink.kind` (`container` → `http://host:<container.port>`,
   `forge` → `http://host:3000`, `external` → already absolute).
-  Status badges follow — `⊘ rate limited` (red, while the harness
-  is parked after a 429), `needs login`, `needs update` — in-flight
-  `◐ pending-state…` pill (replaces buttons during operator-initiated
-  start / stop / restart / rebuild / destroy). Additionally, when a
-  rebuild-queue entry for this agent is `queued` or `running` but no
-  operator-initiated transient is set, the card surfaces a `building…` /
-  `meta-updating…` badge sourced from `rebuildQueueState` (#398) —
-  so the SW4RM tab shows the same rebuild progress visible on the
-  SYST3M tab's R3BU1LD QU3U3. Container name + port, and a
-  `ctx · Nk` chip showing the agent's last-turn context size
-  (from `ContainerView.ctx_tokens`, read from the turn-stats
-  sqlite on each `build_all` sweep; absent until the first turn).
-  The chip colour (green / yellow / red) is keyed off the model's
-  real context window: `build_all` resolves the last turn's model
-  against the host's per-model `contextWindowTokens` config and
-  exposes it as `ContainerView.context_window_tokens`; the badge
-  goes yellow ≥ 50% and red ≥ 75% of that window (the harness
-  compaction watermarks). When the window can't be resolved the
-  badge falls back to fixed 100k / 150k thresholds. (issue #66)
+  **When the container is stopped** (`ContainerView.running = false`),
+  the host clears live-only fields before emitting the state, so
+  the dashboard never renders stale data: the badge chain is
+  replaced by a single muted `■ not running` badge, the nav-strip
+  fetch is skipped (the agent web server is down), and the
+  self-reported status text is suppressed. The agent icon goes
+  straight to the dimmed `/favicon.svg` fallback instead of
+  attempting a doomed load from the container's URL. Static fields
+  — `needs_update`, `deployed_sha`, `pending_reminders`, `parent`,
+  `config` link — remain visible regardless of run state.
+  When the container is running, status badges follow — `⊘ rate
+  limited` (red, while the harness is parked after a 429), `needs
+  login`, `needs update` — in-flight `◐ pending-state…` pill
+  (replaces buttons during operator-initiated start / stop /
+  restart / rebuild / destroy). Additionally, when a rebuild-queue
+  entry for this agent is `queued` or `running` but no
+  operator-initiated transient is set, the card surfaces a
+  `building…` / `meta-updating…` badge sourced from
+  `rebuildQueueState` (#398) — so the SW4RM tab shows the same
+  rebuild progress visible on the SYST3M tab's R3BU1LD QU3U3.
+  Container name + port, and a `ctx · Nk` chip showing the
+  agent's last-turn context size (from `ContainerView.ctx_tokens`,
+  read from the turn-stats sqlite on each `build_all` sweep;
+  absent until the first turn). The chip colour (green / yellow /
+  red) is keyed off the model's real context window: `build_all`
+  resolves the last turn's model against the host's per-model
+  `contextWindowTokens` config and exposes it as
+  `ContainerView.context_window_tokens`; the badge goes yellow
+  ≥ 50% and red ≥ 75% of that window (the harness compaction
+  watermarks). When the window can't be resolved the badge falls
+  back to fixed 100k / 150k thresholds. (issue #66)
 - Line 2: action buttons — `↻ R3BU1LD` always, `DESTR0Y` + `PURG3`
   on sub-agents, `↺ R3ST4RT` + (sub-agents) `■ ST0P` when running,
   `▶ ST4RT` when stopped. Buttons dim + disable while a transient