From 4c425ede696e504dcd3aaebfbc9eea92faea0d04 Mon Sep 17 00:00:00 2001 From: lexis Date: Sat, 23 May 2026 12:27:03 +0200 Subject: [PATCH] docs: document rebuild queue panel + module (follow-up to #340) --- CLAUDE.md | 15 ++++++++++++--- docs/web-ui.md | 31 ++++++++++++++++++++++++++----- 2 files changed, 38 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 119127a..0a6ebc6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,9 +33,10 @@ hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched) in main.rs) + mutation events (`ApprovalAdded` / `ApprovalResolved`, `QuestionAdded` / `QuestionResolved`, - `TransientSet` / `TransientCleared`). Each - frame carries a monotonic per-process `seq` - clients use to dedupe against snapshot reads. + `TransientSet` / `TransientCleared`, + `RebuildQueueChanged`). Each frame carries a + monotonic per-process `seq` clients use to + dedupe against snapshot reads. src/approvals.rs sqlite Approval queue + kinds src/operator_questions.rs sqlite question queue backing `ask` / `answer` (both operator + agent-to-agent) @@ -63,6 +64,14 @@ hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched) surface). Backs AgentRequest::GetLooseEnds + ManagerRequest::GetLooseEnds (the get_loose_ends MCP tool). + src/rebuild_queue.rs global serialised queue for long-running ops + (rebuild / meta_update / spawn / destroy). + Single background worker drains FIFO; dedup + collapses re-enqueued still-queued entries. + `QueueEntry` carries id, agent, kind, state, + source, parent_id (cascade grouping), timing, + reason, error. Emits `RebuildQueueChanged` + snapshots on every mutation. src/actions.rs approve/deny/destroy (transient-aware) src/auto_update.rs startup rebuild scan + ensure_manager + meta::lock_update_hyperhive bump diff --git a/docs/web-ui.md b/docs/web-ui.md index 30139fe..61b4fa3 100644 --- a/docs/web-ui.md +++ b/docs/web-ui.md @@ -122,7 +122,21 @@ the previous process's socket release resolves itself. meta-update running" banner and the update button is disabled (snapshot field `meta_update_running`, live event `meta_update_running`). -5. **M1ND H4S QU3STI0NS** — pending operator-targeted `ask` +5. **R3BU1LD QU3U3** — pending and recently-completed container + operations: rebuilds, meta-update cascades, and first-spawns. + One operation runs at a time; the worker drains FIFO. Each row + shows a state glyph (`⏸` queued / `▶` running / `✔` done / + `✖` failed / `⊘` cancelled), kind glyph + verb (`↻ rebuild`, + `◆ meta_update`, `✨ spawn`, `🗑 destroy`), agent name, source + chip (`manual | meta_update | auto_update | crash_recover`), + timing, and an optional reason / error. Meta-update cascade + rebuilds nest under their parent entry (`parent_id` grouping; + `rqe-child` CSS class). Dedup: re-enqueueing a still-queued op + for the same agent collapses into the existing entry. Running + entries tick elapsed seconds live (same pattern as the TTL + countdown). Cold-loaded from `/api/state.rebuild_queue`; live + updates via `rebuild_queue_changed` snapshot event. +6. **M1ND H4S QU3STI0NS** — pending operator-targeted `ask` questions, i.e. rows with `target IS NULL` (peer-to-peer questions live in the same table but never surface here) (amber pulsing border). Free-text fallback always rendered @@ -132,23 +146,23 @@ the previous process's socket release resolves itself. with `[cancelled]`. Questions with a `ttl_seconds` show a `⏳ MM:SS` chip; the host-side watchdog auto-cancels with `[expired]` when the deadline fires. -6. **QU3U3D R3M1ND3RS** — reminders agents have scheduled for +7. **QU3U3D R3M1ND3RS** — reminders agents have scheduled for themselves (via the `remind` tool) but not yet delivered. Each row shows the owner, due time, and message; a `CANC3L` button hard-deletes (`POST /cancel-reminder/{id}`) and a `R3TRY` button re-arms one whose delivery failed (`POST /retry-reminder/{id}`). Backed by `GET /api/reminders`. -7. **P3NDING APPR0VALS** — the queue (see "Approval card" +8. **P3NDING APPR0VALS** — the queue (see "Approval card" below). The R3QU3ST SP4WN form lives at the top of this section since submitting it immediately queues an approval that lands directly below. -8. **0PER4T0R 1NB0X** — recent messages addressed to `operator`, +9. **0PER4T0R 1NB0X** — recent messages addressed to `operator`, derived client-side from the dashboard event stream (no longer a snapshot field). Cold load seeds from `/dashboard/history`'s 200-message backfill; subsequent `sent` events with `to == "operator"` are appended live. Cap 50, newest-first. -9. **MESS4GE FL0W** — live broker tail wrapped in a +10. **MESS4GE FL0W** — live broker tail wrapped in a `.terminal-wrap` (same chrome as the per-agent terminal). Cold load backfills the last ~200 messages from `/dashboard/history`; live frames arrive on @@ -388,6 +402,13 @@ payload): `crash_watch` poll. Client upserts/removes by name; the pending overlay is read from `transientsState` since the payload doesn't carry it. +- `rebuild_queue_changed` (seq, queue: `Vec`) — + full snapshot of the rebuild queue on every mutation (enqueue, + state transition, dedup collapse, terminal-history trim). + Same snapshot-over-diff rationale as `tombstones_changed` / + `meta_inputs_changed`: the list is small and the client's + `parent_id` grouping is most naturally re-derived from the + full list. Cold-loaded from `/api/state.rebuild_queue`. `/api/state` is **only fetched on cold-load and on the few forms that mutate non-event-derived state** (PURG3 +