From 38920d3af1b98db2d31bbe87d48bb491099f9957 Mon Sep 17 00:00:00 2001
From: lexis <lexis@hyperhive>
Date: Mon, 25 May 2026 01:43:54 +0200
Subject: [PATCH] docs: update web-ui.md for agent header redesign and
 in-flight rebuild badge (#394 #398)

---
 docs/web-ui.md | 92 ++++++++++++++++++++++++++++----------------------
 1 file changed, 52 insertions(+), 40 deletions(-)

diff --git a/docs/web-ui.md b/docs/web-ui.md
index ebd2882..0bd3473 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -256,9 +256,13 @@ guess from container state.
   `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 start / stop /
-  restart / rebuild / destroy), container name + port, and a
+  `◐ 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).
@@ -476,43 +480,51 @@ Three fixed-position layers frame a full-viewport terminal:
 
 **Fixed-overlay header** (`<header class="agent-header">`): frosted
 glass — `backdrop-filter: blur` lets scrolled terminal rows show
-through. Left to right:
-- Agent icon (`<img src="/icon">`).
-- Title (`<h2 id="title">`) + meta-nav (`<nav id="meta-links">`):
-  backend-supplied `StateSnapshot.links` rendered as icon-only
-  anchors. Always includes `📊 stats` (`kind = Container`);
-  `🖥 screen` when the VNC compositor is enabled; `⬡ forge` (profile)
-  + `↳ config` (agent-configs mirror) when the agent has a forge
-  account; followed by any `hyperhive.dashboardLinks` extras
-  (`kind = External`). The dashboard card's icon strip is the same
-  list via `GET /api/agent/{name}/links` — agent backend is the
-  single source of truth.
-- **State row** (`<div id="state-row">`): alive badge + state badge
-  + model chip + ctx badge + cost badge + last-turn chip + cancel
-  button + new-session button.
-  - Alive badge: `● alive` (green) / `⊘ rate limited` (red) /
-    `◌ needs login` / `◌ logging in` / `○ offline` / `… connecting`.
-    Driven by `LiveEvent::StatusChanged`.
-  - State badge: `💤 idle` / `🧠 thinking` / `📦 compacting` /
-    `○ offline` / `… booting` + age suffix. Driven by
-    `LiveEvent::TurnStateChanged ({ state, since_unix })`.
-  - Model chip: `model · <name>`. Driven by `LiveEvent::ModelChanged`.
-  - Ctx badge: `ctx · 142k` — last inference's prompt size (the
-    context window utilisation number to watch before compacting).
-    Tooltip shows % of window when `context_window_tokens` is known.
-  - Cost badge: `cost · 1.3M` — cumulative tokens billed across every
-    inference in the last turn. Tool-heavy turns rebill the cached
-    prefix per call, so this routinely exceeds the window — cost
-    signal, not size signal.
-  - Both driven by `LiveEvent::TokenUsageChanged { ctx, cost }` at
-    turn-end.
-  - `■ cancel turn` (visible while thinking) → `POST /api/cancel`.
-  - `↻ new session` (always, amber) → `POST /api/new-session`; next
-    turn drops `--continue`.
-- **Inbox pill** (`📬 inbox · N`): hidden when empty; click opens the
-  inbox flyout in the side panel.
-- **Loose-ends pill** (`🪢 loose ends · N`): hidden when empty; click
-  opens the loose-ends flyout in the side panel.
+through. Three flex columns (#394 redesign):
+
+- **Agent icon** (`<img class="agent-icon">`): full-height square
+  identity anchor (6em, `height: 100%; aspect-ratio: 1`). Falls back
+  to the dimmed hyperhive mark on load error.
+- **Main column** (`.agent-header-main`): two rows.
+  - Row 1 (`.agent-header-title-row`): title (`<h2 id="title">`) +
+    meta-nav (`<nav id="meta-links">`). Meta-nav renders
+    backend-supplied `StateSnapshot.links` as icon-only anchors — always
+    `📊 stats` (`kind = Container`); `🖥 screen` when VNC is enabled;
+    `⬡ forge` (profile) + `↳ config` (agent-configs mirror) when the
+    agent has a forge account; any `hyperhive.dashboardLinks` extras
+    (`kind = External`). A `↑ dashboard` link is prepended by the JS
+    so the host dashboard is one click away. `GET /api/agent/{name}/links`
+    is the single source of truth.
+  - Row 2 (`.agent-state-row`): alive badge + state badge + model chip
+    + ctx badge + cost badge + last-turn chip + cancel button.
+    - Alive badge: `● alive` (green) / `⊘ rate limited` (red) /
+      `◌ needs login` / `◌ logging in` / `○ offline` / `… connecting`.
+      Driven by `LiveEvent::StatusChanged`.
+    - State badge: `💤 idle` / `🧠 thinking` / `📦 compacting` /
+      `○ offline` / `… booting` + age suffix. Driven by
+      `LiveEvent::TurnStateChanged ({ state, since_unix })`.
+    - Model chip: `model · <name>`. Driven by `LiveEvent::ModelChanged`.
+    - Ctx badge: `ctx · 142k` — last inference's prompt size.
+      Tooltip shows % of window when `context_window_tokens` is known.
+    - Cost badge: `cost · 1.3M` — cumulative tokens billed across every
+      inference in the last turn (tool-heavy turns rebill the cached
+      prefix per call — cost signal, not size signal).
+    - Both driven by `LiveEvent::TokenUsageChanged { ctx, cost }` at
+      turn-end.
+    - `■ cancel turn` (visible while thinking) → `POST /api/cancel`.
+- **Right cluster** (`.agent-header-pills`): flyout pills + overflow.
+  - **Inbox pill** (`📬 inbox · N`): hidden when empty; click opens
+    the inbox flyout in the side panel.
+  - **Loose-ends pill** (`🪢 loose ends · N`): hidden when empty;
+    click opens the loose-ends flyout.
+  - **Overflow button** (`⋯`): always visible. Opens a frosted popover
+    (`#overflow-menu`, positioned outside the header to escape any
+    stacking context) with three rows: `↑ dashboard` (link), `↻ rebuild
+    container` (POST confirm, same action as the dashboard R3BU1LD
+    button), `↻ new claude session` (POST confirm → `POST
+    /api/new-session`; next turn drops `--continue`). Both destructive
+    actions require one extra click to acknowledge (#394 — rare ops
+    shouldn't live in the primary state strip).
 
 `/api/state` is fetched once on cold load (+ while
 `status === 'needs_login_in_progress'`); all other updates arrive via