hyperhive/docs/process/conventions.md

# 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. `hive-priv` writes them to `/etc/hyperhive-hive-facts` before
every container start. The agent's environment generator
(`nix/agent-modules/hive-facts.nix`) passes them to every unit, including
`hivectl choom` sessions, and `/etc/set-environment` exports them in login
shells that no unit starts (`nixos-container root-login`). Neither 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.

### Wake injection

`hive_core_agent_sock::Request::Wake { from, body }` is the
wake-event-injection surface on the host-served per-agent socket.
Recipient is implicit — the agent the socket belongs to — and `from`
is caller-chosen so the wake prompt can label the source verbatim
(`"matrix: new message in #general"`, `"forge: PR #42 opened"`, etc.). <!-- lint:allow: example strings, not real tags -->
`hive-c0re` handles it; matrix, bash and forge don't call it — their
notifications upsert a todo on the harness's in-agent socket
(`HIVE_AGENT_SOCKET`), which signals the same turn loop without a
hive-c0re round-trip. See
[`docs/turn-loop/mcp.md` § Waking the agent from inside the
container](../turn-loop/mcp.md#waking-the-agent-from-inside-the-container).

Identity = socket means anything that can connect to
`/run/hive/mcp.sock` is implicitly trusted to inject wakes. 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 special
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
  (`socket_server::handle_send` fans out via `Coordinator::broadcast_send`).
- `operator` — the human at the dashboard. Reserved so no agent can take
  the name, and refused as a recipient: the broker answers a `send` to it
  with `OPERATOR_SEND_REFUSAL` (`hive-sh4re/src/manager.rs`). 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`;
each frame carries a `seq` field for the snapshot-dedupe dance
(see `docs/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. Always returns a list (`Messages { messages }`) — empty when
nothing's pending, single-pop when `max = None` (default 1, the
single-message behaviour), batched up to `max` when caller asks for
more (server-side cap is 5; values above clamp silently). The wire
request still carries an optional `wait_seconds` (long-poll the first
message, once one arrives — or one is already pending — the call
drains up to `max` in total): the harness's own turn-driving loop
uses it internally (`hive-agent`'s `recv_next`, 180s). The
agent-facing MCP `recv` tool doesn't expose this parameter — it
always passes `wait_seconds: None`, an immediate peek.

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.

`AgentRequest::AckUntil { up_to }` is the agent-facing bulk-triage
escape hatch (`mcp__hyperhive__ack_until`). Unlike `AckTurn` **it's**
visible to claude: each recv row and wake prompt carries a
`[msg #<id>]` marker (the broker row id; transient pings show no
marker — their sentinel id 0 has nothing to ack), and
`ack_until(up_to: n)` marks every one of the agent's rows with
`id <= n` handled in a single UPDATE — pending and delivered alike.
This bounds the redelivered-flood cost after a restart: instead of
popping dozens of already-handled messages one turn at a time, the
agent notes the highest id it has seen and acks up to it.
Recipient-scoped (an agent can only ack its own rows); also drains
the in-memory `unacked_ids` / `requeued_ids` bookkeeping below the
cutoff so a later `AckTurn` doesn't double-update and a stale
redelivery tag can't outlive its row. The operator-side sibling 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 still owes itself a `recv` for. Informational + not
  cancellable (drain with `recv`); 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.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` | `send`, `recv`, `ack_until` |
| `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/tools/bash.md`. |
| `web_tools` | the Claude built-ins `WebFetch`/`WebSearch` |
| `manage_root_agent` | every agent's state (rw) + config (ro) bind-mounted into the holder's container, plus `/applied` and `/meta` (ro) |

**Always-on tools** — `Permission::ALWAYS_ON_TOOLS` exposes `set_status`,
`compact`, and `mark_todos_done` 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.

**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.

**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.
- hive-c0re copies each agent's entry from that file into the agent's
  runtime dir (`/run/hive/swarm-permissions.json` in the container) at every
  start and after every 30-second pass, with whether the import below is
  still pending. The harness and the subagent daemon hold that copy until
  their own first read succeeds, so an agent whose queue is down starts on
  its last stored grant, not the default.

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, and an
agent that reads its own key unset keeps the grant in its copy.

**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
proposed/applied repos and rides along on every fetch (see
`docs/agent-lifecycle/config-changes.md::Two repos 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.

**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/tools/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/tools/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/tools/swarmctl-cli.md`:
  ```sh
  nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/tools/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`.

## 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/agent-lifecycle/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/agent-lifecycle/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.