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