Review fixes for #4879 (argus):
- mcp.md: the 'Waking the agent' cross-ref pointed at Core tools, which
never mentions UpsertTodo/HIVE_AGENT_SOCKET. Point it at
docs/tools/bash.md's 'Completion as a todo (loose-ends v2)' section,
which documents the actual upsert/signal/clear mechanism.
- conventions.md 'Wake injection': still framed AgentRequest::Wake (a
type that no longer exists) as the live wake surface with matrix/forge
as callers. hive_core_agent_sock::Request::Wake has exactly one
non-test reference on origin/main (the handler at
socket_server/mod.rs:307) and no client; matrix/bash/forge all moved
to the in-agent todo socket. Rewritten to match, linking mcp.md's
'Waking the agent' section instead of duplicating it.
docs/tools/matrix.md:136-137 has the same stale AgentRequest::Wake claim
(and contradicts its own :159-165) but is out of scope (#4136) — noted
as a follow-up in the PR body instead of edited.
mcp.md:
- matrix and subagent extra MCP servers are http (hive-matrix-daemon,
hive-subagent-daemon), not stdio; screen is the one entry that still
uses the stdio default (nix/agent-modules/matrix.nix:290-297,
screen.nix:22-25)
- set_status is always-on, not meta-group-gated; mark_todos_done (also
always-on) was undocumented (hive-sh4re/src/permissions.rs:151,
hive-agent-mcp/src/mcp/mod.rs:425)
- System messages: HelperEvent has 3 variants, not the 8 previously
listed; ApprovalResolved/ContainerCrash routing and the swarm-wide
NATS notices stream (swarm_notices.rs) replace the old per-agent
todo-wake description for rebuilt/killed/destroyed/logged_in/needs_login
- get_loose_ends's approval rows are manager-only; PendingMessages and
UnreadMatrix were missing from the description
(hive-sh4re/src/inbox.rs:127-184)
- subagent spawning runs on hive-runtime (claude or ACP), not
claude-only (hive-subagent-mcp/src/session.rs:77)
- Waking section: matrix/bash/forge all moved to the in-agent todo
socket; the host Wake request has no built-in caller left today
agent-hierarchy.md:
- distinguished the swarm-wide agent roster (swarm-controller's
identity store, authoritative) from the hive-local topology.json
(a derived, reconciled cache scoping ManageRootAgent's bind-mounts),
linking README's framing
- noted services.hyperhive.ruthless (a hive can run with no manager at
all)
- Wire-protocol bullet: the only privileged Request variants left are
the scheduling ops; Kill/Start/Restart/Update/GetLogs don't exist on
this socket
- Prompt/tools: prompt::render hardcodes the agent role for every
container today (role:manager blocks are dead code); the tool
allow-list has no Flavor switch, it's HIVE_TOOL_GROUPS same as any
agent
Not touched: agent-hierarchy.md:140-200 (Harness systemd unit shape,
kept in place — see PR follow-ups) and docs/agent-lifecycle/approvals.md
(blocked on #4853).
authelia 4.39.20 exits at startup on `users: {}` ("users: non zero value
required"), and the first-boot unit seeded exactly that, so a swarm with
no users crash-looped authelia and answered 502 until `swarmctl user add`
ran.
The first-boot unit now writes one subject, `swarm.placeholder`, when
the users database is absent, empty, or exactly `users: {}`:
- `disabled: true` — authelia returns "user not found" for a disabled
user before any password check (file_user_provider.go,
CheckUserPassword).
- password: an argon2id digest with an all-zero key. It decodes (authelia
rejects a non-digest at startup) and no known password hashes to it.
- the `.` keeps it out of agent names (`[a-z0-9-]`), and `swarmctl user
add` refuses it as already existing. Neither writer removes users, and
both round-trip `disabled`.
A file with any user in it is never touched.
The docs that described the crash-loop (sso.md, gateway.md, setup.md,
the sso-unavailable error page) now describe the placeholder; the
writers' load_store docs and the seed fixtures follow. module-eval
nats-authelia asserts the seed branch.
swarm-controller/README.md "What it does" was still missing two route
groups argus caught: linked external matrix/forge accounts
(PUT .../matrix-accounts/{account}, .../forge-accounts/{label}) and
config-PR status (GET /api/config-prs, /api/agents/{name}/config-pr).
Verified against the router at main.rs:2874-2899.
swarm/README.md opens with the swarm and its control plane; hive identity
and the directory follow as the substrate. Upgrade notes move into a
<details> block, the per-agent queue publishing detail into another, and
the one-paragraph pointer sections collapse into a link list.
Fact fixes, checked against origin/main:
- an empty swarm.hives fails eval (swarm.nix:341-354); it does not mean
"not in a swarm"
- swarm.domain is required with a hive (hive-network.nix:156,188), hiveName
with a hive, store or homeserver (hyperhive.nix:161-166)
- the matrix container trusts the hive's trust-bundle.pem at runtime under
self-signed certs (hive-matrix.nix:1046-1052, lib/hive-ca-trust.nix:76-85)
- singleHostSwarm also defaults the controller, localHostsEntry, the nats
callout keys and the bao bootstrap token path (local-defaults.nix:72-129)
- swarm-controller serves far more than /health: roster, wanted state, job
graph, agent creation and credential mints (main.rs:2874-2899)
- swarmctl user add needs --email for the forge account and refuses an
existing user (setup.md:67-71, swarmctl/src/main.rs:425-430); document
agent mint-identity and mint-forge-token
- agent creation also mints store identity, forge token and matrix
account, and declares the agent paused (main.rs:1822-1920, 247-248)
Refs #3902
frontend/README.md:
- swarm-ui has real pages (HivesPage, AgentsPage, JobsPage,
CreateAgentForm, IssueReportPage, account-linking forms, routed in
App.tsx) and is served via nix/host-modules/swarm-ui.nix +
swarm-controller's swarm-ui-facing endpoints — drop the stale
package.json-derived 'no functionality yet' claim
- dashboard is a vanilla-JS + custom-element MPA (core.js, common.js,
tabs.js, ...) with a couple of Preact-rendered pages (builds.js,
swarm.js), not uniformly Preact like agent/swarm-ui
- drop the build.mjs line-count guess (actual: agent=93,
dashboard=134, swarm-ui=167)
- frontend/README.md: list the missing packages/swarm-ui package, fix
the vanilla-JS claim (all packages depend on preact), and the
deprecated hyperhive.frontend.extraFiles spelling
- hive-c0re/README.md: hive-c0re no longer provisions per-agent
forge/matrix accounts (swarm-controller does); it wires gateway
vhosts and reconciles forge/matrix config
- hive-metric/README.md: OTEL_EXPORTER_OTLP_HEADERS is never set by
the harness and has no way to be set
- hive-agent-sock/README.md: fix the deprecated
hyperhive.extraMcpServers spelling
- docs/process/gotchas.md: fix a dangling hive-ag3nt/ path, the real
directory is hive-agent/
Also fixes pre-existing vale error-level alerts (passive voice,
Microsoft.Auto, Microsoft.Contractions) in the same files so
prose-lint-errors passes clean.
The old FORGES tab wrote forge-<label>-token/forge-<label>.json directly;
the swarm-fetch unit that replaced it never deletes a pair for a label it
doesn't list, so those files keep being read by hive-forge -f <label>
until the operator links an account under the same label in the swarm UI,
which overwrites both files (nix/agent-modules/forge-accounts.nix:11-13,159-176).
hive-matrix-daemon removes undeclared matrix-token-<name> files on
every start (hive-matrix-mcp/src/main.rs:100), so there is no window
where an account linked through the old per-agent MATRIX tab keeps
working — it must be declared via matrixAccounts at swarm/agent
level.
Frame the turn loop runtime-neutrally: every turn runs through
hive-runtime, on claude (default) or an ACP agent. The loop steps,
harness binary shape and hive-agent README now say so; claude-only
failure detection gets its own heading; claude-invocation.md opens with
its scope and links the ACP side to hive-runtime/README.md.
Fact fixes: on-boot file paths (/run/hive-config, not /run/hive),
hive-claude is a crates.io dependency with no README here, hive-agent
has no client.rs or forge_notify.rs, the claude launch-config layer is
hive-agent's mcp_config.rs, agent forge/matrix accounts are
swarm-controller's, hive-c0re's dashboard is dashboard/, and the
deprecated hyperhive.gui.enable / hyperhive.extraMcpServers spellings.
Refs #3902
- hivectl/README.md: split matrix.rs/github.rs into accurate per-module
lines (matrix.rs invites a matrix user to the hive Space/room,
cli.rs:289-296; it is not per-agent). Fixed the summary line's
'provisioning verbs' to name the actual verb groups left after the
facts pass.
- web-ui/README.md: the swarm/ui.md pointer no longer promises roster/
creating-agents/linking-accounts content that page doesn't have.
- Reverted the unrelated doesn't/does not drive-by at hivectl/README.md:5.
docs/web-ui/README.md now frames itself as the per-hive dashboard (host
approvals, container state, rebuild queue) and points to swarm/ui.md for
swarm-wide day to day, matching the README's swarm-first reframe.
Credentials page fixes: it has only a GitHub PAT tab now (2c7e586f
removed the FORGES tab and moved external forge accounts to the swarm
UI; credentials.html never had a matrix tab).
hivectl/README.md: agents.rs has no create verb (hivectl-cli.md has no
'create' entry; agents.rs's create is swarm-level, swarmctl agent
create). forge.rs reconciles config, it doesn't provision an account;
matrix.rs/github.rs do agent-scoped invites/token writes; gateway.rs
manages the gateway's own htpasswd users — split out of the former
single 'per-integration account/token provisioning' line.
Fix the 4 pre-existing vale error-level hits on main (docs/README.md:83,
docs/getting-started/setup.md:11,127, docs/swarm/bao.md:4) that fail CI's
prose-lint-errors job for every docs PR regardless of its own diff.
An operator now links an agent's external forge account (label, base URL,
token) in the swarm UI. swarm-controller stores it at
swarm/agents/<agent>/forge/<label>. There is no index: the store's
listing of the agent's forge/ directory is the set of accounts.
In the agent, hive-agent-forge-accounts (oneshot + 2-minute timer, as
the agent user, under its own store certificate) lists
swarm/agents/<agent>/forge/ with the `list` #4866 grants an agent on its
own metadata subtree, reads each account, and writes
<state>/forge-<label>-token and forge-<label>.json in the names and shape
hive-forge -f already reads. An empty listing (a 404, which `bao kv list
-format=json` answers with `{}` and an empty stderr) is zero accounts; a
denial or an unreachable store fails the unit. It never deletes: files
for labels not listed, including ones the hive wrote, stay as they are.
Removed: the dashboard FORGES tab (credentials.js/html section and its
CSS), hive-c0re's extra_forges.rs and its routes, priv_client's
extra-forge calls, and hive-priv's WriteAgentExtraForgeAccount /
DeleteAgentExtraForgeAccount with their helpers. The GITHUB tab and
WriteAgentGithubToken stay.
Also: persistence.md's matrix avatar note names the exit-75 restart on a
changed account listing, not the dashboard, as what brings a linked
account up.
Refs #4348
hive-matrix-daemon now learns which external matrix accounts it has from
the swarm secret store, under the agent's own certificate, and the hive
push chain for matrix is gone.
The daemon lists swarm/agents/<agent>/matrix/ (the `list` its policy
grants on its own metadata subtree), reads each account's homeserver
from its credential, and brings the accounts up with their tokens from
the store. Every two minutes it lists again and exits with 75 when the
set of linked accounts changed; the unit restarts on 75 without counting
a failure. A listed name whose credential reads as absent is skipped and
logged once. At start it removes the matrix-token-<a> /
matrix-account-<a>.json pairs a hive delivered (a sidecar marks a pair
as delivered; a declared tokenFile keeps its token).
Removed: CredentialNotice and the $SWARM.credential.* subject and NATS
grant, the controller's publish and its queue precondition on the PUT
route, hive-c0re's credential subscription arm and workers/credential.rs,
priv_client::write_agent_matrix_token, hive-priv's WriteAgentMatrixToken
and its helpers, and the daemon's state-dir account discovery.
Kept: WriteAgentGithubToken and the external-forge path
(WriteAgentExtraForgeAccount, extra_forges.rs) are untouched, and a
declared matrixAccounts tokenFile is still read when the store has no
token for that account.
Refs #4348
render_agent gains a second stanza: list on
secret/metadata/swarm/agents/<agent>/*, next to the existing read on
secret/data/swarm/agents/<agent>/*. An agent can now learn which
credentials it holds by listing its own subtree. Metadata read, writes
and every other principal's paths stay refused.
An agent's policy was only written when it was minted, so existing agents
would never get the new stanza. swarm-controller now rewrites every
agent's policy at start (read_policy::ensure_agent_policies), with the
same 30s / 24h retry as ensure_hive_access. The roster is the store's
hive-agent-* cert-auth roles, listed with the controller's existing
`list` on auth/cert/certs; the writes use its existing grant on
sys/policies/acl/hive-*. Only the policy is written: mint_and_verify
also reissues the certificate, so the pass does not call it.
Refs #4348
`swarm.forge` (what the forge is to every hive: ports, domain, public and
root URLs, OIDC client id and callback) moves to
nix/host-modules/hive-forge/service.nix, together with the rename of the
old `services.hyperhive.forge` tree and the removed `swarm.forge.sso.enable`,
both of which name `swarm.forge` paths. Everything else -- the
`deploy.forgejo` options, the whole `config` block including
`containers.hive-forge`, and the helpers only they read -- stays in
nix/host-modules/hive-forge/default.nix, which now imports ./service.nix.
Importing it from the directory's own default.nix, as hive-c0re/ and
hive-gateway/ do with their option files, keeps the flake's standalone
`nixosModules.hive-forge` export whole.
Both halves read `cfg`, `gatewayCfg`, `swarmDomain` and `deployCfg`. They
are option reads, so each file binds them from `config`. `ssoSourceName`,
`defaultRootUrl` and `effectiveRootUrl` are not options and both halves
need them (the service half builds `sso.redirectUri` from them, the deploy
half registers the login source and sets ROOT_URL), so they are duplicated,
with a note at each copy. `ssoRedirectUri` is read only by the service
half and moves.
`swarm.forge.publicUrl` and `swarm.forge.sso.redirectUri` default from
`deploy.forgejo.behindGateway`; both move as they are.
A pure move: option paths, option definitions and config are unchanged
apart from comments: the two on either side of the cut, the
`ssoRedirectUri` comment and the duplication notes, and the rename
precedent in ./deploy.nix, which now names ./hive-forge/service.nix.
Refs #3742
Four comments pointed at ./swarm-otel.nix for something the split moved
to ./swarm-otel-service.nix: `domain` (otel.nix), `domainBase`
(swarm-ui.nix), the `clientId`/`audience` options
(glue-swarm-otel-oidc-client.nix), and `producerName` (swarm-otel.nix's
own "Read-only option below"). Every other pointer to ./swarm-otel.nix
names its `config` block, units, exporters, authenticators or
assertions, which stayed.
Refs #3742
`swarm.otel` (what the swarm collector is to every hive: its domain,
receiver ports, producer names, client id and the audiences that client
may present) moves to nix/host-modules/swarm-otel-service.nix, together
with the `journaldUnits` removal module and the helpers its defaults
read. Everything else -- the `deploy.swarm-otel` options, the whole
`config` block including `containers.swarm-otel`, and the helpers only
they read -- stays in nix/host-modules/swarm-otel.nix, which default.nix
now imports after the new file.
The service file needs `domainBase` (for `domain`), `baoCfg` (for
`storeProducerName`) and `cfg` plus `pushAudiences` (for `audience`).
`swarmDomain` and `domainBase` move. `cfg`, `hyperhiveCfg`, `baoCfg`,
`vmCfg`, `vlCfg`, `metricsPushUrl`, `logsPushUrl` and `pushAudiences`
are read on both sides and none is an option, so each is bound in both
files; the comments on the push URLs say the two copies must agree.
`swarmCfg` was bound and never read, so neither file carries it.
A pure move: option paths, option definitions and config are unchanged.
Comments changed: the transition comment above `deploy.swarm-otel` now
names the file `swarm.otel` lives in, and the push-URL and
`pushAudiences` comments now describe the per-file readers and the
duplicate. Three otel fixtures evaluate to the same host and container
toplevel derivations, `swarm.otel.*` and `deploy.swarm-otel.*` values
before and after.
Refs #3742
nix/module-eval/bao-controller.nix:49 quoted `gatewayHost`'s description
as `hive-matrix.nix`'s own doc. The option now lives in
hive-matrix-service.nix, so the pointer names that file.
Refs #3742
`swarm.matrix` (what the homeserver is to every hive: server name, ports,
API URL, gateway host, encryption policy, OIDC client id) moves to
nix/host-modules/hive-matrix-service.nix. Everything else -- the
`imports` block with its two renames and the removed `sso.enable`, the
`deploy.matrix` options, the whole `config` block including
`containers.hive-matrix`, and every other let binding -- stays in
nix/host-modules/hive-matrix.nix, which default.nix now imports alongside
the new file.
The `swarm.matrix` block reads three let bindings, and the `config` block
reads all three too: `cfg` (`apiUrl` defaults from `cfg.httpPort`),
`swarmDomain` (`gatewayHost`'s default) and `deployCfg` (`apiUrl` reads
`deployCfg.matrix.enable`). All three are option reads, so each file binds
them from `config.services.hyperhive.*`. Nothing is duplicated.
A pure move: option paths, option definitions and config are unchanged
apart from the comment above `deploy.matrix`, which now names the file
`swarm.matrix` lives in.
Refs #3742
`swarm.authelia` (what the SSO provider is to every hive: ports, domain,
`url`, the OIDC client register, the published names and the bridge's
address) moves to nix/host-modules/swarm-authelia-service.nix. Everything
else -- the `deploy.authelia` options, the whole `config` block including
`containers.swarm-authelia`, and the helpers only they read -- stays in
nix/host-modules/swarm-authelia.nix, which default.nix now imports
alongside the new file.
Both halves read four `let` bindings. `cfg`, `swarmDomain` and `deployCfg`
are option reads, so each file binds them from `config`; the service file
has no `hyperhiveCfg`, so it spells the paths out, as
swarm-nats-service.nix does. `instance` and `unitName` are literals, not
options, so the service file carries its own copy of the two (`unit`'s
default reads `unitName`). `deployCfg` is in the service file only for
`bridgeUrl`'s default, which is moved as it is.
`hyperhiveDomain` had no reader and is dropped rather than carried into
either file.
A pure move: option paths, option definitions and config are unchanged
apart from three comments that pointed "above"/"below" across the new
file boundary and now name the file. Authelia's container toplevel, the
host toplevel (with `c0re.hyperhiveFlake` pinned, since the flake source
path lands in /etc/hyperhive/serve.json), the `swarm.authelia` and
`deploy.authelia` values and option set, and the eleven
module-eval checks that enable authelia evaluate to the same derivations
before and after.
Refs #3742
`swarm.victorialogs` (what the log store is to every hive: container name,
domain, port) moves to nix/host-modules/swarm-victorialogs-service.nix,
together with the only two helpers it reads, `swarmDomain` and
`domainBase`. Everything else -- the `deploy.victorialogs` options, the
whole `config` block including `containers.swarm-victorialogs`, the file
header and the helpers only they read (`swarmAuthRequest` among them) --
stays in nix/host-modules/swarm-victorialogs.nix, which default.nix now
imports alongside the new file.
`hyperhiveCfg` (an alias for `config.services.hyperhive`, not an option) is
read by both halves, so it is duplicated into the service file rather than
shared.
A pure move: option paths, option definitions and config are unchanged
apart from the comment above the `deploy.victorialogs` options, which now
names the file `swarm.victorialogs` lives in. Fixtures enabling the store
evaluate to the same host and container toplevel derivations before and
after.
Refs #3742
`swarm.victoriametrics` (what the metrics store is to every hive: container
name, domain, port) moves to nix/host-modules/swarm-victoriametrics-service.nix,
together with the only two helpers it reads, `swarmDomain` and `domainBase`.
Everything else -- the `deploy.victoriametrics` options, the whole `config`
block including `containers.swarm-victoriametrics`, the file header and the
helpers only they read -- stays in nix/host-modules/swarm-victoriametrics.nix,
which default.nix now imports alongside the new file.
`hyperhiveCfg` (an alias for `config.services.hyperhive`, not an option) is
read by both halves, so it is duplicated into the service file rather than
shared.
A pure move: option paths, option definitions and config are unchanged
apart from the comment above the `deploy.victoriametrics` options, which now
names the file `swarm.victoriametrics` lives in. Fixtures enabling the store
evaluate to the same host and container toplevel derivations before and
after.
Refs #3742
glue-swarm-bao-otel-oidc-client.nix:34 still pointed clientId's
declaration at ./swarm-bao.nix after the split moved it to
./swarm-bao-service.nix. Line 17, which points the config block's
deploy.bao.enable gate at ./swarm-bao.nix, is unchanged -- that part
stayed.
`swarm.bao` (what the secret store is to every hive: container name,
domain, UI domain and OIDC client, port, collector client id and
telemetry port) moves to nix/host-modules/swarm-bao-service.nix, together
with `domainBase`, the only helper it reads besides `cfg`. Everything
else -- the `deploy.bao` options, the removed-option import, the whole
`config` block including `containers.swarm-bao`, and the helpers only
they read -- stays in nix/host-modules/swarm-bao.nix, which default.nix
now imports alongside the new file.
Both halves read `cfg` (`swarm.bao.ui.oidc.redirectUri` defaults from
`cfg.ui.domain`; the config block reads `cfg` throughout). It is an
option read, so each file binds it from `config.services.hyperhive.swarm.bao`.
The service file has no `hyperhiveCfg`, so its `swarmDomain` reads
`config.services.hyperhive.swarm.domain` directly, as
swarm-nats-service.nix does.
A pure move: option paths, option definitions and config are unchanged
apart from the comment above `deploy.bao`, which now names the file
`swarm.bao` lives in, and the pointer in swarm-nats-service.nix to the
`domainBase` rationale, which moved with it.
Refs #3742
