docs: document rebuild queue panel + module (follow-up to #340)

This commit is contained in:
lexis 2026-05-23 12:27:03 +02:00
parent a2ed35cd19
commit 4c425ede69
2 changed files with 38 additions and 8 deletions

View file

@ -33,9 +33,10 @@ hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched)
in main.rs) + mutation events in main.rs) + mutation events
(`ApprovalAdded` / `ApprovalResolved`, (`ApprovalAdded` / `ApprovalResolved`,
`QuestionAdded` / `QuestionResolved`, `QuestionAdded` / `QuestionResolved`,
`TransientSet` / `TransientCleared`). Each `TransientSet` / `TransientCleared`,
frame carries a monotonic per-process `seq` `RebuildQueueChanged`). Each frame carries a
clients use to dedupe against snapshot reads. monotonic per-process `seq` clients use to
dedupe against snapshot reads.
src/approvals.rs sqlite Approval queue + kinds src/approvals.rs sqlite Approval queue + kinds
src/operator_questions.rs sqlite question queue backing `ask` / src/operator_questions.rs sqlite question queue backing `ask` /
`answer` (both operator + agent-to-agent) `answer` (both operator + agent-to-agent)
@ -63,6 +64,14 @@ hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched)
surface). Backs AgentRequest::GetLooseEnds + surface). Backs AgentRequest::GetLooseEnds +
ManagerRequest::GetLooseEnds (the ManagerRequest::GetLooseEnds (the
get_loose_ends MCP tool). 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/actions.rs approve/deny/destroy (transient-aware)
src/auto_update.rs startup rebuild scan + ensure_manager + src/auto_update.rs startup rebuild scan + ensure_manager +
meta::lock_update_hyperhive bump meta::lock_update_hyperhive bump

View file

@ -122,7 +122,21 @@ the previous process's socket release resolves itself.
meta-update running" banner and the update button is disabled meta-update running" banner and the update button is disabled
(snapshot field `meta_update_running`, live event (snapshot field `meta_update_running`, live event
`meta_update_running`). `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, i.e. rows with `target IS NULL` (peer-to-peer
questions live in the same table but never surface here) questions live in the same table but never surface here)
(amber pulsing border). Free-text fallback always rendered (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 with `[cancelled]`. Questions with a `ttl_seconds` show a
`⏳ MM:SS` chip; the host-side watchdog auto-cancels with `⏳ MM:SS` chip; the host-side watchdog auto-cancels with
`[expired]` when the deadline fires. `[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. themselves (via the `remind` tool) but not yet delivered.
Each row shows the owner, due time, and message; a `CANC3L` Each row shows the owner, due time, and message; a `CANC3L`
button hard-deletes (`POST /cancel-reminder/{id}`) and a button hard-deletes (`POST /cancel-reminder/{id}`) and a
`R3TRY` button re-arms one whose delivery failed `R3TRY` button re-arms one whose delivery failed
(`POST /retry-reminder/{id}`). Backed by `GET /api/reminders`. (`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 below). The R3QU3ST SP4WN form lives at the top of this
section since submitting it immediately queues an approval section since submitting it immediately queues an approval
that lands directly below. 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 derived client-side from the dashboard event stream (no longer
a snapshot field). Cold load seeds from a snapshot field). Cold load seeds from
`/dashboard/history`'s 200-message backfill; subsequent `/dashboard/history`'s 200-message backfill; subsequent
`sent` events with `to == "operator"` are appended live. Cap `sent` events with `to == "operator"` are appended live. Cap
50, newest-first. 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). `.terminal-wrap` (same chrome as the per-agent terminal).
Cold load backfills the last ~200 messages from Cold load backfills the last ~200 messages from
`/dashboard/history`; live frames arrive on `/dashboard/history`; live frames arrive on
@ -388,6 +402,13 @@ payload):
`crash_watch` poll. Client upserts/removes by name; the `crash_watch` poll. Client upserts/removes by name; the
pending overlay is read from `transientsState` since the pending overlay is read from `transientsState` since the
payload doesn't carry it. payload doesn't carry it.
- `rebuild_queue_changed` (seq, queue: `Vec<QueueEntry>`) —
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 `/api/state` is **only fetched on cold-load and on the few
forms that mutate non-event-derived state** (PURG3 + forms that mutate non-event-derived state** (PURG3 +