Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/5-project/process/conventions.md
iris e4cfac6926 frontend: root test and typecheck scripts, and tests for the review runs wording and the terminal drag
npm test and npm run typecheck now run in every workspace that has them (the repo root had only build and clean). New tests cover RunsTypes (labels and tones for every outcome, the classification count) and termDrag (what a drag carries and how the hover reads it). instructions.ts cannot be imported by a test under Node because of its .js specifier for unified-diff.ts, so it is not covered, and the conventions doc says so.
2026-11-20 00:28:04 +01:00

584 lines
30 KiB
Markdown

# Conventions
Code-style and process expectations across the workspace. Most of these
exist because something already went wrong without them.
## Naming
- Containers are length-bounded by `nixos-container` (≤ 11 chars).
- Sub-agents are `h-<name>` with `<name>` ≤ 9 chars.
- One agent is the bootstrap/root container, with a fixed name (`ruth` today).
- `MAX_AGENT_NAME` in `hive-c0re/src/lifecycle/mod.rs` enforces the cap.
- Per-agent web UI port = `WEB_PORT_BASE + FNV1a(name) % WEB_PORT_RANGE`
(8100..8999) for every agent; dashboard
`services.hyperhive.deploy.hive-controller.dashboardPort` (default 7000).
## Hive identity (label + domain + display names)
Four env vars cover the identity surface, read by
`hive-agent/src/identity.rs`:
- `HIVE_LABEL` — short, hive-local agent label (`iris`,
`damocles`). `label()` returns it; falls back to empty string if
the env var is missing so downstream callers can decide how to
surface "unknown agent" rather than getting a panic from this
module.
- `HYPERHIVE_HIVE_DOMAIN` — the hive's canonical DNS domain (e.g.
`darkest.space`), set by `nix/host-modules/hive-c0re/environment.nix`
from `services.hyperhive.domain`. When configured, `qualify(label)`
returns `${label}@${domain}` (for example `iris@darkest.space`); when
unset (single-hive deployments, dev/test) it degrades to just
the short label so existing callers see no change. The
qualified form surfaces in the per-agent web UI title, the
system-prompt template, and `/api/state.qualified_label`.
- `HYPERHIVE_HIVE_NAME` — human display name of this hive
(`pr1ma`). Read by `hive_name()`; `None` when unset.
- `HYPERHIVE_SWARM_NAME` — human display name of the wider swarm
this hive belongs to (`constellat1on`). Read by `swarm_name()`;
federated hives at different DNS domains can share a swarm
name.
Inside an agent container, the hive's name and domain don't come from the
agent's build, and neither do the hive's other per-host values: the dashboard
port (`HIVE_DASHBOARD_PORT`), the pinned claude-code
(`HYPERHIVE_CLAUDE_CODE_PATH`), extra OTEL labels
(`HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES`) and the queue's address
(`HIVE_AGENT_NATS_URL`, from `deploy.hive-controller.queue.agentNatsUrl`) and the egress proxy's address and direct hosts (`HIVE_SQUID_PROXY`, `HIVE_EGRESS_NO_PROXY`, see [the egress proxy](../../4-implementation/networking/network.md#egress-proxy-squid)). `hive-priv` writes them to
`/etc/hyperhive-hive-facts` before every container start, leaving out any the
hive doesn't set; the agent then uses its own default. The agent's environment
generator (`nix/agent-modules/hive-facts.nix`) passes all but the two egress facts, which only the proxy fetch reads, to every unit,
including `hivectl choom` sessions, and `/etc/set-environment` exports them in login
shells that no unit starts (`nixos-container root-login`). None is part of
an agent's closure, and an agent started on another hive reports that hive.
`hive_name` + `swarm_name` are **distinct** from
`HYPERHIVE_HIVE_DOMAIN`: the domain may carry the hive name as
its leftmost label by convention, but the convention isn't
machine-readable, and federated hives at different DNS domains
can share a swarm name. Humans want both: the address
(`@darkest.space`) AND the prose name (`pr1ma`). Matrix MXIDs
use the domain-based convention.
## Identity = socket
No auth tokens exist on the per-agent unix sockets. The socket
*path* identifies the principal; perms come from "who has the
bind-mount." A sub-agent only sees its own `/run/hive/mcp.sock`;
hive-c0re owns the host admin socket.
Matrix, bash and forge wake the agent by upserting a todo on the harness's
in-agent socket (`HIVE_AGENT_SOCKET`), which signals the turn loop without a
hive-c0re round-trip. See
[`docs/4-implementation/turn-loop/mcp.md` § Waking the agent from inside the
container](../../4-implementation/turn-loop/mcp.md#waking-the-agent-from-inside-the-container).
The host-served `/run/hive/mcp.sock` has no verb that injects a message into
the agent's own inbox.
Anything that can connect to `/run/hive/mcp.sock` is implicitly trusted to
call its verbs. That's fine: the bind-mount only exposes the socket inside the
agent's own container, so the trust boundary is the container's process
namespace, not the wire surface.
## Recipient sentinels
The broker reserves a few recipient names, which have a fixed
meaning that ordinary agent labels can never collide with — agent
name validation rejects any character outside `[a-z0-9_-]`, so the
angle-bracket and asterisk shapes below are structurally safe.
- `*` — broadcast: deliver to every running agent except the sender
(`Coordinator::broadcast_send`, used by hive-c0re's own system broadcasts).
- `operator` — the human at the dashboard. Reserved so no agent can take
the name. It appears only as the sender of operator-authored messages.
The broker stores the recipient exactly as the agent passed it.
## Wire protocol
JSON line-delimited over unix sockets in both directions (host admin
/ manager / agent). SSE streams (`/dashboard/stream` on hive-c0re,
`/events/stream` on the per-agent web UIs) are `text/event-stream`;
the per-agent `/events/stream` frames carry a `seq` field for the
snapshot-dedupe dance (see `docs/4-implementation/web-ui/shape.md`). Request/response types live in `hive-sh4re`
— change them in one place. The dashboard event vocabulary lives
in `hive-c0re::dashboard_events::DashboardEvent`.
### Broker delivery + ack cycle
`AgentRequest::Recv` is the only path that delivers messages to an
agent. It returns a list (`Messages { messages }`) of zero or one
message: empty when nothing is pending. The request carries an optional
`wait_seconds` (long-poll for the next message); the harness's own
turn-driving loop uses it (`hive-agent`'s `recv_next`, 180s). The
agent-facing MCP surface has no `recv` tool at all.
Per-row bookkeeping inside the broker:
<!-- vale write-good.Passive = NO -->
- `delivered_at = NOW` set on every popped row.
- Each recipient has an in-memory `unacked_ids` list of every row
delivered since the last `AckTurn`.
- `redelivered = true` on a row if `RequeueInflight` resurfaced it
(the harness prepends a "may already be handled" hint when this
flag is set so the per-message warning is visible).
<!-- vale write-good.Passive = YES -->
`AgentRequest::AckTurn` closes out the in-memory list — the harness
fires it after `TurnOutcome::Ok`, marking every message popped since
the last ack as fully handled. Claude doesn't see this surface; it's
strictly a harness↔broker pairing. On `TurnOutcome::Failed` the
harness intentionally skips the ack so the unacked rows stay
in-flight in the DB and get picked up by the next requeue sweep.
`AgentRequest::RequeueInflight` is the recovery pair: fired by the
harness exactly once at boot, before the serve loop starts. Catches
the crashed-mid-turn / OOM-killed / container-restarted cases where
a previous harness session popped messages but never drove them to
a clean turn-end. Resets `delivered_at` back to NULL on every
unacked row (so the next `Recv` pops them again), and remembers
each id in a per-recipient in-memory set so the next `Recv` can tag
the row with `redelivered: true`. Idempotent + cheap when there's
nothing in flight, so the at-boot fire is unconditional.
Agents have no bulk-ack of their own: the harness acks a turn's message
with `AckTurn`. The operator-side bulk action is the dashboard's "mark all
read" (unbounded, per-agent).
### Loose-ends wire shape
`LooseEnd` is the per-row response shape for `GetLooseEnds` — one
request shape, no per-socket flavours. Tagged enum so new thread kinds
(forge PRs, etc.) can land later without breaking existing handlers.
Each row carries enough context that the caller renders
it directly as a bulleted list, no follow-up fetch needed.
`GetLooseEnds` takes no target — it always returns the caller's own
rows. `Reminder` rows always carry `owner == self`.
Per-variant fields:
- `Reminder { id, owner, message, due_at, age_seconds }` —
`due_at` is the absolute time the scheduler is targeting (RFC
3339 on the wire, see *Timestamps on the wire* below); clients
compute time-until-fire against it.
- `PendingMessages { count }` — undelivered inbox messages the
agent hasn't handled yet. Informational + not
cancellable; only emitted when `count > 0`,
and surfaced first in the list as the most
actionable signal. Counted host-side from the broker
(`count_pending`), so it reflects what's genuinely still queued —
the wake-message that drove the current turn is already delivered
and not counted.
- `UnreadMatrix { rooms, summary }` — unread matrix notifications.
Informational + not cancellable (clear with `mark_read`). Unlike
the others, the in-container harness injects this, not hive-c0re,
because the matrix daemon lives inside the agent.
`age_seconds` saturates at zero on any clock anomaly (back-step,
unsynchronised wall clock, etc.) so the bulleted list never
shows nonsense ages.
`cancel_loose_end` is the matching write surface, handled in the
harness without a hive-c0re round-trip: `reminder` deletes one of the
caller's own pending reminders, `todo` clears one of its todos.
### Agent metadata
`AgentRequest::GetAgentMeta { name }` returns identity + status for
an agent. Self-introspection when `name = None`; target query when
`name = Some`.
Response is `AgentMeta { name, running, hyperhive_rev,
status_text, status_set_at, hive_name, swarm_name, matrix_accounts }`:
- `hyperhive_rev`: `None` only when the configured flake URL has
no canonical path. Otherwise carries the rev the target is
currently pinned at.
- `running`: whether the target's container is currently up. When
`false`, the host clears `status_text` / `status_set_at` —
on-disk values from before the stop are stale snapshots, not
live status. Defaults to `true` on the
wire: the deserializer treats a payload without the field as
running.
- `status_text` / `status_set_at`: last value written via
`SetStatus`, plus its unix timestamp. Both `None` when the
target has never set a status, when the agent name is unknown,
or when `running = false` (see above).
- `hive_name` / `swarm_name`: display names read from
`HYPERHIVE_HIVE_NAME` / `HYPERHIVE_SWARM_NAME` env (sourced from
`services.hyperhive.deploy.hive-controller.hiveName` / `services.hyperhive.swarm.name`).
Both `None` when the options aren't configured.
- `matrix_accounts`: one `MatrixIdentity` per configured + live matrix
account the agent can act as. Empty for agents with no matrix
provisioning.
### Timestamps on the wire
Timestamp fields that cross a JSON boundary (dashboard API + SSE,
the wire structs in hive-sh4re) serialize as **RFC 3339 UTC strings**
(`2026-07-02T18:30:00Z`) via `hive_sh4re::wire_time` — Rust keeps the
fields as `i64` unix seconds internally, only the JSON representation
changes, and deserialization accepts both the string form and a bare
integer (rolling-deploy skew, persisted blobs).
**Input-direction** fields agents compute as epoch (`remind`'s
`at_unix_timestamp`) stay integers. The
`*_unix` field *names* stay for now — renaming is the wire-types
refactor's concern. The dashboard frontend parses via
`util.js::epochSec` wherever it needs arithmetic and feeds the string
straight to `new Date(s)` for display.
### HTTP error bodies
Every HTTP API in this repo answers failures with **RFC 9457
`application/problem+json`** (`{ type, title, status, detail }`), with the
human-readable cause in `detail`. An endpoint returning a bare string
or a bespoke error shape is a **bug to file against the daemon that
returned it**, not something for the caller to work around.
Use the `problem_details` crate (`features = ["axum"]`), which the daemons
already depend on: type a handler `Result<_, ProblemDetails>` and hand
`ProblemDetails::from_status_code(...).with_detail(...)` to `Err`.
The reason is the consumer, not tidiness. The UIs show errors through one
shared component with a copy button, so a caller has to know **which part of
the body is the message**. A bare string forces it to treat the whole payload
as prose, which is the difference between offering "copy the cause" and
dumping a response — and the cause is frequently the entire diagnosis (a
JetStream permission refusal, a TLS chain failure) rather than a summary.
Not in scope: the `hivectl` host-admin and in-agent unix sockets. Those are a
JSON-line protocol with their own result types; RFC 9457 is an HTTP format.
## Permissions
One set of named `Permission` values (`hive_types::Permission`)
decides what an agent may do: which MCP and built-in tools it gets, and which
host access it has.
| Permission | Grants |
|---|---|
| `messaging` | nothing (kept as an accepted value; agents message over matrix) |
| `meta` | `get_agent_meta` (`set_status` is always-on, see below) |
| `inbox` | `get_loose_ends`, `cancel_loose_end`, `remind` |
| `execution` | the `bash` MCP server (`mcp__bash__run`/`status`/`kill`), rendered into the agent's MCP config only with it; a subagent gets Claude's own `Bash` instead. See `docs/4-implementation/agent-tools/bash.md`. |
| `web_tools` | the Claude built-ins `WebFetch`/`WebSearch` |
| `manage_root_agent` | every agent's state (rw) bind-mounted into the holder's container, plus `/meta` (ro) |
| `logs` | the log store: `swarm-logs` queries. Checked by `swarm-logs-auth` at the gateway, not by a tool list. Off by default. |
| `metrics` | the metrics store: `swarm-metrics` queries. Checked by `swarm-metrics-agent-auth`, the same binary, for the metrics gateway. Off by default. |
**Always-on tools** — `Permission::ALWAYS_ON_TOOLS` exposes `set_status`,
`compact`, `mark_todos_done` and `transcribe_audio` to every agent regardless of its
permissions. The operator dashboard depends on every agent being able to
report its status chip, and the server-side `SetStatus` handler has no
permission check (only length validation), so gating it would only desync
the `--allowedTools` list from what the host actually accepts. Revoking
`meta` therefore drops `get_agent_meta` but never `set_status`.
`mark_todos_done` is here because producers push todos to an agent whether
or not it holds `inbox`, and an agent without it still needs to clear them.
`transcribe_audio` is here because it only turns an audio file the agent
already holds into text through the swarm's service; it reaches nothing the
agent couldn't read.
**Where they live** — in the swarm, not on the hive: the `permissions` field of
the agent's key in the `agent-permissions` KV bucket
(`swarm-wire/src/agent_permissions.rs`), which swarm-controller alone
writes. Set them with `swarmctl agent permissions get|set|clear <agent>`
(`/api/agents/{name}/permissions`), or on the swarm UI's create-agent screen
(`permissions` in `POST /api/agents`). A missing key or an unset field means
the default (`Permission::DEFAULT`): `messaging`, `meta`, `inbox`,
`execution`, for every agent whatever its name. `"permissions": []` grants
none. swarm-controller logs every refused `PUT` or `DELETE` on that route at `warn` as
`agent permissions: request refused`, with the fields `op`, `agent`, `status` and `detail`.
**`logs` and `metrics`** — off for every agent until granted, and separate
because logs are the more sensitive. Grant one with
`swarmctl agent permissions set <agent>` (listing it with the others) or the
create-agent screen; the setup assistant creates ruth with both, through the `ruth` archetype. An agent
without it gets a 403 from the store's gateway when `swarm-logs` or
`swarm-metrics` queries; a bad secret is still a 401.
An agent decodes its own record, in its harness
(`hive-agent/src/swarm_permissions.rs`, through `swarm_queue_client::agent_permissions::read`),
and a build that doesn't know a name would drop to no permissions. The controller
therefore refuses a change that adds `logs` or `metrics` to an existing
agent, with a 409, unless both the agent's hive (`tolerant-permissions` in its
status snapshot) and its running harness (the same entry in its turn-state
header, `swarm_wire::hive_status`) advertise it. A harness not yet updated, a
stopped agent and one that hasn't sent its first header (up to a minute after
a restart) all refuse; keeping a grant it already holds needs no report. A
create has no harness yet and checks the hive only.
The controller mirrors the two grants to the store leaf
`swarm/agents/<agent>/observability` (`swarm_secret_client::observability`),
which the gateways read, and the gateway denies when it can't read that leaf.
A change that drops a grant writes the leaf first and the record second, so a
failed write changes nothing; a change that adds one writes the record first,
so a failed write leaves the gateway denying. Every five minutes the controller
also makes each agent's leaf equal its record and logs a warning for each leaf
it corrects. A revoked grant stops working within `authVerdictTtl` (60
seconds by default) of the agent's last allowed query.
**Internet flag** — the record also carries `unrestricted_internet`, a
boolean that isn't a `Permission`. An absent value means on, so every agent
that existed before the field keeps the open access it had. `POST /api/agents`
writes `false` for an agent that has no record, unless the request names a
value. Over an existing record (a re-create) it keeps the stored list and flag,
an absent flag included, and a value in the request wins. A `PUT` that leaves
the field out and a `DELETE` (`swarmctl agent permissions clear`) also keep the
stored value; a `DELETE` on an agent that has one rewrites the record to just
that value. Read it with
`swarm_queue_client::agent_permissions::unrestricted`. The hive reads it for
the agent's squid policy: [the egress proxy](../../4-implementation/networking/network.md#egress-proxy-squid)
lets an unrestricted agent's credential reach any destination, and holds the
others to the base list and the allow-list. An agent sends its credential once it has fetched it, from its next start.
**Log mode** — `internet_log` is a second boolean, meaningful only beside an
explicit `unrestricted_internet: false`; read the pair with
`swarm_queue_client::agent_permissions::internet_mode`. A `PUT` that sets
`unrestricted_internet` without `internet_log` turns it off, the route refuses
`internet_log: true` unless the stored or requested flag is `false`, and a
`DELETE` keeps it. A hive that doesn't read the field sees `false` and enforces
the list. The proxy's handling is under _Log mode_ in [the egress proxy](../../4-implementation/networking/network.md#egress-proxy-squid).
**Repository limit** — the record also carries `max_repos`, how many repositories
the agent's forge account may create, 0 to 100. An absent value is 0. Only the
controller reads it: it sets the account's Forgejo `max_repo_creation` from it at
`CreateForgeUser`, and again for an existing account within seconds of a change,
at every start and every five minutes (`forge::agent_max_repos`). It also turns
off creating organizations on every agent account. A `PUT` that leaves the field
out, a `DELETE`, and a re-create keep the stored value; the route refuses more
than 100.
**SSH switch** — the record also carries `ssh`, whether the agent's login role
attaches the SSH signing policy. An absent value is off. Only the controller reads
it (`agent_ssh`). A `PUT` that leaves the field out, a `DELETE` and a re-create
keep the stored value.
**How a change applies** —
- The agent's harness reads its own key every 10 seconds and builds every
turn's `--tools`, `--allowedTools` and MCP config from the last value, so a
change reaches the next turn. An ACP agent's permission check reads it on
each request.
- The subagent daemon reads the key on each `start`/`continue`; a running
subagent keeps its tools.
- hive-c0re reads each of its agents' keys every 30 seconds
(`workers/swarm_permissions.rs`) into
`/var/lib/hyperhive/swarm-agent-permissions.json`, outside the meta repo.
nspawn fixes the bind mounts at container start, so when an agent's
`manage_root_agent` changes hive-c0re restarts it after its current turn.
- Until its first read succeeds, an agent holds no permissions: no
`execution` (so no `bash`), only the always-on tools. A subagent it starts
holds the same. After a read, an unset key means the default. A failed read
keeps the last value read, so an unreachable queue at start keeps the agent
closed until a read succeeds.
Every reader keeps its last good value on a failed read.
**Moving off the meta repo** — on its first boot with this code a hive copies
`meta/capabilities.json` and `meta/tool-groups.json` into the stored value,
sends them to swarm-controller once as one list per agent (without
`lifecycle` and `forge`, which gave no tools; the controller writes a key
only where there is none, and only for agents that hive's wanted state
declares), and deletes
both files from the meta repo when the controller answers
(`workers/permissions_import.rs`). Until then hive-c0re reads no keys. An
agent reads a key the controller hasn't yet written as unset, the default,
so an agent whose meta grant differs from the default holds the default
until the import lands.
**Not configurable from `agent.nix`** — that file changes through config PRs
an agent can open, so letting it declare its own permissions would let an
agent grant itself any tool by submitting a config commit, bypassing the
operator gate.
**Adding to the set** — add a variant to `Permission` in
`hive-types/src/permission.rs` and to `Permission::ALL`, and enforce it where
it applies. A new `#[tool]` fn on `AgentServer` (`hive-agent-mcp/src/mcp/mod.rs`)
goes into the matching `Permission::tools()` slice: that's the single source
of truth `mcp_config::allowed_mcp_tools` (`hive-agent/src/mcp_config.rs`)
reads each turn.
## Async forms
Dashboard + per-agent mutating forms carry `data-async`; the shared
`bindAsyncForms` `submit` listener (`frontend/packages/shared/src/forms.js`,
imported as `@hive/shared/forms.js` and wired up from `tabs.js` on the
dashboard and `app.js` on the per-agent UI) intercepts, shows a spinner,
POSTs `application/x-www-form-urlencoded` (axum's `Form` extractor
rejects multipart), calls `refreshState()` on success. New mutating
forms should add `data-async` and optionally `data-confirm` (for a
JS-side `confirm()` prompt).
`refreshState` defers automatically when `document.activeElement`
sits inside a managed section so the operator's typing isn't lost;
collapsible `<details data-restore-key=…>` survive the re-render
via `snapshotOpenDetails` / `restoreOpenDetails`.
## `rebuild` is the reconcile verb
`job_queue::templates::rebuild` builds the DAG that reconciles a
container to its wanted state: it folds `write_dropins` (the nspawn-conf
rewrite — `PRIVATE_NETWORK=1`, `HOST_ADDRESS` = the bridge gateway IP,
sets `EXTRA_NSPAWN_FLAGS` — plus the systemd resource-limits drop-in)
into the `Swap` node, then runs `nixos-container update` + stop +
start across the `StopForUpdate → Swap → RebuildBookkeeping`
brace and the tail `Reconcile` node. `flake.nix` itself lives in the agent's
`agent-configs/<name>` repo and rides along with its pinned commit (see
`docs/4-implementation/agent-state/config-changes.md::Deploy markers per agent`).
Anything that changes per-container state on the host should be
re-applied here so a manual `↻ R3BU1LD` from the dashboard is
sufficient to recover.
## Actions live in one place
`destroy` (and the lifecycle helper) live in
`actions.rs` / `hive-c0re/src/dashboard/`. The admin socket and the dashboard
POST handlers both call into them so the two surfaces never drift.
## Commit messages
Short, lowercase, no `Co-Authored-By` trailer. Imperative mood, no
period. Body explains *why* when the reasoning isn't self-evident;
otherwise the subject alone is fine. Wrap at ~72 cols.
## Commit before test
Stage and commit when work *looks* ready, then run validation
(`cargo check`, `nix flake check`, real deploy). Failures get a
follow-up commit rather than an amend. The commit history is the
work log; rewriting it loses signal.
## Building & local checks
Build through the **flake devshell**, not a bare toolchain — agent
containers ship no global rust. `nix develop -c <cmd>` runs one
command inside the project-pinned env (cargo/clippy/rustfmt plus the
C compiler + `libsqlite3`/`ring` link deps); outside it a bare
`cargo build` fails with `failed to find tool "cc"` / `cannot find
-lsqlite3`. One command per invocation — agents run each task as a
fresh non-interactive process, so there's no persistent shell to
reuse.
```sh
nix develop -c cargo clippy --all-targets -- -D warnings
nix develop -c cargo test
nix fmt # treefmt — authoritative, NOT bare cargo fmt
```
`nix fmt` (treefmt) is the formatter CI gates on; bare `cargo fmt`
misses the non-rust files treefmt also covers, so always run `nix
fmt` before pushing. It also formats and lints Python with ruff.
**Frontend checks** run from `frontend/`: `npm test` runs the unit tests of every
workspace that has any (today the swarm UI's, with Node's own runner), and
`npm run typecheck` runs `tsc` in each that has a typecheck. Build with
`npm run build`. Pure logic goes in a `.ts` module that a test imports directly. A test
under Node can't import a module that names a sibling with a `.js` specifier, as the
build resolves it.
**Clippy discipline — never add `#[allow(clippy::…)]`.** All lints are
CI-fatal at `-D warnings` (pedantic included); every warning that fires
must be *fixed*, not silenced. Common patterns:
- `too_many_lines` — extract a helper function or a sub-struct
(the `TurnAccum` extraction in `stats.rs` is a worked example).
- `doc_markdown` (brand name without backticks in a doc comment) — add
backticks: `` `DOMPurify` `` instead of `DOMPurify`.
- `must_use` / `unused_results` — actually handle or explicitly discard
the return value (`let _ = …` is fine when intentional).
If a lint seems wrong for a specific call site, file an issue and ask
mara — don't add `#[allow]` speculatively. The gate is intentional.
**The devshell checks aren't the full `nix flake check`.** Clippy /
fmt / `cargo test` cover most gates, but `nix flake check` runs extra
check derivations they don't:
- **`hivectl-docs`** regenerates `docs/2-handbook/hives/hivectl-cli.md` from
hivectl's clap tree and **fails if the committed copy is stale**.
**After any change to a hivectl verb or flag, regenerate it**:
```sh
nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/hives/hivectl-cli.md
```
clippy / fmt / `cargo test` all pass *without* this — only the
flake check catches the drift, and `ci-log` often can't show you
why (it 500s on a fast failure), so you're left guessing "builder
flake" when it's a stale doc.
- **`swarmctl-docs`** is the same check for `swarmctl` /
`docs/2-handbook/swarm/swarmctl-cli.md`:
```sh
nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/2-handbook/swarm/swarmctl-cli.md
```
- there's also a flake `cargo-test` check and NixOS module
evaluation in the set.
When local clippy/fmt/test pass but CI's `nix flake check` fails,
**don't assume a transient builder problem** — reproduce the real
gate locally: `nix flake check` (shares the build farm, use
sparingly) or build just the suspect check, for example `nix build
.#checks.x86_64-linux.hivectl-docs`.
## Testing seams and test doubles
- **A new test seam is a trait, used generically** (`impl Seam` or a type
parameter). No `dyn Fn` closure bags: a trait names each question the code
asks and gives the test one place to answer it.
- **A double that only answers and records uses `mockall`** (a
dev-dependency): put `#[cfg_attr(test, mockall::automock)]` on the trait,
set canned replies with `returning`, and assert calls with `times` and
`withf`. The attribute keeps `mockall` out of release builds. Examples:
`Probes` in `hive-priv/src/storage.rs`, `Publisher` and `Tokens` in
`swarm-builder/src/main.rs`.
- **`automock` can't mock a trait with a supertrait** such as `Clone`: a mock
doesn't implement it. Declare the mock with `mockall::mock!` as a plain
struct and implement the trait for `Arc<Mock…>`, as `swarm-builder` does.
Better, leave the supertrait off the trait and bound the callers.
- **Stateful fakes stay hand-written**: in-memory stores whose reads see earlier
writes. Real-process stubs such as `ScriptSpawn` also stay, since they run a
real `sh` on purpose.
- **Nothing migrates in one sweep.** Move an existing expectation-style fake
to `mockall` when you touch its file for another reason.
## Best-effort oneshot services
The harness ships a family of one-shot systemd services that
configure agent-side surfaces from values delivered to the agent at
provisioning time:
- `forge-avatar-sync` — uploads `services.hyperhive.agent.icon` SVG to the
agent's Forgejo profile, so the icon shows up on commits / PRs /
issue comments.
(The matrix profile avatar is **not** a oneshot — `hive-matrix-daemon`
sets it over its live authenticated Client; see
`docs/4-implementation/agent-state/persistence.md::matrix avatar`.)
Shape contract — every one of these:
1. **Always `exit 0`**, even on internal failure. A non-zero exit
would mark the unit `failed`, which in turn aborts
`nixos-container update` and blocks rebuilds. The agent's
capability surface isn't allowed to gate the container
build.
2. **No `set -e`** in the script body. Subshell failures must not
propagate. Use `... || true` on every external call that can
fail (forge unreachable, missing icon, parse error, etc.)
3. **Skip silently when prerequisites are missing**: no token
file, no icon, no reachable upstream → `echo` a short skip
line + `exit 0`. The next boot tries again.
4. **Wired to `multi-user.target`** so they run on every boot
(lets a rotated token / new icon take effect without
`systemctl restart` gymnastics).
5. **Re-runnable**: a second invocation produces the same final
state (idempotent uploads, idempotent config rewrites). Used
by the `.path` watchers that re-fire on token appearance (see
`docs/4-implementation/agent-state/persistence.md::Matrix per-agent daemon`).
The service stays root-owned so the bootstrap ordering doesn't need a
user-existence check before each fire.
This pattern keeps the rebuild path resilient: any failure inside
these services degrades the corresponding surface (no avatar) but never blocks the container from coming up. The
operator notices through `journalctl -u <unit>` rather than a
broken switch-to-configuration.