The option was only mentioned in passing in the system-prompt render
section. Add a proper ### section (following the pattern of Agent icon,
user.passwordlessSudo, etc.) with the nix snippet, default, effect on
$HIVE_DOCS_DIR + system prompt, and a note on the narrow docs flake
input that avoids full container rebuilds on doc edits.
After the fix in c708f698, POSTs no longer always return 200 — they use
semantic status codes: 400 for bad input, 409 for retryable state
conflicts (turn in flight, hive-c0re busy), 500 only for genuine failures.
Update the preamble to the Per-agent endpoints section to reflect this.
hive-c0re never writes outside its StateDirectory + RuntimeDirectory:
- /etc writes (nixos-containers) go through hive-priv, not c0re
- /etc/hyperhive/serve.json is read-only at startup (written by the
NixOS activation script, not by the daemon)
- nix builds delegate to hive-priv via the privileged Unix socket;
hive-c0re itself never invokes nix directly
So strict is safe: systemd keeps /var/lib/hyperhive (StateDirectory)
and /run/hyperhive (RuntimeDirectory) writable; everything else is
read-only, shrinking the writable attack surface to exactly what the
service needs.
Add docs/observability.md covering all services.hyperhive.otel.*
options: enable, endpoint, protocol, headersCredential,
extraResourceAttributes, debug (new in cb0a66147a), and
metricIntervalMs.
Includes:
- Built-in OTEL_RESOURCE_ATTRIBUTES labels (service.name, agent, hive, swarm)
- Cumulative temporality note (avoids Prometheus DELTA drop)
- Network note for host-side collectors on non-standard ports,
cross-referencing docs/network.md exposeHostPorts
Also:
- CLAUDE.md: add reading-path entry for the new doc
- docs/network.md: link the OTEL mention to observability.md
Closes no issue — gap found during doc sweep.
The renderer dispatch section only mentioned recv and Bash as fmtToolUse
examples. Update the description to cover the full range: matrix tools,
remind, scheduling, and the fmtArgsGeneric fallback.
join_room and open_dm shared a fall-through case with
(fmtRoom(input.room) || fmtUser(input.user_id) || '?'). fmtRoom()
returns the string '?' when input.room is undefined — truthy — so
the fmtUser() fallback was never reached and open_dm always displayed
'open_dm* ?'.
Split into two separate cases: join_room reads input.room, open_dm
reads input.user_id. Both degrade to '?' via fmtRoom/fmtUser's own
null guard.
mcp__matrix__send_message now has a specific fmtToolUse case and no
longer falls through to fmtArgsGeneric. Update the prose to reflect
that common tools have specific cases.
Root contexts (systemd services running as root, PID 1) default to
store=auto which resolves to the LOCAL nix store — bypassing the host
daemon, its remote builders (muede-pc2), and any prebuilt derivation
outputs already in the shared store. This causes spurious full
rebuilds of agent toplevels that the host already built and cached.
Two changes:
harness-base.nix:
- Add systemd.globalEnvironment.NIX_REMOTE = "daemon" — sets
DefaultEnvironment in systemd.conf so every unit in the container
inherits NIX_REMOTE=daemon. Non-root contexts already default to
the daemon socket; this only matters for root services that would
otherwise use the local store.
- Add NIX_REMOTE = "daemon" to environment.variables so interactive
shells also have it set (redundant with /etc/profile.d/nix-daemon.sh
but explicit and profile-agnostic).
hive-c0re.nix (hive-priv service):
- Add NIX_REMOTE = "daemon" to the service environment. hive-priv
runs as root and invokes nixos-container update + nix prebuild; these
must route through the host daemon so they see the shared store and
remote builders, not a private local store.
The sandbox-fallback = true in harness-base.nix is kept as a belt-
and-suspenders fallback but becomes a no-op for the common case once
nix routes through the daemon (the daemon builds on the host where
sandboxing works).
ProtectSystem=full makes /usr, /etc, and /boot read-only. Safe for
hive-c0re because it never writes to those paths directly:
- /etc writes (e.g. /etc/nixos-containers) go through hive-priv
- /etc/hyperhive/serve.json reads are read-only
- All runtime writes go to StateDirectory (/var/lib/hyperhive) and
RuntimeDirectory (/run/hyperhive), which remain writable under full
ProtectSystem=strict (everything read-only) is still deferred — it
requires auditing ReadWritePaths for every nix path c0re touches.
RestrictAddressFamilies deferred pending a watched deploy.
Also tightens the comment block to not mention a numbered issue.
hive-c0re runs as the unprivileged hive-core user and delegates all
privileged operations to hive-priv via a Unix socket. Add the subset of
systemd sandboxing directives that are provably safe without a watched
deploy (no ProtectSystem / RestrictAddressFamilies, which require mapping
the full set of filesystem/network paths first):
- NoNewPrivileges: already unprivileged; no setuid/capability escalation
- PrivateTmp: nix subprocesses use StateDirectory temp paths, not /tmp
- ProtectHome: HOME is /var/lib/hyperhive (StateDirectory), not /home/*
- ProtectKernelTunables: no sysctl writes needed
- ProtectKernelLogs: logs via systemd-journal group, not /dev/kmsg
- ProtectControlGroups: cgroup writes go through hive-priv, not c0re
- RestrictNamespaces: namespace creation goes through hive-priv
- LockPersonality: no personality changes needed
- RestrictRealtime: no real-time scheduling
Follows the same pattern as hive-priv (PrivateTmp + ProtectHome already
present there). Deferred: ProtectSystem=strict + ReadWritePaths +
RestrictAddressFamilies — those need a watched deploy per the #1845 plan
since getting the ReadWritePaths wrong silently breaks runtime I/O.
Previously, serveConfig was a pkgs.writeText store path embedded in
ExecStart. Any repo edit (gateway.nix, frontend, unrelated nix modules)
changes hyperhiveFlakeSource → serveConfig hash → ExecStart → systemd
restarts hive-c0re → StartupSweep → every agent rebuilt unnecessarily.
Fix: write the JSON to /etc/hyperhive/serve.json via environment.etc
(a managed /etc symlink to the store-path content). ExecStart now
references the stable /etc path, changing only when cfg.package (the
hive-c0re binary) changes. Unrelated module edits no longer bounce c0re
or trigger a cascade agent rebuild.
hive-c0re still restarts — and triggers the sweep — when its binary
changes, which is the correct invariant: a new release legitimately
needs to resync all agents with updated harness modules.
`mcp__hyperhive__remind` calls previously rendered as the generic
`fmtArgsGeneric` output — with a multi-field input that showed
`message: "..." · delay_seconds: 300`, burying the message after
a verbose field name.
New format: `remind* +5m "check on PR..."` (or `at HH:MMZ` for
absolute timestamps). The timing renders first so it's scannable
at a glance, followed by the first 60 chars of the message body.
Works for all three input shapes: delay_seconds, at_unix_timestamp,
and file_path-only (shows the path as the preview).
After the SW4RM and Y3R C4LL extractions from tabs.js (PRs merged
earlier), several docs still pointed at `assets/tabs.js::fn`. Update
them to the authoritative module:
- dashboard.md: renderContainers, buildAgentTree → swarm.js
renderApprovals → call.js
renderPeerHives → swarm.js
- shape.md: generic "tabs.js render function" → "domain module"
- conventions.md: clarify async-form listener lives in tabs.js (dashboard)
AND app.js (per-agent UI)
Several MCP tools appeared with the generic wrench icon (🔧) making
them hard to identify in the scrollback. fmtToolUse also lacked
specific formatters for some frequently-used tools, falling through
to fmtArgsGeneric.
Icons added:
- ack_until → ✅ (mark-as-read semantics)
- get_logs → 📜 (log viewer)
- get_host_journal → 📜 (journal reader)
fmtToolUse cases added:
- ack_until → "ack_until* ≤N" (message-id bound)
- get_logs → "get_logs* <agent> [NL]"
- get_host_journal → "get_host_journal* <container|unit> [/grep/] [NL]"
- restart/start/update → "restart* <name>" etc. (previously used
fmtArgsGeneric; now match kill's pattern)
Closes#2188.
The renderer dispatch section was missing entries for three system
subtypes that now have specific renderers (added in the preceding
commits on this branch). Update the row taxonomy table and the
numbered dispatch description to cover all four system-subtype
handlers (thinking_tokens was already documented; 1b–1e are new).
compact_boundary events currently render as the generic "⚙ compact_boundary"
muted note. The event carries useful metadata — pre/post token counts,
duration and trigger — that are invisible to the operator.
With this change the row reads:
· ⚙ compact · manual · 772k→6k tokens · 101s
Fields rendered (all guarded — missing fields are silently omitted):
- trigger ("manual" or "auto")
- pre_tokens→post_tokens (formatted with k/M suffixes)
- duration_ms (ms or s)
Closes#2187.
Currently both system subtypes fall through to the generic muted
note renderer (⚙ <subtype>), giving the operator no insight into
what is happening.
plugin_install:
Render status explicitly — "loading…" on started, "✓ done" on
completed — so a slow plugin boot is visible in the scrollback
instead of two identical cryptic rows.
commands_changed:
Render the count of available slash commands in the summary row
and expand to the full list in a collapsible details block. The
list is most useful right after a fresh plugin_install so the
operator can see exactly which /commands are now on offer.
Both handlers sit immediately before the generic catch-all in the
system-subtype dispatch in renderStream, preserving the existing
fall-through for other subtypes (context_window_exceeded etc.).
Closes#2183.
CLAUDE_CODE_OTEL_DIAG_STDERR was always set when OTEL is enabled, making
OTEL SDK errors (e.g. 404 from a misconfigured collector endpoint) appear
in every agent's stderr unconditionally. Move it behind a new opt-in flag.
Changes:
- nix/modules/hive-c0re.nix: add services.hyperhive.otel.debug (bool,
default false); wire to HYPERHIVE_OTEL_DEBUG env on hive-c0re unit.
- hive-c0re/src/meta.rs: add debug field to OtelConfig; read
HYPERHIVE_OTEL_DEBUG; emit hyperhive.otel.debug = true when set.
- nix/templates/harness-base.nix: add hyperhive.otel.debug internal
option; move CLAUDE_CODE_OTEL_DIAG_STDERR out of otelSettingsEnv into
a debug-gated lib.optionalAttrs block.
Default behaviour: OTEL exports silently (no stderr noise). Operators
troubleshooting collector connectivity set services.hyperhive.otel.debug
= true to re-enable the diagnostic output.
Forgejo's default mirror behaviour syncs on every git access, which
re-introduces external DNS latency at clone time. The hive-ci runner
shares the host netns, so a host-resolver blip turns an otherwise
local clone into a hard failure (data.forgejo.org DNS lookup that
has nothing to do with the repo being cloned).
Fix:
- New MIRROR_INTERVAL const (8h0m0s) used in ensure_mirror_repo.
- On creation: pass interval=MIRROR_INTERVAL in the migrate API body.
- On existing mirror: PATCH mirror_interval on every startup so repos
seeded before this change converge without manual intervention.
A stale mirror (up to 8 hours old) is fine for CI; a broken clone
from a transient DNS blip is not. The actions/checkout mirror is
refreshed periodically rather than triggered by runner pulls.
R3BU1LD QU3U3 and M3T4 1NPUTS moved from /core.html to /builds.html
(the BU1LDS page); the BUILD log tab moved from /logs.html to /builds.html.
dashboard.md still described the old 4-tab C0R3 page and 4-tab L0GS page.
Changes:
- C0R3 page section: update to the actual 2 tabs (K3PT ST4T3 +
C0NT41N3R L04D); add pointer to BU1LDS page
- Add new BU1LDS page section: R3BU1LD QU3U3 (with all 9 queue kind
glyphs + deferred-start parent_id note), M3T4 1NPUTS, BUILD L0GS
- L0GS page section: update to actual 3 tabs (AGENT / SYSTEM / AUDIT);
remove BUILD sub-tab prose; add pointer to BU1LDS page
- Fix two stale 'C0R3 page R3BU1LD QU3U3' refs to 'BU1LDS page'
- web-ui.md index: mention BU1LDS alongside C0R3 and L0GS
Two undocumented features from recent commits:
feat(core) 6ab0757cc6: K3PT ST4T3 now has two
sub-sections — tombstones (existing) and a new 'stale permission entries'
list showing agents with capability/tool-group JSON entries but no live
container. Lazy-loaded, auto-refreshes on capabilities_changed +
tool_groups_changed; each entry has a 'clear perms' button.
feat(dash) 4375ab6246: container rows show an
active model badge (blue) when the container is running and the harness has
persisted a model name in harness/hyperhive-model. Stale values suppressed
for stopped containers.
