docs(persistence): reframe stale 'the manager' as the root agent

Config-repo editor, meta RO-mount, non-destroyable container, and the
topology.json example now refer to the root agent / bootstrap container
rather than 'the manager'. The /run/hyperhive/manager/mcp.sock path is a
real runtime path, kept (clarified as the root agent's manager-flavour
socket).
This commit is contained in:
iris 2026-06-23 12:01:40 +02:00 committed by mara
commit adb76f3cdf

View file

@ -180,16 +180,16 @@ Survives destroy/recreate, gone on `--purge`.
Under `/var/lib/hyperhive/agents/<name>/`:
- `config/` — the proposed nix repo (manager-editable). Bind-mounted
- `config/` — the proposed nix repo (root-agent-editable). Bind-mounted
**read-only** to `/agents/<name>/config` inside the sub-agent's own
container so the agent can inspect what defines it and request
precise changes from the manager; RW into the manager via the
precise changes from the root agent; RW into the root agent via the
`/agents` tree bind.
- `claude/` — claude OAuth credentials, bind-mounted RW to
`/home/<name>/.claude` inside the container.
- `state/` — durable notes and `hyperhive-harness.json`. Bind-mounted
to `/agents/<name>/state` inside the container (uniform for
sub-agents + manager). The `$HYPERHIVE_STATE_DIR` env var exposes
all agents — sub-agents + root). The `$HYPERHIVE_STATE_DIR` env var exposes
the same path to in-container scripts. Notable files written here
by the harness:
- `hyperhive-status` — single-line free-text status string written
@ -237,8 +237,8 @@ sibling's.
Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
applied repo. Tracks `flake.nix` (module-only boilerplate; never
edited after first spawn) + `agent.nix` (the actual config; the
manager's edits land here via the approval flow) + any other
files the manager committed. `.git/` carries the proposal /
root agent's edits land here via the approval flow) + any other
files committed via the approval flow. `.git/` carries the proposal /
approved / building / deployed / failed / denied tag history.
Under `/var/lib/hyperhive/meta/` — the swarm-wide deploy flake plus
@ -251,7 +251,7 @@ Contents:
canonical "what's deployed where." The git log is the deploy
audit trail (one commit per successful deploy or hyperhive bump).
- `topology.json` — parent/child agent graph
(`{ "alice": "manager", "bob": "alice", "manager": null }`).
(`{ "alice": "root", "bob": "alice", "root": null }`).
Written by `topology::set_parent`; read by the dashboard, the
renderer, and `<parent>` / `<children>` recipient resolution.
- `tool-groups.json` — per-agent MCP tool group grants
@ -263,7 +263,7 @@ Contents:
`capabilities::set_caps`; injected as `HIVE_CAPABILITIES` env
var. Absent agents have no extra capabilities.
Manager has the meta dir RO-mounted at `/meta/`.
The root agent has the meta dir RO-mounted at `/meta/`.
Marker file `/var/lib/hyperhive/.meta-migration-done` is
written by the startup migration after every container has
@ -285,8 +285,8 @@ step would re-fire).
claude creds, /state/ notes, and the harness dir are all gone.
No undo.
The manager is non-destroyable from both paths (declarative
container; would fight with the host's NixOS config).
The root/bootstrap container is non-destroyable from both paths
(declarative container; would fight with the host's NixOS config).
### btrfs subvolumes for `/var/lib/hyperhive/agents/<name>`
@ -323,7 +323,8 @@ Without that, every restart wipes bind sources and existing
containers can't be started.
- `/run/hyperhive/host.sock` — admin socket (host-side CLI).
- `/run/hyperhive/manager/mcp.sock` — manager-privileged socket.
- `/run/hyperhive/manager/mcp.sock` — the root agent's privileged
(manager-flavour) socket.
- `/run/hyperhive/agents/<name>/mcp.sock` — per-sub-agent socket
(bind-mounted into the container as `/run/hive/mcp.sock`).