diff --git a/docs/coordinator.md b/docs/coordinator.md index e915b0a4..9dadde45 100644 --- a/docs/coordinator.md +++ b/docs/coordinator.md @@ -38,7 +38,7 @@ somewhere." | `MetaUpdate` | `nix flake update` on the meta flake. The worker runs the lock bump itself, then enqueues a cascade of `Rebuild` entries with `parent_id` set to the meta-update's id. | | `Spawn` | First-deploy of a new agent (approval-driven). Same serialisation as `Rebuild` from the operator's POV. | | `Destroy` | For future use (`destroy --purge` does real I/O). Variant exists so the wire shape doesn't change later; not currently routed through the queue. | -| `Restart` | Stop + start a container without touching config (~5-10s). Routed through the queue so it serialises against in-flight rebuilds for the same agent — prevents a restart racing a rebuild mid-flight. Sources: dashboard ↺ button, manager `restart` MCP tool. | +| `Restart` | Stop + start a container without touching config (~5-10s). Routed through the queue so it serialises against in-flight rebuilds for the same agent — prevents a restart racing a rebuild mid-flight. Sources: dashboard ↺ button, the `restart` MCP tool. | | `PermChange` | Write a tool-group or capability change to the shared JSON file (`tool-groups.json` / `capabilities.json`), then rebuild the agent so the updated `HIVE_TOOL_GROUPS` / `HIVE_CAPABILITIES` env var takes effect. Serialising the file write through the queue prevents concurrent dashboard batch-apply actions from racing on the shared file. After a successful file write, emits `CapabilitiesChanged` or `ToolGroupsChanged` SSE snapshot so the P3RM1SS10NS tab updates live. | | `GracefulStop` | Quiesce then stop a container (the `?graceful=1` path on `/kill/`). Signals the harness (its next `Recv` returns `GracefulStop` — the inbound fence — so it runs one stop-checkpoint turn to flush durable `/state`, then exits), waits for it to drain (bounded by a 3-min timeout → hard-stop fallback), then runs the normal container-stop teardown. Queued so it can't race an in-flight rebuild for the same agent. | @@ -55,7 +55,7 @@ since the current run started). | Source | Meaning | |--------|---------| -| `Manual` | Operator clicked rebuild / update-all / meta-update on the dashboard, or any other direct human action (CLI, manager tool). | +| `Manual` | Operator clicked rebuild / update-all / meta-update on the dashboard, or any other direct human action (CLI, an agent MCP tool). | | `AutoUpdate` | Legacy startup-sweep source (flat, no parent). Replaced by `StartupSweep` for new boots. | | `StartupSweep` | Child of a `StartupSweep` parent entry; boot-time per-agent rebuild with the sweep as the visual group header. | | `Approval` | Triggered by an operator-approved `ApprovalKind::{Spawn, ApplyCommit}`. | diff --git a/docs/gateway.md b/docs/gateway.md index d223b110..14b08c36 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -269,9 +269,9 @@ firewall-open would defeat the single-front-door story. `httpsPort` — the gateway always terminates TLS (self-signed floor), so both are always served. -The manager hashes into the same port range as sub-agents (no -"manager pinned at 8000" special case), so one range opening covers -every container. +The root/bootstrap container hashes into the same port range as +sub-agents (no special case), so one range opening covers every +container. The dashboard port (`cfg.dashboardPort`, default 7000) is *not* listed in either case — it binds `127.0.0.1` only, so a firewall diff --git a/docs/gotchas.md b/docs/gotchas.md index bfbf8305..bce915c7 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -96,7 +96,7 @@ across `destroy`/recreate (`--purge` wipes them). ## Persistent notes dir per agent `/var/lib/hyperhive/agents//state/` bind-mounts to -`/agents//state` (RW; uniform for sub-agents + manager). +`/agents//state` (RW; uniform for all agents — sub-agents + root). The harness exposes the same path via `$HYPERHIVE_STATE_DIR`. System prompts tell agents to keep durable knowledge here (`notes.md`, anything else). The harness also @@ -112,7 +112,7 @@ unlucky. Operator resolves a collision by renaming the offending agent (different hash → different port) and rebuilding. No state file, no probing, no port-allocation drift — the value is reproducible from just the name. Every agent — including the -manager — hashes into 8100..8999 via the same FNV-1a; dashboard +root/bootstrap container — hashes into 8100..8999 via the same FNV-1a; dashboard at `cfg.dashboardPort` (default 7000). ## Restart races on TCP bind diff --git a/docs/network.md b/docs/network.md index 0f3d9330..f40e9308 100644 --- a/docs/network.md +++ b/docs/network.md @@ -130,7 +130,7 @@ address arithmetic. `lifecycle::set_nspawn_flags` when creating or updating containers. Each agent gets a deterministic IP derived from its name so the address is reproducible across destroy/recreate. This applies uniformly to all -containers including the manager — no special case. +containers including the root/bootstrap container — no special case. `HOST_ADDRESS` is the bridge gateway IP (the address part of `HIVE_NETWORK_SUBNET`, via `lifecycle::bridge_gateway_ip` — taken verbatim @@ -163,9 +163,9 @@ wiring is runtime: an instant no-op in shared-netns mode (the marker is absent, so `ConditionPathExists` skips it). -**Why isolation is safe for the manager**: all hive-c0re communication goes +**Why isolation is safe for the root agent**: all hive-c0re communication goes through unix domain sockets (`/run/hive/mcp.sock` for agent requests, -`/run/hive/priv.sock` for privileged ops, per-agent manager sockets). +`/run/hive/priv.sock` for privileged ops, per-agent privileged sockets). These are bind-mounted into containers via the nspawn conf. UDS paths traverse the VFS, not the network stack, so `PRIVATE_NETWORK=1` does not affect them. diff --git a/docs/security.md b/docs/security.md index cebfb621..14fd6d44 100644 --- a/docs/security.md +++ b/docs/security.md @@ -110,7 +110,7 @@ known operations; there is no arbitrary command pass-through: **Container allowlist** — every request is validated against an allowlist before any operation: only names matching `h-` (the -standard agent prefix), the manager container, or the known sibling +standard agent prefix), the root/bootstrap container, or the known sibling service containers (`hive-gateway`, `hive-forge`, `hive-matrix`, `hive-ci`) are accepted. Arbitrary container names are rejected. diff --git a/docs/web-ui.md b/docs/web-ui.md index ed52f3d3..4231fda6 100644 --- a/docs/web-ui.md +++ b/docs/web-ui.md @@ -1,8 +1,8 @@ # Web UI Two web surfaces share the same skeleton: the dashboard (port 7000) -and the per-agent UIs (every container — including the manager — -hashes into :8100-8999 via `lifecycle::agent_web_port`'s FNV-1a). +and the per-agent UIs (every container — including the root/bootstrap +container — hashes into :8100-8999 via `lifecycle::agent_web_port`'s FNV-1a). Both are SPAs — `GET /` returns a static shell, `/api/state` returns JSON, JS renders. No full-page reloads.