hivectl has verbs scattered across CLAUDE.md and domain docs (gateway.md
has the gateway subcommands, matrix.md has a brief mention) but no
single cheatsheet. Add docs/tools/hivectl.md covering all subcommands:
- forge create-user: provision/refresh agent or human forge accounts
- matrix create-user / sync-admin / promote-user / reset-password
- gateway create-user / delete-user / list-users (htpasswd management)
- agents restart / restart-all (container lifecycle via admin socket)
- choom <name> [--fresh]: interactive claude session in agent container
Also add a reading-path entry to CLAUDE.md pointing at the new file.
persistence.md: bash-tasks/ says "persist until container purge" but
bash_tasks_vacuum now runs hourly and deletes terminal task trios older
than 48 hours. Update the description to reflect actual retention policy.
matrix.md: add step 6 to the Provisioning flow section documenting that
hive-c0re restarts hive-matrix-daemon immediately after writing the
access_token (fix for issue #1329). Previously the doc stopped at token
write; the restart + .path-trigger fallback interplay was undocumented.
The nixpkgs bump to clippy 0.1.95 / cargo 1.95.0 added + strengthened a
large batch of lints. CI denied ALL warnings (`-D warnings`) against the
`pedantic = warn` workspace lint, so the bump hard-failed `nix flake
check` workspace-wide with zero code changes — and would recur on every
future clippy bump.
Posture fix (the durable part): CI now runs
`-D warnings -A clippy::pedantic`, so the default/correctness/style lints
stay a hard gate while the "extra, opinionated" pedantic group is
advisory only (still `warn` for local `cargo clippy` via the workspace
lints table, just non-blocking in CI). `-A` rather than `-W` so the
group drop doesn't re-enable the specific pedantic lints the workspace
allows (e.g. `must_use_candidate`).
Also fixes the genuine DEFAULT/STYLE lints the bump surfaced across the
workspace (doc_lazy_continuation, collapsible_if, ptr_arg,
match_like_matches_macro, …) via `cargo clippy --fix` + manual stragglers
(`too_many_arguments` #[allow] on the host-config constructors), and
three tests that had rotted while the CI runner was offline (#1221):
- topology::top_level_agents_in_multi_root — hardcoded unsorted expected
- rebuild_queue::depends_on_evicted_dep_counts_as_resolved — needs
MAX_HISTORY_PER_KIND newer terminals to evict, not one
- coordinator::agent_paths doctest — illustrative pseudo-code, now `ignore`
Validated: clippy + formatting + cargo-test checks all pass.
Reminder due-at labels ("in 3m 45s") and schedule next-fire cells
were computed once at render time and never updated. For short-horizon
reminders the stale count was visually misleading.
Both renderers now stamp data-due-at=<unix> on their respective
elements (.reminder-due / .sched-due). A shared 1s setInterval
ticker walks all live elements and rewrites textContent using
fmtDuration / fmtAgo — same zero-re-render pattern as the
existing question TTL chip ticker.
web_ui.rs: add available_models() helper that reads HIVE_AVAILABLE_MODELS
(comma-separated, injected by services.hyperhive.availableModels nix option).
Falls back to ["haiku", "sonnet", "opus"] when absent or empty. Field added
to StateSnapshot so the frontend receives the list on cold-load.
app.js: replace hardcoded MODEL_ALIASES array with availableModels module var.
Seeded from state.available_models before setHeader/populateOverflowMenu on
first /api/state load. Well-known aliases (haiku/sonnet/opus) still get their
descriptive labels; operator-declared custom model names show the name itself.
Implements the frontend + web_ui.rs side of issue #1359 (nix option shipped
separately in PR #1360 by atlas).
renderMetaInputs snapshots the set of checked data-meta-input values before
calling root.replaceChildren(), then restores them after rebuilding the list.
Without this, a MetaInputsChanged SSE event (e.g. fired when a concurrent
meta-update completes) would silently wipe any checkboxes the operator had
ticked but not yet submitted — forcing them to re-select their inputs.
Adds a per-agent hyperhive.availableModels list option (default
[ haiku sonnet opus ]) rendered into the HIVE_AVAILABLE_MODELS env var
(comma-separated) so the per-agent web UI model quick-picker lists
exactly the configured models instead of a hardcoded set. Operators set
a shared default hive-wide or narrow it per-agent.
An assertion guards that hyperhive.model is present in the list so the
picker can always offer the model the agent is actually running.
Approval cards render their age label ("requested N ago") at
render time from a cold /api/state or an approval_added /
approval_resolved SSE event. An approval sitting pending for
an hour would show a stale "0s ago" unless one of those events
fired in the meantime.
Fix: stamp data-requested-at=<unix> on each .approval-ts span.
A 1s setInterval ticker reads all live chips, recomputes the
relative time via fmtAgo, and toggles .stale (amber highlight)
at exactly the 1-hour threshold — no longer dependent on
the next full re-render cycle to apply the amber colour.
Previously only the 'all' chip showed a count (all · N). The operator
had to click each chip to see how many questions were in each category.
Now every chip shows its own count:
all · 5 @operator · 2 @peer · 3 @agentname · 1
This lets the operator see the distribution at a glance and navigate
directly to whichever category has pending items without guessing.
Stamp data-rqe-enqueued / data-rqe-finished / data-rqe-state on queued
and terminal rqe-when spans. A 30s ticker updates them in place so
'queued 2m ago' and 'done 5m ago' labels advance as time passes.
Complement to the keyed rebuild-queue row cache: rows now persist
across snapshots, so without a ticker these static fmtAgo labels
would become arbitrarily stale. The running-entry elapsed ticker
(data-rqe-elapsed, 1s interval) already handled that state;
this fills the gap for queued and terminal states.
Apply the same fingerprint-cache pattern as the container row cache to
the rebuild-queue list. Maintain rebuildQueueRowCache (Map<id, {el,
fingerprint}>) so renderRebuildQueue can reuse <li> nodes whose state
hasn't changed across rebuild_queue_changed snapshots.
The rebuild queue emits a full snapshot on every mutation (a single
rebuild emits queued → running (+ step changes) → done/failed — each
transition is an event). Before this change every event caused a full
replaceChildren() wipe of the list. After this change only the row(s)
whose fingerprint changed get rebuilt; the rest survive intact.
The elapsed-time ticker (data-rqe-elapsed + 1s setInterval) already
updates running-entry timestamps in-place, so ticking elapsed seconds
don't require a re-render and are excluded from the fingerprint.
DOM order is reconciled via insertBefore with no wipe, same as the
container cache.
renderQuestions() was calling root.replaceChildren() on every
question_added / question_resolved SSE event, wiping all <li>
elements including any textarea the operator was typing into.
Add questionRowCache (Map<id, {el, fingerprint}>):
- questionRowFingerprint encodes the static fields that determine
the <li> DOM structure (asker, target, asked_at, deadline_at,
question text, options, multi)
- buildQuestionLi extracts the <li>-building code so it can be
called only when the fingerprint changes
- renderQuestions reuses cached <li> nodes for unchanged questions
and evicts entries for resolved/cancelled questions
Effect: when a new question arrives while the operator is typing a
reply, the existing <li> is reused — the textarea value, radio
selection, and checkbox state are all preserved.
The history <details> open state is also saved before and restored
after the replaceChildren call, so the answered-history panel does
not collapse when a live question event fires.
renderApprovals() called root.replaceChildren() on every
approval_added / approval_resolved SSE event, wiping the spawn
form's name input if the operator had started typing a new agent
name.
Save the current input value before the wipe and restore it into
the freshly-built input element. The form itself is still rebuilt
(no keyed-cache needed here — approval cards have no user inputs),
so all other behaviour is unchanged.
Adds a navigation entry in the per-agent ⋮ overflow menu that opens the
AGENT log tab pre-filtered to that container. The link uses the ?agent= URL
param introduced by the accompanying logs.js change — the operator lands
directly in the journal viewer without having to pick an agent from the
dropdown.
Placed between the rebuild action and the destructive destroy/purge block
so it's reachable but clearly separated from dangerous actions.
Adds ?agent=name and ?unit=svc URL params to pre-select the agent on
the AGENT tab (used by the per-agent overflow menu journal logs link).
Last-fetched timestamp chip shows how stale the output is.
Agent selection is NOT persisted to localStorage — URL params only.
Per mara's review: drop the #hive:<server> room alias (special chars) and
rediscover the canonical Space by its hardcoded plain name instead.
ensure_hive_space dedup is now:
1. room-id file present -> reuse it
2. else scan the admin's joined rooms for the m.space named HIVE_SPACE_NAME
('hive') and adopt the first match (re-persisting the file) -> recovers
the existing space after a state wipe instead of creating a duplicate
3. else createRoom (plain name, no alias)
find_space_by_name walks /joined_rooms and checks each room's m.room.create
type == m.space and m.room.name == 'hive'. No alias, no special-char anchor.
server_name is no longer needed by ensure_hive_space (dropped the param).
ensure_hive_space relied solely on the persisted room-id file. If that file
is ever lost (a full /var/lib/hyperhive wipe), the next sweep blind-creates a
new m.space — the homeserver keeps the old one, so duplicate hive spaces
accumulate (observed: multiple 'hive'/'pr1ma' rooms on the live instance).
Anchor the Space to a stable canonical alias #hive:<server>:
- fast path (room-id file present): reuse it and heal the alias mapping so
it keeps pointing at the canonical room
- no file: resolve #hive:<server> and adopt the existing room if present,
re-persisting the file — recovers the space after a wipe instead of
duplicating it
- only create (with the alias) when neither yields a room
server_name is now discovered before ensure_hive_space in ensure_all and
threaded through (the alias needs it). Existing deployments heal the alias
onto their current space on the next sweep; no new room is created when the
file is present.
Adds an invite_user tool to the per-agent matrix MCP so an agent can invite
another user to a room it's already in (e.g. pull a peer into an existing
chat). Mirrors the existing join_room/send_dm wiring:
- protocol.rs: DaemonRequest::InviteUser { room, user_id }
- handlers.rs: invite_user — parse user_id, resolve room, room.invite_user_by_id
- socket.rs: dispatch arm
- bin/mcp.rs: invite_user tool + InviteUserArgs
room accepts an id or alias; the caller must hold a power level high enough
to invite (the homeserver error is surfaced verbatim otherwise). The invitee
then accepts via join_room. allowedTools is already '*' for the matrix server,
so the tool is exposed without a nix change.
Adds three one-click model shortcuts (haiku / sonnet / opus) at the
bottom of the agent overflow menu (⋯), below a separator and a small
'model' section label.
- The active model alias is highlighted with .active (purple border +
tint) so the operator can see at a glance which model is current.
Matching tolerates both short aliases (haiku) and full API names
(claude-3-5-haiku-20241022) via an endsWith check.
- Clicking the active model is a no-op (closes menu, no POST).
- Clicking a different alias calls postModel() and closes the menu.
- renderModelChip() keeps the picker buttons in sync on every
/api/state refresh without rebuilding the menu.
Before this change the operator had to type /model <name> in the
compose box. The overflow menu provides a discoverability path for
operators who don't remember slash commands.
On refreshState, the hive-identity title update (fired once when
hive_name/swarm_name are configured) now reads any existing (N) prefix
and preserves it, so the title doesn't briefly drop back to the bare
identity string before refreshTabCounts re-applies the prefix.
When approvals or questions are waiting, document.title is prefixed
with (N) so the operator can see activity in a background browser
tab without switching windows. Clears to the base title when zero.
Implemented in refreshTabCounts (1s tick): strips any existing
prefix before re-applying so the hive-identity title update (once
on state load) composes cleanly.
The M1ND H4S QU3STI0NS paragraph was a minimal stub that omitted
most of the questions UI:
- Filter chips row (all · N / @operator / @peer / per-participant)
with localStorage persistence
- Peer-targeted questions (agent-to-agent asks) and the
operator's ability to override-answer them (0V3RR1D3 button)
- Full answer-form anatomy (textarea, option list, merge logic,
Enter-to-submit, separate cancel form)
- Answered-history collapsible (◆ answ3red (N) details element)
Also clarify the P3NDING APPR0VALS paragraph: explicitly mention
the pending/history tab pair (it was documented in the Approval
card section but not called out at the tab level).
Full `nix flake check` (CI) runs the treefmt formatting derivation. While the
hive-ci runner was offline (#1221), PRs merged without it, leaving 5 files
unformatted: hive-ag3nt/src/web_ui.rs, hive-c0re/src/bin/hivectl.rs,
hive-c0re/src/knowledge.rs, hive-c0re/src/matrix.rs,
hive-forge/src/verbs/attachment_get.rs. `nix fmt` output, pure formatting.
The BUILD sub-tab description was written before the auto-scroll,
live elapsed-time ticker, and SSE-driven list refresh were added.
Update it to cover:
- Live elapsed-time chip: ticks every second via setInterval,
cleared on finish/error
- Sticky-bottom auto-scroll: follows new output while the operator
is at the bottom; silently appends when scrolled up
- SSE-driven list refresh: rebuild_queue_changed fires a 2s-debounced
fetchBuild() while on the BUILD tab; refresh button still works for
immediate re-fetch
Stamp data-set-at on .status-age spans so the '(set N ago)' label
stays accurate as time passes. Previously the age was computed once
when the async dashboard-state fetch completed and never updated.
With the keyed container row cache, rows persist much longer between
rebuilds (no more full rebuild on every SSE event), making stale
status-age labels more noticeable. The 30s ticker fixes this without
requiring a full row rebuild or re-fetch.
Maintain a module-level containerRowCache (Map<name, {el, fingerprint}>)
that preserves <li> elements across renderContainers calls. Each row's
fingerprint encodes everything that affects its rendered output:
container running/login/update/reminder state, derived pending/opRunning
labels, tree position (depth, isLast, ancestorIsLast), selection, agent
question counts, and link-base context.
When the fingerprint is unchanged the existing DOM node is reused:
- no replaceChildren wipe for stable rows
- the async dashboard-state fetch (nav strip, ctx badge, status text)
is skipped — previously-fetched data stays in place
- DOM order is reconciled via insertBefore with zero layout work for
in-place nodes
Before this change every SSE event (container_changed, rebuild_queue_
changed, transient_set/cleared, question_added/resolved) caused a full
wipe + rebuild of the entire container list, triggering N concurrent
/api/dashboard-state fetches where N is the number of running agents.
After this change only the rows whose state actually changed are
rebuilt; the rest survive intact across re-renders.
If the operator had an agent:foo filter active and all of foo's questions
were resolved, foo's chip disappears from the filter row on the next
render — but the stored filter value is still agent:foo. The section
then shows "no questions match this filter" with no active chip visible,
leaving the operator confused.
Fix: compute the set of valid filter values (all, operator, peer, plus
one agent:<name> per current participant) before rendering. If the stored
value is not in the set, silently reset it to 'all'. Write directly to
localStorage rather than via setQuestionsFilter() to avoid a re-entrant
renderQuestions() call.
When a question_added or question_resolved SSE event fires, the handler
calls renderQuestions() directly — bypassing the snapshotOpenDetails /
restoreOpenDetails pair that refreshState wraps around it. This caused
the answered-history <details> (data-restore-key="q-history") to
collapse every time a question arrived or was resolved while the
operator had it open.
Fix: call snapshotOpenDetails() at the start of renderQuestions() and
restoreOpenDetails() at the end. The double-restore in the refreshState
path is harmless — re-opening an already-open <details> is idempotent,
and restoreOpenDetails is a no-op when the snapshot set is empty.
When the agent page is accessed via hive-gateway (path is /agent/<name>/)
the dashboard lives at the same origin's root (/), not at the direct
TCP port. Both app.js (overflow menu / setHeader) and stats.js
(dashboard-link anchor) previously hardcoded http://hostname:port which
is wrong or unreachable behind HTTPS TLS termination.
Detection: if location.pathname starts with '/agent/', use
location.origin + '/' as the dashboard base. Otherwise fall back to the
original direct-TCP construction for non-gateway deploys.
The dashboard.md 'Line 3: drill-in triggers' section described inline
↳ logs and ↳ build logs side-panel affordances that were removed from
the container row some time ago (navigation links were consolidated onto
the Line 1 nav strip; journal + build-log viewing moved to /logs.html).
Replace that stale section with accurate documentation of the per-agent
⋮ overflow menu (restart/stop/start/rebuild + journal-logs deep-link +
destroy/purge + deployed-sha forge link).
Also update the AGENT and SYSTEM sub-tab descriptions to cover:
- localStorage persistence of agent/unit selection across page loads
- ?agent= / ?unit= URL params for deep-linking (used by the ⋮ menu)
- 'fetched N ago' chip after each successful fetch (ticks every 30 s)
The compose box's send-error path used:
flow.insertBefore(row, flow.firstChild)
This inserts the error before the first (oldest) child — at the top of
the terminal's scroll area — which is completely out of view since the
operator is at the bottom watching new messages.
Changed to flow.append(row) + scroll the wrap element to the bottom so
the error appears where the operator is looking. Also prefixed the
message with '✗ ' so it's visually distinct from regular flow rows.
Two small fixes in tabs.js:
1. renderApprovalHistory showed 'spawn' for init_config approvals.
The pending-approvals path already handles the three kinds correctly
(apply / init / spawn); history used a two-branch ternary that fell
through to 'spawn' for init_config. Fixed to match the pending path.
2. The 1s interval that ticks rebuild-queue elapsed badges contained a
second loop polling '.build-logs-runtime[data-bl-elapsed]'. No code
in tabs.js ever sets that attribute — the logs page manages its own
elapsed timers inside logs.js. Removed the dead loop.
Three UX improvements for the live build log viewer:
1. Auto-scroll (sticky-bottom): live build output now scrolls to the
bottom as new lines arrive. Stops auto-scrolling when the operator
manually scrolls up; resumes when they scroll back to the bottom.
Same intent-tracking pattern used by the terminal pane.
2. Elapsed-time ticker: running builds show a live seconds/minutes
counter in the row header that ticks every second. Stops and shows
the final duration when the build finishes (done frame received)
or errors out.
3. SSE-driven list refresh: subscribes to /dashboard/stream and
debounces a fetchBuild() call (2s) whenever rebuild_queue_changed
fires while the BUILD tab is active. New log entries and status
changes appear without a manual refresh.
