From e9e4408af1d5f72eace78e45353aea8649a80d76 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:51:18 +0200
Subject: [PATCH 01/64] docs(gotchas): group entries by area, fix misplaced
 nix-fmt section

---
 docs/gotchas.md | 148 +++++++++++++++++++++++++++---------------------
 1 file changed, 84 insertions(+), 64 deletions(-)

diff --git a/docs/gotchas.md b/docs/gotchas.md
index 6cbc7f9c..b5bf6782 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -2,8 +2,12 @@
 
 NixOS + nspawn quirks and lessons we hit the hard way. If something
 here looks unmotivated in the code, there's usually a story underneath.
+Grouped by area — jump to the section that matches what you're
+touching.
 
-## `nixos-container` doesn't expose `--bind` on the CLI
+## NixOS / nspawn containers
+
+### `nixos-container` doesn't expose `--bind` on the CLI
 
 The CLI doesn't accept `--bind`. Path is via `EXTRA_NSPAWN_FLAGS` in
 `/etc/nixos-containers/<NAME>.conf` — the start script
@@ -11,18 +15,18 @@ The CLI doesn't accept `--bind`. Path is via `EXTRA_NSPAWN_FLAGS` in
 `systemd-nspawn` invocation. `lifecycle::set_nspawn_flags()` rewrites
 this line.
 
-## `/run/systemd/nspawn/*.nspawn` overrides are ignored
+### `/run/systemd/nspawn/*.nspawn` overrides are ignored
 
 `nixos-container`'s start script builds the nspawn command line
 directly. Dropping a `.nspawn` file under `/run/systemd/nspawn/`
 looks like the obvious extension point and does nothing. Use
 `EXTRA_NSPAWN_FLAGS` (above).
 
-## `boot.isNspawnContainer = true`
+### `boot.isNspawnContainer = true`
 
 Not `boot.isContainer = true`. Renamed in nixos-25.11+.
 
-## `nixos-container create` auto-assigns `HOST_ADDRESS` / `LOCAL_ADDRESS`
+### `nixos-container create` auto-assigns `HOST_ADDRESS` / `LOCAL_ADDRESS`
 
 …in the `.conf`. The start script's `if HOST_ADDRESS set →
 --network-veth` branch then forces a private netns — silently fatal
@@ -30,7 +34,7 @@ for our web UIs (the bind is invisible from the host). We
 force-clear `HOST_ADDRESS` / `LOCAL_ADDRESS` / `HOST_ADDRESS6` /
 `LOCAL_ADDRESS6` / `HOST_BRIDGE` and set `PRIVATE_NETWORK=0`.
 
-## systemd service PATH ≠ host PATH
+### systemd service PATH ≠ host PATH
 
 The hive-c0re service sets `path = [ pkgs.git "/run/current-system/sw" ]`.
 In-container harness services do the same so anything an agent adds
@@ -40,7 +44,7 @@ editing the service definition.
 `environment.HYPERHIVE_GIT` bakes git's absolute path in (read by
 `lifecycle::git_command()`) for the host.
 
-## `systemd.services.*.path` appends `/bin` to every entry
+### `systemd.services.*.path` appends `/bin` to every entry
 
 NixOS's `systemd.services.<unit>.path` list feeds every entry through
 `lib.makeBinPath`, which **appends `/bin` unconditionally**. That's
@@ -62,19 +66,21 @@ contains a non-existent directory. The first symptom is usually
 the setuid sudo wrapper lives at `/run/wrappers/bin/sudo` and
 the path entry resolves to `/run/wrappers/bin/bin` instead.
 
-## `RuntimeDirectoryPreserve = "yes"`
+### `RuntimeDirectoryPreserve = "yes"`
 
 …keeps `/run/hyperhive/` (and the per-agent sub-dirs) across
 hive-c0re restarts. Without it, every restart wipes bind sources and
 existing containers can't be started.
 
-## `register_agent` is idempotent
+### `register_agent` is idempotent
 
 Drops any prior socket task before rebinding. Required so a
 hive-c0re restart followed by `rebuild alice` recreates the agent's
 socket without needing a clean reinstall.
 
-## `claude-code` is unfree
+## Claude Code packaging & credentials
+
+### `claude-code` is unfree
 
 `claude-code` comes from the flake's main `nixpkgs` (nixos-26.05).
 It's unfree, so the agent modules set `config.allowUnfreePredicate`
@@ -125,7 +131,7 @@ the hive's `claude` out from under it. The price of the root is that an
 old `claude-code` can't be reclaimed until every agent has rebuilt past
 it and the old generations are gone.
 
-## Claude credentials are per-agent
+### Claude credentials are per-agent
 
 `/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to
 `/home/<name>/.claude` (RW). Sharing one dir across agents is NOT viable —
@@ -133,7 +139,7 @@ OAuth refresh tokens rotate, so any sibling refresh invalidates all
 the others. Login flow runs from the per-agent web UI; creds persist
 across `destroy`/recreate (`--purge` wipes them).
 
-## Persistent notes dir per agent
+### Persistent notes dir per agent
 
 `/var/lib/hyperhive/agents/<name>/state/` bind-mounts to
 `/agents/<name>/state` (RW; uniform for all agents).
@@ -143,7 +149,9 @@ durable knowledge here (`notes.md`, anything else). The harness also
 writes its events log here (`hyperhive-events.sqlite`).
 Survives `destroy`/recreate alongside the claude dir.
 
-## Web UI ports collide on hash
+## Networking & ports
+
+### Web UI ports collide on hash
 
 Sub-agent web UI ports are deterministic FNV-1a of the agent name
 modulo 900 (range 8100..8999). With ~30 agents the birthday-paradox
@@ -155,7 +163,7 @@ reproducible from just the name. Every agent hashes into
 8100..8999 via the same FNV-1a; dashboard
 at `cfg.dashboardPort` (default 7000).
 
-## Restart races on TCP bind
+### Restart races on TCP bind
 
 Both the dashboard and per-agent web UI use `tokio::net::TcpSocket`
 with `SO_REUSEADDR` plus a retry-on-`AddrInUse` loop (12 tries,
@@ -166,22 +174,18 @@ overlap" case. REUSEADDR does **not** allow two simultaneous
 `LISTEN` sockets on the same port (that would be `SO_REUSEPORT`,
 which we don't use) — exclusivity is preserved.
 
-## Orphan approvals
+## Approvals
+
+### Orphan approvals
 
 If state dirs are wiped out from under a pending approval (test
 scripts, manual `rm -rf`), the dashboard's next render marks them
 `failed` with note `"agent state dir missing"` so they fall out of
 `pending`. They stay in sqlite for audit.
 
-## Nix store `cp -r` preserves read-only bits
+## Gateway / SPA serving
 
-Copying a nix store path with `cp -r src/. $out/` inside a
-`pkgs.runCommand` derivation preserves the read-only permissions of
-store files. Any subsequent write into the copied tree (adding new
-files in subdirectories) fails with `EPERM`. Fix: pass
-`--no-preserve=mode,ownership` so the output tree is writable.
-
-## SPA fallback: use `Accept` header map, not `try_files ... /index.html`
+### SPA fallback: use `Accept` header map, not `try_files ... /index.html`
 
 The naive nginx pattern for a path-prefix SPA (`try_files $uri $uri/
 /matrix/index.html`) silently swallows asset 404s — a missing JS file
@@ -210,7 +214,17 @@ firefox / safari are consistent). Asset fetches (`image/*`,
 fall through to the trailing `=404`. No extension list to maintain;
 no named-location indirection needed.
 
-## `nix build flake#name` does not walk into `nixosConfigurations`
+## Build & dev workflow
+
+### Nix store `cp -r` preserves read-only bits
+
+Copying a nix store path with `cp -r src/. $out/` inside a
+`pkgs.runCommand` derivation preserves the read-only permissions of
+store files. Any subsequent write into the copied tree (adding new
+files in subdirectories) fails with `EPERM`. Fix: pass
+`--no-preserve=mode,ownership` so the output tree is writable.
+
+### `nix build flake#name` does not walk into `nixosConfigurations`
 
 `nix build` resolves the fragment (`#name`) against the flake's
 **top-level output attrs** — not against `nixosConfigurations`
@@ -233,12 +247,7 @@ instead of `meta#nixosConfigurations.argus.config…`. The fix:
 `split_once('#')` to separate flake path from name, then template
 `{path}#nixosConfigurations.{name}.config.system.build.toplevel`.
 
-## `hive-forge`: prefer over raw curl pipelines
-
-Full CLI reference: [`docs/tools/forge.md`](tools/forge.md).
-Never use raw `curl` for forge access.
-
-## Containerized nix-daemon needs `sandbox-fallback = true`
+### Containerized nix-daemon needs `sandbox-fallback = true`
 
 Agent containers bind-mount the host's nix-daemon socket. nspawn
 containers don't get user-namespaces by default, so `nix build`
@@ -249,7 +258,7 @@ and fail outright if the host daemon's
 fall back to unsandboxed local builds rather than failing. Security
 implications: `docs/security.md`.
 
-## Linking workspace binaries locally needs `nix develop`
+### Linking workspace binaries locally needs `nix develop`
 
 The Rust workspace links `libsqlite3-sys` (rusqlite) against the
 system `libsqlite3`. Agent containers carry no system libsqlite3 on
@@ -271,7 +280,7 @@ e.g. `docs/tools/hivectl-cli.md` via the `hivectl markdown-docs`
 subcommand (its `hivectl-docs` flake check otherwise only fails in
 CI on drift).
 
-## Split asset derivations away from the rust workspace
+### Split asset derivations away from the rust workspace
 
 `nix/packages/assets.nix` builds the branding SVG/PNG family + claude
 system-prompt template + claude-settings JSON as its own derivation,
@@ -285,7 +294,46 @@ The agent-configs PNG is rendered from the SVG via `rsvg-convert` at
 build time; librsvg dependency lives here, not in the rust
 derivation's `nativeBuildInputs`.
 
-## Weston VNC compositor (per-agent `hyperhive.gui.enable`)
+### `nix fmt` fails in a git worktree with "object not found"
+
+`nix fmt` (and any `nix` command that fetches a `git+file://` flake
+URL) uses libgit2 internally to compute `revCount` — the number of
+commits reachable from HEAD. This walk fails with:
+
+```
+error: getting Git object '<hash>': object not found (libgit2 error code = 9)
+```
+
+when a commit that was reachable at some earlier evaluation is now gone
+(GC'd, rebased away, or pruned). The failure is persistent: clearing
+`~/.cache/nix/{eval-cache-v6,gitv3,fetcher-cache-v4.sqlite}` does not
+help because the missing object is a structural gap in the git object
+graph itself, not in nix's caches.
+
+**Workaround: use a plain clone, not a git worktree.**
+
+```bash
+git clone http://<forge>/hyperhive/hyperhive.git ~/hh-work
+cd ~/hh-work && nix fmt
+```
+
+The root cause is specific to worktrees: a worktree shares the object
+store with its parent repo. If the parent repo's history was rewritten
+(rebase, force-push, `git gc --prune`) while the worktree was checked
+out at a branch tip that references the pruned commits via its reflog or
+history, libgit2's rev-walk encounters the gap. A plain clone has its
+own self-consistent object store and is immune to the issue.
+
+## Tooling
+
+### `hive-forge`: prefer over raw curl pipelines
+
+Full CLI reference: [`docs/tools/forge.md`](tools/forge.md).
+Never use raw `curl` for forge access.
+
+## GUI (weston/VNC)
+
+### Weston VNC compositor (per-agent `hyperhive.gui.enable`)
 
 `nix/agent-modules/weston-vnc.nix` adds an optional Weston Wayland
 compositor with the VNC backend, surfaced as
@@ -361,7 +409,9 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
   `wl_event_source_timer_update` treats as "disarm", so the
   compositor never goes idle and never locks.
 
-## Nix options reference (`nix/docs/default.nix`)
+## Nix docs pipeline
+
+### Nix options reference (`nix/docs/default.nix`)
 
 `pkgs.nixosOptionsDoc` over two evaluated module trees:
 `hostEval` (a stub NixOS system loading the `nix/host-modules/` aggregator with every
@@ -397,7 +447,7 @@ options tree picks up everything under that root — picking against
 stray roots produces an empty tree and renders the host page as
 template chrome with no `<h2>` headers.
 
-### Docs drv stability: `nixSrc`
+#### Docs drv stability: `nixSrc`
 
 Naively, the docs evaluation depends on `self` (the flake's store path),
 so every commit — even Rust-only or frontend-only changes — produces new
@@ -426,33 +476,3 @@ Why `builtins.unsafeDiscardStringContext`? The path string
 make `builtins.path` include `self` as a build dependency even after
 content-addressing the directory. Discarding the context makes the
 resulting `nixSrc` truly independent of `self`'s store path.
-
-### `nix fmt` fails in a git worktree with "object not found"
-
-`nix fmt` (and any `nix` command that fetches a `git+file://` flake
-URL) uses libgit2 internally to compute `revCount` — the number of
-commits reachable from HEAD. This walk fails with:
-
-```
-error: getting Git object '<hash>': object not found (libgit2 error code = 9)
-```
-
-when a commit that was reachable at some earlier evaluation is now gone
-(GC'd, rebased away, or pruned). The failure is persistent: clearing
-`~/.cache/nix/{eval-cache-v6,gitv3,fetcher-cache-v4.sqlite}` does not
-help because the missing object is a structural gap in the git object
-graph itself, not in nix's caches.
-
-**Workaround: use a plain clone, not a git worktree.**
-
-```bash
-git clone http://<forge>/hyperhive/hyperhive.git ~/hh-work
-cd ~/hh-work && nix fmt
-```
-
-The root cause is specific to worktrees: a worktree shares the object
-store with its parent repo. If the parent repo's history was rewritten
-(rebase, force-push, `git gc --prune`) while the worktree was checked
-out at a branch tip that references the pruned commits via its reflog or
-history, libgit2's rev-walk encounters the gap. A plain clone has its
-own self-consistent object store and is immune to the issue.

From f500863f2f03673dc471396fae03da4e1d3e89f7 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:51:22 +0200
Subject: [PATCH 02/64] docs(turn-loop): fix crate-count claim, trim historical
 framing

---
 docs/turn-loop/README.md | 36 ++++++++++++++----------------------
 1 file changed, 14 insertions(+), 22 deletions(-)

diff --git a/docs/turn-loop/README.md b/docs/turn-loop/README.md
index ee382050..71baa55c 100644
--- a/docs/turn-loop/README.md
+++ b/docs/turn-loop/README.md
@@ -65,11 +65,10 @@ agents) runs:
 
 ## Harness binary shape
 
-Two sibling binaries out of the one `hive-ag3nt` crate, all
-role-agnostic. (The earlier split into `hive-ag3nt` + `hive-m1nd`
-was collapsed because the privilege boundary lives server-side at
-the broker socket (`/run/hive/mcp.sock`): `ManagerRequest` calls are
-refused by the standard agent socket regardless of who sends them.)
+Two sibling crates, both role-agnostic (there is one role: agent —
+the privilege boundary lives server-side at the broker socket
+(`/run/hive/mcp.sock`), which refuses `ManagerRequest` calls regardless
+of who sends them):
 
 - `hive-agent` — long-running harness loop (the inbox poll +
   claude-pump + ack/requeue cycle described above).
@@ -80,18 +79,11 @@ refused by the standard agent socket regardless of who sends them.)
   transport — no per-turn stdio child (eliminates the re-registration
   race).
 
-### `Surface` trait + zero-sized type tags
-
-`AgentRequest` / `AgentResponse` (= `ManagerRequest` / `ManagerResponse` —
-type aliases) are the wire types. There is one role: agent.
-`bin/hive-agent.rs` factors the turn loop through a `Surface` trait
-with one zero-sized impl (`AgentSurface`) wrapping:
-
-- One async method per wire op: `ack_turn`, `requeue_inflight`,
-  `inbox_unread`, `post_turn_counts`, `send_to_parent`, `recv_next`.
-
-`main()` calls `serve_main::<AgentSurface>` for all roles. The turn
-loop (`serve_loop` / `handle_turn`) has no per-role branches.
+`hive-agent`'s wire types (`AgentRequest` / `AgentResponse`, aliased as
+`ManagerRequest` / `ManagerResponse`) and its turn loop are factored
+through a small `Surface` trait with one zero-sized impl, so the loop
+itself has no per-role branches. See `hive-agent/src/main.rs`'s module
+doc for the trait shape.
 
 ### Boot wiring
 
@@ -103,12 +95,12 @@ opens turn-stats sqlite, prepares the on-boot files (see
 [claude-invocation](claude-invocation.md#on-boot-files)),
 installs claude plugins, spawns `web_ui::serve` + `vacuum::run`,
 and either drops into `serve_loop` directly (`Online`) or parks on
-the login flow first (`NeedsLogin`). (The forge notification poller
-used to be spawned here too; it is its own process now —
-`hive-forge-notify`, see [`forge.md`](../forge.md).)
+the login flow first (`NeedsLogin`). Forge notifications are polled by
+their own process, not this loop — see `hive-forge-notify` in
+[`forge.md`](../forge.md).
 
-`spawn_todo_socket` opens the todos store and the socket the in-container
-producers dial. Matrix / bash / forge-notify daemons and the in-process
+Boot also opens the todos store and the socket in-container producers
+dial. Matrix / bash / forge-notify daemons and the in-process
 `disk_watch` todo producer (low state-disk space) are the built-in
 producers, but the socket accepts any `subsystem` marker — a
 user-configured MCP server can push its own todos the same way. See

From 5df263b2022e626de0771991aa1aeab0f786f409 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:51:28 +0200
Subject: [PATCH 03/64] docs(turn-loop): drop historical framing, point to
 turn.rs module doc

---
 docs/turn-loop/claude-invocation.md | 21 ++++++++-------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md
index f5b3df9a..0d92d3d4 100644
--- a/docs/turn-loop/claude-invocation.md
+++ b/docs/turn-loop/claude-invocation.md
@@ -218,9 +218,7 @@ socket at `/run/hive/` once at startup:
   `services.hyperhive.c0re.operatorPronouns`, default `she/her`).
   When `hyperhive.docs.enable` is set, `HIVE_DOCS_DIR` is present
   in the environment and `render()` appends a one-sentence pointer
-  telling the agent the docs are mounted at that path (in lieu of
-  the old CLAUDE.md-in-docs-dir approach, which was dropped in
-  favour of this direct injection).
+  telling the agent the docs are mounted at that path.
   Passed via `--system-prompt-file`.
 
   **Marker grammar.** `<!-- role:X -->` opens a block; any
@@ -242,14 +240,11 @@ socket at `/run/hive/` once at startup:
   empty-string env vars and missing env vars round-trip the
   same way.
 
-The per-turn plumbing lives in `hive_ag3nt::turn`: `write_mcp_config` /
-`write_system_prompt` (on-boot files), `make_session` (builds the durable
-`InfiniteSession`, once), `drive_turn` (the policy state machine —
-reset/auto-reset, the turn, 401-retry, deferred-compact-at-turn-end),
-`run_pending_compact` (idle operator compact), `BusSink` (stream → bus +
-`Telemetry` applied via `apply_telemetry`), `emit_turn_end`, `session_title`
-/ `session_store` / `archive_session` (identity + turn-boundary reset). The
-actual claude spawn, stream classification, and the reactive/proactive
-compaction loop are in the `hive-claude` crate. Login-wait
-(`wait_for_login`) lives in `hive_ag3nt::login`.
+The per-turn plumbing described on this page — on-boot files, session
+identity, the reset/auto-reset/retry state machine, and the
+telemetry-to-bus bridge — lives in `hive-agent`'s `turn` module; see its
+`//!` doc comment (`hive-agent/src/turn.rs`) for the exact call shape.
+The actual claude spawn, stream classification, and the
+reactive/proactive compaction loop are in the `hive-claude` crate.
+Login-wait lives in `hive-agent`'s `login` module.
 

From d14d3b25afae1bffe7afc5d55e750f91c141141f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:51:33 +0200
Subject: [PATCH 04/64] docs(turn-loop): dedupe self-continue note, drop
 wake-CLI history

---
 docs/turn-loop/mcp.md | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md
index 40fcc11b..86f6b121 100644
--- a/docs/turn-loop/mcp.md
+++ b/docs/turn-loop/mcp.md
@@ -95,12 +95,11 @@ at_unix_timestamp?)`.
   payloads spill to `/agents/<self>/state/reminders/`. Pending count
   capped at 50 per agent (`HIVE_REMIND_MAX_PENDING_PER_AGENT`).
 
-There is no same-turn self-continue tool: ending the turn and letting
-an external wake drive the next one is always the right move — it
-checkpoints the session and observes wakes that only reach the harness
-between turns. Multi-step work rides `remind` for a durable self-wake,
-or an in-container todo wake (bash-task completion, forge notification,
-matrix activity) for work already in flight.
+There is no same-turn self-continue tool — see
+[Turn outcomes](README.md#turn-outcomes) for why. Multi-step work rides
+`remind` for a durable self-wake, or an in-container todo wake
+(bash-task completion, forge notification, matrix activity) for work
+already in flight.
 
 **Meta** (`meta` group): `set_status(text)`, `get_agent_meta(name?)`.
 
@@ -164,11 +163,9 @@ inject a wake-up event into the agent's inbox via the per-agent
 socket at `/run/hive/mcp.sock`. Speak the wire protocol directly —
 JSON-line over the unix socket: `{"cmd":"wake","from":"matrix","body":
 "new dm from @alice"}\n`. Same shape as any other `AgentRequest`; see
-`hive-sh4re::AgentRequest::Wake`. (An earlier `hive-agent-wake` CLI
-wrapper existed for this but was removed — no shipped co-process
-daemon actually shelled out to it; every one that wakes the harness
-(matrix, bash) dials the socket directly, so the raw protocol is the
-only path now.)
+`hive-sh4re::AgentRequest::Wake`. Every built-in producer that wakes
+the harness (matrix, bash) dials the socket directly — there is no
+CLI wrapper, just the raw protocol.
 
 The wake event lands in the broker as `{from:<label>,
 to:<agent>, body}`, waking whatever `recv` call the harness
@@ -199,7 +196,7 @@ than deriving from SSE events.
 
 `mcp::run_tool_envelope`: every MCP tool handler logs the request,
 runs the body, logs the result. Pre-/post-log only — the inbox
-status hint moved to the wake prompt + UI header.
+status hint lives in the wake prompt + UI header, not here.
 
 ## Tool whitelist (`mcp_config::ALLOWED_BUILTIN_TOOLS`)
 

From ecdd3d390fb733058f72ea9cd849151d4ddb1629 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:54:31 +0200
Subject: [PATCH 05/64] docs(turn-loop): drop historical framing, fix stale
 hive_ag3nt:: refs

---
 docs/turn-loop/claude-invocation.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md
index 0d92d3d4..377921b4 100644
--- a/docs/turn-loop/claude-invocation.md
+++ b/docs/turn-loop/claude-invocation.md
@@ -14,12 +14,13 @@ claude --print --verbose --output-format stream-json --model <name> \
 lookup/archive, and the durable-session compaction loop — live in the
 reusable **`hive-claude`** crate (`hive_claude::{Claude, InfiniteSession,
 Attach, CompactionPolicy, PercentPolicy, Telemetry, Sink, SessionStore}`;
-see `hive-claude/README.md`). `hive_ag3nt::turn` is the hyperhive **policy
-layer** on top: it builds the per-turn config from the bus, bridges the
-output stream onto the event bus (`BusSink`), and owns the compaction /
-auto-reset / retry decisions in `drive_turn`. The lib returns everything it
-parsed from a turn (usage, cost, context window, resolved model) as
-`Telemetry`, which the policy layer applies to the bus.
+see `hive-claude/README.md`). `hive-agent`'s `turn` module is the
+hyperhive **policy layer** on top: it builds the per-turn config from
+the bus, bridges the output stream onto the event bus (`BusSink`), and
+owns the compaction / auto-reset / retry decisions in `drive_turn`. The
+lib returns everything it parsed from a turn (usage, cost, context
+window, resolved model) as `Telemetry`, which the policy layer applies
+to the bus.
 
 **Which `claude` binary.** The bare name `claude`, resolved off the
 harness unit's PATH. By default that's the `claude-code` in the agent's
@@ -205,7 +206,7 @@ socket at `/run/hive/` once at startup:
   race), trading that for a hard dependency on the daemon's uptime
   (`Restart=always`, no stdio fallback). Extra servers stay stdio.
 - `claude-system-prompt.md` — rendered from
-  `hive-ag3nt/prompts/system.md` by `hive_ag3nt::prompt::render`:
+  `hive-agent/prompts/system.md` by `hive-agent`'s `prompt::render`:
   HTML-comment markers (`<!-- role:agent -->...<!-- /role:agent -->`,
   same for `role:manager`) gate the role-specific blocks; everything
   else is shared. Five placeholders are then

From c570da0932e9e83409bb00d30e601ef39e1e39cd Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:54:37 +0200
Subject: [PATCH 06/64] docs(turn-loop): dedupe matrix.url rationale, trim
 historical framing

---
 docs/turn-loop/config.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md
index e02c5a45..0f81c8ef 100644
--- a/docs/turn-loop/config.md
+++ b/docs/turn-loop/config.md
@@ -50,8 +50,8 @@ hyperhive.user.passwordlessSudo = true;  # default
 Grants the per-agent unix user passwordless `sudo` (`NOPASSWD: ALL`).
 Enabled by default so claude's shell tools work for operations that
 need root inside the container (`systemctl`, package managers in dev
-shells, etc.) — the same privilege surface the previous root-user shape
-had, now elevated explicitly rather than implicitly.
+shells, etc.) — the agent user gets root explicitly via `sudo` rather
+than running as root itself.
 
 Set to `false` for agents that should be strictly unprivileged.
 Any tool invocation that needs root then fails loudly with the standard
@@ -162,13 +162,12 @@ Override per-agent when an agent should talk to a different homeserver
 — for example a remote hive's tuwunel reached over a VPN, or an
 external Matrix server for a federation-only agent.
 
-**Defaults to `null`, meaning "no matrix" — for the same reason
-`forge.url` does.** The homeserver may live on another host, and a
-loopback default resolves inside the agent's own netns to the agent,
-so it would be a value that evaluates fine and then talks to the wrong
-machine. With `null` the daemon has no homeserver and no-ops exactly as
-it does without a token. The hive only forwards `HIVE_MATRIX_URL` when
-it actually has a matrix vhost to name, so `null` survives where a hive
+**Defaults to `null`, meaning "no matrix" — same reasoning as
+`forge.url` above** (a loopback default would resolve inside the
+agent's own netns to the agent itself, not the homeserver). With
+`null` the daemon has no homeserver and no-ops exactly as it does
+without a token. The hive only forwards `HIVE_MATRIX_URL` when it
+actually has a matrix vhost to name, so `null` survives where a hive
 runs no homeserver, or where the agent modules are evaluated outside a
 hive.
 

From 737b6dabd57187b0c3ae46c2868d3f6dc880e561 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:54:54 +0200
Subject: [PATCH 07/64] docs(turn-loop): fix stale hive_ag3nt:: Bus reference
 in mcp.md

---
 docs/turn-loop/mcp.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md
index 86f6b121..09ced3bb 100644
--- a/docs/turn-loop/mcp.md
+++ b/docs/turn-loop/mcp.md
@@ -178,7 +178,7 @@ the bind-mount is the agent's own container only.
 
 ## Authoritative state
 
-`hive_ag3nt::events::Bus` carries the current turn-loop state in
+`hive-agent`'s `events::Bus` carries the current turn-loop state in
 addition to the broadcast channel and the events history. Variants:
 
 - `Idle` — sitting on `Recv` waiting for mail.

From 979325895575ae34b6cf7af096d2f1d99019fd5e Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:55:50 +0200
Subject: [PATCH 08/64] docs(turn-loop): fix one more stale hive_ag3nt::
 reference

---
 docs/turn-loop/claude-invocation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md
index 377921b4..e37c24e3 100644
--- a/docs/turn-loop/claude-invocation.md
+++ b/docs/turn-loop/claude-invocation.md
@@ -195,7 +195,7 @@ next turn picks it up like any other inbox message.
 
 ## On-boot files
 
-`hive_ag3nt::turn::write_*` writes two files next to the per-agent
+`hive-agent`'s `turn` module writes two files next to the per-agent
 socket at `/run/hive/` once at startup:
 
 - `claude-mcp-config.json` — points claude at the persistent

From 58459bbbb33b9510dc547da647a656b58ef0bb20 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:45:09 +0200
Subject: [PATCH 09/64] docs(security): drop origin-story framing, point to
 module doc instead of internals

---
 docs/security.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/docs/security.md b/docs/security.md
index d2051adc..dda8f4b5 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -5,9 +5,8 @@
 The sections below document specific mechanisms (the state-file endpoint,
 nixbld isolation, privilege separation). This section frames the model they
 serve: **what hyperhive defends, what it deliberately does not, and where the
-operator is accepting risk.** It emerged from a security discussion on
-2026-06-24 (prompted by the `gh` CLI helper work) and is the reference for
-"is it safe to give an agent capability X?".
+operator is accepting risk.** It is the reference for "is it safe to give an
+agent capability X?".
 
 ### The trust boundary is the container, not credential storage
 
@@ -167,8 +166,8 @@ token policy bounds file reads; network isolation bounds network reach.
 - `/home/<name>/.claude/` — mode `0700`, owned by the per-agent
   user `<name>`. nixbld users cannot read it.
 - `$HYPERHIVE_STATE_DIR/forge-token` (= `/agents/<name>/state/forge-token`)
-  — written at mode `0600` by `hive-c0re/src/forge.rs` and chowned to the
-  per-agent uid:gid by `lifecycle::chown_to_agent`. nixbld users
+  — written at mode `0600` and chowned to the per-agent uid:gid (see
+  `hive-c0re/src/forge.rs`'s module doc for exactly where). nixbld users
   cannot read it.
 
 **Policy**: all credential files written to agent state directories MUST be mode

From c6eda124b1ed9d21ac93633570da9762d99a05c2 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:46:35 +0200
Subject: [PATCH 10/64] docs(boundary): drop changelog framing, dedupe
 ReloadGatewayNginx explainer

---
 docs/boundary.md | 55 ++++++++++++++++++++++++------------------------
 1 file changed, 27 insertions(+), 28 deletions(-)

diff --git a/docs/boundary.md b/docs/boundary.md
index c3ba808c..6f389643 100644
--- a/docs/boundary.md
+++ b/docs/boundary.md
@@ -5,12 +5,10 @@ _implementation_ work — container network isolation, the unifying
 gateway, core-daemon privsep — is tracked as `area:ops` issues on
 the forge.
 
-The operator/agent boundary is now technically enforced, not just a
-convention. Containers run in private netns (network isolation is
+The operator/agent boundary is technically enforced, not just a
+convention: containers run in private netns (network isolation is
 always on), the gateway proxies all operator-facing traffic, and
-`hive-c0re` runs as the unprivileged `hive-core` user. All three
-`area:ops` pillars — network isolation, the gateway, and privsep —
-are complete and active.
+`hive-c0re` runs as the unprivileged `hive-core` user.
 
 ## Two principals, two paths
 
@@ -47,9 +45,9 @@ every boundary claim above is aspirational. Network isolation is what
 makes the boundary _real_; the gateway and privsep are ergonomics and
 defence-in-depth layered on top.
 
-Network isolation is now complete and always on: every agent container
-runs in a private netns behind the hive bridge. The shared-netns mode
-was removed. See `docs/network.md`.
+Network isolation is complete and always on: every agent container
+runs in a private netns behind the hive bridge, and there is no
+shared-netns mode. See `docs/network.md`.
 
 Concretely, the core daemon's dashboard `/api` carries **no
 application-layer authentication** — operator-authority routes are served
@@ -64,15 +62,18 @@ operator-authority route inherits that assumption. `hive-ci` is treated like an
 agent for this purpose — it runs untrusted PR code and is netns-isolated for
 the same reason.
 
-The `area:ops` issues followed this sequencing:
+The boundary rests on three layers:
 
-1. **Gateway** — pure ergonomics win, unblocks same-origin (lets the
-   cross-origin CORS shim on `/answer-question/{id}` go away), no
-   behavioural risk. An nginx nixos-container now sits in front of all
-   surfaces; per-agent UIs are proxied under `/agent/<name>/`.
-2. **Network isolation** — the load-bearing step that turns the
-   honour-system split into an enforced boundary. **Complete** —
-   always-on, unconditional; the shared-netns mode was removed.
+1. **Gateway** — fronts all surfaces (dashboard + every per-agent UI)
+   on one origin. An nginx nixos-container proxies per-agent UIs under
+   `/agent/<name>/`, which is what lets the inline-answer POST to
+   `/answer-question/{id}` go same-origin instead of needing a
+   cross-origin CORS shim. Pure ergonomics — no behavioural risk on
+   its own.
+2. **Network isolation** — the load-bearing layer: every agent
+   container runs in a private netns behind the hive bridge, always
+   on and unconditional. This is what turns the operator/agent split
+   from an honour-system convention into an enforced boundary.
 3. **Privsep** — defence in depth on the core process; `hive-c0re`
    runs as the unprivileged `hive-core` user and delegates root
    operations to `hive-priv`, a narrow socket-activated helper. See
@@ -84,15 +85,14 @@ The `area:ops` issues followed this sequencing:
 systemd unit. The unit binds `/run/hive/priv.sock` with
 `SocketGroup=hive-core` and mode `0660` and passes the ready listener
 to the helper as fd 3 (`LISTEN_FDS`). The helper requires this and
-bails if it isn't socket-activated — there is intentionally no
-self-bind fallback.
+bails if it isn't socket-activated.
 
-Dropping the old fallback removed a dev/prod divergence: when
-`hive-priv` bound the socket itself it created the file owned by
-root's primary group rather than `hive-core`, so a `hive-core` client
-couldn't connect the way the socket unit's `SocketGroup` grant
-intends. Requiring socket activation everywhere means dev and prod
-take the exact same path and the group grant always holds.
+⚠️ There is intentionally no self-bind fallback: if `hive-priv` bound
+the socket itself, it would create the file owned by root's primary
+group rather than `hive-core`, and a `hive-core` client couldn't
+connect the way the socket unit's `SocketGroup` grant intends.
+Requiring socket activation everywhere keeps dev and prod on the
+exact same path, so the group grant always holds.
 
 ### the per-agent socket dir
 
@@ -129,10 +129,9 @@ nginx reaches all of `/run/hive-agent` as a plain host path. Dropping
 them and the rest of the host. That costs no network isolation: nginx
 binds the host's `:80`/`:443` and reaches `localhost` upstreams, which a
 netns would have to be opened up for anyway.
-🔑 It does mean nothing *implicitly* scopes the privileged reload verb,
-so the scope is explicit: the unit name is hard-coded in `hive-priv` —
-see `PrivRequest::ReloadGatewayNginx`. **A caller cannot name the unit,
-so the verb cannot be steered at another service.**
+🔑 It does mean nothing *implicitly* scopes the privileged reload verb —
+see [`docs/security.md`](security.md#hive-c0re-privilege-separation) for
+how `PrivRequest::ReloadGatewayNginx`'s containment works.
 
 ⚠️ Contrast `/shared`, which *is* sticky world-writable (`1777`): it has
 many legitimate writers, so sticky is the best available answer there.

From 66442d41ffaa9ae569ea2010c6b3e8e5cf328a73 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:47:26 +0200
Subject: [PATCH 11/64] docs(agent-hierarchy): restructure audit doc into
 current/planned, trim internals

---
 docs/agent-hierarchy.md | 318 +++++++++++++++++-----------------------
 1 file changed, 137 insertions(+), 181 deletions(-)

diff --git a/docs/agent-hierarchy.md b/docs/agent-hierarchy.md
index d3c11ff4..7c24a665 100644
--- a/docs/agent-hierarchy.md
+++ b/docs/agent-hierarchy.md
@@ -1,11 +1,13 @@
 # Agent hierarchy & privileges
 
-Design + audit doc for the agent-privileges + tree-shape milestone
-(the [issue tree](http://localhost:3000/hyperhive/hyperhive/issues/361)).
-The implementation lands in pieces; this doc tracks what's done, what's
-planned, and what currently special-cases the manager.
+Every agent has a place in an operator-editable parent/child tree, used
+to scope which agents can manage which others. This doc covers how the
+tree is stored and edited today, the rules that are meant to run on top
+of it once enforcement is finished, and where the manager still gets
+special-cased in the meantime. Tracking issue:
+[hyperhive#361](http://localhost:3000/hyperhive/hyperhive/issues/361).
 
-## Current state (as of this PR)
+## Where the tree lives
 
 Topology lives in the hive-c0re-owned **meta repo**, alongside
 `flake.nix`, at `/var/lib/hyperhive/meta/topology.json`:
@@ -18,45 +20,35 @@ Topology lives in the hive-c0re-owned **meta repo**, alongside
 }
 ```
 
-`null` = root-level agent. New agents **default to root** (`null` parent) —
-there is no structural manager that everything hangs under. Hierarchy is
-built explicitly: an agent that requests a sub-agent gets a
-requester-as-parent edge written at its `init_config` approval (so `bob`
-above was spawned by `alice`), and the operator can reparent any agent. The
-bootstrap container (`ruth`) is just another root. Re-parenting is
-operator-driven:
+`null` = root-level agent. New agents **default to root** — there is no
+structural manager that everything hangs under. Hierarchy is built
+explicitly: an agent that requests a sub-agent gets a
+requester-as-parent edge written at its `init_config` approval (so
+`bob` above was spawned by `alice`), and the operator can reparent any
+agent, including the bootstrap container (`ruth`) — it's just another
+root. The manager is reparentable like any other agent; there's no
+"structurally root" carve-out. Its privileges live on its MCP socket,
+not its tree position (see *Manager special-casing today* below).
 
-- CLI: `hivectl agent <child> set-parent --parent <new>` (or `--root` to
-  promote). Exactly one of `--parent` / `--root` is required.
+### Reparenting
+
+- CLI: `hivectl agent <child> set-parent --parent <new>` (or `--root`
+  to promote). Exactly one of `--parent` / `--root` is required.
 - Dashboard: `POST /api/topology/set-parent` (form fields `child`,
   optional `new_parent` — absent / empty ⇒ promote to root).
 - Wire: `HostRequest::SetParent { child, new_parent: Option<String> }`.
 
-All three converge on `topology::set_parent`, which delegates the
-validation rules to a pure `apply_set_parent` helper. Refuses:
+All three go through the same validation, which refuses:
 
 - unknown `child` / `new_parent` (typo guard),
 - self-parenting,
-- cycles (32-hop ancestor walk, mirroring `is_descendant_of`).
+- cycles (a bounded ancestor walk — moving the manager under one of
+  its own descendants is the only real safety concern here, and it's
+  caught the same way as any other agent).
 
-The manager is reparentable like any other agent — there's no
-"structurally root" carve-out; the manager's privileges live on its
-MCP socket, not its tree position, and the cycle walk above catches
-the only real safety concern (moving the manager under one of its
-own descendants).
-
-Idempotent no-op fast path skips the disk write when the parent is
-already what's requested. After a successful write the surfaces call
-`Coordinator::rescan_containers_and_emit` so connected dashboard
-viewers see the tree repaint without polling
-(`ContainerView.parent` is sourced from `topology.json`).
-
-**Today's caveat:** the move is purely a JSON edit. Only the
-top-level manager (`root`) gets `/var/lib/hyperhive/agents`
-bind-mounted at `/agents` in its container, so sub-agents don't yet
-see their would-be children's state. Once sub-manager bind mounts
-land alongside cap enforcement, `set_parent` grows a companion
-umount-old / mount-new / restart-cascade step.
+Setting a parent to its current value is a no-op (no disk write). A
+successful change triggers an immediate rescan, so connected dashboard
+viewers see the tree repaint without polling.
 
 ### Why meta, not per-agent `agent.nix`
 
@@ -65,37 +57,39 @@ consent, and operator-driven re-parenting shouldn't require touching
 the moved agent's config. Topology IS a system-level concern; meta is
 where system-level facts live.
 
-### Flow
+### How `topology.json` gets updated
 
-1. **Read**: `topology::read()` parses `topology.json` into a
-   `BTreeMap<String, Option<String>>`. Missing / unparsable file →
-   empty map → every agent treated as root (safe degradation for
-   fresh installs that haven't run `meta::sync_agents` yet).
-2. **Reconcile**: `meta::sync_agents` calls `topology::reconcile`
-   alongside its `flake.nix` regeneration. New agents default to root
-   (null parent) — an agent-requested sub-agent already carries an
-   explicit requester-as-parent edge from its `init_config` approval, so
-   only user/operator-initiated spawns hit this default, and those are
-   roots; removed agents drop. Existing entries are preserved as-is so
-   operator overrides stick across regenerations. Pending-init agents
-   (an operator-approved proposed config repo but no container yet —
-   `Coordinator::pending_init_names`) are kept too, so the
-   `child -> parent` edge written when `request_init_config` is approved
-   survives the gap until the first apply-commit spawns the container.
-3. **Inject**: `meta::render_flake` looks up each agent's parent and
-   passes it to `mkAgent`. When non-null, the mkAgent body sets
-   `HIVE_PARENT = parent` in the agent's systemd service environment
-   so the harness / claude prompts can see it.
-4. **Surface**: `container_view::build_all` reads `topology.json` and
-   populates `ContainerView.parent: Option<String>` on every rescan.
-   The dashboard renders the field as a tree.
+- **Read** — parsed into an agent→parent map; a missing or unparsable
+  file degrades safely to "every agent is root" (covers a fresh
+  install that hasn't synced yet).
+- **Reconcile** — runs alongside the periodic meta/flake regeneration.
+  New agents default to root unless they already carry an explicit
+  parent edge from an `init_config` approval; existing entries
+  (including operator overrides) are preserved; removed agents drop.
+  Agents that are approved but not yet spawned keep their edge too, so
+  it survives the gap until the container actually appears.
+- **Inject** — each container's parent (if any) is exposed to its own
+  environment as `HIVE_PARENT`, so the harness / system-prompt
+  renderer can see it.
+- **Surface** — every rescan re-reads `topology.json` and populates
+  `ContainerView.parent`, which the dashboard renders as a tree.
 
-## Target topology semantics
+See `hive-c0re/src/topology.rs` and `hive-c0re/src/meta.rs`'s module
+docs for the exact call chain.
 
-Once enforcement lands the rules collapse into:
+### Current limitation: state-dir visibility lags topology
+
+Reparenting today is purely a JSON edit. Only the top-level manager
+(`root`) gets `/var/lib/hyperhive/agents` bind-mounted at `/agents` in
+its container, so sub-agents don't yet see their would-be children's
+state dirs. Once sub-manager bind mounts land alongside capability
+enforcement, reparenting will grow a companion
+umount-old / mount-new / restart-cascade step.
+
+## Planned topology semantics (once ancestor-based enforcement lands)
 
 | operation                                                               | who can do it                                                                           |
-| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
 | `kill` / `start` / `restart` / `update` (any descendant)                | any ancestor                                                                            |
 | `request_init_config` (spawn a new child)                               | any agent, child added under self                                                       |
 | config change via forge PR (any descendant's config)                    | any ancestor                                                                            |
@@ -105,106 +99,71 @@ Once enforcement lands the rules collapse into:
 | `request_update_meta_inputs` (bump meta lock)                           | root agents only (today: just `manager`)                                                |
 
 "Ancestor" walks `ContainerView.parent` chains; cycles are guarded by a
-visited-set at dispatch time (a malformed topology.json can't lock the
-dispatcher into a loop).
+visited-set at dispatch time (a malformed `topology.json` can't lock
+the dispatcher into a loop).
 
-## Current manager special-casings — the audit
+## Manager special-casing today
 
-What currently makes the manager different from every other agent, and
-which axis the post-milestone version reads each special-case along:
+Enforcement of the ancestor rules above isn't fully wired yet, so the
+**manager (`ruth`) still gets some hard-coded special treatment**
+other agents don't:
 
-### A — naming + bootstrap
+- **Naming/bootstrap** — the manager's broker recipient name, state-dir
+  key, and nixos-container name are all `ruth` (container `h-ruth`).
+  `hive-c0re` spawns it directly at boot if missing, with no operator
+  approval step — every other agent goes through `request_init_config`
+  → approval. Topology-wise, `ruth` is still just another root agent.
+- **Wire-protocol** — the `ManagerRequest::*` operations
+  (`RequestInitConfig`; `Kill` / `Start` / `Restart` / `Update`;
+  `GetLogs`; `RequestUpdateMetaInputs`) are reachable only from the
+  manager's socket flavour today. Planned rule for each is in the
+  table above ("any agent, child added under self" for init-config,
+  "any ancestor" for lifecycle/logs); `RequestUpdateMetaInputs` stays
+  a root-only capability even post-milestone, not a topology rule.
+  One exception: `Wake` (inject a `from: <X>` message into the
+  caller's own inbox) isn't really privileged — every per-agent daemon
+  (e.g. `hive-forge-notify`) needs it, and sub-agents already have the
+  equivalent on their own socket.
+- **Storage/mounts** — only the manager container gets
+  `/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can
+  manage any agent's state dir — config is not authored there, since a
+  real config change is a PR from a clone), plus RO mounts for
+  `/applied` (diff against what's deployed) and `/meta` (system-wide
+  deploy log). Planned: each agent gets RW to `/agents/<descendant>/`
+  for just its own subtree — the manager's full-forest RW becomes the
+  "root's subtree is everything" case of that same rule. RO `/meta`
+  access will be gated on a "meta read" capability; only
+  `request_update_meta_inputs` writes `flake.lock`, gated by its own
+  capability.
+- **Prompt/tools** — the system prompt uses `<!-- role:agent -->` /
+  `<!-- role:manager -->` marker blocks, and a `Flavor::{Agent,
+  Manager}` switch picks the MCP tool allow-list claude sees. Both are
+  already parametrised on a single flavour value, so the planned
+  per-capability-group version (`cap:<group>` prompt blocks + a
+  matching tool allow-list) is additive rather than a rewrite.
+- **State dirs** — *not* special-cased: `HYPERHIVE_STATE_DIR` is
+  injected uniformly via `systemd.globalEnvironment` for every
+  container including the manager, so all token/state paths resolve
+  through it the same way everywhere.
+- **Scattered ownership checks** — a handful of independent
+  manager-only overrides exist across `hive-c0re` today: loose-ends
+  visibility (manager sees hive-wide, sub-agents only their own),
+  "manager can cancel any question/reminder" overrides on the owner
+  check, `destroy` refusing to act on the manager, and crash-watch
+  skipping the manager (it auto-restarts via systemd instead of going
+  through the crash-watch loop). Each is planned to become an
+  ancestor/descendant check instead of a manager-name check — see the
+  module docs for `loose_ends.rs`, `operator_questions.rs`,
+  `broker.rs`, `reminder_scheduler.rs`, `actions.rs`, and
+  `crash_watch.rs` for the current owner-check logic in each.
 
-- `MANAGER_AGENT = "ruth"` (broker recipient name),
-  `MANAGER_NAME = "ruth"` (logical name, state-dir key), and
-  `MANAGER_CONTAINER = "h-ruth"` (nixos-container name); the `h-`
-  prefix lets `lifecycle::list()` use a single `starts_with("h-")`
-  filter.
-- `auto_update::ensure_manager` runs at hive-c0re boot and spawns
-  `h-ruth` if missing. **Topology**: ruth defaults to root-level (no
-  parent); hive-c0re handles the bootstrap lifecycle directly.
+None of the above is a stable interface — treat the module doc
+comments as the source of truth for exactly which checks exist today.
 
-### B — wire-protocol privileges
+## Future work: sub-agents inside the same container
 
-The `ManagerRequest::*` variants in `hive-sh4re/src/lib.rs` are
-operations the manager flavour socket can make that sub-agent sockets
-can't:
-
-| variant                                 | semantic                                       | post-milestone                                                                                                                                                |
-| --------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `RequestInitConfig`                     | seed an agent's proposed config repo           | **topology** — existing direct child (re-init) or a brand-new name (child added under self on approval); a name owned by a different parent is refused        |
-| `Kill` / `Start` / `Restart` / `Update` | container lifecycle on an existing agent       | **topology** — descendants only                                                                                                                               |
-| `RequestUpdateMetaInputs`               | bump meta `flake.lock`                         | **per-agent cap** (root-only today; a future "let coder bump its own input" might grant it)                                                                   |
-| `GetLogs`                               | journalctl scrape of a sub-agent               | **topology** — descendants only                                                                                                                               |
-| `Wake`                                  | inject a `from: <X>` message into self's inbox | **not really privileged** — the wire surface exists because the per-agent daemons (e.g. `hive-forge-notify`) need it. Sub-agents have the same via their own socket. |
-
-### C — storage / mounts (`hive-c0re::lifecycle`)
-
-The manager container's nspawn bind set:
-
-- `HOST_AGENTS_ROOT (/var/lib/hyperhive/agents) → /agents` RW — so the
-  manager can manage any agent's state dir. Config is **not** authored
-  here: a config change is a PR from a clone, and `<agent>/config/` is
-  a copy for reading (its write access is a defect tracked separately)
-- `HOST_APPLIED_ROOT (/var/lib/hyperhive/applied) → /applied` RO — so
-  the manager can diff against what's deployed
-- `HOST_META_ROOT (/var/lib/hyperhive/meta) → /meta` RO — so the
-  manager can read the system-wide deploy log
-
-Tree-shape version:
-
-- Each agent gets RW to `/agents/<descendant>/` for every descendant in
-  its subtree. The root agent (today: manager) gets RW to the full
-  forest as a special case of "the root has every other agent as a
-  descendant".
-- RO `/meta` access if the agent holds a "meta read" cap.
-- `request_update_meta_inputs` is the only path that actually writes
-  `flake.lock`, gated by the cap; everyone else stays RO.
-
-### D — drop legacy `/state` for manager ✓ done
-
-`lifecycle.rs` no longer binds `/state` for the manager.
-`HYPERHIVE_STATE_DIR` is now injected uniformly via
-`systemd.globalEnvironment` in `meta.rs` for every container
-(manager included), so all token/state paths resolve through
-`$HYPERHIVE_STATE_DIR`. The agent-module shell scripts
-(tea-login, forge-avatar-sync) simplified from glob+for loops to a
-direct `$HYPERHIVE_STATE_DIR/<token>` read.
-
-### E — prompt + tools
-
-- `prompts/system.md` with `<!-- role:agent -->` / `<!-- role:manager -->`
-  marker blocks, assembled by `hive_ag3nt::prompt::render` based on
-  flavor. **Per-agent cap list** of what the agent can do — already
-  a single parametrised prompt; once per-agent cap groups land the
-  marker grammar grows `cap:<group>` blocks the renderer reads from
-  the per-agent ToolGroup set.
-- `mcp.rs::Flavor::{Agent, Manager}` controls which MCP tools claude
-  sees. Already structured this way internally — the per-flavour
-  allow-list becomes a per-cap-set lookup.
-
-### F — drive-by checks across c0re
-
-- `loose_ends.rs`: manager sees hive-wide loose-ends, sub-agents only
-  their own. **Topology** — every agent sees its own + its
-  descendants'.
-- `operator_questions.rs` + `broker.rs`: "manager can cancel any
-  question" override on the owner check. **Topology** — agents can
-  moderate threads of their descendants.
-- `reminder_scheduler.rs`: same override pattern for reminder cancel.
-  **Topology** — descendants only.
-- `actions.rs`: `destroy` refuses to act on `MANAGER_NAME` (no
-  foot-shooting). **Topology** — agents can destroy descendants but
-  never themselves or ancestors.
-- `crash_watch.rs`: skips `ContainerCrash` for the manager (it
-  auto-restarts via systemd). **Topology** — the root container has
-  different recovery semantics, every other agent falls into the same
-  watch loop.
-
-### G — sub-agents inside the same container
-
-Future work: when enabled for an agent, it can spawn temporary
-"sub-agents" that run inside its own container. Lighter than a full
+When enabled for an agent, it will be able to spawn temporary
+"sub-agents" that run inside its own container — lighter than a full
 nspawn agent. Open questions, not yet wired:
 
 - Inherit caps from parent, or take an explicit narrower set?
@@ -216,17 +175,16 @@ nspawn agent. Open questions, not yet wired:
 ## Harness systemd unit shape
 
 One harness serve binary (`hive-agent`, with its `hive-agent-mcp`
-sibling), one shared `nix/agent-modules/` tree, one
-service unit (`systemd.services.hive-agent`) for all agents. There
-is no longer a separate manager service name or role distinction in
-the harness — privilege differences live server-side in the broker
-socket (which tool groups and manager-surface calls each agent
-receives).
+sibling), one shared `nix/agent-modules/` tree, one service unit
+(`systemd.services.hive-agent`) for all agents. There is no separate
+manager service name or role distinction in the harness — privilege
+differences live server-side in the broker socket (which tool groups
+and manager-surface calls each agent receives).
 
 `agent.nix` and `ruth.nix` both import the shared `nix/agent-modules/`.
 `ruth.nix` additionally sets forge defaults to suppress the
-subscription/participation firehose so ruth's inbox stays focused
-on direct mentions, reviews, and assignments.
+subscription/participation firehose so ruth's inbox stays focused on
+direct mentions, reviews, and assignments.
 
 ### Environment variables set on the unit
 
@@ -248,32 +206,30 @@ on direct mentions, reviews, and assignments.
 path = [ "/run/wrappers" "/run/current-system/sw" ];
 ```
 
-`/run/wrappers` comes first so setuid wrappers (notably `sudo`)
-resolve before bare nix-store binaries. NixOS's
-`systemd.services.<unit>.path` appends `/bin` to every entry via
-`lib.makeBinPath`; passing `/run/wrappers/bin` directly produces
-`/run/wrappers/bin/bin` which doesn't exist (`docs/gotchas.md::
-systemd.services.*.path appends /bin to every entry`). With the
-harness running as the per-agent user this matters: without the
-wrapper dir on PATH, `sudo` resolves to the un-setuid nix-store
-binary and rejects with `must be owned by uid 0 and have the setuid
-bit set` regardless of `hyperhive.user.passwordlessSudo`.
+`/run/wrappers` (not `/run/wrappers/bin`) comes first so setuid
+wrappers — notably `sudo` — resolve before bare nix-store binaries; see
+[`docs/gotchas.md`](gotchas.md) ("`systemd.services.*.path` appends
+`/bin` to every entry") for why the trailing `/bin` matters in
+general. It's load-bearing here because the harness runs as the
+per-agent user: without the wrapper dir on `PATH`, `sudo` resolves to
+the non-setuid nix-store binary and every
+`hyperhive.user.passwordlessSudo` grant fails with "must be owned by
+uid 0 and have the setuid bit set."
 
 ### `serviceConfig` highlights
 
-- `ExecStart = pkgs.hyperhive/bin/hive-agent` — same binary for
-  every agent.
+- `ExecStart = pkgs.hyperhive/bin/hive-agent` — same binary for every
+  agent.
 - `Restart = on-failure`, `RestartSec = 2` — keeps the harness
   resilient across transient crashes without thundering retries.
 - `RuntimeDirectory = "hive-config"` → `/run/hive-config/` owned by
   `User=`, auto-cleared on stop. The harness writes regenerated
   `claude-{mcp-config,settings,system-prompt}` files there
-  (`paths::config_dir`). Deliberately separate from `/run/hive`,
-  which the host bind-mounts in root-owned and which holds
-  hive-c0re's `mcp.sock`.
-- `User = Group = userName` — drops root inside the container; sudo
-  is the explicit escalation surface
-  (`hyperhive.user.passwordlessSudo`).
+  (`paths::config_dir`). Deliberately separate from `/run/hive`, which
+  the host bind-mounts in root-owned and which holds hive-c0re's
+  `mcp.sock`.
+- `User = Group = userName` — drops root inside the container; sudo is
+  the explicit escalation surface (`hyperhive.user.passwordlessSudo`).
 
 ## Cross-references
 

From 785b59a4bbab2e431b6cf0e7bc2e6a7eccc574ac Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:53:15 +0200
Subject: [PATCH 12/64] docs(dashboard): fix misplaced CR3D3NTIALS content,
 dedupe, trim history

---
 docs/web-ui/dashboard.md | 401 ++++++++++++++++++---------------------
 1 file changed, 180 insertions(+), 221 deletions(-)

diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index 6183d159..3359540e 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -212,8 +212,8 @@ Three sub-tabs: **R3BU1LD QU3U3** (default), **M3T4 1NPUTS**,
 `/api/state` and subscribes to `/api/dashboard/stream` for
 `rebuild_queue_changed`, `meta_inputs_changed`, `meta_update_running`.
 The SW4RM tab (`/dashboard.html`) does **not** read this endpoint at
-all — mara, on review: "swarm.js should not need to pull in the jobq
-to do its job." Its per-agent pending badges are transient-only, and
+all, by design — the swarm view stays independent of job-queue
+internals. Its per-agent pending badges are transient-only, and
 its queue-summary banner reads the much narrower `GET /api/jobq/rollup`
 instead (see Container row, below) — a handful of pre-tallied counts,
 not the graph.
@@ -239,23 +239,21 @@ array order, unchanged from the wire). A row shows a state glyph (`⏸`
 pending / `▶` running / `◐` finishing — own work done, a sub-node
 still running / `✔` done / `✖` failed / `⊘` cancelled / `·` skipped)
 and each step's own label/agent. A `Node`-kind dep on a sibling shows
-as a plain "waits on: `<label>`" text line under the row — an earlier
-gutter-rail version was reverted (it broke visually whenever a nested
-subtree sat between the two related rows; text has no such gap).
+as a plain "waits on: `<label>`" text line under the row rather than a
+gutter rail — a rail breaks visually whenever a nested subtree sits
+between the two related rows, since a text line needs no continuous
+vertical space to draw.
 `builds.js` mounts the element with `cancellable` set, which turns on
 a per-node cancel button (`✕`) on any non-terminal row — the button
 dispatches `hive-jobq-graph-cancel`, and the page does the actual
 `POST /api/rebuild-queue/{id}/cancel`, matching the wire event as its
 own domain concept (the component knows nothing about that endpoint).
-**Still no source chip, kind label, timing, or build-log deep-link on
-rows** — no equivalent of the old `DagView`'s `source`/`reason`/
-`created_at`, which were `NodeKind::Dag`-specific fields the generic
-wire doesn't carry; per mara's original steer ("dont feel constrained
-by what the ui does currently"), rows present what the endpoint
-actually gives rather than reconstructing the old per-row chrome.
-Settled entries render their **full step tree**, not just a bare
-summary — unlike the old `DagView` projection, this wire does not
-filter `Done` nodes out.
+**Rows carry no source chip, kind label, timing, or build-log
+deep-link** — the generic graph wire doesn't carry those fields, and
+rows are meant to present exactly what the endpoint provides rather
+than reconstruct chrome the backend no longer sends. Settled entries
+render their **full step tree**, not just a bare summary — the wire
+does not filter `Done` nodes out.
 
 **State filter (hyperhive#2606).** A row of per-state checkboxes above
 the tree — one per lifecycle state, matching the row glyphs — lets the
@@ -359,24 +357,6 @@ The status dot renders these states:
   !live` "provisioned but offline" case.
 - **grey** — no token (not provisioned).
 
-### GITHUB tab
-
-Provision a single per-agent GitHub personal access token (see
-[`docs/github.md`](../github.md) for the injection + `gh`/git-push
-mechanics). No login flow — the operator pastes an existing PAT for a
-dedicated bot account, with a security-warning banner (dedicated account +
-minimally-scoped token) and a link to
-[github.com/settings/tokens](https://github.com/settings/tokens).
-
-Status reads `GET /api/github-account?agent=<name>` →
-`{ present: bool }` — whether the agent's `github-token` file exists.
-There's no live/heartbeat concept for a static PAT, so this is just a
-"token stored ✓" / "not set" line, unlike MATRIX's status-dot taxonomy.
-Provisioning posts `POST /api/github-account` (form-encoded `agent`,
-`token`) → `200 { ok: true }` on success, or the same `error_response`
-shape `/api/matrix-account-login` uses on failure. The token is never
-echoed back in either direction.
-
 The container-down cross-reference (`/api/state`) takes precedence over
 the age check. `as_of_unix` is tooltipped ("live as of N ago") throughout
 so freshness is always legible. When `live` is absent (an older backend
@@ -398,6 +378,24 @@ regardless of outcome. The account list reflects what is *provisioned*
 (an account with a stored token), so a config-declared-but-unprovisioned
 account appears only once it has been provisioned through the form.
 
+### GITHUB tab
+
+Provision a single per-agent GitHub personal access token (see
+[`docs/github.md`](../github.md) for the injection + `gh`/git-push
+mechanics). No login flow — the operator pastes an existing PAT for a
+dedicated bot account, with a security-warning banner (dedicated account +
+minimally-scoped token) and a link to
+[github.com/settings/tokens](https://github.com/settings/tokens).
+
+Status reads `GET /api/github-account?agent=<name>` →
+`{ present: bool }` — whether the agent's `github-token` file exists.
+There's no live/heartbeat concept for a static PAT, so this is just a
+"token stored ✓" / "not set" line, unlike MATRIX's status-dot taxonomy.
+Provisioning posts `POST /api/github-account` (form-encoded `agent`,
+`token`) → `200 { ok: true }` on success, or the same `error_response`
+shape `/api/matrix-account-login` uses on failure. The token is never
+echoed back in either direction.
+
 ### FORGES tab
 
 Store a **label + base URL + access token** for an external Forgejo/Gitea/
@@ -467,10 +465,8 @@ The current capabilities are:
 Each row is one agent. Columns are the capability names returned by
 `GET /api/capabilities` as `caps: Vec<String>`. Checking or unchecking
 boxes only stages the change in-browser; nothing is written until the
-page-level **save all** button (described below) is clicked. The
-checkboxes reflect the *effective* set (explicit grant or role default),
-so a default-perms agent shows its real grants rather than blank; absent
-agents in the assignment map have no extra capabilities.
+page-level **save all** button (described below) is clicked. Row
+values follow the `effective`/`assignments` rule described above.
 
 **T00L GR0UPS** — per-agent tool-group permissions. Tool groups are
 named buckets of MCP tools; each agent starts with a role default
@@ -752,9 +748,8 @@ isn't currently listed.
 
 The row is a `flex-wrap: wrap` container holding ts / arrow / from / sep
 / to chips inline; the **body wraps to its own full-width line below** the
-chips (`flex: 1 1 100%`) so the body always gets the full row width down to
-the content edge — long timestamps + agent names used to push the body ~30ch
-in and force awkward narrow-column wraps. `min-width: 0` keeps
+chips (`flex: 1 1 100%`) so long timestamps and agent names never push the
+body into a narrow trailing column. `min-width: 0` keeps
 `word-break: break-word` effective so the body doesn't force the row wider
 than its container. Sticky-bottom auto-scroll + "↓ N new" pill. Below the
 stream sits a terminal-style compose box: `@name` picks the recipient
@@ -783,9 +778,8 @@ latter — never guessed from the operator's browser hostname + a container
 port, which is only right by accident off plain localhost. Operators without
 matrix or forge enabled — or with forge on but no public URL configured —
 never see a dead or wrong link. `home.js` also fills the swarm/hive identity
-line at the top. Dashboard is now served at `/dashboard.html` (route swap
-completed in #1464 step 2); the home page at `/` replaces the old dashboard
-root. All dashboard sub-pages include a `← Home` back-link for navigation.
+line at the top. All dashboard sub-pages include a `← Home` back-link for
+navigation.
 
 ## L0GS page (`/logs.html`)
 
@@ -862,122 +856,127 @@ is known stopped up front (`ContainerView.running = false`) the
 fallback fires immediately, skipping the doomed `<url>/icon`
 fetch entirely.
 
-- Line 1: agent name (link → new tab), m1nd/ag3nt chip, an
-  **icon-only nav strip** plus live agent-owned state, all populated
-  async from a single `GET /api/dashboard-state` call to the
-  agent's own backend. The response (`DashboardState`) carries:
-  `links` (nav strip entries — `📊 stats`, `🖥 screen` when GUI is
-  enabled, `⬡ forge profile`, `↳ agent-configs mirror`, plus any
-  agent-declared `dashboardLinks` extras), `status_text` /
-  `status_set_at` (agent self-reported status — the `(set N ago)`
-  chip is stamped `data-set-at` and ticks every 30s to stay fresh
-  across the long-lived keyed row cache), `rate_limited`,
-  `ctx_tokens` / `context_window_tokens` (context-window badge
-  data). The agent backend is the single source of truth for all
-  of these. The dashboard resolves each `AgentLink.kind` against a
-  per-agent base URL depending on whether hive-gateway is in front
-  (`StateSnapshot.gateway_enabled`, sourced from the
-  `HIVE_GATEWAY_ENABLED` env the c0re NixOS module sets when
-  `services.hyperhive.gateway.enable = true`). Gateway-on (default):
-  base URL is `/agent/<name>` (same origin, gateway proxies to the
-  per-agent harness — TCP or unix-domain depending on the agent's
-  `HIVE_WEB_SOCKET` opt-in, see
-  `docs/gateway.md::Per-agent unix-socket upstream`).
-  Gateway-off (legacy / local dev): base URL is
-  `http://<host>:<container.port>` (direct TCP fallback). Forge
-  links resolve against `state.forge_public_url` (sourced from
-  `services.hyperhive.forge.publicUrl`) and are omitted entirely when
-  that's unset — never guessed from `<host>:3000`. External links are
-  already absolute. The same base URL drives the primary agent-name
-  link + favicon fetch, so the whole row routes through the gateway
-  as a unit.
-  **When the container is stopped** (`ContainerView.running = false`),
-  the async `dashboard-state` fetch is skipped entirely (the agent
-  web server is down), so the badge chain is replaced by a single
-  badge, the nav strip is empty, and status text / rate-limited / ctx
-  badges are suppressed. The agent icon goes straight to the dimmed
-  `/favicon.svg` fallback instead of attempting a doomed load from the
-  container's URL. Static fields — `needs_update`, `deployed_sha`,
-  `pending_reminders`, `parent`, `config` link — remain visible
-  regardless of run state.
-  **Which single badge (hyperhive#3139):** `ContainerView.failed`
-  (systemd `ActiveState=failed` — the unit exhausted its bounded
-  restarts and gave up on its own) draws a red `✖ gave up` badge;
-  otherwise a plain muted `■ not running` — a container an operator
-  stopped deliberately. Both states read `running: false`; `failed` is
-  the orthogonal fact (a fifth one alongside `paused`/`needs_update`/
-  `needs_login`, same "independent flags, no state machine" shape —
-  see `ContainerView`'s own doc comment) that tells them apart. An
-  older backend without the field serves `failed: undefined`, which
-  reads falsy — degrades cleanly to the single `not running` badge.
-  When the container is running, status badges follow — `⊘ rate
-  limited` (red, while the harness is parked after a 429), `needs
-  login`, `needs update` — plus **one `◐ pending-state…` pill per
-  active transient** (replaces buttons during operator-initiated
-  start / stop / restart / rebuild / destroy). An agent can carry
-  **several transients at once** (mara: "show all running nodes that
-  name the agent") — e.g. a lease-exempt `prebuild` running alongside
-  a `stop_for_update` on the same agent — and each renders as its own
-  independent badge rather than being collapsed into one label,
-  matching the existing multi-badge convention this line already uses
-  for `paused`/`needs_update`/model/ctx.
-  Any pending badge means the row is actually **running** something
-  right now — there is no separate queued-but-not-started row state
-  to visually distinguish it from (see **Pending-badge derivation**
-  below), so every row carrying ≥1 badge keeps the amber row tint AND
-  draws a **rotating amber ring** around the agent icon.
+**Line 1** — agent name (link → new tab), m1nd/ag3nt chip, an
+**icon-only nav strip** plus live agent-owned state, all populated
+async from a single `GET /api/dashboard-state` call to the agent's
+own backend. The response (`DashboardState`) carries: `links` (nav
+strip entries — `📊 stats`, `🖥 screen` when GUI is enabled, `⬡ forge
+profile`, `↳ agent-configs mirror`, plus any agent-declared
+`dashboardLinks` extras), `status_text` / `status_set_at` (agent
+self-reported status — the `(set N ago)` chip is stamped `data-set-at`
+and ticks every 30s to stay fresh across the long-lived keyed row
+cache), `rate_limited`, `ctx_tokens` / `context_window_tokens`
+(context-window badge data). The agent backend is the single source
+of truth for all of these. The dashboard resolves each `AgentLink.kind`
+against a per-agent base URL depending on whether hive-gateway is in
+front (`StateSnapshot.gateway_enabled`, sourced from the
+`HIVE_GATEWAY_ENABLED` env the c0re NixOS module sets when
+`services.hyperhive.gateway.enable = true`). Gateway-on (default):
+base URL is `/agent/<name>` (same origin, gateway proxies to the
+per-agent harness — TCP or unix-domain depending on the agent's
+`HIVE_WEB_SOCKET` opt-in, see
+`docs/gateway.md::Per-agent unix-socket upstream`).
+Gateway-off (legacy / local dev): base URL is
+`http://<host>:<container.port>` (direct TCP fallback). Forge
+links resolve against `state.forge_public_url` (sourced from
+`services.hyperhive.forge.publicUrl`) and are omitted entirely when
+that's unset — never guessed from `<host>:3000`. External links are
+already absolute. The same base URL drives the primary agent-name
+link + favicon fetch, so the whole row routes through the gateway
+as a unit.
 
-  **Pending-badge derivation:** transients only (`transientsState`,
-  keyed `agent -> Map<kind, since_unix>`) — a transient is **derived
-  from a job-queue node currently `Running`** against that agent, not
-  declared per request, so its label follows the operation as it
-  progresses (a rebuild reads `stop_for_update`, then `swap`, then
-  `reconcile` rather than one constant `rebuilding` for its whole
-  life). Two consequences for anything rendering it:
+**When the container is stopped** (`ContainerView.running = false`),
+the async `dashboard-state` fetch is skipped entirely (the agent
+web server is down), so the badge chain is replaced by a single
+badge, the nav strip is empty, and status text / rate-limited / ctx
+badges are suppressed. The agent icon goes straight to the dimmed
+`/favicon.svg` fallback instead of attempting a doomed load from the
+container's URL. Static fields — `needs_update`, `deployed_sha`,
+`pending_reminders`, `parent`, `config` link — remain visible
+regardless of run state.
 
-  - The label vocabulary is **open** — it is the node's own wire tag
-    (`NodeKind::as_str`, the same strings the graph wire's node
-    labels carry),
-    not a fixed set. Treat it as an opaque display string; do not
-    switch on specific values. `restarting` in particular no longer
-    exists, because no node kind is unique to a restart.
-  - It is **not** exclusively operator-initiated, and **not** limited
-    to rebuild-shaped work — `running_transients()` on the backend is
-    a status-only test (any `Running` node whose payload names a
-    non-empty agent lights a pill), so work the operator never
-    clicked (a meta-update cascade, a crash-recover rebuild, a
-    lease-exempt `prebuild`) lights the same mechanism.
+**Line 2** — status badges only (no per-card action buttons — actions
+moved to the **selection bar** or the **per-agent `⋮` menu**, see
+below).
 
-  Ops with no queue node behind them (destroy, migration) supply
-  their own label directly via `TransientSet`/`TransientCleared`
-  events carrying no backing node at all.
+### Status badges
 
-  **Queued (not-yet-started) work shows nothing on the card.** An
-  earlier version of this page had a job-queue-backed fallback badge
-  for the `Pending` case (`queuedOpsByAgent()`, reading a `GET
-  /api/jobq/graph` fetch); removed per mara, on review of
-  hyperhive#3028's PR: *"swarm.js should not need to pull in the jobq
-  to do its job,"* followed by *"remove the per agent pending stuff -
-  only show what is running."* Per-agent badges never came back — only
-  the queue-summary banner below did, once a narrow enough endpoint
-  existed for it to read instead of the full graph.
-  An **active model badge** (`model · <name>`, blue) appears when the
-  container is running and the harness has persisted a model name
-  (`harness/hyperhive-model`). Read by hive-c0re's `ContainerView`
-  (`read_active_model`); absent until the agent has completed at least
-  one turn and stale values are suppressed for stopped containers.
-  A `ctx · Nk` chip showing the agent's last-turn context size,
-  populated from `DashboardState.ctx_tokens` (absent until the
-  agent has completed at least one turn). The chip colour (green /
-  yellow / red) is keyed off `DashboardState.context_window_tokens`
-  (the real context window for the model the agent last ran on,
-  authoritative from the agent side); the badge goes yellow ≥ 50%
-  and red ≥ 75% of that window, matching the harness compaction
-  watermarks. When the window value is absent the badge falls back
-  to fixed 100k / 150k thresholds.
-- Line 2: status badges only (no per-card action buttons — actions
-  moved to the **selection bar** or the **per-agent `⋮` menu**, see
-  below).
+**Which single badge (hyperhive#3139):** `ContainerView.failed`
+(systemd `ActiveState=failed` — the unit exhausted its bounded
+restarts and gave up on its own) draws a red `✖ gave up` badge;
+otherwise a plain muted `■ not running` — a container an operator
+stopped deliberately. Both states read `running: false`; `failed` is
+the orthogonal fact (a fifth one alongside `paused`/`needs_update`/
+`needs_login`, same "independent flags, no state machine" shape —
+see `ContainerView`'s own doc comment) that tells them apart. An
+older backend without the field serves `failed: undefined`, which
+reads falsy — degrades cleanly to the single `not running` badge.
+
+When the container is running, status badges follow — `⊘ rate
+limited` (red, while the harness is parked after a 429), `needs
+login`, `needs update` — plus **one `◐ pending-state…` pill per
+active transient** (replaces buttons during operator-initiated
+start / stop / restart / rebuild / destroy). An agent can carry
+**several transients at once** — e.g. a lease-exempt `prebuild`
+running alongside a `stop_for_update` on the same agent — and each
+renders as its own independent badge rather than being collapsed
+into one label, matching the existing multi-badge convention this
+line already uses for `paused`/`needs_update`/model/ctx.
+
+Any pending badge means the row is actually **running** something
+right now — there is no separate queued-but-not-started row state
+to visually distinguish it from (see **Pending-badge derivation**
+below), so every row carrying ≥1 badge keeps the amber row tint AND
+draws a **rotating amber ring** around the agent icon.
+
+**Pending-badge derivation:** transients only (`transientsState`,
+keyed `agent -> Map<kind, since_unix>`) — a transient is **derived
+from a job-queue node currently `Running`** against that agent, not
+declared per request, so its label follows the operation as it
+progresses (a rebuild reads `stop_for_update`, then `swap`, then
+`reconcile` rather than one constant `rebuilding` for its whole
+life). Two consequences for anything rendering it:
+
+- The label vocabulary is **open** — it is the node's own wire tag
+  (`NodeKind::as_str`, the same strings the graph wire's node
+  labels carry), not a fixed set. Treat it as an opaque display
+  string; do not switch on specific values. `restarting` in
+  particular no longer exists, because no node kind is unique to a
+  restart.
+- It is **not** exclusively operator-initiated, and **not** limited
+  to rebuild-shaped work — `running_transients()` on the backend is
+  a status-only test (any `Running` node whose payload names a
+  non-empty agent lights a pill), so work the operator never
+  clicked (a meta-update cascade, a crash-recover rebuild, a
+  lease-exempt `prebuild`) lights the same mechanism.
+
+Ops with no queue node behind them (destroy, migration) supply
+their own label directly via `TransientSet`/`TransientCleared`
+events carrying no backing node at all.
+
+**Queued (not-yet-started) work shows nothing on the card.** Only
+running work gets a per-agent pending badge — by design, there is no
+fallback badge for work that's merely `Pending` in the queue, since
+the swarm view stays independent of job-queue internals. The queue-
+summary banner below is the only queued-work indicator on this tab,
+and it reads the narrow `/api/jobq/rollup` endpoint rather than the
+full graph.
+
+**Active model badge** (`model · <name>`, blue) appears when the
+container is running and the harness has persisted a model name
+(`harness/hyperhive-model`). Read by hive-c0re's `ContainerView`
+(`read_active_model`); absent until the agent has completed at least
+one turn and stale values are suppressed for stopped containers.
+
+**`ctx · Nk` chip** shows the agent's last-turn context size,
+populated from `DashboardState.ctx_tokens` (absent until the
+agent has completed at least one turn). The chip colour (green /
+yellow / red) is keyed off `DashboardState.context_window_tokens`
+(the real context window for the model the agent last ran on,
+authoritative from the agent side); the badge goes yellow ≥ 50%
+and red ≥ 75% of that window, matching the harness compaction
+watermarks. When the window value is absent the badge falls back
+to fixed 100k / 150k thresholds.
 
 **Per-agent `⋮` overflow menu** — a `⋮` button appears on the right
 edge of each container row. Clicking it opens a small dropdown with
@@ -1011,19 +1010,11 @@ fixed order, zero counts included — rather than the full
 `/api/jobq/graph` tree: `running` sums the `Running` and `Finishing`
 entries' `roots` (`Finishing` = own work done, subtree still going,
 still in flight), `queued` reads the `Pending` entry's `roots`.
-`roots` specifically, not `nodes` — the banner has always meant *N
-whole operations*, not raw steps (one rebuild is ~7 nodes but 1
-root); `nodes` exists on the same endpoint for a consumer that wants
+`roots` specifically, not `nodes` — the banner means *N whole
+operations*, not raw steps (one rebuild is ~7 nodes but 1 root);
+`nodes` exists on the same endpoint for a consumer that wants
 step-level counts instead, unused here.
 
-This banner went through two prior shapes before landing here, both
-per mara review comments on hyperhive#3028's PR: a client-side
-derivation over the full graph (*"swarm.js should not need to pull in
-the jobq to do its job"*), then removed entirely rather than keep
-that interim fetch (*"dont replace one legacy thing with another"*).
-Restored once the dedicated rollup endpoint (hyperhive#3033) existed
-for it to read directly instead.
-
 ### Themed dialogs
 
 All confirmations, prompts, and transient error notices use an
@@ -1065,67 +1056,35 @@ the dashboard and CLI paths behave identically.)
 
 ### Topology tree
 
-Container rows render as a forest, not a flat list — each agent
-sits indented under its declared parent. `swarm.js::buildAgentTree`
-walks `ContainerView.parent` for every container in the snapshot
-and produces a render order with per-row depth + sibling-position
-info:
-
-- Top-level rows are agents with `parent = null` OR a parent that
-  doesn't appear in the container map (orphans get hoisted to root
-  so they're still visible).
-- Within each level children sort alphabetically by name; roots
-  likewise.
-- Cycle safety: any container not reached during the root-walk is
-  appended at the end as a root, so no agent ever silently
-  disappears from the list when the topology JSON is malformed.
-- The pre-topology rendering shape (every container at depth 0,
-  flat list) collapses to the same visual today when no parent
-  field is set — bit-identical fallback path.
+See **SW4RM tab** above for the parent/child derivation, sibling
+sort order, and cycle-safety rules (`swarm.js::buildAgentTree` walks
+`ContainerView.parent`) — this section covers only how the tree is
+*drawn*.
 
 The per-row prefix column (`.tree-prefix`) is **DOM-painted, not
-text-glyph-painted**. Each indent lane is its own positioned
-`<span>` so CSS can draw full-height vertical bars that bridge the
-gap between sibling rows; using text box-drawing characters
-(`├─`, `└─`, `│  `) only paints one text-line tall and leaves
-visible breaks between the taller-than-one-line container cards.
-The bars come in two flavours: continuation (the ancestor's
-subtree extends below this row → vertical line top→bottom) or
-blank (ancestor was the last sibling at its level → no line
-needed). The joint at the row's own depth column is `├` (more
-siblings below) or `└` (last sibling at this depth — vertical
-stops at the row's icon midline).
-
-**Indent + lane geometry.** Each depth level shifts the row right
-by `1.8em` (the lane width). The per-depth ladders are hardcoded
-for six levels — enough for any plausible hive topology, and the
-typed `attr()` function from CSS Values 5 that would collapse
-this to one rule is still partial-support (Chromium-only as of
-2026). The `.tree-prefix` span sits absolutely positioned with
-`left: -<depth>*1.8em` so its right edge meets the row content
-(the icon) and its leftmost lane lines up with top-level rows'
-icons at `x = 0`. Each `.tree-lane` is `flex: 0 0 1.8em` so all
-lanes have equal width. Continuation bars are drawn at lane
-center (`left: 0.6em`, `border-left: 1px solid currentColor`,
-`top: 0; bottom: 0`) and extend through `.containers { gap: 0.4em }`
-into the next sibling's prefix (`bottom: -0.4em` on the prefix
-span itself) so adjacent ancestor lines visually merge into one
-unbroken vertical line. The horizontal stub at a row's own joint
-lands at the icon midline so the L/T meets the icon edge cleanly.
-When every container has `parent = null` (pre-topology state) the
-`[data-depth]` attribute is absent on every row and these rules
-are no-ops — the layout reads exactly like the legacy flat list.
+text-glyph-painted**: each indent lane is its own positioned `<span>`
+so CSS can draw full-height vertical bars that bridge the gap between
+sibling rows. Plain text box-drawing characters (`├─`, `└─`, `│  `)
+would only paint one text-line tall and leave visible breaks between
+the taller-than-one-line container cards, so the bars are drawn as
+CSS borders instead: a continuation bar runs the full height of an
+ancestor's still-open subtree, and the joint at a row's own depth is
+`├` (more siblings below) or `└` (last sibling — the line stops at
+the row's icon midline). Exact lane widths and positioning live in
+`swarm.js`'s tree-prefix rendering and its paired CSS rules — not
+reproduced here since they're tuned in pixel units and will drift.
+When every container is at depth 0 (no `parent` set) these rules are
+all no-ops and the layout reads like a plain flat list.
 
 ## Selection bar
 
-Per-card action buttons (`R3ST4RT` / `ST0P` / `ST4RT` / `R3BU1LD` /
-`DESTR0Y` / `PURG3`) used to live on each container row; the
-operator picked the bulk-bar model instead. Clicking an agent's
-icon toggles its selection (an in-memory `Set<name>`); `Esc` or
-the bar's `✕ clear` button drops everything. The selection
-persists across tab switches in-memory — the bar just hides on
-non-SW4RM tabs since other tabs don't show the agent cards needed
-to cross-reference.
+Bulk actions (`R3ST4RT` / `ST0P` / `ST4RT` / `R3BU1LD` / `DESTR0Y` /
+`PURG3`) live here rather than as per-card buttons — see **Container
+row** above. Clicking an agent's icon toggles its selection (an
+in-memory `Set<name>`); `Esc` or the bar's `✕ clear` button drops
+everything. The selection persists across tab switches in-memory —
+the bar just hides on non-SW4RM tabs since other tabs don't show the
+agent cards needed to cross-reference.
 
 When one or more agents are selected (via icon click), a sticky
 frosted-mauve bar slides up from the bottom of the viewport

From b1d43fc1e7ff6eb7d067be07691b711f37a50b31 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:43:31 +0200
Subject: [PATCH 13/64] docs(web-ui): point port-hash detail at gotchas.md
 instead of restating it

---
 docs/web-ui.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/web-ui.md b/docs/web-ui.md
index 61901099..37513f7d 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -1,8 +1,10 @@
 # Web UI
 
 Two web surfaces share the same skeleton: the dashboard (port 7000)
-and the per-agent UIs (every container hashes into :8100-8999 via
-`lifecycle::agent_web_port`'s FNV-1a).
+and the per-agent UIs (each container's port is a deterministic hash
+in :8100-8999 — see
+[`gotchas.md#web-ui-ports-collide-on-hash`](gotchas.md#web-ui-ports-collide-on-hash)
+for the mechanics and the collision caveat).
 Both are SPAs — `GET /` returns a static shell, `/api/state`
 returns JSON, JS renders. No full-page reloads.
 

From 721a99ed64d8dd1824a1fa5437172f471915d833 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:43:50 +0200
Subject: [PATCH 14/64] docs(web-ui/shape): add routes header, trim historical
 framing

---
 docs/web-ui/shape.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md
index 0de8445c..718010d1 100644
--- a/docs/web-ui/shape.md
+++ b/docs/web-ui/shape.md
@@ -3,6 +3,8 @@
 > Part of [Web UI](../web-ui.md). See also:
 > [Dashboard layout](dashboard.md) · [Per-agent page](agent.md)
 
+## Shared routes
+
 - `GET /` → `index.html` from the bundled frontend dist (see
   `frontend/`). Both binaries' routers declare their dynamic
   endpoints first and then `fallback_service(ServeDir::new(...))`
@@ -19,8 +21,8 @@
   `dashboard.css` / `flow.css` / `logs.css`); `common.css` inlines
   `base.css` + `terminal.css` via esbuild's `@import` resolution.
   `terminal.js` exports `{ create, linkify }` as ES module
-  members (no more `window.HiveTerminal` global outside the
-  back-compat shim the IIFE bodies still use). The dashboard's
+  members; a back-compat shim in the IIFE bodies still exposes
+  a `window.HiveTerminal` global for callers that need it. The dashboard's
   `#msgflow` and the per-agent `#live` log are both backed by
   this terminal — sticky-bottom auto-scroll, "↓ N new" pill,
   history backfill, SSE plumbing all live there. Each page
@@ -209,13 +211,11 @@ soon as they blur.
 **Atomic section repaint:** every managed-section renderer goes
 through `paintAtomic(liveRoot, build)`: the builder appends into
 a fresh `DocumentFragment` (off-DOM) and the commit is one
-`replaceChildren` call. The naive `root.innerHTML = ''; root.append(...)`
-shape was visibly flashing empty on every poll cycle — on async
-paths the await yield gave the browser a paint opportunity between
-the clear and the re-append, and on complex builds (many `el()`
-allocations) layout could escape the per-task budget even on the
-synchronous path. The fragment approach keeps the intermediate
-empty state invisible. Builders receive the fragment as their
+`replaceChildren` call, so the intermediate empty state is never
+visible — clearing and re-appending directly into the live root can
+leave it empty for a paint (on async builders) or a whole frame (on
+large synchronous ones), which reads as a visible flash on every
+poll cycle. Builders receive the fragment as their
 `root`, so existing renderer code carries over unchanged; early
 returns inside the builder still commit whatever was appended
 before they returned.

From f104d39c72dbba1b1513bb4c6fb3f90ebb606430 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:45:11 +0200
Subject: [PATCH 15/64] docs(web-ui/agent): add section headers, dedupe shared
 shape/rendering detail, trim changelog framing

---
 docs/web-ui/agent.md | 54 ++++++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 25 deletions(-)

diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md
index 7bde2cb1..387ccd2b 100644
--- a/docs/web-ui/agent.md
+++ b/docs/web-ui/agent.md
@@ -4,7 +4,11 @@
 > [Shape (shared)](shape.md) · [Dashboard layout](dashboard.md)
 
 
-Three fixed-position layers frame a full-viewport terminal:
+Three fixed-position layers frame a full-viewport terminal: a header,
+scrollable main content, and a footer composer — plus a slide-in side
+panel for flyouts and long content.
+
+## Header
 
 **Fixed-overlay header** (`<header class="agent-header">`): frosted
 glass — `backdrop-filter: blur` lets scrolled terminal rows show
@@ -121,8 +125,11 @@ just `name`). The frontend uses `qualified_label` to set the browser
 tab title so two tabs from different hives are distinguishable; the
 header `<h2 id="title">` stays short.
 
+## Main content
+
 **Main content** (`<main class="agent-main">`): fills the viewport
 and scrolls behind the fixed header + footer.
+
 - `#status` overlay: empty when online; shows the login form / OAuth
   URL when `status` is `needs_login_*`. The OAuth code input is
   `type="password"` with a `👁 reveal` toggle that flips it back to
@@ -146,11 +153,15 @@ and scrolls behind the fixed header + footer.
   `.agent-main` and `.terminal-wrap` both `inset: 0` fill the same
   area.
 
+## Footer / composer
+
 **Fixed-overlay footer** (`<footer class="agent-composer">`): frosted
 glass, symmetric with the header. Contains the operator-input
 textarea (`#term-input`) — multi-line, Enter sends, Shift+Enter
-newlines, Tab-completes slash commands (see "Terminal-embedded
-prompt" below).
+newlines, Tab-completes slash commands (see [Terminal-embedded
+prompt](#terminal-embedded-prompt) below).
+
+## Side panel
 
 **Side panel** (slide-in from right): singleton shared with the
 dashboard's side panel shape. Carries inbox and todos flyouts (opened
@@ -175,21 +186,12 @@ the checked ids to `POST /api/todos/mark-done`, which dismisses them
 from the harness-local store (same effect as `cancel_loose_end(kind:
 "todo")`, just from the web UI instead of the agent's own tool calls).
 
-Older per-agent flyouts this doc used to describe (a "loose-ends"
-list of questions/approvals/reminders backed by a since-removed
-`GET /api/loose-ends`, and a read-only "tasks" list of in-flight bash
-tasks backed by a since-removed `GET /api/bash-tasks`) no longer
-exist — todos superseded both. A third casualty of that migration —
-an "ask → operator" inline-answer form that used to mount under an
-`mcp__hyperhive__ask(to: "operator", ...)` row in the terminal
-scrollback — depended on the same removed `/api/loose-ends` endpoint
-and was found dead (hyperhive#2922: the binding never fired, so the
-slot never mounted a form). Per mara's call on that issue, it was
-removed rather than rebuilt — the main dashboard's own question
-surfacing (`dashboard/src/swarm.js` + `call.js`) is the one supported
-path for answering a pending question as the operator; this agent's
-own terminal just shows the `ask` tool call like any other tool call,
-with no inline answer affordance.
+The todos flyout is the only per-agent flyout — there is no separate
+"loose-ends" or "tasks" list. There is also no inline answer form for
+`ask` tool calls in this terminal: an `ask` renders like any other
+tool call, and the operator answers a pending question from the
+dashboard's Y3R C4LL tab instead (see
+[`terminal-rendering.md`](../terminal-rendering.md#inline-ask-operator-answer)).
 
 ## Live view
 
@@ -202,17 +204,19 @@ seconds) — a flattened sibling of the event tag on both the live
 SSE frame and the replayed history rows. The web UI:
 
 - fetches `GET /events/history` on page load and replays the last
-  2000 events (oldest first, with `.no-anim` so they don't
-  stagger);
+  2000 events (oldest first);
 - then subscribes to `GET /events/stream` (SSE) for live tail;
 - shows a granular state badge above the terminal, driven
   authoritatively from `/api/state.turn_state`. SSE turn_start /
   turn_end still flip the badge instantly between renders;
-- sticky-bottom auto-scroll: scrolling up parks the view; new rows
-  surface a "↓ N new" pill instead of yanking;
 - terminal-themed: phosphor mauve glow, Crust bg,
   backdrop-filter blur, row fade-in slide-up.
 
+The backfill/live-tail dedupe, sticky-bottom auto-scroll, and "↓ N
+new" pill are the shared terminal-pane mechanics described in
+[Shape](shape.md#shared-terminal-pane) — this page's log is one
+instance of that same factory.
+
 Per-stream rendering (see [`docs/terminal-rendering.md`](../terminal-rendering.md) for
 the full row taxonomy and dispatch logic):
 
@@ -323,9 +327,9 @@ shaped).
      (`projects/<hash>/*.jsonl`), sessions, shell-snapshots,
      plans, settings, telemetry, and the dir itself, so
      `claude --continue` keeps working after a fresh login.
-     Wholesale `remove_dir_all` of `~/.claude/` was the previous
-     shape and broke session continuity; the narrowed allow-list
-     is the fix.
+     ⚠️ Deleting the whole `~/.claude/` directory instead breaks
+     session continuity — logout must stay narrowed to just the
+     credential files.
   3. Flip `LoginState::NeedsLogin` + emit a `LiveEvent::Note`
      describing exactly what was wiped, then emit
      `needs_login_idle`. The turn-loop's next iteration parks

From fda6a9ac9dc7a22194ba9b4312d3b27475a4ead8 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:45:21 +0200
Subject: [PATCH 16/64] docs(terminal-rendering): rewrite ask-answer section in
 present tense

---
 docs/terminal-rendering.md | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/docs/terminal-rendering.md b/docs/terminal-rendering.md
index 5ff08259..9e463aad 100644
--- a/docs/terminal-rendering.md
+++ b/docs/terminal-rendering.md
@@ -210,17 +210,13 @@ This keeps less-frequent tools that don't have a specific
 `fmtToolUse` case from dumping raw JSON. Common matrix and
 hyperhive tools have their own cases and skip this path.
 
-## Inline ask-operator answer (removed)
+## Inline ask-operator answer
 
-An `mcp__hyperhive__ask(to: "operator", ...)` row used to mount an
-inline answer form (`.ask-answer-inline-slot`, `reconcileAskBinds()`)
-directly in the terminal scrollback. It depended on a since-removed
-`/api/loose-ends` endpoint and had been silently dead since that
-removal (hyperhive#2922) — ripped out rather than rebuilt (mara: only
-the main dashboard's own question surfacing needs to work). An `ask`
-tool call now renders like any other tool call, with no inline answer
-affordance; the operator answers via the dashboard
-(`dashboard/src/swarm.js` + `call.js`).
+An `mcp__hyperhive__ask(to: "operator", ...)` row has no inline
+answer form in this terminal — it renders like any other tool call.
+The operator answers a pending question from the main dashboard's
+own question surfacing (`dashboard/src/swarm.js` + `call.js`, the
+Y3R C4LL tab), not from the per-agent page.
 
 ## Dashboard side (not covered here)
 

From b15e0e973cce9014cf5353de068ae6c835cd479d Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:46:26 +0200
Subject: [PATCH 17/64] docs(network): dedupe UDS control-plane explanation

---
 docs/network.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/docs/network.md b/docs/network.md
index f538bf95..39f24c1e 100644
--- a/docs/network.md
+++ b/docs/network.md
@@ -245,12 +245,11 @@ wiring is runtime:
   It is ordered `before` the harness (`hive-ag3nt`), the matrix daemon, and
   `tea-login` so the resolver is correct before the first DNS lookup.
 
-**Why isolation is safe**: all hive-c0re communication goes
-through unix domain sockets (`/run/hive/mcp.sock` for agent requests,
-`/run/hive/priv.sock` for privileged ops).
-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.
+**Why isolation is safe**: hive-c0re's control-plane sockets are unix
+domain sockets bind-mounted into containers, not network listeners — see
+the *Control plane (no network)* bullet under [Network
+map](#network-map) above. `PRIVATE_NETWORK=1` has no effect on a path
+that never touches the network stack.
 
 The nix side also enables IP forwarding + NAT (agents reach the internet
 through the host) and drops bridge-subnet → loopback traffic (defence-in-depth

From df81ec46f0da5dd0629f3dd181571b07b2dd4344 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:50:14 +0200
Subject: [PATCH 18/64] docs(gateway): trim historical framing, dedupe repeated
 TLS/routing statements

---
 docs/gateway.md | 37 ++++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 15 deletions(-)

diff --git a/docs/gateway.md b/docs/gateway.md
index fd86ef1f..66039431 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -1,6 +1,6 @@
 # hive-gateway
 
-Single nginx in front of every hyperhive web surface. Runs on the **host**, next to hive-c0re; system-config (not meta-flake managed). Configured via `services.hyperhive.gateway.*` + per-subsystem opt-in flags in `services.hyperhive.{forge,matrix,...}`. (It lived in a `hive-gateway` container until #3088 — one that shared the host netns anyway, so the boundary gave no network isolation while costing a resolv.conf sync, a machine-bus reload and three bind mounts.)
+Single nginx in front of every hyperhive web surface. Runs on the **host**, next to hive-c0re, rather than in its own container: it shares the host netns anyway (see [Vhost map](#vhost-map) below), so containerizing it would buy no network isolation while costing a resolv.conf sync, a machine-bus reload, and three bind mounts. System-config (not meta-flake managed). Configured via `services.hyperhive.gateway.*` + per-subsystem opt-in flags in `services.hyperhive.{forge,matrix,...}`.
 
 ## Vhost map
 
@@ -21,7 +21,8 @@ The authelia vhost is declared only by the host that **runs** authelia, not by e
 
 ⚠️ **A `502` from this vhost usually means authelia has no users yet, not that the proxy is misconfigured.** Authelia treats an empty user store as a fatal startup error, so an enabled-but-unbootstrapped swarm crash-loops the container while the vhost in front of it works perfectly. Check `journalctl -M swarm-authelia -u authelia-swarm` before suspecting anything here; the bootstrap step is in [`swarm/sso.md`](swarm/sso.md).
 
-Per-agent UIs stay sub-path because they're hyperhive-internal and base-path-aware. External standard apps (forge / matrix) get sub-domains because their defaults work cleanly at sub-domain root + per-origin cookies / storage isolation matters.
+Per-agent UIs stay sub-path, forge and matrix get sub-domains — see
+[Sub-domain shape (rationale)](#sub-domain-shape-rationale) below for why.
 
 ## Discovery flow (matrix)
 
@@ -37,7 +38,7 @@ Federation peers fetch `.well-known/matrix/server` → `{"m.server":"matrix.<hiv
 
 ## SPA fallback (Accept-header pattern)
 
-The per-agent UIs and the `matrix.<hive>` vhost serve a flutter/SPA bundle via the Accept-header pattern below. (The `<hive>` dashboard catch-all used this too but now routes by **path** — see the dashboard note after.) Two requirements collide:
+The per-agent UIs and the `matrix.<hive>` vhost serve a flutter/SPA bundle via the Accept-header pattern below. The dashboard vhost instead routes by **path** — see [Dashboard: path-based routing](#dashboard-path-based-routing-not-accept-header) below. Two requirements collide:
 
 - hard-refresh on a sub-route must serve `index.html` (SPA's client-side router takes over after JS bootstrap)
 - a non-navigation request that isn't an on-disk asset must NOT get HTML with the wrong content-type
@@ -48,13 +49,13 @@ For matrix / per-agent static assets, `<final>` is `=404` (a missing asset is ju
 
 ### Dashboard: path-based routing (not Accept-header)
 
-Now that every hive-c0re backend route lives under `/api/` plus the single `/webhook/knowledge` endpoint, the dashboard vhost routes by **path**, not Accept header:
+Every hive-c0re backend route lives under `/api/` plus the single `/webhook/knowledge` endpoint, so the dashboard vhost routes by **path**, not Accept header — deterministic, unlike a content-type split where the same URL could resolve differently depending on the caller's `Accept` header:
 
 - `location /api/` → hive-c0re (`7000`): all dashboard data, actions/mutations, and the two SSE streams (`/api/dashboard/stream`, `/api/build-logs/id/{id}/stream`). Carries `proxy_buffering off` + a 1d read timeout for the streams.
 - `location /webhook/` → hive-c0re: the knowledge webhook.
 - `location /` → the dashboard dist (from the `servedFrontend` nix-store path) with `try_files $uri /index.html` (SPA fallback).
 
-Each location carries a duplicated `auth_basic` block (separate locations don't inherit it). This keeps the gateway static-serving the dashboard dist while hive-c0re stays API-only — a frontend-only change no longer rebuilds + restarts the core daemon. The earlier `map $http_accept` Accept-header split was replaced because it made the *same* URL behave differently by content-type (e.g. `/api/state` fetched with `Accept: text/html` wrongly returned `index.html`); path routing is deterministic. A new top-level c0re route prefix (beyond `/api` + `/webhook`) needs a matching `location` added to the dashboard vhost.
+Each location carries a duplicated `auth_basic` block (separate locations don't inherit it). This keeps the gateway static-serving the dashboard dist while hive-c0re stays API-only — a frontend-only change doesn't rebuild or restart the core daemon. A new top-level c0re route prefix (beyond `/api` + `/webhook`) needs a matching `location` added to the dashboard vhost.
 
 ## Local dev (`localHostsEntry`)
 
@@ -204,7 +205,13 @@ On by default, and listens on `httpsPort` (default 443) on every vhost beside th
 
 The issuer is a **host-held hive CA**, not a bare self-signed leaf. A host service (`hive-tls-ca.service`, from the `hive-tls` module) generates a long-lived CA (`services.hyperhive.tls.caValidityDays`, default ~20y) under `services.hyperhive.tls.stateDir` (default `/var/lib/hive-tls`), then signs a gateway **leaf** (`leafValidityDays`, default 30d) with it. `hive-gateway-self-signed-cert` then imports the leaf into nginx's state dir (`/var/lib/hive-gateway/tls/{cert,key}.pem`).
 
-⚠️ **Do not collapse that import unit into pointing nginx at the CA dir.** It does two jobs. It re-modes the leaf (`hive-tls-ca` writes the key `0600 root:root`; nginx's pre-start `nginx -t` runs as the *nginx user*, so a `0600` key fails the config test and blocks the unit), and it guarantees **every cert path the nginx config names exists** — which is what the swarm-services fallback below is for. Removing it re-creates the #3097 outage.
+⚠️ **Do not collapse that import unit into pointing nginx at the CA dir.**
+It does two jobs, and skipping it has taken the gateway down in production
+before. It re-modes the leaf (`hive-tls-ca` writes the key `0600
+root:root`; nginx's pre-start `nginx -t` runs as the *nginx user*, so a
+`0600` key fails the config test and blocks the unit), and it guarantees
+**every cert path the nginx config names exists** — which is what the
+swarm-services fallback below is for.
 
 **Why a CA, not a bare leaf**: a bare self-signed leaf is its own trust anchor, so every regeneration is a new anchor every consumer must re-trust — and a runtime-generated leaf can't be wired into an agent's build-time trust store at all. With a stable CA, agents and federation peers trust it *once*; leaf rotation never re-breaks them.
 
@@ -250,8 +257,8 @@ services.hyperhive.swarm.hives.example = { domain = "example.com"; };  # no cert
 
 ### Fronting with an external TLS terminator
 
-There is no http-only mode: the gateway always terminates TLS (self-signed
-floor). Two paths for an operator who wants their own TLS terminator:
+There is no http-only mode (see [TLS modes](#tls-modes) above). Two paths
+for an operator who wants their own TLS terminator:
 
 - give the gateway the real cert via `tls.certDir` (or `tls.acme`) so it
   serves proper TLS directly — no separate proxy needed; or
@@ -259,8 +266,8 @@ floor). Two paths for an operator who wants their own TLS terminator:
   intended direction for "bring your own proxy" — the gateway is not meant
   to expose an unencrypted TCP upstream).
 
-**`.well-known/matrix/{client,server}` scheme** is always `https` now — the
-gateway always terminates TLS, so discovery responses always advertise https.
+Because of this, `.well-known/matrix/{client,server}` discovery responses
+always advertise `https` (see [Discovery flow](#discovery-flow-matrix) above).
 
 ## Firewall posture (host-level)
 
@@ -276,8 +283,8 @@ host-loopback fallback for the pre-UDS/gateway-disabled case, but isn't
 what the gateway itself proxies through.
 
 `services.hyperhive.gateway.openFirewall = true` opens both `port` and
-`httpsPort` — the gateway always terminates TLS (self-signed floor), so
-both are always served.
+`httpsPort` — both are always served, since the gateway always terminates
+TLS (see [TLS modes](#tls-modes) above).
 
 Every agent hashes into the same port range (no special case), so
 one range opening covers every container.
@@ -589,7 +596,7 @@ header is added alongside the other security headers.
 enabling it on a deployment that later loses TLS locks browsers out
 until `max-age` expires. Only enable when TLS is permanent.
 
-The gateway always terminates TLS now (self-signed floor), so HSTS is
-always served over https when enabled — the old "HSTS requires a TLS mode"
-assertion is gone (it can no longer be violated).
+Since the gateway always terminates TLS (see [TLS modes](#tls-modes)
+above), an enabled HSTS header is always served over https — there is no
+TLS-less mode that could violate it.
 

From fea40ed770108cc79f6f7e7bcce78119223ece15 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:51:08 +0200
Subject: [PATCH 19/64] docs(matrix): rephrase build-fix intro away from
 changelog framing

---
 docs/matrix.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/matrix.md b/docs/matrix.md
index 5c27216f..167ff14d 100644
--- a/docs/matrix.md
+++ b/docs/matrix.md
@@ -250,7 +250,7 @@ Both fixed in `nix/host-modules/hive-matrix.nix` via two derivations:
   incremental cost) and (b) installs `fluffychat-web-imaging`'s
   outputs into `$out`.
 
-Two non-obvious fixes from review history:
+Two non-obvious details worth knowing before touching either derivation:
 
 - **`make -C js`** instead of `cd js; make` — keeps the build-phase
   pwd at the source root so `installPhase` doesn't have to know

From 8a2ffbbef7e87a37fcd72c7e794e82363d7ef339 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:45:04 +0200
Subject: [PATCH 20/64] docs(ci): fix required-check contradiction, dedupe
 bootstrap, trim history

---
 docs/ci.md | 51 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 28 insertions(+), 23 deletions(-)

diff --git a/docs/ci.md b/docs/ci.md
index 150c1e40..7b414467 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -31,17 +31,19 @@ writeup.
 
 ## CI checks
 
-Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers):
+Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers),
+defined in [`.forgejo/workflows/ci.yml`](../.forgejo/workflows/ci.yml). All
+three are required checks (forge branch protection) — a hit on any of them
+blocks merge.
 
-| Job | What it runs | Currently required |
-| --- | --- | --- |
-| **nix flake check** | treefmt + rustfmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation | yes |
-| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) | no (red, non-blocking) |
-| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) | no (red, non-blocking) |
+| Job | What it runs |
+| --- | --- |
+| **nix flake check** | treefmt + rustfmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation |
+| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) |
+| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) |
 
-The tracker-tag and comment-block checks are non-blocking today (a hit fails the
-check but does not prevent merge) while the legacy backlog is cleaned up. They are
-expected to become required checks once the tree is clean.
+`hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
+without an empty commit.
 
 ### Running checks locally
 
@@ -68,14 +70,17 @@ diagnostic if either fails — catching the issue locally before CI sees it.
 Note that the hook does **not** run `cargo clippy` or `cargo test` (those are
 slow); run those manually before pushing Rust changes.
 
-## Operator bootstrap
+## Configuration reference
 
-Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's it — no manual token provisioning.
+The internal forge is always present (mandatory), so the runner always has a
+hive-forge instance to register against — nothing extra to enable beyond
+`services.hyperhive.forge.ci.enable = true` (see *For operators* above).
 
-**Requirements:**
-
-- The internal forge is always present (mandatory), so the runner always has a hive-forge instance to register against — nothing extra to enable.
-- Optional: tune `services.hyperhive.forge.ci.name` (runner name in forge admin panel), `concurrency` (parallel job capacity), `labels` (workflow targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration string e.g. `"3h"` — a job that exceeds it is killed so a hung or runaway build can't hold the runner's single slot indefinitely).
+Optional tuning: `services.hyperhive.forge.ci.name` (runner name in forge
+admin panel), `concurrency` (parallel job capacity), `labels` (workflow
+targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration
+string e.g. `"3h"` — a job that exceeds it is killed so a hung or runaway
+build can't hold the runner's single slot indefinitely).
 
 ## Container design
 
@@ -86,7 +91,14 @@ Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's
 
 ## Auto-registration flow
 
-Registration is **off the container's boot-critical path** — hive-c0re owns it and runs it out of band, so a slow forge or core-token never delays the container's start. (The earlier design ran a host-side `hive-ci-prefetch.service` that gated `container@hive-ci` start on a forge round-trip, which could exceed the nspawn start timeout and trip a restart loop; moving registration into hive-c0re removed that.) The core admin token is held only by hive-c0re on the host; only the runner registration token reaches the container.
+Registration is **off the container's boot-critical path** — hive-c0re owns
+it and runs it out of band, so a slow forge or core-token never delays the
+container's start. Gotcha: don't gate the container's own start on a forge
+round-trip (a host-side unit that did this could exceed the nspawn start
+timeout and trip a restart loop) — registration must stay something
+hive-c0re drives after the container is already up. The core admin token is
+held only by hive-c0re on the host; only the runner registration token
+reaches the container.
 
 ### hive-c0re side (`forge/ci_runner.rs`, run during the startup sweep)
 
@@ -139,13 +151,6 @@ runner as a hard `git clone` failure. The
 hive-c0re-managed namespaces (`config/`, `shared/`, `agents/`, `core/`)
 to avoid provisioning collisions.
 
-## CI workflow
-
-Three jobs are defined in [`.forgejo/workflows/ci.yml`](../.forgejo/workflows/ci.yml):
-`nix flake check`, `tracker-tag lint`, and `comment-block lint`. All three are
-required — a lint failure blocks merge. `hive-forge ci-rerun --pr N` dispatches
-a `workflow_dispatch` retrigger without an empty commit.
-
 ## Security: unsandboxed builds and trusted contributors
 
 **hive-ci should only run CI for trusted contributors.** The security boundary is weaker than it looks:

From 93bb3a294fdb89435aab7fedb5cd08bd9c12b97f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:46:51 +0200
Subject: [PATCH 21/64] docs(forge): reframe changelog-style asides as
 present-tense gotchas

---
 docs/forge.md | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/docs/forge.md b/docs/forge.md
index 6eaacbd7..0aa0f90c 100644
--- a/docs/forge.md
+++ b/docs/forge.md
@@ -51,9 +51,9 @@ read it without touching c0re's host-side credential store.
 
 Two things live in the `agent-configs` Forgejo organization:
 
-- A config repo per agent (`agent-configs/<name>`). As of #1787 the
+- A config repo per agent (`agent-configs/<name>`). The
   agent is a **write collaborator on its own** repo — it can push
-  config-change branches and (once #1838 P2 lands) open config PRs — but
+  config-change branches and (once config-PR support lands) open config PRs — but
   `main` is branch-protected core-only: only hive-c0re's verify-and-ff-push
   merge handler lands on `main`, an operator-team approval is required, and
   the agent can neither push `main` directly nor self-merge. `main` is
@@ -118,19 +118,20 @@ That size property is the whole point. A container rebuild starts the
 poller with no memory of what it delivered, re-scans `?all=false`, and
 finds nothing stale — the delivered threads are already read on forge.
 Forge's own read-state is thus the durable, cross-rebuild record of
-what's been delivered; there is **no persisted cursor**. (This
-replaced an earlier design that left threads unread and leaned on a
-persisted dedup cursor: a rebuild that lost the cursor re-delivered the
-entire still-unread backlog as fresh wakes — the notification flood of
-#2593 / #2106.)
+what's been delivered; there is **no persisted cursor**.
 
-**Read-before-comment coupling, dropped on purpose.** The old design
-left threads unread so the hive-forge read-before-comment guard (which
-keys off forge unread-state) would force the agent to view a thread
-before commenting. That coupling is gone: the broker wake already
-carries the notification body, so *delivery is the read*. An agent that
-wants the full thread still runs `hive-forge comments` / `view`; the
-guard no longer blocks a first comment on a freshly-delivered thread.
+**Gotcha:** don't reintroduce a persisted dedup cursor here. A design
+that leaves threads unread and tracks delivery via a separately-persisted
+cursor is fragile — losing that cursor across a rebuild re-delivers the
+agent's entire still-unread backlog as a flood of fresh wakes. Forge's
+own read-state is the only durable record this design needs.
+
+**Read-before-comment guard doesn't block a fresh wake.** hive-forge's
+read-before-comment guard (which keys off forge unread-state) does not
+force the agent to view a thread before commenting on it: the broker
+wake already carries the notification body, so *delivery is the read*.
+An agent that wants the full thread still runs `hive-forge comments` /
+`view`.
 
 **In-process dedupe (tiny, ephemeral).** A single-process map (thread
 id → last-delivered `updated_at`) guards the narrow window where a
@@ -244,8 +245,8 @@ A notification carrying a `latest_comment_url` normally takes the comment
 path. But a merged/closed subject **keeps** its `latest_comment_url` set,
 so a just-merged PR that had any prior discussion would route to the
 comment path and render `[comment on PR]` (with a stale pre-merge comment
-body) instead of `[PR merged]` — the agent never learns its PR merged
-(#2495). So when the notification IS the merge/close transition — its
+body) instead of `[PR merged]` — the agent never learns its PR merged.
+So when the notification IS the merge/close transition — its
 event time (`updated_at`) is within `NEW_ITEM_TOLERANCE_SECS` of the
 subject's `closed_at` (set for both `merged` and `closed`) — the
 state-change path wins even with a comment url present
@@ -280,7 +281,7 @@ A review submitted with **no body** carries no `latest_comment_url`,
 so it misses the comment path and lands on the state-change path with
 `state == "open"` — exactly like a freshly opened PR. Labeling that
 `new PR` is misleading: agents dismiss it as a duplicate of the
-original open notification and miss the review (#1637). So the `open`
+original open notification and miss the review. So the `open`
 state only earns the `new <kind>` label when the notification's event
 time (`updated_at`) is within `NEW_ITEM_TOLERANCE_SECS` (120s) of the
 subject's `created_at`. Anything later is labeled `activity on <kind>`

From c681b8a34014f50aed7f8765385f17ef2a5c3c1f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:44:26 +0200
Subject: [PATCH 22/64] docs(swarm): dedupe CA summary, drop stale/inaccurate
 fn refs

---
 docs/swarm/README.md | 31 ++++++++++++++-----------------
 1 file changed, 14 insertions(+), 17 deletions(-)

diff --git a/docs/swarm/README.md b/docs/swarm/README.md
index d7c3b8e1..95776d2d 100644
--- a/docs/swarm/README.md
+++ b/docs/swarm/README.md
@@ -73,14 +73,11 @@ and `qualify()` / `qualified_label()` semantics.
 
 ## Swarm CA
 
-A hive's internal TLS chains to a **swarm root CA**: the root signs each
-hive's own CA, and that hive CA signs the gateway leaf, so a peer that
-trusts the root once validates every hive in the swarm rather than being
-pinned to each one by hand.
-
-Provisioning modes, what to hand a peer (`trust-bundle.pem`, never
-`ca.pem`), the name constraints on a hive CA, and how an existing hive
-adopts the hierarchy: [`ca.md`](ca.md).
+A hive's internal TLS chains to a **swarm root CA**, so a peer that
+trusts the root validates every hive in the swarm rather than being
+pinned to each one by hand. Provisioning modes, what to hand a peer
+(`trust-bundle.pem`, never `ca.pem`), the name constraints on a hive
+CA, and how an existing hive adopts the hierarchy: [`ca.md`](ca.md).
 
 ## Running the swarm's shared services
 
@@ -183,17 +180,17 @@ environment and forwarded to agent containers.
 
 ## What the config does at runtime
 
-1. **Dashboard P33RS tab** — `parse_peer_hives()` in `dashboard.rs`
-   reads `HYPERHIVE_PEERS` and includes
-   `peer_hives: Vec<{ name, url }>` in `/api/state`. The dashboard
-   shows a P33RS tab (hidden when the list is empty) with a card per
-   peer linking to `https://{domain}/`. See
-   `docs/web-ui/dashboard.md` § P33RS tab.
+1. **Dashboard P33RS tab** — hive-c0re reads `HYPERHIVE_PEERS` and
+   surfaces it as the peer list in the dashboard's state API. The
+   dashboard shows a P33RS tab (hidden when the list is empty) with a
+   card per peer linking to `https://{domain}/`. Wire format + module
+   pointer: `docs/web-ui/dashboard.md` § P33RS tab.
 
 2. **Agent identity** — the same `HYPERHIVE_PEERS` env var is
-   forwarded to agent containers by `meta.rs`; agent code can call
-   `identity::peers()` to discover peer hives and address them with
-   qualified names (`agent@domain`).
+   forwarded to agent containers, so agent code can discover peer
+   hives and address them with qualified names (`agent@domain`). See
+   `hive-agent/src/identity.rs`'s module doc for the label/domain
+   helpers.
 
 3. **Matrix federation** — when `matrix.enable` is on, tuwunel
    federates with the peer's matrix server (discovered via the peer's

From 42282410ad7511f71993d25b27056176b81f5d87 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:44:34 +0200
Subject: [PATCH 23/64] docs(swarm): cross-link services.md to sso.md and
 secrets.md

---
 docs/swarm/services.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/swarm/services.md b/docs/swarm/services.md
index 6b65109c..bcc64252 100644
--- a/docs/swarm/services.md
+++ b/docs/swarm/services.md
@@ -57,3 +57,7 @@ small-deployment choices, and the scope is the justification: redis
 buys shared session state across replicas and there is one instance;
 SMTP exists to mail humans, and provisioning here is programmatic.
 
+See [`sso.md`](sso.md) for bootstrapping the first user and the OIDC
+relying-party flow, and [`secrets.md`](secrets.md) for where each of
+authelia's keys is generated and read.
+

From b02af390072ae6d1a032ce65900dde11e3b17f8f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:44:49 +0200
Subject: [PATCH 24/64] docs(swarm): point sso.md's secrets section at
 secrets.md instead of restating it

---
 docs/swarm/sso.md | 22 ++++++----------------
 1 file changed, 6 insertions(+), 16 deletions(-)

diff --git a/docs/swarm/sso.md b/docs/swarm/sso.md
index 7b587e0f..c858428f 100644
--- a/docs/swarm/sso.md
+++ b/docs/swarm/sso.md
@@ -91,22 +91,12 @@ an attribute edit can invalidate a login by accident.
 ## What secrets exist, and where each one lives
 
 Every secret in the swarm, with its generator and its path, is tabulated
-in one place: [`secrets.md`](secrets.md). The rows relevant here are
-authelia's own keys (session, JWT, storage-encryption, OIDC HMAC, OIDC
-issuer) plus the two halves of each client secret.
-
-What matters for this page is the shape rather than the paths. Authelia's
-own keys are generated **in-container**, because nothing outside that
-container ever reads them — that is the test worth applying to any secret
-added here. The plaintext half of a client secret is the one that fails
-it: its reader lives in a different container, and that is the entire
-reason a delivery step exists.
-
-**None of it is ever written into a nix expression.** authelia's
-`settings` are rendered into the nix store, which is world-readable and
-permanent, so the client digest reaches authelia through `settingsFiles`
-(merged at runtime) and every other secret through a `*File` option
-carrying a path rather than a value.
+in one place: [`secrets.md`](secrets.md), including authelia's own keys
+(session, JWT, storage-encryption, OIDC HMAC, OIDC issuer) and the two
+halves of each client secret. That page's two rules — a secret is always
+a path, never a value, and the generator and the reader are usually in
+different containers — are why the client secret's plaintext half needs
+the delivery step below and the rest of authelia's keys don't.
 
 ## Getting the plaintext to the relying party
 

From 79a02f68592af23684082fb02c176688285bb526 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:45:02 +0200
Subject: [PATCH 25/64] docs(swarm): trim tuwunel internals to the
 operator-relevant fact

---
 docs/swarm/ca.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md
index 537087f9..5db8d4e8 100644
--- a/docs/swarm/ca.md
+++ b/docs/swarm/ca.md
@@ -176,12 +176,10 @@ Two consumers, and only one of them is fine:
 
   The consumption differs per runtime and is the part worth knowing.
   tuwunel links no openssl, which makes `SSL_CERT_FILE` look inapplicable
-  — it isn't. Its outbound client is `reqwest` with the `rustls` feature,
-  which builds a `rustls_platform_verifier::Verifier`; because tuwunel
-  calls `tls_certs_merge` (additive) rather than `tls_certs_only`, the
-  platform roots stay alongside its compiled-in webpki set. On Linux that
-  verifier resolves through `rustls-native-certs` → `openssl-probe`,
-  which reads `SSL_CERT_FILE`.
+  — it isn't: its rustls-based TLS stack still resolves trust through the
+  platform certificate store on Linux, and that store honors
+  `SSL_CERT_FILE`, so the env var takes effect the same way it would for
+  an OpenSSL-linked binary.
 
   > ⚠️ **Concatenate; never point `SSL_CERT_FILE` at the anchor alone.**
   > `openssl-probe` uses it *instead of* the default store, so naming

From c14d93268795bf325ff300214846a741ea00a2d1 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:52:29 +0200
Subject: [PATCH 26/64] docs(persistence): dedupe destroy/purge + agent_power
 against other sections, trim historical framing

---
 docs/persistence.md | 88 ++++++++++++++++++++++-----------------------
 1 file changed, 42 insertions(+), 46 deletions(-)

diff --git a/docs/persistence.md b/docs/persistence.md
index 7024b115..dda2a6be 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -79,16 +79,13 @@ header/targets split, and the per-agent power-intent registry:
   `scheduled_prompts(id)` — requires `PRAGMA foreign_keys = ON`
   per connection (set at open).
 - `agent_power` — one tiny row per agent: `agent PK / wanted (up |
-  offline) / updated_at` — the durable power *intent* behind the job
-  queue's desired-state reconciliation
-  (`docs/coordinator.md::Job queue`; owner: `hive-c0re/src/stores/power.rs`).
-  Written synchronously by every operator/agent power action
-  (dashboard start/stop, `hivectl stop`, the MCP kill/start tools,
-  spawn approval); read by `Reconcile` nodes and the boot reconcile.
-  Intent survives hive-c0re restarts — in-flight queue work
-  deliberately does not. Agents without a row are seeded from
-  observed state on first touch (running ⇒ `up`); destroy deletes
-  the row.
+  offline) / updated_at`, owned by `hive-c0re/src/stores/power.rs`.
+  This is the durable power *intent* the job queue reconciles the
+  observed container state against; intent survives hive-c0re
+  restarts even though in-flight queue work doesn't. See
+  [`docs/coordinator.md`'s Desired-state
+  section](coordinator.md#desired-state-spec-vs-status) for who
+  writes and reads it and how reconciliation works.
 
 Retention:
 
@@ -190,12 +187,10 @@ Shape:
 The turn loop is the only writer today, but it still goes
 read-modify-write under a shared in-process lock and merges into the
 existing object rather than reconstructing it — so a second writer
-preserves fields it doesn't own, and the lock closes the lost-update
-window between a writer's read and its rename. (The forge notification
-poller used to be that second writer, for a delivery-dedupe cursor. It
-persists nothing now — forge's own read-state is the durable record of
-what has been delivered — and it is a separate process, which an
-in-process lock could not have serialised anyway.)
+would preserve fields it doesn't own, and the lock closes the
+lost-update window between a writer's read and its rename. The lock
+is in-process only, so it wouldn't serialise a writer running as a
+separate process; none of today's writers are.
 
 hive-c0re reads this file on each `build_all` sweep (~10s) via
 `container_view::read_harness_flags`. Falls back to the legacy individual
@@ -209,11 +204,12 @@ Full stdout + stderr capture for every `nixos-container` / `nix
 build` invocation the lifecycle layer fires. One row per invocation;
 the row accumulates lines as the child runs.
 
-Replaces the legacy 32-line stderr ring buffer that `lifecycle::run`
-kept. The ring tail routinely truncated real eval errors ("tried
-alternatives" blocks alone are often 30+ lines), so failures bailed
-with an arbitrary tail whose full stream only lived in the host
-journal. With this table the dashboard can surface the entire log.
+Capturing the full stream (rather than a short tail buffer) matters
+because real eval errors routinely run long — "tried alternatives"
+blocks alone are often 30+ lines — so a truncated tail would cut off
+the actual failure and leave only the host journal holding the
+complete output. With this table the dashboard can surface the entire
+log.
 
 Two indices:
 - `(agent, started_at)` — backs the per-agent latest-N lookup used
@@ -323,11 +319,9 @@ notes, clearing a stuck sentinel) as well as reading it.
 
 **`harness` is not mounted at all.** It holds the child's own runtime
 material — `bash-tasks/`, the turn-stats and event sqlite dbs — and
-nothing argues for a parent reading it, let alone writing it. It used to
-be mounted RW for "the same management reasons" as `state`, which was
-never an argument so much as the side-effect of one loop treating all
-three dirs alike. hive-c0re reads a child's harness dir **directly on the
-host** when it wants those stats, which needs no mount into the parent.
+nothing argues for a parent reading it, let alone writing it. hive-c0re
+reads a child's harness dir **directly on the host** when it wants
+those stats, which needs no mount into the parent.
 
 **`config` is read-only, including for the parent.** A config change is
 a PR on the child's config repo, made from a clone and merged after
@@ -339,8 +333,9 @@ boundary a convention rather than a permission.
 ⚠️ Not to be confused with the seeding done when an `InitConfig`
 approval resolves: that writes the child's initial config repo as
 **hive-c0re, against the host path**, and `read_only` on a bind
-constrains writers *inside* a container only. The two are unrelated, and
-reading them as the same thing is what kept this mount writable.
+constrains writers *inside* a container only. The two are unrelated —
+conflating them is an easy way to reason your way into thinking this
+mount should be writable when it shouldn't.
 
 Per-child isolation still holds: a container only ever has its *own*
 dirs plus its direct children's bind-mounted, never a sibling's.
@@ -396,25 +391,21 @@ deleted.
 
 ## Destroy vs purge
 
-- `DESTR0Y` (default) — stops + removes the nspawn container,
-  drops the systemd drop-in, fails any pending approvals. State
-  dirs stay put; the agent appears in the dashboard's K3PT ST4T3
-  section as a tombstone with `⊕ R3V1V3` and `PURG3` actions.
-  `R3V1V3` queues a Spawn approval that reuses the kept state on
-  approve (no re-login).
-- `PURG3` (opt-in via the dashboard button or
-  `hivectl agent <name> destroy --purge`) — DESTR0Y plus wipes
-  `/var/lib/hyperhive/{agents,applied}/<name>/`. Config history,
-  claude creds, /state/ notes, and the harness dir are all gone.
-  No undo.
+See [For operators](#for-operators) above for what each action does to
+an agent's state. The mechanics, for completeness:
 
-The root/bootstrap container is **imperative** infrastructure — managed
-end-to-end by hive-c0re, not declared in the host's NixOS config.
-`auto_update::ensure_root_agent` recreates it on the next hive-c0re
-startup if it's absent (bypassing the approval queue, as required
-infrastructure). A soft policy guard in `actions::destroy` currently
-refuses to destroy it; even without that guard, destroying it would only
-be transient — hive-c0re brings it back on the next startup.
+- `DESTR0Y` also drops the systemd drop-in and fails any pending
+  approvals; the tombstone's `⊕ R3V1V3` button queues a Spawn approval
+  that reuses the kept state on approve.
+- `PURG3` wipes `/var/lib/hyperhive/{agents,applied}/<name>/` — the
+  union of everything `DESTR0Y` left behind.
+
+The root/bootstrap agent's specialness is implemented as a soft policy
+guard in `actions::destroy` that refuses to destroy it, backstopped by
+`auto_update::ensure_root_agent`, which recreates it on the next
+hive-c0re startup if it's ever absent (bypassing the approval queue,
+as required infrastructure) — so even without the guard, destroying it
+would only be transient.
 
 ### btrfs subvolumes for `/var/lib/hyperhive/agents/<name>`
 
@@ -443,6 +434,11 @@ until an explicit opt-in upgrade.
 Per-subvolume disk-usage accounting and optional quotas are a
 follow-up (the qgroup work), not part of the base migration.
 
+This is the same subvolume `hivectl agent <name> subvol snapshot push`
+sends to the swarm's snapshot store — see
+[`docs/snapshot-store.md`](snapshot-store.md) for what a pushed
+snapshot contains and how the store authenticates a sender.
+
 ## Run-time dirs
 
 `/run/hyperhive/` is tmpfs-backed (systemd `RuntimeDirectory=`) but

From e418de0f732d11b64246b8e3682a18a30b79e264 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:52:31 +0200
Subject: [PATCH 27/64] docs(coordinator): trim changelog-style framing, drop
 review-comment quote

---
 docs/coordinator.md | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/docs/coordinator.md b/docs/coordinator.md
index 047296c0..893cb908 100644
--- a/docs/coordinator.md
+++ b/docs/coordinator.md
@@ -12,9 +12,9 @@ Every container/meta operation (rebuild, meta-update, first-spawn, power
 changes) is submitted to the global job-DAG queue (`hive-c0re/src/job_queue/`)
 as a **DAG of primitive nodes**. One scheduler task drives all DAGs;
 concurrency comes from the resource classes below, not from multiple workers.
-The old special cases — the graceful-stop watcher thread, the deferred-start
-fast-lane follow-up, the meta-update cascade pre-enqueue — are all just DAG
-*shapes* now.
+Special cases like graceful stop, deferred starts, and the meta-update
+cascade need no bespoke code paths — each is expressed as a DAG *shape*
+built from the same primitive nodes.
 
 ### Two levels: DAG and node
 
@@ -30,8 +30,7 @@ A DAG is **declared, not described**: a template builds it through
 `b.node(kind)` handed back, and the builder inserts the nodes itself. A handle
 only exists for a node already declared, so every edge points backwards and a
 cycle cannot be written down — there is no submit-time validation pass, because
-there is no malformed spec to reject. (The old queue had a petgraph `toposort`
-here, guarding against the positional indices that used to express edges.)
+there is no malformed spec to reject.
 
 ### Node inventory (primitives)
 
@@ -61,7 +60,7 @@ Cheap — no build slot:
 | `Drain`         | await the harness clearing the fence, bounded by the 3-min graceful-stop timeout; resolves ok either way                              |
 | `WriteDropin`   | `set_nspawn_flags` + `set_resource_limits` + daemon-reload                                                                            |
 | `WritePermFile` | commit `tool-groups.json` / `capabilities.json` (single git commit under `META_LOCK`) + emit the P3RM1SS10NS snapshots                |
-| `Reparent`      | `set-parent` / `set-parent-bulk`: apply every `(child, new_parent)` move under one `META_LOCK` commit (`meta::bulk_commit_topology`), send the per-agent move notifications, rescan + diff-emit. Agentless like `MetaLock` — a bulk move can span multiple agents, and a reparent touches the meta repo, not any one container. `moves` is `(Ident, Option<Ident>)` pairs, not raw strings — mara: "use Ident type instead of string" (#2719, issuecomment 42691). Rides `Template::MetaUpdate` rather than a dedicated `Template` variant — that enum is on its way out (see `#2665`, still open/blocked on a scope question) and is already internal-only (it never reaches the graph wire), so the stand-in only affects `terminal_hook` dispatch (resolves to no hook either way) and history-retention bucketing |
+| `Reparent`      | `set-parent` / `set-parent-bulk`: apply every `(child, new_parent)` move under one `META_LOCK` commit (`meta::bulk_commit_topology`), send the per-agent move notifications, rescan + diff-emit. Agentless like `MetaLock` — a bulk move can span multiple agents, and a reparent touches the meta repo, not any one container. `moves` is typed `(Ident, Option<Ident>)` pairs, not raw strings. Rides the existing `Template::MetaUpdate` variant rather than a dedicated one — it's internal-only (never reaches the graph wire), so the stand-in only affects `terminal_hook` dispatch (resolves to no hook either way) and history-retention bucketing |
 
 There is deliberately **no `GitCommit` node**: `meta.rs` fuses each mutation
 with its commit under its internal `META_LOCK` mutex, so a standalone commit
@@ -308,10 +307,11 @@ span agents; consumers derive a group's agent(s) from its nodes. Build logs
 are likewise **per-node**: the dashboard renders the node tree and keys the
 live-log panel off the running node.
 
-The event used to ship the whole queue as a typed `DagView`/`NodeView`
-projection. That was a second rendering of the same graph, kept in
-agreement by hand with the endpoint every consumer actually read; it is
-gone, and the event's whole job is now telling a client *when* to refetch.
+The event carries no payload by design: shipping a typed projection of
+the whole queue in the event itself would be a second rendering of the
+same graph that has to be kept in agreement by hand with the endpoint
+every consumer actually reads. Telling a client *when* to refetch is
+the event's whole job.
 
 ---
 
@@ -411,8 +411,7 @@ Sequence for a rebuild DAG (each step is its own queue node):
    (near-instant after the prebuild).
 5. `Reconcile` — boot into the new generation when `wanted = Up`; the
    in-container activation script transitions old → new. Holds no build
-   slot, so the next DAG's `Prebuild` overlaps the container boot — the old
-   "deferred start" split, now structural.
+   slot, so the next DAG's `Prebuild` overlaps the container boot.
 
 The approval deploy uses this same chain rather than a rebuild path of its
 own. Its `DeployApply` node does not build: it merges, opens the two-phase

From ea18ebeff4e85b08e506da70587e33ad929ec093 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:52:34 +0200
Subject: [PATCH 28/64] docs(snapshot-store): cross-link the state subvolume to
 persistence.md

---
 docs/snapshot-store.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/snapshot-store.md b/docs/snapshot-store.md
index 2ea3c35b..7cfedaa2 100644
--- a/docs/snapshot-store.md
+++ b/docs/snapshot-store.md
@@ -183,7 +183,10 @@ the access-review list.
 ### What a snapshot contains
 
 The snapshot covers an agent's **state subvolume**, which is the parent
-of `state/`, `claude/` and `harness/`. Consequences:
+of `state/`, `claude/` and `harness/` (see
+[`docs/persistence.md`'s btrfs subvolume
+section](persistence.md#btrfs-subvolumes-for-varlibhyperhiveagentsname)
+for how and when that subvolume is created). Consequences:
 
 - The Claude session (`claude/`) travels, so a restored agent keeps its
   live `--continue` session rather than needing to log in again.

From f29df9cadb534788cab0accd46cb1096597d4713 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:46:46 +0200
Subject: [PATCH 29/64] docs(approvals): trim historical framing, dedupe
 ask/answer with conventions.md

---
 docs/approvals.md | 113 ++++++++++++++++------------------------------
 1 file changed, 38 insertions(+), 75 deletions(-)

diff --git a/docs/approvals.md b/docs/approvals.md
index 05ca03dd..d3885c49 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -212,10 +212,9 @@ An agent target's delivery is `push_todo` (`Coordinator::push_todo`,
 `docs/coordinator.md` covers the mechanism generally), not a broker
 `Message` — a scheduled prompt wakes its target with a todo instead of
 driving an immediate turn, by design. `key = "schedule:<id>"` per
-target gives `push_todo`'s own upsert-by-key dedup the job a
-now-removed `has_pending_with_body` broker check used to do: a re-fire
-of the *same schedule* against a target that hasn't reviewed the last
-one collapses into that one todo instead of stacking up.
+target drives `push_todo`'s own upsert-by-key dedup: a re-fire of the
+*same schedule* against a target that hasn't reviewed the last one
+collapses into that one todo instead of stacking up.
 
 **`operator` is the one exception** — it's a valid schedule target but
 has no in-container todo inbox, so it keeps the original broker
@@ -290,8 +289,7 @@ declares one flake input per agent (`agent-<n>.url =
 "git+http://<forge>/agent-configs/<n>.git"`) and one
 `nixosConfigurations.<n>` output per agent. Each output wraps
 `inputs.agent-<n>.nixosModules.default` with the identity +
-`HIVE_PORT` / `HIVE_LABEL` / `HIVE_DASHBOARD_PORT` injection
-module that `setup_applied` used to generate inline.
+`HIVE_PORT` / `HIVE_LABEL` / `HIVE_DASHBOARD_PORT` injection module.
 Containers run against `--flake /var/lib/hyperhive/meta#<n>`.
 
 The declared input url is the agent's **forge config repo** (the
@@ -419,9 +417,9 @@ submitter pushes again (or closes it) to retry.
 ### Dispatch via the job queue
 
 Long-running approval work — `MergeConfigPr`, `UpdateMetaInputs`,
-`Spawn` — no longer runs inline inside `actions::approve`. Instead
-the approval handler submits a DAG to the global job queue
-(`docs/coordinator.md::Job queue`):
+`Spawn` — runs as a DAG on the global job queue
+(`docs/coordinator.md::Job queue`), submitted by the approval handler
+rather than run inline:
 
 | `ApprovalKind` | DAG submitted | source |
 |---|---|---|
@@ -502,9 +500,9 @@ forge into its own state dir, commit on a branch, open a PR**, and let
 the operator review and approve it. There is deliberately no second,
 mount-shaped path that reaches the same file without the review.
 
-Agents holding the `can_manage_top_level_agents` topology role
-(defined as `ROLE_CAN_MANAGE_TOP_LEVEL_AGENTS` in `hive-c0re/src/agent_config/topology.rs`)
-get additional host-side bind mounts via `set_nspawn_flags`:
+Agents holding the `can_manage_top_level_agents` topology role (see
+`hive-c0re/src/agent_config/topology.rs`) get additional host-side
+bind mounts via `set_nspawn_flags`:
 
 - `/var/lib/hyperhive/agents/` → `/agents/` (RW) — all top-level
   agents' proposed repos (not just direct children).
@@ -536,34 +534,24 @@ cat /meta/flake.lock | jq '.nodes | with_entries(select(.key | startswith("agent
 The RO binds block push at the kernel level — git plumbing inside the
 container cannot corrupt either authoritative repo.
 
-## Migration from the pre-tag / pre-meta schemes
+## Startup migrations (older hosts)
 
-Both overhauls (tag-driven flow + meta flake) ship in-place
-migrations that run on every hive-c0re startup. Idempotent;
-each phase is a no-op once already applied. Behaviour:
+hive-c0re runs a couple of idempotent migrations on every startup so a
+host set up before the tag-driven-deploy + meta-flake scheme (both
+described above) converges to it automatically. Each phase is a no-op
+once already applied:
 
-- Tag-driven phase: assumes the operator ran the one-shot
-  `git tag deployed/0 main` script (see commit history /
-  earlier docs revisions) once per agent. Tagging is
-  non-destructive: it doesn't touch live containers, state
-  dirs, or claude creds.
-- Meta-flake phase: rewrites each `applied/<n>/flake.nix` to
-  the module-only boilerplate, wires the `applied` remote in
-  each proposed repo, and bootstraps the meta repo from the
-  current agent list. Set `HIVE_SKIP_META_MIGRATION=1` on the
-  service to defer.
+- **Tags**: agents from before the tag-driven scheme are tagged
+  `deployed/0` on `main` once. Non-destructive — it doesn't touch live
+  containers, state dirs, or claude creds.
+- **Meta flake**: rewrites each `applied/<n>/flake.nix` to the
+  module-only boilerplate, wires the `applied` remote in each proposed
+  repo, and bootstraps the meta repo from the current agent list. Set
+  `HIVE_SKIP_META_MIGRATION=1` on the service to defer this phase.
 
-  A further step used to `nixos-container update` every
-  container onto `meta#<n>`, guarded by a marker file so it
-  ran once per hive. It is gone: containers have been rendered
-  onto `meta#<n>` at creation for long enough that no live hive
-  needs the repoint, and a one-shot nobody can still trigger is
-  dead weight. Same for the `root` → `h-root` container rename.
-
-No state loss in either migration. claude creds, /state/
-notes, the events DB, proposed history, and applied history
-all survive. The root agent keeps its session; sub-agents stay
-logged in.
+No state loss in either migration: claude creds, `/state/` notes, the
+events DB, and both proposed + applied history all survive. The root
+agent keeps its session; sub-agents stay logged in.
 
 ## The root/bootstrap container is hive-c0re-managed
 
@@ -606,35 +594,11 @@ renders only for the root agent. The root agent's approval-gating
 behaviour comes from its CLAUDE.md / agent-specific instructions, not
 the system prompt template.
 
-`ask(question, options?, multi?, ttl_seconds?, to?)` is available to
-**any agent** — it queues a question and returns the id immediately.
-When `to` is omitted (or `"operator"`) the question shows up on the
-dashboard; when `to` is another agent's name, the recipient receives a
-`HelperEvent::QuestionAsked` and answers via their own `answer`
-tool. Either way the answer arrives back as
-`HelperEvent::QuestionAnswered { id, question, answer, answerer }`
-in the asker's inbox. Storage is `hive-c0re::operator_questions`
-(sqlite) — same table, with a nullable `target` column
-(NULL = operator). Dispatch goes through
-`hive-c0re/src/questions.rs::{handle_ask, handle_answer}`. The answer flow is:
-
-```
-POST /answer-question/{id}                       agent: Answer { id, answer }
-  → OperatorQuestions::answer(_, _, "operator")    → questions::handle_answer
-  → notify_agent(asker, QuestionAnswered {         → OperatorQuestions::answer(_, _, agent)
-       answerer: "operator", ... })                → notify_agent(asker, QuestionAnswered {
-                                                       answerer: agent, ... })
-```
-
-Two more paths resolve a pending question with a sentinel answer:
-
-- `POST /cancel-question/{id}` (✗ CANC3L button on the dashboard)
-  resolves with `[cancelled]`. The asking agent sees a terminal state
-  and can fall back.
-- `ttl_seconds` deadline: a tokio watchdog spawned at submit time
-  fires `answer(id, "[expired]")` once the ttl runs out. Already-
-  resolved races no-op. The dashboard surfaces a `⏳ MM:SS` chip
-  on each pending question with a deadline.
+Any agent (root or not) can also ask a structured question of the
+operator or a peer agent via the `ask`/`answer` MCP tools, independent
+of the approval flow above — see
+`docs/conventions.md#question-routing-ask--answer` for the routing
+rules, `ttl_seconds` expiry, and cancellation.
 
 ## Helper events to the submitting agent
 
@@ -673,15 +637,14 @@ root agent. Variants (`hive_sh4re::manager::HelperEvent`):
   The recipient responds via `Answer { id, answer }` and the
   asker sees the matching `QuestionAnswered`.
 
-The rest of the original lifecycle notices — `Rebuilt`, `Killed`,
-`Destroyed`, `NeedsLogin`, `LoggedIn`, `ConfigReady` — were pure "FYI,
-check when convenient" events with no reason to drive an immediate
-turn, so they've been migrated off `HelperEvent` onto
-`push_todo`/`push_todo_submitter` (see above): `agent_todo_socket`
-push instead of a broker message, `subsystem = "core"`,
-`key = "<event>:<agent>"` for dedup, one free-text `summary` in place
-of the old structured fields (`rebuilt_todo_summary` renders
-`Rebuilt`'s former `ok`/`note`/`sha`/`tag` into that string).
+The remaining lower-urgency lifecycle notices — `Rebuilt`, `Killed`,
+`Destroyed`, `NeedsLogin`, `LoggedIn`, `ConfigReady` — are "FYI, check
+when convenient" events with no reason to drive an immediate turn, so
+they deliver via `push_todo`/`push_todo_submitter` (see above) instead
+of `HelperEvent`: an `agent_todo_socket` push instead of a broker
+message, `subsystem = "core"`, `key = "<event>:<agent>"` for dedup,
+and a single free-text `summary` (`rebuilt_todo_summary` renders
+`Rebuilt`'s `ok`/`note`/`sha`/`tag` fields into that string).
 
 Optional `sha` field on `ApprovalResolved` carries the canonical
 hive-c0re-vouched commit sha. Optional `tag` carries the deploy

From a7f375190a665d77748bfeec8a49fce33896943e Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:47:47 +0200
Subject: [PATCH 30/64] docs(readme): drop Rust function-name citation for
 plain-language behavior

---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 02fa53b7..d3b5d0df 100644
--- a/README.md
+++ b/README.md
@@ -110,10 +110,10 @@ sudo hivectl matrix create-user mara                      # provisions a matrix
 sudo hivectl matrix create-user mara --password-stdin     # … reading one line from stdin
 ```
 
-For agent names (i.e., a `Coordinator::agent_state_root(name)` exists),
-`hivectl` persists the resulting token to the agent's state dir like the
-boot sweep does. For non-agent names (e.g. the operator's own forge/matrix
-account), it prints the token to stdout and writes nothing.
+For a name that's a managed agent, `hivectl` persists the resulting token
+to that agent's state dir, the same as the boot sweep does. For a
+non-agent name (e.g. the operator's own forge/matrix account), it prints
+the token to stdout and writes nothing.
 
 ## Build / deploy
 

From dd8b5db7ab09f999cf5fe7b1b3436902a49ec5f1 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 11:59:07 +0200
Subject: [PATCH 31/64] docs: fix remaining stale internal references from the
 #3281 sweep

Two follow-ups the per-file sweep workers flagged but couldn't fix
themselves (either not their assignment, or not visible from their
worktree):

- web-ui/dashboard.md's P33RS tab named dashboard.rs, which no longer
  exists (hive-c0re/src/dashboard/ is a module dir now); the function
  moved to state_snapshot.rs.
- approvals.md and conventions.md used hive_ag3nt:: as a Rust
  module-path prefix. hive-agent is a bin-only crate (no lib target),
  so that prefix never resolved to anything; also fixed the
  hive-ag3nt/prompts/system.md path to the real hive-agent/prompts/.

All three verified directly against the current source tree, not
guessed.
---
 docs/approvals.md        | 4 ++--
 docs/conventions.md      | 2 +-
 docs/web-ui/dashboard.md | 3 ++-
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/approvals.md b/docs/approvals.md
index d3885c49..c3258656 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -586,8 +586,8 @@ updates the root agent itself.
 
 ## Root-agent policy
 
-The system prompt (`hive-ag3nt/prompts/system.md`, rendered via
-`hive_ag3nt::prompt::render`) is the **same for every agent**; what
+The system prompt (`hive-agent/prompts/system.md`, rendered by
+`hive-agent/src/prompt.rs`) is the **same for every agent**; what
 varies is which MCP tools are surfaced (gated by tool groups and
 capabilities in `agent.nix`). There is no `role:manager` block that
 renders only for the root agent. The root agent's approval-gating
diff --git a/docs/conventions.md b/docs/conventions.md
index e98b6ab6..fe2ef6e7 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -16,7 +16,7 @@ exist because something already went wrong without them.
 ## Hive identity (label + domain + display names)
 
 Four env vars cover the identity surface, read by
-`hive_ag3nt::identity`:
+`hive-agent/src/identity.rs`:
 
 - `HIVE_LABEL` — short, hive-local agent label (`iris`,
   `damocles`). `label()` returns it; falls back to empty string if
diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index 3359540e..46132f25 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -657,7 +657,8 @@ is `https://{domain}/`. Both are derived from the env var
 objects) that the nix module writes into the c0re container
 environment. `cert_fingerprint` is null for CA-trusted (e.g.
 Let's Encrypt) peers and non-null to pin a self-signed cert.
-`parse_peer_hives()` in `dashboard.rs` converts each entry to the
+`parse_peer_hives()` in `hive-c0re/src/dashboard/state_snapshot.rs`
+converts each entry to the
 `PeerHiveView { name: domain, url: "https://domain/" }` shape the
 frontend reads.
 

From 4f03a82cc58222e38e387c19730f58a68e887f1f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:03:33 +0200
Subject: [PATCH 32/64] docs: fix 3 more stale dashboard.rs refs argus caught
 in review

hive-c0re/src/dashboard.rs became a module directory
(hive-c0re/src/dashboard/) a while back; three more references to it
as a single file survived the #3281 sweep (conventions.md x2,
web-ui/shape.md's StateSnapshot pointer). Same bug class the sweep
was hunting for, argus caught it in review.
---
 docs/conventions.md  | 5 +++--
 docs/web-ui/shape.md | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/conventions.md b/docs/conventions.md
index fe2ef6e7..839d6eaa 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -408,7 +408,8 @@ bypass the operator approval gate.
 **Adding a new capability** — add a variant to `Capability` in
 `hive-sh4re/src/lib.rs` + an arm to `as_str`. Add it to `Capability::ALL` (the
 source of truth for the permissions UI columns). Implement the access check in
-the relevant handler (`agent_server.rs`, `mcp.rs`, or `dashboard.rs`).
+the relevant handler (`agent_server.rs`, `mcp.rs`, or a handler under
+`hive-c0re/src/dashboard/`).
 
 ## Async forms
 
@@ -441,7 +442,7 @@ sufficient to recover.
 ## Actions are factored
 
 `approve` / `deny` / `destroy` (and the lifecycle helper) live in
-`actions.rs` / `dashboard.rs`. The admin socket and the dashboard
+`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
diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md
index 718010d1..97d0b410 100644
--- a/docs/web-ui/shape.md
+++ b/docs/web-ui/shape.md
@@ -198,7 +198,8 @@ listener: read `data-confirm`, swap the button to a spinner, POST
 `application/x-www-form-urlencoded`, re-enable the button on success
 (refreshState may keep the form mounted, so we don't rely on a
 re-render), call `refreshState()`. State shapes live in
-`dashboard.rs::StateSnapshot` and `web_ui/state.rs::StateSnapshot` — when
+`hive-c0re/src/dashboard/state_snapshot.rs::StateSnapshot` and
+`web_ui/state.rs::StateSnapshot` — when
 adding state fields, plumb through the snapshot struct and the
 relevant domain module (`assets/swarm.js`, `assets/call.js`, etc.) render function.
 

From 844337ca91fb43cc8db7e19b8147cd3c6a1045a1 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:26:35 +0200
Subject: [PATCH 33/64] docs(gotchas): fix stale set_nspawn_flags path +
 SPA-fallback file/paths

Verified against hive-c0re/src/lifecycle/host_config.rs (function lives
in the host_config submodule, not bare lifecycle::) and
nix/host-modules/hive-matrix.nix (the working Accept-header SPA
fallback lives there, serving fluffychat at the vhost root /index.html,
not a /matrix/ path prefix in a nonexistent hive-gateway.nix).
---
 docs/gotchas.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/gotchas.md b/docs/gotchas.md
index b5bf6782..a3b131c8 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -12,8 +12,8 @@ touching.
 The CLI doesn't accept `--bind`. Path is via `EXTRA_NSPAWN_FLAGS` in
 `/etc/nixos-containers/<NAME>.conf` — the start script
 (`/nix/store/.../container_-start`) expands it unquoted into the
-`systemd-nspawn` invocation. `lifecycle::set_nspawn_flags()` rewrites
-this line.
+`systemd-nspawn` invocation. `lifecycle::host_config::set_nspawn_flags()`
+rewrites this line.
 
 ### `/run/systemd/nspawn/*.nspawn` overrides are ignored
 
@@ -187,21 +187,22 @@ scripts, manual `rm -rf`), the dashboard's next render marks them
 
 ### SPA fallback: use `Accept` header map, not `try_files ... /index.html`
 
-The naive nginx pattern for a path-prefix SPA (`try_files $uri $uri/
-/matrix/index.html`) silently swallows asset 404s — a missing JS file
+The naive nginx pattern for an SPA (`try_files $uri $uri/
+/index.html`) silently swallows asset 404s — a missing JS file
 returns `index.html` with a 200, so the JS runtime never loads and the
 page renders blank with no visible error. Extension allowlists (tried
 as an alternative) have the same maintenance problem: any new file
 extension the SPA ships breaks silently.
 
-The pattern that works (`hive-gateway.nix`) keys the fallback on the
+The pattern that works (`nix/host-modules/hive-matrix.nix`, serving
+fluffychat at the matrix gateway vhost's root) keys the fallback on the
 HTTP `Accept` header:
 
 ```nginx
 # Outside the server block (appendHttpConfig):
 map $http_accept $matrix_spa_target {
   default          "/__matrix_spa_no_html_fallback";
-  "~*text/html"    "/matrix/index.html";
+  "~*text/html"    "/index.html";
 }
 
 # Inside the location:

From ac58823eb30f5eab3f4726d20847458ea78f80d7 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:26:39 +0200
Subject: [PATCH 34/64] docs(turn-loop): fix stale AgentRequest/ManagerRequest
 wire-type names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified against hive-agent/src/main.rs and hive-core-agent-sock/src/lib.rs:
there is no AgentRequest/AgentResponse or ManagerRequest/ManagerResponse
alias anywhere in the tree — hive-agent uses hive_core_agent_sock's
unified Request/Response enum directly.
---
 docs/turn-loop/README.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/turn-loop/README.md b/docs/turn-loop/README.md
index 71baa55c..c952841c 100644
--- a/docs/turn-loop/README.md
+++ b/docs/turn-loop/README.md
@@ -67,8 +67,8 @@ agents) runs:
 
 Two sibling crates, both role-agnostic (there is one role: agent —
 the privilege boundary lives server-side at the broker socket
-(`/run/hive/mcp.sock`), which refuses `ManagerRequest` calls regardless
-of who sends them):
+(`/run/hive/mcp.sock`), which refuses privileged `Request` variants
+regardless of who sends them):
 
 - `hive-agent` — long-running harness loop (the inbox poll +
   claude-pump + ack/requeue cycle described above).
@@ -79,10 +79,11 @@ of who sends them):
   transport — no per-turn stdio child (eliminates the re-registration
   race).
 
-`hive-agent`'s wire types (`AgentRequest` / `AgentResponse`, aliased as
-`ManagerRequest` / `ManagerResponse`) and its turn loop are factored
-through a small `Surface` trait with one zero-sized impl, so the loop
-itself has no per-role branches. See `hive-agent/src/main.rs`'s module
+`hive-agent`'s wire types (`hive_core_agent_sock::{Request, Response}` —
+one unified enum shared by the agent and manager sockets) and its turn
+loop are factored through a small `Surface` trait with one zero-sized
+impl, so the loop itself has no per-role branches. See
+`hive-agent/src/main.rs`'s module
 doc for the trait shape.
 
 ### Boot wiring

From 0f92e58ebb913971c8501026b3672c66a81bf3bc Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:26:42 +0200
Subject: [PATCH 35/64] docs(turn-loop): fix stale context_window_tokens module
 path + on-boot files dir

Verified against hive-agent/src/harness_state.rs (context_window_tokens
lives there, only imported into events.rs) and hive-agent/src/paths.rs
(config_dir() defaults to /run/hive-config, deliberately separate from
/run/hive/ which holds the per-agent socket).
---
 docs/turn-loop/claude-invocation.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md
index e37c24e3..681050d5 100644
--- a/docs/turn-loop/claude-invocation.md
+++ b/docs/turn-loop/claude-invocation.md
@@ -51,7 +51,7 @@ survives restart; override path: `HYPERHIVE_MODEL_FILE` env var
 for tests.
 
 Context-window size is looked up per-model via
-`events::context_window_tokens(model)`. Resolution order (first
+`harness_state::context_window_tokens(model)`. Resolution order (first
 match wins):
 
 1. `HIVE_CONTEXT_WINDOW_TOKENS_<KEY>` env var, where `KEY`
@@ -129,7 +129,7 @@ window with two triggers baked into its `run`:
 The **when** is a `hive_claude::CompactionPolicy` injected by the harness:
 `turn::make_session` builds a `PercentPolicy` that compacts once the
 model-reported context fill reaches `HIVE_COMPACT_WATERMARK_PERCENT`
-(default **75%**), falling back to `events::context_window_tokens(model)`
+(default **75%**), falling back to `harness_state::context_window_tokens(model)`
 for the window on turns the model didn't report one. `0` disables proactive
 compaction (the reactive path always applies). The proactive path is
 best-effort — a failed checkpoint or `/compact` never fails the turn that
@@ -195,8 +195,11 @@ next turn picks it up like any other inbox message.
 
 ## On-boot files
 
-`hive-agent`'s `turn` module writes two files next to the per-agent
-socket at `/run/hive/` once at startup:
+`hive-agent`'s `turn` module writes two files into its own per-service
+runtime dir, `/run/hive-config/` (`RuntimeDirectory = "hive-config"`,
+deliberately separate from `/run/hive/`, the host-owned dir holding the
+per-agent socket — so the harness owns this write surface and nothing
+needs to `chown` a bind mount), once at startup:
 
 - `claude-mcp-config.json` — points claude at the persistent
   `hive-mcp-http` daemon (`http://127.0.0.1:{port}/mcp`, port from

From 6d744765724cc1545cba51cb49c1627881027400 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:26:46 +0200
Subject: [PATCH 36/64] docs(turn-loop): fix stale rmcp version +
 AgentRequest::Wake reference

Verified against Cargo.lock (rmcp resolves to 2.2.0, Cargo.toml pins
"2") and hive-core-agent-sock/src/lib.rs (the Wake variant lives on
Request there; hive_sh4re::AgentRequest doesn't exist).
---
 docs/turn-loop/mcp.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md
index 09ced3bb..70461d41 100644
--- a/docs/turn-loop/mcp.md
+++ b/docs/turn-loop/mcp.md
@@ -1,6 +1,6 @@
 # MCP surface
 
-The harness ships an embedded MCP server (rmcp 1.7). The built-in
+The harness ships an embedded MCP server (rmcp 2). The built-in
 `hyperhive` surface is served over streamable HTTP by a persistent
 `hive-mcp-http` daemon (loopback, `127.0.0.1:<hyperhive.mcp.httpPort>`,
 per-container private netns). Claude connects to its stable URL via
@@ -162,8 +162,8 @@ External MCP servers (and any other in-container process) can
 inject a wake-up event into the agent's inbox via the per-agent
 socket at `/run/hive/mcp.sock`. Speak the wire protocol directly —
 JSON-line over the unix socket: `{"cmd":"wake","from":"matrix","body":
-"new dm from @alice"}\n`. Same shape as any other `AgentRequest`; see
-`hive-sh4re::AgentRequest::Wake`. Every built-in producer that wakes
+"new dm from @alice"}\n`. Same shape as any other request on this
+socket; see `hive_core_agent_sock::Request::Wake`. Every built-in producer that wakes
 the harness (matrix, bash) dials the socket directly — there is no
 CLI wrapper, just the raw protocol.
 

From b662bc857886d2664ef6261ed05f5b5544ff09a0 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:26:50 +0200
Subject: [PATCH 37/64] docs(turn-loop): fix stale plugin defaults +
 dashboardLinks reader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified against nix/agent-modules/claude-settings.nix (claudeMarketplaces
and claudePlugins defaults both gained a second entry — the hive's own
claude-plugins marketplace and base@hyperhive plugin — that the doc never
picked up) and hive-agent/src/web_ui/state.rs (dashboardLinks is read by
the harness's own per-agent web UI, not hive-c0re / the operator
dashboard).
---
 docs/turn-loop/config.md | 56 +++++++++++++++++++++++++---------------
 1 file changed, 35 insertions(+), 21 deletions(-)

diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md
index 0f81c8ef..d7e2b15d 100644
--- a/docs/turn-loop/config.md
+++ b/docs/turn-loop/config.md
@@ -71,9 +71,9 @@ hyperhive.dashboardLinks = [
 ];
 ```
 
-Declares extra navigation links that appear on the agent's dashboard
-card and in the per-agent page header alongside the built-in forge /
-config / container links. Each entry has:
+Declares extra navigation links that appear in the per-agent page
+header alongside the built-in forge / config / container links. Each
+entry has:
 
 | Field | Required | Description |
 |-------|----------|-------------|
@@ -82,10 +82,12 @@ config / container links. Each entry has:
 | `icon` | no | Emoji or short glyph prefix. Defaults to empty string. |
 
 The list is written to `<state>/hyperhive-dashboard-links.json` by a
-one-shot systemd unit at container boot. `hive-c0re` reads the file on
-each container-view snapshot and attaches the links to the agent card
-(`kind = External`) without any code change. Omitting the option
-(default empty) produces no extra links.
+one-shot systemd unit at container boot. The harness's own web UI
+(`agent_links` in `hive-agent/src/web_ui/state.rs`) reads the file on
+each `/api/state` snapshot and appends the entries to the per-agent
+nav as `kind = External` links — no `hive-c0re` / operator-dashboard
+involvement, and no code change needed to pick up a new entry.
+Omitting the option (default empty) produces no extra links.
 
 ## Custom static files
 
@@ -174,31 +176,43 @@ hive.
 ## Claude Code plugins
 
 The harness installs Claude Code plugins before the serve loop opens.
-Two per-agent `agent.nix` options control this:
+Three per-agent `agent.nix` options control this:
 
 ```nix
-hyperhive.claudeMarketplaces = [ "anthropics/claude-plugins-official" ];  # default
-hyperhive.claudePlugins = [ "skill-creator@claude-plugins-official" ];     # default
-hyperhive.claudePluginsAutoUpdate = false;                                 # default
+hyperhive.claudeMarketplaces = [                        # default
+  "anthropics/claude-plugins-official"
+  "${hyperhive.packages.claude-plugins}"                # hive's own local marketplace, registered as `hyperhive`
+];
+hyperhive.claudePlugins = [                              # default
+  "skill-creator@claude-plugins-official"
+  "base@hyperhive"
+];
+hyperhive.claudePluginsAutoUpdate = false;               # default
 ```
 
 - **`claudeMarketplaces`** — list of marketplace sources passed to
-  `claude plugin marketplace add <source>`. The official Anthropic
-  marketplace is pre-configured by default; override or extend to add
-  custom marketplaces. Idempotent — re-adding an existing source is
-  a no-op.
+  `claude plugin marketplace add <source>`. Defaults to Anthropic's
+  official marketplace plus hyperhive's own `claude-plugins` nix
+  package (see `nix/packages/claude-plugins.nix`) — a local-path
+  marketplace registered under the name `hyperhive`, so a hive-authored
+  skill needs no forge repo or git remote to ship. Override or extend
+  to add custom marketplaces. Idempotent — re-adding an existing
+  source is a no-op.
 - **`claudePlugins`** — list of plugin specs passed to
   `claude plugin install <spec>`. Each spec is installed on every boot
   (`install` is expected to be idempotent); failures log a warning but
-  do not abort boot. Defaults to Anthropic's `skill-creator`, so every
-  agent can author, refine, and evaluate its own skills without any
-  per-agent wiring.
+  do not abort boot. Defaults to Anthropic's `skill-creator` (so every
+  agent can author, refine, and evaluate its own skills) plus
+  hyperhive's own `base` plugin — skills that apply to every agent
+  regardless of role (currently just `state-hygiene`) — all without
+  any per-agent wiring.
 
 > Both plugin lists follow ordinary NixOS list-option semantics: a
 > per-agent definition **replaces** the default, it does not extend it.
-> An agent that sets `claudePlugins` and still wants `skill-creator`
-> has to list it explicitly alongside its own entries — likewise for
-> the official marketplace in `claudeMarketplaces`.
+> An agent that sets `claudePlugins` and still wants the defaults has
+> to list `skill-creator@claude-plugins-official` and `base@hyperhive`
+> explicitly alongside its own entries — likewise for the two default
+> entries in `claudeMarketplaces`.
 - **`claudePluginsAutoUpdate`** — when `true`, runs
   `claude plugin marketplace update` before installing plugins to pull
   the latest index. Disabled by default to keep boot times short and

From efc30a0bcfbf21234f60f263c4bfb45d98113e57 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:27:33 +0200
Subject: [PATCH 38/64] docs(turn-loop): fix stale topology::parent_of
 reference

Verified against hive-c0re/src/agent_config/topology.rs: there is no
parent_of function; <parent> sentinel resolution happens in
topology::resolve_recipient.
---
 docs/turn-loop/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/turn-loop/README.md b/docs/turn-loop/README.md
index c952841c..48c0f413 100644
--- a/docs/turn-loop/README.md
+++ b/docs/turn-loop/README.md
@@ -112,8 +112,8 @@ merge work.
 Plugin install failures are not fatal: each entry comes back as a
 human-readable failure string that gets routed via
 `Surface::send_to_parent` to the agent's topology parent (the
-broker resolves `<parent>` per `topology::parent_of`; root agents
-and the manager fall through to operator).
+broker resolves `<parent>` per `topology::resolve_recipient`; root
+agents and the manager fall through to operator).
 
 ### Turn outcomes
 

From 637d36a11f668968614906c7ed9ac821bd93a444 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:29:08 +0200
Subject: [PATCH 39/64] docs(turn-loop): fix wrong HelperEvent lifecycle-event
 list
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified against hive-sh4re/src/manager.rs and docs/approvals.md: only
ApprovalResolved/ContainerCrash/NeedsUpdate/QuestionAsked/QuestionAnswered
are HelperEvents delivered as inbox messages. spawned/rebuilt/killed/
destroyed/needs_login/logged_in/config_ready aren't HelperEvent variants
at all — they deliver via Coordinator::push_todo/push_todo_submitter
(the in-container todo socket), not the broker inbox.
---
 docs/turn-loop/mcp.md | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md
index 70461d41..35d8b3bb 100644
--- a/docs/turn-loop/mcp.md
+++ b/docs/turn-loop/mcp.md
@@ -63,16 +63,23 @@ ttl_seconds?, to?)`, `answer(id, answer)`, `ack_until(up_to)`.
   `ack_until(N)` to prevent re-pop. Acked rows never redeliver.
   Transient pings (sentinel id 0) have nothing to ack and show no marker.
 
-**System messages** (from sender `system`): lifecycle and Q&A events
+**System messages** (from sender `system`): the higher-urgency
+lifecycle + Q&A events (`hive_sh4re::manager::HelperEvent`) are
 delivered as regular inbox messages (same `recv` path; body is a JSON
 object with an `event` discriminant field). The **submitting agent**
 (the root agent for top-level containers; an agent with the `approvals`
-tool group for its own subtree) receives lifecycle events (`spawned`,
-`rebuilt`, `killed`, `destroyed`, `container_crash`, `needs_login`,
-`logged_in`, `config_ready`, `needs_update`, `approval_resolved`). Any
-agent receives Q&A events when it is the declared target
-(`question_asked`) or the asker (`question_answered`). Full payload
-shapes and routing logic in
+tool group for its own subtree) receives `container_crash`,
+`needs_update`, and `approval_resolved` this way. Any agent receives
+Q&A events when it is the declared target (`question_asked`) or the
+asker (`question_answered`). The remaining, lower-urgency lifecycle
+notices — `spawned`, `rebuilt`, `killed`, `destroyed`, `needs_login`,
+`logged_in`, `config_ready` — skip the inbox entirely: they land as
+todos on the submitting agent's in-container todo socket instead
+(`Coordinator::push_todo`/`push_todo_submitter`, `subsystem = "core"`),
+which still wakes a turn (the todo-wake path — see [Turn
+outcomes](README.md#turn-outcomes)) but via a generic "call
+`get_loose_ends`" prompt rather than the event body itself. Full
+payload shapes and routing logic in
 [`docs/approvals.md` § Helper events](../approvals.md#helper-events-to-the-submitting-agent).
 
 **Inbox** (`inbox` group): `get_loose_ends(agent?)`,

From 3e4965251179d8fb09a10ba4e89a8bbffe844f05 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:31:28 +0200
Subject: [PATCH 40/64] docs(gotchas): fix wrong claim that
 hyperhive-events.sqlite lives in state dir

Verified against hive-agent/src/paths.rs: harness-internal files
(hyperhive-events.sqlite, hyperhive-turn-stats.sqlite, hyperhive-model)
live in the separate harness dir, specifically kept out of the
agent-visible state dir.
---
 docs/gotchas.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/gotchas.md b/docs/gotchas.md
index a3b131c8..c50421be 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -145,9 +145,12 @@ across `destroy`/recreate (`--purge` wipes them).
 `/agents/<name>/state` (RW; uniform for all agents).
 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
-writes its events log here (`hyperhive-events.sqlite`).
-Survives `destroy`/recreate alongside the claude dir.
+durable knowledge here (`notes.md`, anything else) — the harness's own
+internal files (`hyperhive-events.sqlite`, `hyperhive-turn-stats.sqlite`,
+`hyperhive-model`) live in the separate `harness` dir instead, so they
+don't clutter what claude sees as "my notes dir" (see
+[`docs/persistence.md`](persistence.md)). Survives `destroy`/recreate
+alongside the claude dir.
 
 ## Networking & ports
 

From 1277f5d4ca5620f6a14fe38701dc1971c8d2562a Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:19:12 +0200
Subject: [PATCH 41/64] docs(security): fix stale forge.rs path, GetAgentMeta
 validator, hive-priv table

---
 docs/security.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/security.md b/docs/security.md
index dda8f4b5..3a142cc0 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -134,9 +134,9 @@ dashboard renders anchors only for tokens that passed the same checks the
 read endpoint enforces.
 
 The same invariant holds wherever an agent-supplied name reaches a filesystem
-path: the agent socket's `GetAgentMeta` validates `name` with
-`validate_agent_name` before building `agent_notes_dir(name)`, so a `..`
-component can't traverse.
+path: the agent socket's `GetAgentMeta` takes `name` as a serde-validated
+`hive_types::Ident` (or falls back to `Ident::parse` for the "self" case)
+before building `agent_notes_dir(name)`, so a `..` component can't traverse.
 
 ## Nix builds and credential isolation
 
@@ -167,7 +167,7 @@ token policy bounds file reads; network isolation bounds network reach.
   user `<name>`. nixbld users cannot read it.
 - `$HYPERHIVE_STATE_DIR/forge-token` (= `/agents/<name>/state/forge-token`)
   — written at mode `0600` and chowned to the per-agent uid:gid (see
-  `hive-c0re/src/forge.rs`'s module doc for exactly where). nixbld users
+  `hive-c0re/src/forge/mod.rs`'s module doc for exactly where). nixbld users
   cannot read it.
 
 **Policy**: all credential files written to agent state directories MUST be mode
@@ -209,7 +209,8 @@ known operations; there is no arbitrary command pass-through:
 
 | Operation                                            | What it runs                                                                              |
 | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `StartContainer` / `StopContainer` / `KillContainer` | `nixos-container start/stop/kill <name>`                                                  |
+| `StartContainer` / `StopContainer`                   | `nixos-container start/stop <name>`                                                        |
+| `KillContainer`                                      | `machinectl kill <machine> --signal=SIGKILL` (`nixos-container` has no kill verb)          |
 | `CreateContainer` / `UpdateContainer`                | `nixos-container create/update <name> --flake <ref>`                                      |
 | `DestroyContainer`                                   | `nixos-container destroy <name>`                                                          |
 | `ListContainers`                                     | `nixos-container list`                                                                    |
@@ -226,7 +227,9 @@ known operations; there is no arbitrary command pass-through:
 **Container allowlist** — every request is validated against an
 allowlist before any operation: only names matching the agent-name
 convention (char-validated) or the known sibling service containers
-(`hive-gateway`, `hive-forge`, `hive-matrix`, `hive-ci`) are accepted.
+(`hive-forge`, `hive-matrix`, `hive-ci`) are accepted. `hive-gateway` is
+a host unit, not a container, so it is not in this list — see
+`ReloadGatewayNginx` above for how its access is scoped instead.
 Arbitrary container names are rejected.
 
 **Socket-activated** — systemd starts `hive-priv` on the first

From 720e5340dea21c06b62817a1662969de79b9dc8f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:19:21 +0200
Subject: [PATCH 42/64] docs(boundary): fix answer-question path and
 nonexistent AgentRequest type

---
 docs/boundary.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/boundary.md b/docs/boundary.md
index 6f389643..a37b300e 100644
--- a/docs/boundary.md
+++ b/docs/boundary.md
@@ -29,9 +29,10 @@ always on), the gateway proxies all operator-facing traffic, and
 point.** They live on the core backend.
 
 Worked example — answering an operator-targeted question is a
-`POST /answer-question/{id}` on the core dashboard, _never_ an
-`AgentRequest` variant. If it were a per-agent-socket request, an
-agent could `curl` its own socket and spoof an operator answer.
+`POST /api/answer-question/{id}` on the core dashboard, _never_ a
+per-agent-socket `Request` variant. If it were a per-agent-socket
+request, an agent could `curl` its own socket and spoof an operator
+answer.
 The per-agent web UI POSTs cross-origin to the core for these
 (see the inline-answer feature — the loose-ends section on each
 agent page).

From 723e33ae6cfdce0f213914e81ae1650eacdb7ee8 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:20:04 +0200
Subject: [PATCH 43/64] docs(agent-hierarchy): fix stale topology.rs path,
 ManagerRequest, dead reminder_scheduler.rs ref, and hardcoded forge URLs

---
 docs/agent-hierarchy.md | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/docs/agent-hierarchy.md b/docs/agent-hierarchy.md
index 7c24a665..c54b1ca4 100644
--- a/docs/agent-hierarchy.md
+++ b/docs/agent-hierarchy.md
@@ -4,8 +4,8 @@ Every agent has a place in an operator-editable parent/child tree, used
 to scope which agents can manage which others. This doc covers how the
 tree is stored and edited today, the rules that are meant to run on top
 of it once enforcement is finished, and where the manager still gets
-special-cased in the meantime. Tracking issue:
-[hyperhive#361](http://localhost:3000/hyperhive/hyperhive/issues/361).
+special-cased in the meantime. Tracking issue: hyperhive#361
+(`$HIVE_FORGE_URL/hyperhive/hyperhive/issues/361`).
 
 ## Where the tree lives
 
@@ -74,8 +74,8 @@ where system-level facts live.
 - **Surface** — every rescan re-reads `topology.json` and populates
   `ContainerView.parent`, which the dashboard renders as a tree.
 
-See `hive-c0re/src/topology.rs` and `hive-c0re/src/meta.rs`'s module
-docs for the exact call chain.
+See `hive-c0re/src/agent_config/topology.rs` and `hive-c0re/src/meta.rs`'s
+module docs for the exact call chain.
 
 ### Current limitation: state-dir visibility lags topology
 
@@ -113,10 +113,11 @@ other agents don't:
   `hive-c0re` spawns it directly at boot if missing, with no operator
   approval step — every other agent goes through `request_init_config`
   → approval. Topology-wise, `ruth` is still just another root agent.
-- **Wire-protocol** — the `ManagerRequest::*` operations
+- **Wire-protocol** — the privileged `Request` variants
   (`RequestInitConfig`; `Kill` / `Start` / `Restart` / `Update`;
-  `GetLogs`; `RequestUpdateMetaInputs`) are reachable only from the
-  manager's socket flavour today. Planned rule for each is in the
+  `GetLogs`; `RequestUpdateMetaInputs`) — marked `*(privileged)*` in
+  `hive-core-agent-sock`'s unified `Request` enum — are reachable only
+  from the manager's socket flavour today. Planned rule for each is in the
   table above ("any agent, child added under self" for init-config,
   "any ancestor" for lifecycle/logs); `RequestUpdateMetaInputs` stays
   a root-only capability even post-milestone, not a topology rule.
@@ -153,9 +154,11 @@ other agents don't:
   skipping the manager (it auto-restarts via systemd instead of going
   through the crash-watch loop). Each is planned to become an
   ancestor/descendant check instead of a manager-name check — see the
-  module docs for `loose_ends.rs`, `operator_questions.rs`,
-  `broker.rs`, `reminder_scheduler.rs`, `actions.rs`, and
-  `crash_watch.rs` for the current owner-check logic in each.
+  module docs for `loose_ends.rs`, `stores/operator_questions.rs`,
+  `stores/broker.rs`, `actions.rs`, and `workers/crash_watch.rs` for
+  the current owner-check logic in each. (Reminder cancellation has
+  since moved fully in-agent — see the note on
+  `CancelLooseEndKind::Reminder` in `hive-c0re/src/questions.rs`.)
 
 None of the above is a stable interface — treat the module doc
 comments as the source of truth for exactly which checks exist today.
@@ -233,7 +236,10 @@ uid 0 and have the setuid bit set."
 
 ## Cross-references
 
-- Milestone: ["Agent privileges and sub-agents"](http://localhost:3000/hyperhive/hyperhive/issues/361)
-- Dashboard render: ["show agent topology in container list"](http://localhost:3000/hyperhive/hyperhive/issues/363)
-- Audit table source: [milestone comment](http://localhost:3000/hyperhive/hyperhive/issues/361#issuecomment-3335)
+- Milestone: "Agent privileges and sub-agents"
+  (`$HIVE_FORGE_URL/hyperhive/hyperhive/issues/361`)
+- Dashboard render: "show agent topology in container list"
+  (`$HIVE_FORGE_URL/hyperhive/hyperhive/issues/363`)
+- Audit table source: milestone comment
+  (`$HIVE_FORGE_URL/hyperhive/hyperhive/issues/361#issuecomment-3335`)
 - Operator/agent trust boundary (orthogonal axis): [`boundary.md`](boundary.md)

From 3e9f2f2fd5ba4bcd0b8a7f0164892c6076b390c9 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:23:46 +0200
Subject: [PATCH 44/64] docs(dashboard): fix stale facts found in
 source-verification sweep

- server-warnings banner: was described as disk-pressure-only; it's now
  a push-based registry with multiple producers (forge/CI boot
  failures, agent-state warnings), and shown on more standalone pages
  than listed
- browser tab title: actual default/format is "hyperhive // h1ve-c0re",
  not "hive / c0re"
- SW4RM container tree: ContainerView.parent comes from
  agent_config/topology.rs, not the ambiguous dashboard/topology.rs
  (which only holds set-parent endpoints)
- T00L GR0UPS: tool-group enumeration was missing "forge"; root agent's
  default (MANAGER_DEFAULT) is not literally "all groups" -- it excludes
  forge and web_tools
- ST4TS moved to its own /stats.html page a while back; section still
  called it a dashboard tab
- P33RS is a headline block within the SW4RM tab, not its own tab --
  contradicted the doc's own chrome-header description
- active model badge: reads hyperhive-harness.json's active_model
  field, not a bare harness/hyperhive-model file
- themed dialogs: modal.js lives in the shared package
  (@hive/shared/modal.js), and themedToast takes (message, opts) not
  a single options object
- graceful stop: backend uses a Signal/Drain job-queue node pair, not
  a "GracefulStop" transient kind; hivectl flag is `stop --graceful`,
  not a bare `--graceful`
- container_state_changed event: named a nonexistent
  auto_update::rebuild_agent as an emit site; actual sites are
  actions::approve and the job queue's own node execution

Verified against hive-c0re/src (dashboard/, stats/, job_queue/,
container_view.rs), hive-sh4re/src/permissions.rs, and the dashboard
frontend package (tabs.js, stats.js, swarm.js, builds.js, modal.js).

No structural/prose changes beyond what the fact corrections required.
---
 docs/web-ui/dashboard.md | 126 +++++++++++++++++++++++----------------
 1 file changed, 76 insertions(+), 50 deletions(-)

diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index 46132f25..1428aff2 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -27,22 +27,27 @@ from the dashboard tab strip.
 - **Banner-thin** (`░▒▓█▓▒░ HYPERHIVE / HIVE-C0RE / WE ARE THE WIRED ░▒▓█▓▒░`)
   — sits below the tab strip.
 - **Server-warnings banner** — a generic, sticky top-of-page strip shown
-  on **every** page (dashboard + the stand-alone FL0W / L0GS / H0M3
-  pages), injected at the top of `<body>` by `renderServerWarnings` in
-  `common.js`. Driven by `state.server_warnings` — a list of
-  `{ kind, level, message }` from hive-c0re's `host_stats::server_warnings`
-  — and coloured by `level` (`warn` amber / `crit` red). The backend owns
-  the threshold + message, so adding a new system warning needs no
-  frontend change. The only producer today is the host disk-pressure
-  check (a `statvfs` probe of `/nix`: ≥85% used → `warn`, ≥95% → `crit`,
-  e.g. `⚠ host nix store N% full (G GiB free) — garbage-collect …`).
-  Hidden when there are no warnings.
-- **Browser tab title** — `hive / c0re` by default; updated to
-  `<swarm> / <hive>` once `hive_name` / `swarm_name` arrive in the
-  state snapshot. When there are pending approvals or unanswered
-  questions, a `(N)` prefix is prepended — `(3) pr1ma / hive-c0re`
-  — so the operator can see the call count in an unfocused browser
-  tab without opening the dashboard. The prefix is set on the
+  on **every** page (dashboard + every stand-alone page — FL0W, L0GS,
+  H0M3, C0R3, BU1LDS, CR3D3NTIALS, ST4TS, S3TT1NGS), injected at the top
+  of `<body>` by `renderServerWarnings` in `common.js`. Driven by
+  `state.server_warnings` — a list of `{ kind, level, message }` — and
+  coloured by `level` (`warn` amber / `crit` red). The backend owns the
+  threshold + message, so adding a new system warning needs no frontend
+  change. Warnings are a push-based registry (`hive-c0re`'s
+  `warnings.rs`): any subsystem raises/clears its own entry via an RAII
+  guard, and `host_stats::server_warnings()` is just a cheap snapshot of
+  that registry. Producers today include the host disk-pressure check
+  (a `statvfs` probe of `/nix`: ≥85% used → `warn`, ≥95% → `crit`, e.g.
+  `⚠ host nix store N% full (G GiB free) — garbage-collect …`), forge
+  provisioning/CI-runner boot failures, and agent-state warnings
+  (`pending_logins`, `agents_crashing`) computed alongside the container
+  snapshot. Hidden when there are no warnings.
+- **Browser tab title** — `hyperhive // h1ve-c0re` by default; updated
+  to `<swarm> / <hive> // h1ve-c0re` once `hive_name` / `swarm_name`
+  arrive in the state snapshot. When there are pending approvals or
+  unanswered questions, a `(N)` prefix is prepended — `(3) pr1ma //
+  h1ve-c0re` — so the operator can see the call count in an unfocused
+  browser tab without opening the dashboard. The prefix is set on the
   initial `/api/state` cold-load and updated live by
   `approval_added` / `approval_resolved` / `question_added` /
   `question_resolved` SSE events; it's preserved when
@@ -55,7 +60,10 @@ surfaces, not tab panes.
 ## SW4RM tab
 
 **C0NTAINERS** — live containers rendered as a depth-first
-tree using `ContainerView.parent` (populated by `topology.rs`).
+tree using `ContainerView.parent` (populated by
+`hive-c0re/src/agent_config/topology.rs` — not to be confused with
+`hive-c0re/src/dashboard/topology.rs`, which only holds the
+set-parent endpoints).
 Each container's row is prefixed with ASCII tree glyphs (`├─`,
 `└─`, `│  ` continuation columns) showing the agent
 parent/child hierarchy. When every container has `parent = null`
@@ -470,18 +478,22 @@ values follow the `effective`/`assignments` rule described above.
 
 **T00L GR0UPS** — per-agent tool-group permissions. Tool groups are
 named buckets of MCP tools; each agent starts with a role default
-(sub-agents: `messaging`, `meta`, `inbox`, `execution`; root agent: all
-groups). Checking / unchecking stages which groups are active for the
-agent; the page-level **save all** button (below) commits it. Columns
-come from `GET /api/tool-groups`. A rebuild is queued so
-`HIVE_TOOL_GROUPS` takes effect.
+(sub-agents: `messaging`, `meta`, `inbox`, `execution` —
+`ToolGroup::AGENT_DEFAULT`; root agent is seeded to
+`ToolGroup::MANAGER_DEFAULT` — `messaging`, `meta`, `inbox`,
+`lifecycle`, `approvals`, `scheduling`, `diagnostics`, `execution`,
+i.e. every group except `forge` and `web_tools`). Checking /
+unchecking stages which groups are active for the agent; the
+page-level **save all** button (below) commits it. Columns come from
+`GET /api/tool-groups`. A rebuild is queued so `HIVE_TOOL_GROUPS`
+takes effect.
 
 The current tool groups are: `messaging`, `meta`, `inbox`, `lifecycle`,
-`approvals`, `scheduling`, `diagnostics`, `execution`, `web_tools`. All
-listed in `ToolGroup::ALL` in `hive-sh4re`. The `web_tools` group is
-special: it carries no MCP tools; instead it adds Claude's built-in
-`WebFetch` and `WebSearch` to `--tools` / `--allowedTools` for that
-agent session.
+`approvals`, `scheduling`, `diagnostics`, `forge`, `execution`,
+`web_tools`. All listed in `ToolGroup::ALL` in `hive-sh4re`. The
+`web_tools` group is special: it carries no MCP tools; instead it adds
+Claude's built-in `WebFetch` and `WebSearch` to `--tools` /
+`--allowedTools` for that agent session.
 
 Both tables share the same visual shape: `.cap-table-wrap` /
 `.tg-table-wrap` outer scroll container, `thead` with a label column
@@ -588,14 +600,17 @@ attribute; a shared 1s ticker rewrites it in-place — showing
 `overdue X ago` once the deadline passes — without triggering a
 full re-render of the list.
 
-## ST4TS tab
+## ST4TS page (`/stats.html`)
 
 Hive-wide turn statistics, aggregated across every agent's
-`hyperhive-turn-stats.sqlite` for the selected window. Distinct from
+`hyperhive-turn-stats.sqlite` for the selected window. Not a dashboard
+tab — a standalone page reached from the **Stats** tile on the H0M3
+hub, same minimal chrome as `/flow.html` / `/logs.html`. Distinct from
 each agent's own `/stats` page (which carries the per-agent trend
 charts): ST4TS is the swarm-level rollup.
 
-- **Window selector** (`1h`–`30d`) re-fetches on change.
+- **Window selector** (`1h`, `4h`, `24h`, `3d`, `7d`, `30d`, `all`) —
+  a hash-routed tab strip (`#1h` / `#24h` / …) — re-fetches on change.
 - **Summary chips**: active agents, turns, total/input/output/cache-read
   tokens, and a labelled **est cost**.
 - **Busiest agents** table — one row per agent (most turns first):
@@ -614,7 +629,7 @@ Backed by `GET /api/stats-hive?window=<w>` in `hive-c0re`
 500 ms `busy_timeout`, since `turn_stats` is rollback-journal) and rolls
 the rows up — missing / unreadable / zero-turn dbs are skipped so one
 bad db never fails the endpoint. This is a **pull** surface (no SSE):
-the data is fetched on tab activation and on window change. Rendered
+the data is fetched on page load and on window change. Rendered
 with plain tables + CSS bars — the dashboard bundle ships no chart
 library.
 
@@ -627,13 +642,16 @@ the model id, longest match wins) mapping to
 `{ input, output, cache_read, cache_write }` USD-per-million-token
 prices. Models not covered fall back to hive-c0re's built-in estimate.
 
-## P33RS tab
+## P33R H1V3S (within the SW4RM tab)
 
-Peer hives in this swarm. The tab is hidden when the
+Peer hives in this swarm. Not its own tab — a headline block
+(`#peers-block`) rendered under the SW4RM tab's container list (see
+"Chrome header" above: "Peer hives render as a headline under SW4RM
+rather than a tab"). The block is hidden when the
 `state.peer_hives` array from `/api/state` is empty — i.e. when
 `services.hyperhive.swarm.hives` holds no hive other than this one.
 When at least one peer is present the `hidden` attribute is removed
-and the tab becomes active.
+and the cards render.
 
 **P33R H1V3S** — each peer renders as a card row: a hexagon icon
 (`⬡`), the peer's DNS domain as the primary name, and the peer
@@ -964,10 +982,12 @@ and it reads the narrow `/api/jobq/rollup` endpoint rather than the
 full graph.
 
 **Active model badge** (`model · <name>`, blue) appears when the
-container is running and the harness has persisted a model name
-(`harness/hyperhive-model`). Read by hive-c0re's `ContainerView`
-(`read_active_model`); absent until the agent has completed at least
-one turn and stale values are suppressed for stopped containers.
+container is running and the harness has persisted a model name (the
+`active_model` field of `hyperhive-harness.json`, the consolidated
+harness state file in the agent's state dir). Read by hive-c0re's
+`ContainerView` (`read_active_model`); absent until the agent has
+completed at least one turn and stale values are suppressed for
+stopped containers.
 
 **`ctx · Nk` chip** shows the agent's last-turn context size,
 populated from `DashboardState.ctx_tokens` (absent until the
@@ -1019,7 +1039,7 @@ step-level counts instead, unused here.
 ### Themed dialogs
 
 All confirmations, prompts, and transient error notices use an
-in-app themed dialog system (`assets/modal.js`) rather than the
+in-app themed dialog system (`@hive/shared/modal.js`) rather than the
 browser's native `confirm()` / `prompt()` / `alert()` chrome, so
 they match the Catppuccin palette and can't be styled away by the
 OS. Three primitives, all built on the `openDialog` core:
@@ -1031,7 +1051,7 @@ OS. Three primitives, all built on the `openDialog` core:
   button takes focus). Backdrop click and `Esc` both cancel.
 - `themedPrompt(...)` — a modal with a text input, resolving to the
   entered string or `null`.
-- `themedToast({ type, ... })` — a non-blocking toast (top-right,
+- `themedToast(message, { type, ... })` — a non-blocking toast (top-right,
   `info` / `error` / `ok`) for transient validation + action
   failures, so an error doesn't trap the operator behind a modal.
   Single-action errors auto-dismiss; bulk / partial-failure
@@ -1047,13 +1067,18 @@ and flush state before the container stops` checkbox. When ticked,
 the action POSTs `/api/kill/<name>?graceful=true` (the bulk path
 appends the flag per-agent); unticked is the instant hard stop
 (`/api/kill/<name>` with no query). The backend enqueues a
-`GracefulStop` rebuild-queue transient: the harness runs one
-stop-checkpoint turn (so the agent can flush `/state`) and then
-exits, with a 3-minute timeout that falls back to a hard stop. The
-quiescing progress surfaces through the same rebuild-queue
-transient + build log the card already reads for a rebuild. (The
-`hivectl --graceful` CLI flag enqueues the same `GracefulStop`, so
-the dashboard and CLI paths behave identically.)
+`Signal` → `Drain` job-queue node pair (`NodeKind::Signal` /
+`NodeKind::Drain`): `Signal` sets the graceful-stop fence and kicks
+the harness so it runs one stop-checkpoint turn (so the agent can
+flush `/state`); `Drain` awaits the harness clearing that fence,
+bounded by a 3-minute timeout (`GRACEFUL_STOP_TIMEOUT`) that
+resolves either way and falls back to the downstream mechanical
+stop. The quiescing progress surfaces through the same
+rebuild-queue pending-badge mechanism the card already reads for a
+rebuild — there's no build log, since a graceful stop runs no nix
+build. (The `hivectl stop --graceful` CLI flag enqueues the same
+`Signal`/`Drain` pair, so the dashboard and CLI paths behave
+identically.)
 
 ### Topology tree
 
@@ -1434,9 +1459,10 @@ payload):
 - `container_state_changed` (container: ContainerView) /
   `container_removed` (name) — per-row container mutations,
   emitted by `Coordinator::rescan_containers_and_emit` from
-  every mutation site (`actions::approve` post-spawn,
-  `actions::destroy`, the lifecycle_action wrapper,
-  `auto_update::rebuild_agent`) and from the 10s
+  many mutation sites — post-spawn approval bookkeeping
+  (`actions::approve`), the job queue's own node execution
+  (`job_queue::exec`, e.g. after a rebuild's stop/swap/start
+  steps or a destroy's teardown step) — and from the 10s
   `crash_watch` poll. Client upserts/removes by name; the
   pending overlay is read from `transientsState` since the
   payload doesn't carry it.

From 26b55f34d35a0cd0df123df98a1d3d7192a5a355 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:22:52 +0200
Subject: [PATCH 45/64] docs(web-ui/shape): fix stale CSS bundle count, SSE
 route prefix, bind-retry cap claims

Verified against frontend/packages/dashboard/build.mjs, hive-c0re/src/dashboard/mod.rs,
and hive-agent/src/web_ui/mod.rs:
- dashboard ships 9 page CSS bundles + colors/theme/common, not 4
- dashboard SSE routes are /api/dashboard/stream + /api/dashboard/history, not
  /dashboard/stream + /dashboard/history
- per-agent bind_with_retry has a MAX_BIND_ATTEMPTS=12 cap (gives up), unlike the
  dashboard's genuinely uncapped retry loop
- assets/swarm.js, assets/call.js -> swarm.js, call.js (no assets/ dir exists)
---
 docs/web-ui/shape.md | 44 +++++++++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md
index 97d0b410..e142299f 100644
--- a/docs/web-ui/shape.md
+++ b/docs/web-ui/shape.md
@@ -16,10 +16,14 @@
 - `GET /static/*` → bundled CSS + JS produced by esbuild
   (`frontend/packages/{dashboard,agent}/build.mjs`). Both pages
   pull the shared terminal pane + Catppuccin palette + typography
-  from `@hive/shared` (was `hive-fr0nt`); the dashboard ships four
-  CSS bundles (`common.css` loaded by every page, plus per-page
-  `dashboard.css` / `flow.css` / `logs.css`); `common.css` inlines
-  `base.css` + `terminal.css` via esbuild's `@import` resolution.
+  from `@hive/shared` (was `hive-fr0nt`); the dashboard ships one
+  CSS bundle per page (`colors.css` + `theme.css` + `common.css`,
+  loaded by every page, plus a page-specific bundle —
+  `dashboard.css` / `flow.css` / `logs.css` / `home.css` /
+  `settings.css` / `stats.css` / `core.css` / `builds.css` /
+  `credentials.css`); `common.css` inlines `@hive/shared`'s
+  `base.css` + `terminal.css` + `tabs.css` + `chrome.css` +
+  `pill.css` via esbuild's `@import` resolution.
   `terminal.js` exports `{ create, linkify }` as ES module
   members; a back-compat shim in the IIFE bodies still exposes
   a `window.HiveTerminal` global for callers that need it. The dashboard's
@@ -42,14 +46,14 @@
   high-water mark at the moment the snapshot was assembled);
   clients use it to dedupe their buffered SSE traffic against
   the snapshot (drop frames with `seq <= snapshot.seq`).
-- `GET /dashboard/stream` (dashboard) / `GET /events/stream`
+- `GET /api/dashboard/stream` (dashboard) / `GET /events/stream`
   (per-agent) → `text/event-stream` SSE for live updates. The
   dashboard stream carries broker `Sent` / `Delivered` (mirrored
   by a forwarder task from the broker's intra-process channel)
   plus mutation events (`approval_added` / `approval_resolved`,
   `question_added` / `question_resolved`, `transient_set` /
   `transient_cleared`). Each frame carries a `seq`. The
-  matching backfill endpoint is `GET /dashboard/history` (last
+  matching backfill endpoint is `GET /api/dashboard/history` (last
   ~200 broker messages wrapped in `{ seq, events }`) on the
   dashboard and `GET /events/history` (last 2000 `LiveEvent`s
   also wrapped in `{ seq, events }`) on the agent.
@@ -201,7 +205,7 @@ re-render), call `refreshState()`. State shapes live in
 `hive-c0re/src/dashboard/state_snapshot.rs::StateSnapshot` and
 `web_ui/state.rs::StateSnapshot` — when
 adding state fields, plumb through the snapshot struct and the
-relevant domain module (`assets/swarm.js`, `assets/call.js`, etc.) render function.
+relevant domain module (`swarm.js`, `call.js`, etc.) render function.
 
 **Focus preservation:** `refreshState` checks whether
 `document.activeElement` sits inside one of the managed sections
@@ -277,18 +281,20 @@ previews are type-aware:
 
 Both bind their TCP listener with `SO_REUSEADDR` via
 `tokio::net::TcpSocket` plus a retry loop on `AddrInUse`
-(exponential backoff capped at 2s, **no attempt cap**) so an nspawn
-restart that races the previous process's socket release resolves
-itself. The retry is uncapped on purpose: a capped budget once
-left the harness silently UI-less for the rest of its lifetime
-when a back-to-back restart held the port longer than the cap
-allowed. Genuine port collisions are preflighted host-side
-(`lifecycle::{spawn,rebuild}` refuses with a clear error,
-surfaced on the dashboard as a banner), so at this layer a
-persistent `AddrInUse` always reflects a recoverable stale
-socket — retrying forever is the safe choice. The first 12
-attempts log at WARN; after that the level drops to INFO so a
-long-held stale socket doesn't flood the journal.
+(exponential backoff capped at 2s) so an nspawn restart that races
+the previous process's socket release resolves itself, but the two
+binaries differ on the attempt budget. The dashboard's
+`bind_with_retry` (`hive-c0re/src/dashboard/mod.rs`) has **no
+attempt cap** — retrying forever is deliberate, since genuine port
+collisions are preflighted host-side (`lifecycle::{spawn,rebuild}`
+refuses with a clear error, surfaced on the dashboard as a banner),
+so at this layer a persistent `AddrInUse` always reflects a
+recoverable stale socket. Its first 12 attempts log at WARN; after
+that the level drops to INFO so a long-held stale socket doesn't
+flood the journal. The per-agent UI's `bind_with_retry`
+(`hive-agent/src/web_ui/mod.rs`) instead gives up after
+`MAX_BIND_ATTEMPTS` (12) and returns the `AddrInUse` error rather
+than looping forever.
 
 The per-agent UI optionally binds a `UnixListener` instead of
 TCP when `HIVE_WEB_SOCKET` is set — the unix-socket transition

From 4388719b76ccfce5ec7f0fc66ae26344830f4e41 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:22:54 +0200
Subject: [PATCH 46/64] docs(web-ui/agent): fix stale NavLink type name

Verified against hive-agent/src/web_ui/state.rs: the struct is AgentLink
(AgentLinkKind for kind), not NavLink -- NavLink doesn't exist anywhere in
the Rust or frontend source.
---
 docs/web-ui/agent.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md
index 387ccd2b..1d6f1169 100644
--- a/docs/web-ui/agent.md
+++ b/docs/web-ui/agent.md
@@ -36,7 +36,7 @@ through. Three flex columns:
     also appears in `DashboardState.links` (`GET /api/dashboard-state`)
     for the dashboard card's icon strip. Both are produced by
     `agent_links()` in hive-ag3nt — the single source of truth.
-    Each `NavLink.kind` resolves
+    Each `AgentLink.kind` resolves
     differently in the frontend: `Container` → same-origin path
     (the agent page is itself container-local); `Forge` →
     `state.forge_public_url + url` (sourced from

From 066cd712eace00c75b5aded42bd5e090ceca9c30 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:23:02 +0200
Subject: [PATCH 47/64] docs(terminal-rendering): re-attribute dispatch logic
 to stream_enrich.rs, fix Write/TodoWrite/Bash dead-path claims

Verified against hive-agent/src/stream_enrich.rs and frontend/packages/agent/src/app.js:
- per-tool icon/summary/category classification moved server-side to
  stream_enrich.rs::enrich() a while ago; fmtToolUse/fmtArgsGeneric/toolIcon no
  longer exist in app.js -- the client now just dispatches on the backend-stamped
  _icon/_summary/_category/_body/_body_type fields. Rewrote the 'Renderer dispatch'
  and 'Salient-arg formatting' (was 'fmtToolUse patterns') sections to match, and
  retargeted the per-tool table's 'Everything else' row to fmt_args_generic.
- Write is no longer a rich diff row -- is_rich_tool() doesn't include it, and
  fmt_builtin_tool formats it identically to Read (flat, no count). Only Edit
  still gets the rich diff.
- TodoWrite and built-in Bash aren't in ALLOWED_BUILTIN_TOOLS (mcp_config.rs) any
  more than Task is -- flagged both as dead paths for consistency with the
  existing Task annotation.
- fixed stray 'ask* has an inline answer form' table note that contradicted the
  doc's own later 'Inline ask-operator answer' section (no such form exists).
- terminal.css path: frontend/packages/shared/src/terminal/terminal.css, not
  .../shared/src/terminal.css; marked npm dep is v18.x, not v4.x.
---
 docs/terminal-rendering.md | 125 +++++++++++++++++++++++--------------
 1 file changed, 78 insertions(+), 47 deletions(-)

diff --git a/docs/terminal-rendering.md b/docs/terminal-rendering.md
index 9e463aad..36b5786d 100644
--- a/docs/terminal-rendering.md
+++ b/docs/terminal-rendering.md
@@ -1,11 +1,16 @@
 # Per-agent terminal: row taxonomy (as built)
 
 Snapshot of how the per-agent web UI's live pane renders each
-event kind today. Source of truth lives in
-`frontend/packages/agent/src/app.js` (`renderStream`, `fmtToolUse`,
+event kind today. The per-tool icon/summary/category (and, for a
+few rich tools, the expandable body) are pre-computed server-side by
+`hive-agent/src/stream_enrich.rs::enrich` and stamped onto the
+stream-json value as `_icon`/`_summary`/`_category`/`_body`/
+`_body_type` before SSE delivery, so the frontend just dispatches on
+those fields instead of re-deriving them. Frontend source of truth
+lives in `frontend/packages/agent/src/app.js` (`renderStream`,
 `renderRichToolUse`, `renderToolResult`, `renderTaskEvent`,
-`mdNode`, `detailsOpenMd`, `fmtArgsGeneric`) +
-`frontend/packages/shared/src/terminal.css` (the shared
+`mdNode`, `detailsOpenMd`) +
+`frontend/packages/shared/src/terminal/terminal.css` (the shared
 `.live .<class>` styling) + the `marked` npm package (markdown).
 
 ## Layout contract
@@ -56,8 +61,8 @@ parent's negative pull.
 | `.turn-time` | `· HH:MM:SS` on turn-start; `· HH:MM:SS · <dur>` on turn-end (child span) | muted, smaller | per-event `ts` (unix seconds) on the live frame + history row | harness |
 | `.text` | (no prefix; markdown body) | fg | claude `assistant.content[].text` | stream-json |
 | `.thinking` | `💭 thinking …` | muted, italic | claude `assistant.content[].thinking` | stream-json |
-| `.tool-use` (flat) | `<icon> Name args…` | cyan | tool_use w/o rich renderer; `<icon>` from `toolIcon(name)`: 📤 send · 📥 recv · ❓ ask · ⏰ remind · 🏷️ set_status · 🪢 loose-ends · ✂️ cancel_loose_end · ℹ️ get_agent_meta · ✅ ack_until · 📜 get_logs/get_host_journal · ↻ restart · ⏹️ kill · ▶️ start · 🔄 update · 📋 list_containers/list_rooms/list_room_members/list_invites · 📖 read_room/Read · 👁️ mark_read · 🛑 bash kill · 🖥️ bash other · 💬 matrix send/reply/dm · 📦 request_* · ⏱️ schedule · 🔧 default | stream-json |
-| `.tool-use` `<details>` | `💾/✏️ Write/Edit <path> · +N` (no `→`) | cyan, body is +/- diff | `renderRichToolUse` Write/Edit | stream-json |
+| `.tool-use` (flat) | `<icon> Name args…` | cyan | tool_use w/o rich renderer; `<icon>` from the backend's `tool_icon(name)` (`stream_enrich.rs`): 📤 send · 📥 recv · ❓ ask · ⏰ remind · 🏷️ set_status · 🪢 loose-ends · ✂️ cancel_loose_end · ℹ️ get_agent_meta · ✅ ack_until · 📜 get_logs/get_host_journal · ↻ restart · ⏹️ kill · ▶️ start · 🔄 update · 📋 list_containers/list_rooms/list_room_members/list_invites · 📖 read_room/Read · 👁️ mark_read · 🛑 bash kill · 🖥️ bash other · 💬 matrix send/reply/dm · 📦 request_* · ⏱️ schedule · 🔧 default | stream-json |
+| `.tool-use` `<details>` | `✏️ Edit <path> · -N +N` (no `→`) | cyan, body is +/- diff | `renderRichToolUse` Edit | stream-json |
 | `.tool-use` `<details open>` | `📤 send → to · NL`, `❓ ask → to`, `✍️ answer #id` | cyan, body is markdown | rich renderer for send / ask / answer | stream-json |
 | `.tool-result` (flat) | `←  <txt>` | muted | short `tool_result` (≤120c, non-recv) | stream-json |
 | `.tool-result-block` `<details>` | `Nl · headline` | muted, body is text | long generic `tool_result` | stream-json |
@@ -87,42 +92,65 @@ suffix, so the terminal degrades cleanly against older event shapes.
 
 ## Renderer dispatch
 
-`renderStream(v, api)` walks each stream-json line:
+`renderStream(v, api)` walks each stream-json line. Most of the
+per-event classification it used to do itself is now pre-computed
+server-side by `hive-agent/src/stream_enrich.rs::enrich` (stamped
+onto the value as `_category`/`_summary`/`_icon`/`_body`/
+`_body_type` at SSE-emit time, for both the live tail and history
+replay) — the client mostly just dispatches on those fields rather
+than re-deriving them from raw claude field names:
 
-1. Drops `system/init`, `rate_limit_event`, `result` (noise /
-   handled elsewhere — `result` powers the `cost` badge).
-1a. `system/thinking_tokens` (claude streams a running
+1. `v._category === 'drop'` → dropped without rendering. Covers the
+   top-level `result` / `rate_limit_event` types (`result` powers the
+   `cost` badge elsewhere) and the `system` subtypes `init` /
+   `result` / `rate_limit_event`.
+1a. `system` events with `_category === 'thinking_tok'`
+   (`subtype == "thinking_tokens"`; claude streams a running
    `estimated_tokens` counter while thinking — many per turn) →
    collapses into a **single** `🧠 thinking … ~N tokens` `.note`
-   row that updates in place. Consecutive ticks reuse the row only
+   row that updates in place, text taken verbatim from the
+   backend-computed `_summary`. Consecutive ticks reuse the row only
    while it's still the last one rendered (`nextElementSibling ==
    null`); any other event after it makes the next tick start a
    fresh row. Avoids a note-per-tick scrollback flood.
-1b. `system/plugin_install` → muted note `⚙ plugin install · loading…`
-   (on `started`) or `⚙ plugin install · ✓ done` (on `completed`).
-   Emitted in pairs: started fires before the plugin loads, completed
-   fires when it's ready. The `uuid` links the pair.
-1c. `system/commands_changed` → collapsible `.note` details row showing
-   the new slash-command count (`⚙ commands changed · N available`).
-   Expanding reveals each `/name` and its aliases. Fires after
-   `plugin_install` when a plugin registers new commands.
-1d. `system/compact_boundary` → muted note showing compaction summary:
-   `⚙ compact · <trigger> · <pre>→<post> tokens · <dur>`. Fields are
-   guarded individually — a missing field is silently omitted. Trigger
-   is `"manual"` (operator `/compact`) or `"auto"`.
-1e. Other `system/` subtypes → muted note `⚙ <subtype>`.
+1b. `system/plugin_install` (matched on `subtype`, not `_category`,
+   so start/complete can coalesce into one row) → muted note
+   `⚙ plugin install · loading…` (on `started`) or
+   `⚙ plugin install · ✓ done` (on `completed`), text from
+   `_summary`. Emitted in pairs: started fires before the plugin
+   loads, completed fires when it's ready.
+1c. `system/status` (matched on `subtype`) → muted note from
+   `_summary`, except while the harness's local `turn_state` is
+   `compacting`: the client overrides the text with an elapsed-time
+   counter (`⚙ compact · <N>s…`) computed client-side from
+   `stateSince`, since the backend can't know client wall-clock time
+   at emit time.
+1d. `_category === 'details'` (currently just `system/commands_changed`)
+   → collapsible `.note` details row: `_summary` as the header
+   (`⚙ commands changed · N available`), `_body` (one `/name` per
+   line) as the expandable content.
+1e. Other `system/` subtypes (e.g. `compact_boundary`, `api_retry`,
+   `api_error`, or an unrecognised subtype) → `_category === 'note'`,
+   rendered as a single muted note from `_summary` — computed by
+   `system_fields()` in `stream_enrich.rs` (e.g. `compact_boundary`
+   → `⚙ compact · <trigger> · <pre>→<post> tokens · <dur>` with each
+   field guarded individually; an unrecognised subtype falls back to
+   `⚙ <subtype>`).
 2. `subtype == "task_started" | "task_notification"` →
    `renderTaskEvent` (subagent activity gets the `⌁` glyph).
 3. `type == "assistant"` → walk `message.content[]`:
    - `text` → `.text` row with a markdown body via `mdNode`.
    - `thinking` → `.thinking` row.
-   - `tool_use` → record `id → name` in `toolNameById`, try
-     `renderRichToolUse` (Write/Edit/send/ask/answer get
-     custom renderings); on miss fall through to a flat
-     `.tool-use` row with `fmtToolUse → fmtArgsGeneric`.
-     `fmtToolUse` surfaces the salient arg per built-in tool
-     (see [`fmtToolUse` patterns](#fmttooluse-patterns) below);
-     `fmtArgsGeneric` handles everything else.
+   - `tool_use` → record `id → name` in `toolNameById`. The backend
+     stamps every `tool_use` entry with `_icon` + `_summary` (via
+     `fmt_tool_use()` in `stream_enrich.rs` — see [salient-arg
+     formatting](#salient-arg-formatting) below) and, for a fixed set
+     of tools, `_category: "rich"` + `_body`/`_body_type`. When
+     `_category === "rich"`, `renderRichToolUse` dispatches on
+     `_body_type` (`"diff"` → `api.detailsDiff`, `"markdown"` →
+     `detailsOpenMd`, else `api.details`) to build the expandable
+     row; otherwise it falls through to a flat `.tool-use` row using
+     `_icon` + `_summary` as-is — no per-tool JS.
 4. `type == "user"` → walk `message.content[]` for
    `tool_result`; `renderToolResult` correlates via
    `tool_use_id → toolNameById` to default-open `recv`
@@ -130,27 +158,29 @@ suffix, so the terminal degrades cleanly against older event shapes.
    long = collapsed details.
 5. Unrecognised shape → `.sys` row (amber, `!` glyph).
 
-### `fmtToolUse` patterns
+### Salient-arg formatting
 
-The `short` name strips the `mcp__hyperhive__` / `mcp__bash__` /
-`mcp__matrix__` prefix and appends `*` (e.g. `recv*`, `run*`,
-`send_message*`). Unprefixed tools (Read, Write, etc.) keep their
-name as-is.
+Server-side (`fmt_tool_use()` and its per-tool-family helpers in
+`hive-agent/src/stream_enrich.rs`), computed into `_summary` and
+read verbatim by the client. The `short` name strips the
+`mcp__hyperhive__` / `mcp__bash__` / `mcp__matrix__` prefix and
+appends `*` (e.g. `recv*`, `run*`, `send_message*`). Unprefixed
+tools (Read, Write, etc.) keep their name as-is.
 
 | Tool | Rendered as |
 |------|-------------|
 | **Claude built-ins** | |
 | `Read` | `Read <path>` |
-| `Write` | rich diff row `Write <path> · +N` |
-| `Edit` | rich diff row `Edit <path> · -N +N` |
+| `Write` | flat, same shape as Read: `Write <path>` — no diff/count (`content` can be megabytes and is one-sided; open the file to inspect it) |
+| `Edit` | rich diff row `Edit <path> · -N +N` (just `+N` for a pure insert, i.e. empty `old_string`) |
 | `Glob` | `Glob <pattern>` |
 | `Grep` | `Grep <pattern>` |
-| `Bash` | `Bash [bg] $ <cmd>` (also rich renderer for full body) |
-| `TodoWrite` | `TodoWrite (N items)` |
+| `Bash` | `Bash [bg] $ <cmd>` (dead path — built-in `Bash` isn't in the agent allow-list either; shell execution goes through `mcp__bash__run` / `run*` below instead) |
+| `TodoWrite` | `TodoWrite (N items)` (dead path — `TodoWrite` isn't in the agent allow-list; its state lives in claude's in-process session and evaporates on `/compact`, so agents plan in `/state` notes instead) |
 | **Core hyperhive** | |
 | `send*` | rich renderer: `send* → to · NL` (default-open body) |
 | `recv*` | `recv*()` · `recv* wait Ns` · `recv* max N` |
-| `ask*` | rich renderer: `ask* → to` (inline answer form for operator) |
+| `ask*` | rich renderer: `ask* → to` (no inline answer form — see [Inline ask-operator answer](#inline-ask-operator-answer)) |
 | `answer*` | rich renderer: `answer* #id` |
 | `remind*` | `remind* +Xm "preview"` or `remind* at HH:MMZ "preview"` |
 | `set_status*` | `set_status* "text"` |
@@ -183,12 +213,12 @@ name as-is.
 | `join_room*/open_dm*` | `join_room* room` / `open_dm* @user` |
 | `invite_user*` | `invite_user* @user → room` |
 | `download_file*` | `download_file* room` |
-| **Everything else** | `fmtArgsGeneric` — see [Extra-MCP tools](#extra-mcp-tools) |
+| **Everything else** | `fmt_args_generic` — see [Extra-MCP tools](#extra-mcp-tools) |
 
 ## Markdown
 
-`mdNode(text)` wraps `marked.parse(text)` (the `marked` v4.x npm
-dep, bundled by esbuild into the page's `app.js`) in a `<div
+`mdNode(text)` wraps `marked.parse(text)` (the `marked` npm dep,
+bundled by esbuild into the page's `app.js`) in a `<div
 class="md">`. CSS in `terminal.css` scopes paragraph / code /
 list / blockquote / link styling under `.live .row .md` so
 the markdown body doesn't bleed into the row's own
@@ -198,8 +228,9 @@ recv message bodies.
 
 ## Extra-MCP tools
 
-`fmtArgsGeneric(name, input)` is the fallback when a tool
-isn't in the built-in `fmtToolUse` switch:
+`fmt_args_generic(name, input)` (`hive-agent/src/stream_enrich.rs`)
+is the fallback when a tool isn't in the built-in `fmt_tool_use`
+switch, computed into `_summary` server-side:
 
 - single string field → `name k: "v"`
 - single number/bool field → `name k: v`
@@ -207,7 +238,7 @@ isn't in the built-in `fmtToolUse` switch:
   `k: [N]` / `k: {…}` with a `…+N` overflow
 
 This keeps less-frequent tools that don't have a specific
-`fmtToolUse` case from dumping raw JSON. Common matrix and
+`fmt_tool_use` case from dumping raw JSON. Common matrix and
 hyperhive tools have their own cases and skip this path.
 
 ## Inline ask-operator answer

From f41acfcc6ecd96fb8d324ecc13a55855c19e7df5 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:24:25 +0200
Subject: [PATCH 48/64] docs(network): fix stale forge/matrix zone claim in
 resolver behaviour

Verified against nix/host-modules/hive-gateway/dnsmasq.nix + gateway.localNames
contributors (hive-forge, hive-matrix, swarm-authelia): forge and the matrix
gateway vhost are swarm-domain names (forge.<swarm-domain>, chat.<swarm-domain>),
not sub-domains of the hive's own domain as the doc previously claimed.
---
 docs/network.md | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/docs/network.md b/docs/network.md
index 39f24c1e..1e40c4b2 100644
--- a/docs/network.md
+++ b/docs/network.md
@@ -112,14 +112,19 @@ schemes pick their own.
 
 ## Resolver behaviour
 
-dnsmasq is **authoritative** for the hive's own zones — answers
-`<hive-domain>`, `forge.<hive-domain>`, `matrix.<hive-domain>` and —
-on the host running it — the swarm's `auth.<swarm-domain>`
-queries with the bridge IP (where nginx is reachable). Everything
-else is forwarded to the host's own resolvers: dnsmasq runs on the host
-and reads the host's `/etc/resolv.conf` directly. Containers don't need
-to know the upstream — they query the bridge IP and dnsmasq does the
-right thing per-name.
+dnsmasq is **authoritative** for the hive's own zone (`<hive-domain>`)
+plus whatever swarm-service names this host contributes via
+`gateway.localNames` — `forge.<swarm-domain>` and `chat.<swarm-domain>`
+(matrix) when this host runs those services, and `auth.<swarm-domain>`
+when it runs authelia — answering each with the bridge IP (where nginx
+is reachable). Note forge and matrix are swarm-domain names, not
+sub-domains of `<hive-domain>`: a swarm runs one forge and one
+homeserver, so their names belong to the swarm rather than to whichever
+hive happens to host them. Everything else is forwarded to the host's
+own resolvers: dnsmasq runs on the host and reads the host's
+`/etc/resolv.conf` directly. Containers don't need to know the
+upstream — they query the bridge IP and dnsmasq does the right thing
+per-name.
 
 There is deliberately no fallback `server=`: dnsmasq queries all known
 upstreams in parallel, so a hardcoded public resolver would take a share

From 150cb1be761bce6bce5cc6d3a3509f04519c89d4 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:24:29 +0200
Subject: [PATCH 49/64] docs(matrix): fix stale matrix.<hive> vhost +
 assertion-list claims

Verified against nix/host-modules/hive-matrix.nix: gatewayHost's current
default is chat.<swarm-domain>, not matrix.<hive>, so the GUI mount point
and fluffychat client line were stale. Also rewrote the Assertion
rationale section, which named an assertion (hyperhiveDomain/serverName)
that doesn't exist in this module and missed the three SSO assertions
that do.
---
 docs/matrix.md | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/matrix.md b/docs/matrix.md
index 167ff14d..b0c0040f 100644
--- a/docs/matrix.md
+++ b/docs/matrix.md
@@ -2,7 +2,7 @@
 
 Private Matrix homeserver (matrix-tuwunel — the conduwuit
 successor) wrapped in a nixos-container, plus optional fluffychat-web
-client at `matrix.<hive>/`. Configured via
+client at `chat.<swarm-domain>/` (the `gatewayHost` vhost). Configured via
 `services.hyperhive.swarm.matrix.*`; vhost routing lives in
 [`gateway.md`](gateway.md).
 
@@ -208,18 +208,28 @@ resource-constrained hosts where a 20 MB request is unexpectedly large.
 
 ## Assertion rationale
 
-Two `config.assertions` entries fail eval early rather than ship
+`config.assertions` in this module fail eval early rather than ship
 surprising behaviour:
 
-- **`hyperhiveDomain != null || cfg.serverName != null`** —
-  `server_name` is embedded into every user / room ID irrevocably;
-  we refuse to spawn the homeserver with a bogus `server_name` we
-  can never change later.
 - **`cfg.gatewayHost != ""`** — same footgun as `forge.domain`:
   empty string renders `.<hive>`-shaped garbage in both nginx
   `server_name` (treated as wildcard catch-all, surprising) and
   `/etc/hosts` (invalid entry). `null` is the right opt-out shape;
   empty string is rejected explicitly.
+- **`sso.enable` requires `sso.clientSecretFile`** — fails at eval,
+  not at boot: tuwunel reads its identity providers from the config
+  file, so a half-configured one can stop the homeserver from
+  starting outright rather than merely hiding a login button.
+- **`sso.enable` requires `swarm.authelia.url`** — without a
+  provider URL there is nothing to discover against.
+- **`sso.enable` requires `gatewayHost != null`** — the SSO callback
+  URL is format-locked to `<homeserver>/_matrix/client/unstable/login/sso/callback/<client_id>`,
+  and the identity provider needs a public name to redirect the
+  browser to.
+
+`server_name`'s own bogus-value guard lives in `hive-network.nix`
+(`services.hyperhive.domain != null`), not here — see
+[`docs/network.md`](network.md).
 
 ## fluffychat-web build fixes
 
@@ -265,5 +275,5 @@ Two non-obvious details worth knowing before touching either derivation:
 Drop both derivations when nixpkgs's flutter builder grows worker
 + emcc support upstream.
 
-Mount point is `matrix.<hive>/`; upstream `--base-href "/"` is
-correct at sub-domain root, no override.
+Mount point is `chat.<swarm-domain>/` (the `gatewayHost` vhost);
+upstream `--base-href "/"` is correct at sub-domain root, no override.

From 0e84e72c21b0b067b87cc9d1c26f8e6758660f1e Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:24:35 +0200
Subject: [PATCH 50/64] docs(gateway): fix stale gateway.enable, selfSignedTls,
 rootUrl, vhost claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified against nix/host-modules/hive-gateway/*.nix + hive-matrix.nix +
hive-forge/default.nix:
- services.hyperhive.gateway.enable was removed (gateway is now
  unconditional) — fixes the Dashboard link shape + Firewall posture
  sections, which described a gateway-off mode that no longer exists.
- gateway.selfSignedTls is a removed option (fails eval), not a
  deprecated-and-ignored one.
- The forge rootUrl auto-derivation now uses https:// behind the
  gateway (httpsPort), not http://.
- Vhost map + discovery-flow + local-dev sections used matrix.<hive> /
  forge.<hive>; current defaults are chat.<swarm-domain> and
  forge.<swarm-domain> (both swarm-domain-rooted, per hive-matrix.nix's
  gatewayHost and hive-forge's domain option).
- hive-c0re.nix is now a directory (nix/host-modules/hive-c0re/); pointed
  the HIVE_FORGE_URL reference at the actual file, environment.nix.
---
 docs/gateway.md | 79 +++++++++++++++++++++++++++----------------------
 1 file changed, 43 insertions(+), 36 deletions(-)

diff --git a/docs/gateway.md b/docs/gateway.md
index 66039431..0bbbf6a8 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -9,11 +9,11 @@ Single nginx in front of every hyperhive web surface. Runs on the **host**, next
 | `<hive>/` | `_` (catch-all) | dashboard dist (static, from `servedFrontend`); `/api/` + `/webhook/` → hive-c0re (`7000`) | always |
 | `<hive>/agent/<name>/` | `_` | per-agent harness (UDS or TCP) | `agents.conf` (runtime-generated) |
 | `<hive>/.well-known/matrix/{client,server}` | `_` | inline JSON (no upstream) | `matrix.enable && domain != null` |
-| `<hive>/matrix/` (deprecated) | `_` | 301 → `matrix.<hive>/` | `matrix.gui.enable` |
-| `forge.<hive>/` | `forge.<hive>` | forgejo (`3000`) | `forge.behindGateway` |
-| `matrix.<hive>/_matrix/*` | `matrix.<hive>` | tuwunel (`8008`) | `matrix.gatewayHost != null` |
-| `matrix.<hive>/` | `matrix.<hive>` | fluffychat-web static | `matrix.gui.enable` |
-| `matrix.<hive>/config.json` | `matrix.<hive>` | inline JSON (FluffyChat boot config) | `matrix.gui.enable && domain != null` |
+| `<hive>/matrix/` (deprecated) | `_` | 301 → `chat.<swarm>/` | `matrix.gui.enable` |
+| `forge.<swarm>/` | `forge.<swarm>` | forgejo (`3000`) | `forge.behindGateway` |
+| `chat.<swarm>/_matrix/*` | `chat.<swarm>` | tuwunel (`8008`) | `matrix.gatewayHost != null` |
+| `chat.<swarm>/` | `chat.<swarm>` | fluffychat-web static | `matrix.gui.enable` |
+| `chat.<swarm>/config.json` | `chat.<swarm>` | inline JSON (FluffyChat boot config) | `matrix.gui.enable && domain != null` |
 | `auth.<swarm>/` | `auth.<swarm>` | authelia (`9091`) | `swarm.authelia.enable` |
 | `<swarm>/` | `<swarm>` | swarm-ui dist (static), behind an authelia subrequest | `swarm.ui.enable` |
 
@@ -28,17 +28,17 @@ Per-agent UIs stay sub-path, forge and matrix get sub-domains — see
 
 Operator points client at `<hive>`. Sequence:
 
-1. Client fetches `https://<hive>/.well-known/matrix/client` → `{"m.homeserver":{"base_url":"https://matrix.<hive>"}}` (no port suffix when gateway listens on 443). The gateway always terminates TLS, so the scheme is always `https`; a non-default `httpsPort` is reflected as the port suffix.
-2. Client connects to `matrix.<hive>/_matrix/client/...`.
+1. Client fetches `https://<hive>/.well-known/matrix/client` → `{"m.homeserver":{"base_url":"https://chat.<swarm>"}}` (no port suffix when gateway listens on 443). The gateway always terminates TLS, so the scheme is always `https`; a non-default `httpsPort` is reflected as the port suffix.
+2. Client connects to `chat.<swarm>/_matrix/client/...`.
 3. Gateway routes `/_matrix/*` → tuwunel at `127.0.0.1:8008`.
 
 matrix-dart-sdk (FluffyChat etc.) hardcodes `https` for the well-known fetch regardless of input scheme, so the discovery endpoint MUST be https — see "Self-signed TLS" below for the cert generation that backs the default-on path.
 
-Federation peers fetch `.well-known/matrix/server` → `{"m.server":"matrix.<hive>"}` and connect to `matrix.<hive>:8448` per spec default. Gateway only listens on configured `port` (+ `httpsPort` when TLS on); cross-hive federation needs either an SRV record (`_matrix._tcp.matrix.<hive>` → port 80 / 443) OR `matrix.openFirewall = true` so peers reach tuwunel's federation port directly. Hyperhive is mostly closed/internal, so this rarely bites.
+Federation peers fetch `.well-known/matrix/server` → `{"m.server":"chat.<swarm>:<httpsPort>"}` (the federation delegation always carries an explicit port, even the HTTPS default 443 — the https-implies-443 elision only applies to the client base_url above). Gateway only listens on configured `port` (+ `httpsPort` when TLS on); cross-hive federation needs either an SRV record (`_matrix._tcp.chat.<swarm>` → port 80 / 443) OR `matrix.openFirewall = true` so peers reach tuwunel's federation port directly. Hyperhive is mostly closed/internal, so this rarely bites.
 
 ## SPA fallback (Accept-header pattern)
 
-The per-agent UIs and the `matrix.<hive>` vhost serve a flutter/SPA bundle via the Accept-header pattern below. The dashboard vhost instead routes by **path** — see [Dashboard: path-based routing](#dashboard-path-based-routing-not-accept-header) below. Two requirements collide:
+The per-agent UIs and the `chat.<swarm>` vhost serve a flutter/SPA bundle via the Accept-header pattern below. The dashboard vhost instead routes by **path** — see [Dashboard: path-based routing](#dashboard-path-based-routing-not-accept-header) below. Two requirements collide:
 
 - hard-refresh on a sub-route must serve `index.html` (SPA's client-side router takes over after JS bootstrap)
 - a non-navigation request that isn't an on-disk asset must NOT get HTML with the wrong content-type
@@ -62,8 +62,8 @@ Each location carries a duplicated `auth_basic` block (separate locations don't
 `services.hyperhive.gateway.localHostsEntry = true` adds entries to the host's `/etc/hosts`:
 
 - `<hive-domain>` → `127.0.0.1`
-- `forge.<hive>` → `127.0.0.1` (when forge.behindGateway)
-- `matrix.<hive>` → `127.0.0.1` (when matrix.gatewayHost set)
+- `forge.<swarm>` → `127.0.0.1` (when forge.behindGateway)
+- `chat.<swarm>` → `127.0.0.1` (when matrix.gatewayHost set)
 - `auth.<swarm>` → `127.0.0.1` (when swarm.authelia.enable)
 
 `lib.unique` de-dupes if any sub-domain happens to equal another entry. Operators with real DNS leave it off.
@@ -150,8 +150,11 @@ When the gateway is in front, the SW4RM tab builds per-agent links
 as same-origin `/agent/<name>/…` URLs instead of the legacy direct
 `http://<host>:<container.port>/` TCP shape. The signal comes from
 `StateSnapshot.gateway_enabled`, sourced from the
-`HIVE_GATEWAY_ENABLED` env the c0re NixOS module sets when
-`services.hyperhive.gateway.enable = true`. Three render sites
+`HIVE_GATEWAY_ENABLED` env the c0re NixOS module now always sets
+(`services.hyperhive.gateway.enable` was removed — the gateway runs
+unconditionally alongside hyperhive), so this is effectively always
+true; the `false` branch is retained as a defensive fallback for the
+env being unset. Three render sites
 flip together: the primary agent-name link, the favicon fetch
 (`<url>/icon`), and the nav-strip `container`-kind links from
 `DashboardState.links` (`GET /api/dashboard-state`). `forge`-kind nav-strip links still
@@ -172,10 +175,10 @@ selected by which (if any) external TLS source is set:
 | ACME (Let's Encrypt) | `tls.acme.enable = true` | nginx via HTTP-01 | `https` |
 | operator cert | `tls.certDir` set | read from the operator's dir | `https` |
 
-The `gateway.selfSignedTls` option is **deprecated and ignored** — self-signed
-is now derived from the absence of `tls.certDir` / `tls.acme`. Setting it to
-`false` (which used to select http-only or force an external cert) warns and
-has no effect; use `tls.certDir` / `tls.acme` to override the default.
+The `gateway.selfSignedTls` option has been **removed** — self-signed
+is now derived from the absence of `tls.certDir` / `tls.acme`. A config
+that still sets it fails eval with a removal message; use `tls.certDir`
+/ `tls.acme` to override the default.
 
 ### ACME / Let's Encrypt (`tls.acme`)
 
@@ -271,16 +274,17 @@ always advertise `https` (see [Discovery flow](#discovery-flow-matrix) above).
 
 ## Firewall posture (host-level)
 
-`hive-c0re.nix` opens the per-agent web-port range
-`8100..8999` in the host firewall **only when
-`services.hyperhive.gateway.enable = false`**. With the gateway on
-(default) it's the sole external entry point and routes to agents over
-the UDS upstream described above (see [Per-agent unix-socket
-upstream](#per-agent-unix-socket-upstream)) — leaving the per-agent
-ports firewall-open would defeat the single-front-door story. The
-hashed TCP port (`lifecycle::agent_web_port`) still exists as a direct
-host-loopback fallback for the pre-UDS/gateway-disabled case, but isn't
-what the gateway itself proxies through.
+The gateway is unconditional — `services.hyperhive.gateway.enable` was
+removed, there is no gateway-off mode. nginx is always the sole
+external entry point and routes to agents over the UDS upstream
+described above (see [Per-agent unix-socket
+upstream](#per-agent-unix-socket-upstream)), so the per-agent web-port
+range `8100..8999` stays closed on the host firewall
+unconditionally — opening it would defeat the single-front-door story.
+The hashed TCP port (`lifecycle::agent_web_port`) still exists as a
+fallback bind for an agent whose `HIVE_WEB_SOCKET` env somehow ends up
+unset, but nothing opens a matching firewall hole for it and the
+gateway itself never proxies through it.
 
 `services.hyperhive.gateway.openFirewall = true` opens both `port` and
 `httpsPort` — both are always served, since the gateway always terminates
@@ -302,9 +306,10 @@ proxy in front.
 Agents poll `HIVE_FORGE_URL` for Forgejo notifications + run all
 `hive-forge` calls against it. Network isolation is always on (the
 shared-netns mode was removed), so agents run in a private netns and
-can never reach the host's loopback. `hive-c0re.nix` sets
-`HIVE_FORGE_URL` to `http://<forge.domain>` (default
-`forge.<hive-domain>`; `services.hyperhive.domain` is required). Agents
+can never reach the host's loopback.
+`nix/host-modules/hive-c0re/environment.nix` sets `HIVE_FORGE_URL` to
+`http://<forge.domain>` (default `forge.<swarm-domain>` — a swarm runs
+one forge; `services.hyperhive.domain` is required). Agents
 get the bridge dnsmasq as their resolver, resolve the hostname →
 bridge IP, then reach nginx on port 80 (the bridge firewall opens
 80+443). nginx proxies to forgejo — the same path an operator browser
@@ -376,14 +381,16 @@ covers most cases:
 
 | Shape | Auto-derived `ROOT_URL` |
 |---|---|
-| `behindGateway = true` | `http://<forge.domain>/` (port suffix omitted when `gateway.port == 80`) |
+| `behindGateway = true` | `https://<forge.domain>/` (port suffix omitted when `gateway.httpsPort == 443`) |
 | `behindGateway = false` | `http://<forge.domain>:<httpPort>/` |
 
-The auto-derivation always uses `http://`. Set `rootUrl` explicitly when
-you need `https://` (e.g. behind a TLS-terminating reverse proxy, or when
-clone URLs must carry `https://` because the gateway terminates TLS), or
-when `forge.domain` resolves differently from the public URL. Must end with
-`/` (Forgejo requirement; an assertion enforces this).
+The gateway always terminates TLS, so the `behindGateway = true` case is
+always advertised over `https://`; only the direct (`behindGateway =
+false`) shape stays `http://`. Set `rootUrl` explicitly when
+`forge.domain` resolves differently from the public URL, or for a
+genuinely bespoke shape (e.g. an external reverse proxy on a different
+host/path). Must end with `/` (Forgejo requirement; an assertion
+enforces this).
 
 ## Per-agent static frontend split
 

From fd891913b018c33408fd1efd3e3361fda3d85d54 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:14:39 +0200
Subject: [PATCH 51/64] docs(forge): fix stale config-PR framing and wrong
 timestamp-helper name

---
 docs/forge.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/forge.md b/docs/forge.md
index 0aa0f90c..bf109010 100644
--- a/docs/forge.md
+++ b/docs/forge.md
@@ -53,7 +53,10 @@ Two things live in the `agent-configs` Forgejo organization:
 
 - A config repo per agent (`agent-configs/<name>`). The
   agent is a **write collaborator on its own** repo — it can push
-  config-change branches and (once config-PR support lands) open config PRs — but
+  config-change branches and open config PRs (Forgejo `pull_request`
+  webhook at `/webhook/config-pr` queues a `MergeConfigPr` approval;
+  `hive-c0re/src/forge/config_pr_poll.rs` re-scans every 5 minutes as a
+  fault-tolerance backstop) — but
   `main` is branch-protected core-only: only hive-c0re's verify-and-ff-push
   merge handler lands on `main`, an operator-team approval is required, and
   the agent can neither push `main` directly nor self-merge. `main` is
@@ -289,7 +292,7 @@ subject's `created_at`. Anything later is labeled `activity on <kind>`
 activity was without an extra reviews fetch. Missing/unparseable
 timestamps default to `new` (preserve prior behavior rather than mask a
 genuine new item). Timestamps are parsed by a small dependency-free
-RFC 3339 → epoch-seconds helper (`parse_rfc3339_secs`).
+RFC 3339 helper (`parse_rfc3339`).
 
 Number is extracted from `subject.html_url`'s last path segment
 (strips `#anchor` first); repo slug from `repository.full_name`.

From af83a868e4283c35024149ec7e02e40daa469710 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:16:03 +0200
Subject: [PATCH 52/64] docs(knowledge): fix stale collaborator model and
 webhook delivery claims

---
 docs/knowledge.md | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/docs/knowledge.md b/docs/knowledge.md
index 7b1e8d39..a46c2a15 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -24,8 +24,9 @@ the local clone updates automatically (see
 ## Repository layout
 
 Canonical forge location: `internal/knowledge` (org `internal`,
-repo `knowledge`). Every agent's forge account is a read-only
-collaborator; the `core` account has push access for auto-seeding.
+repo `knowledge`). The repo is public, so every agent's forge account
+has read access without an explicit per-agent collaborator grant;
+only the `core` account has push access, for auto-seeding.
 
 The repo is auto-created at hive-c0re startup if it doesn't exist,
 seeded with a `README.md` containing a contribution guide and a
@@ -39,11 +40,12 @@ hive-c0re maintains the local clone at
 
 1. **Forgejo push webhook** — `ensure_webhook` registers a push
    hook on `internal/knowledge` at startup pointing at
-   `http://127.0.0.1:<dashboard_port>/webhook/knowledge`. On any
-   push to main (including merge commits) hive-c0re runs
-   `git pull` so agents see the new content on their next turn.
-   The endpoint is loopback-only; no signature verification is
-   needed.
+   `https://<hive_domain>/webhook/knowledge` (routed through the
+   gateway, avoiding the Forgejo SSRF guard that blocks loopback
+   delivery). On any push to main (including merge commits) hive-c0re
+   runs `git pull` so agents see the new content on their next turn.
+   The endpoint is protected by an auto-generated HMAC secret that
+   hive-c0re verifies on every delivery.
 
 2. **Periodic pull** — a background task in `hive-c0re::main`
    pulls on a fixed cadence as a fallback (webhook missed, c0re
@@ -89,9 +91,10 @@ token.
 
 ## Contributing
 
-Agents are read-only collaborators on `internal/knowledge`, so they
-can't push a branch directly. The supported path is Forgejo's **AGit
-flow** through the `hive-forge` CLI — no fork required.
+Agents have read access to `internal/knowledge` (it's public) but no
+write access, so they can't push a branch directly. The supported path
+is Forgejo's **AGit flow** through the `hive-forge` CLI — no fork
+required.
 
 1. Clone the repo (credentials are injected automatically; the `-r`
    flag selects the repo, the clone lands in `./knowledge`):
@@ -125,6 +128,6 @@ flow** through the `hive-forge` CLI — no fork required.
    running container sees the updated content within seconds (see
    [Sync mechanism](#sync-mechanism)).
 
-Do **not** try to `git push` a branch directly — read-only
-collaborator access rejects it. The `--agit` flow above is the
-no-fork path that works from any agent.
+Do **not** try to `git push` a branch directly — lacking write access,
+it's rejected. The `--agit` flow above is the no-fork path that works
+from any agent.

From 8361d3f6a1ad230c7554e86e05dce2c65583018b Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:17:53 +0200
Subject: [PATCH 53/64] docs(ci): fix stale nix option namespace and
 ensure_mirrors file path

---
 docs/ci.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/ci.md b/docs/ci.md
index 7b414467..6c6e4e2e 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -5,7 +5,7 @@ executing CI jobs from `.forgejo/workflows/ci.yml` on every PR.
 
 ## For operators
 
-**Enabling it is one line**: `services.hyperhive.forge.ci.enable = true`
+**Enabling it is one line**: `services.hyperhive.swarm.forge.ci.enable = true`
 in the host NixOS config. No manual token provisioning — hive-c0re
 registers the runner with the forge automatically.
 
@@ -74,9 +74,9 @@ slow); run those manually before pushing Rust changes.
 
 The internal forge is always present (mandatory), so the runner always has a
 hive-forge instance to register against — nothing extra to enable beyond
-`services.hyperhive.forge.ci.enable = true` (see *For operators* above).
+`services.hyperhive.swarm.forge.ci.enable = true` (see *For operators* above).
 
-Optional tuning: `services.hyperhive.forge.ci.name` (runner name in forge
+Optional tuning: `services.hyperhive.swarm.forge.ci.name` (runner name in forge
 admin panel), `concurrency` (parallel job capacity), `labels` (workflow
 targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration
 string e.g. `"3h"` — a job that exceeds it is killed so a hung or runaway
@@ -126,7 +126,7 @@ When `forge.ci.enable` is set, hive-c0re auto-seeds an
 external DNS on the CI critical path.
 
 The mirror is seeded by **hive-c0re** itself during its forge
-provisioning sweep (`forge.rs::ensure_mirrors`). The nix module
+provisioning sweep (`forge/repos.rs::ensure_mirrors`). The nix module
 forwards the effective mirror list as `HYPERHIVE_FORGE_MIRRORS` in the
 `hive-c0re` service environment (JSON-encoded `[{upstream, dest}]`
 list). hive-c0re already holds the admin token for the rest of the
@@ -134,10 +134,10 @@ forge provisioning sweep (orgs, agent accounts, etc.), so mirror
 seeding lives in the same place rather than a separate host-side unit.
 
 **General-purpose mirrors**: you can pre-seed any external repo as a
-pull-mirror via `services.hyperhive.forge.mirrors`:
+pull-mirror via `services.hyperhive.swarm.forge.mirrors`:
 
 ```nix
-services.hyperhive.forge.mirrors = [
+services.hyperhive.swarm.forge.mirrors = [
   { upstream = "https://github.com/actions/checkout"; dest = "actions/checkout"; }
   { upstream = "https://github.com/example/tool";    dest = "mirrors/tool"; }
 ];

From cfb50d8a403dca8d011a6e7bd9b99b019c0b2821 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:17:53 +0200
Subject: [PATCH 54/64] docs(forge): fix stale nix option namespace
 (services.hyperhive.swarm.forge)

---
 docs/forge.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/forge.md b/docs/forge.md
index bf109010..51e8c7cb 100644
--- a/docs/forge.md
+++ b/docs/forge.md
@@ -2,7 +2,7 @@
 
 Private Forgejo instance running in a nixos-container, used as the
 swarm's persistent code-collaboration surface (issues, PRs, reviews,
-attachments). Configured via `services.hyperhive.forge.*`. Container
+attachments). Configured via `services.hyperhive.swarm.forge.*`. Container
 shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
 handling live in [`docs/gateway.md`](gateway.md); this file owns the
 per-agent integration story and the notification pump that wakes

From f5182d68046b91a6a3b9777828e88269a1588ed1 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:18:59 +0200
Subject: [PATCH 55/64] docs(swarm): fix authelia's default vhost domain,
 verified against swarm-authelia.nix

---
 docs/swarm/services.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/swarm/services.md b/docs/swarm/services.md
index bcc64252..94ef096e 100644
--- a/docs/swarm/services.md
+++ b/docs/swarm/services.md
@@ -30,7 +30,7 @@ and has no `enable` to derive from anything.
 ### SSO (authelia)
 
 One authelia per swarm, in a `swarm-authelia` container, at
-`auth.<hive-domain>`. Operator and agents are both subjects of the same
+`auth.<swarm-domain>`. Operator and agents are both subjects of the same
 provider, differentiated by roles and claims rather than by mechanism —
 there is one IdP and one auth path.
 

From 3b24d08226e40d09738bb2f4c11a48ecb583e805 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:18:59 +0200
Subject: [PATCH 56/64] docs(swarm): fix stale four-wiring-sites table,
 verified against hive-gateway modules

---
 docs/swarm/ui.md | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md
index 0bb73bcc..4835d0d5 100644
--- a/docs/swarm/ui.md
+++ b/docs/swarm/ui.md
@@ -61,17 +61,25 @@ not a hole: **reachability is not the access control here.** An agent
 that resolves the name and connects still has no operator session, and
 the subrequest denies it.
 
-## Four wiring sites
+## Two wiring sites
 
-Adding a swarm service name means touching all four. Missing one ships as
-a different flavour of "works from the host, broken from a container":
+Adding a swarm service name means touching two things. Missing the
+second ships as a different flavour of "works from the host, broken from
+a container":
 
 | site | file |
 | --- | --- |
-| vhost | `nix/host-modules/hive-gateway/vhosts.nix` |
+| vhost + `gateway.localNames` | the service's own module (e.g. `nix/host-modules/swarm-ui.nix`) |
 | **certificate name** | `nix/host-modules/swarm.nix` (`serviceDomains`) |
-| DNS record | `nix/host-modules/hive-gateway/dnsmasq.nix` |
-| local-dev hosts | `nix/host-modules/hive-gateway/default.nix` |
+
+The DNS record and the local-dev `/etc/hosts` entry need no separate
+edit: both are derived from `services.hyperhive.gateway.localNames`,
+which a service's own module already has to push its domain into to be
+resolvable — see `nix/host-modules/hive-gateway/dnsmasq.nix` and
+`.../default.nix`'s `networking.hosts`. `vhosts.nix` itself is scoped to
+the surface the hive's own domain serves (dashboard, per-agent routing,
+matrix discovery); a swarm service declares its own vhost next to its
+own options, the way `swarm-ui.nix` and `swarm-authelia.nix` do.
 
 ⚠️ The certificate one is the least obvious and the most visible when
 missed. `serviceDomains` is *both* the services sub-CA's

From 90be37c0c8d62876a08ee220d947fabd40b0723d Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:19:02 +0200
Subject: [PATCH 57/64] docs(swarm): fix stale hivectl peer-config claim,
 verified against hivectl/src/wg.rs

---
 docs/swarm/ca.md | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md
index 5db8d4e8..45b2c39c 100644
--- a/docs/swarm/ca.md
+++ b/docs/swarm/ca.md
@@ -76,26 +76,29 @@ sign leaves, and the chain stops there.
 
 ## What to hand a peer
 
-`hivectl peer-config` prints the `cp` line. The file is
-`<tls.stateDir>/trust-bundle.pem` — the hive CA plus the swarm root —
-**not `ca.pem`**.
+`hivectl peer-config` prints the `services.hyperhive.swarm.hives."<name>"`
+block a peer operator pastes into their own config. When this hive's
+gateway serves a self-signed leaf under the hierarchy (detected by the
+presence of `<tls.stateDir>/trust-bundle.pem`), it also prints a one-time
+`scp` line installing the **swarm root** —
+`<swarm.ca.stateDir>/root.pem`, not this hive's own CA — on the peer's
+host:
 
-The distinction is load-bearing rather than cosmetic: once a hive CA is
-an intermediate, it is no longer something a verifier can build a chain
-*to*. OpenSSL will not terminate a chain at a trusted non-self-signed
-certificate without `-partial_chain`, so handing a peer the bare
-intermediate produces a verification failure that reads like a bad cert
-rather than like a missing anchor. The bundle carries both, so the same
-file works whichever mode issued it.
+```
+scp /var/lib/swarm-ca/root.pem <peer-host>:/var/lib/swarm-ca/root.pem
+```
 
-On a hive that predates the swarm root the bundle is just that hive's
-self-signed CA, so the recipe does not change.
+That is the point of the hierarchy: the root is installed **once per
+swarm host**, not once per peer, so a hive joining later needs no edit on
+the hives already running. A hive whose cert already chains to a public
+CA has nothing to install — `peer-config` says so instead.
 
-⚠️ Consumers must read `trust-bundle.pem`, never `ca.pem` directly. A
-consumer that reads `ca.pem` works fine on a hive that has always been
-self-signed and breaks the moment that hive adopts the hierarchy — so
-the failure is invisible on the deployment you are most likely to test
-on.
+Handing a peer this hive's own `ca.pem` would not work even as a
+one-off: once a hive CA is an intermediate under the swarm root, it is
+no longer something a verifier can build a chain *to* — OpenSSL will not
+terminate a chain at a trusted non-self-signed certificate without
+`-partial_chain`. That is why the tool distributes the root, not a
+per-hive file.
 
 ## Adopting the hierarchy on an existing hive
 

From a17cc3612b7eb5a09b3d5a25ff81d09265e99405 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:24:53 +0200
Subject: [PATCH 58/64] =?UTF-8?q?docs(persistence):=20fix=20stale=20facts?=
 =?UTF-8?q?=20=E2=80=94=20reminders/todos=20moved=20in-container,=20vacuum?=
 =?UTF-8?q?=20ownership,=20topology=20writer,=20matrix=20glob,=20qgroup=20?=
 =?UTF-8?q?quotas=20shipped?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/persistence.md | 123 +++++++++++++++++++++++++++-----------------
 1 file changed, 77 insertions(+), 46 deletions(-)

diff --git a/docs/persistence.md b/docs/persistence.md
index dda2a6be..679b2dd3 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -40,20 +40,23 @@ schemas, file layouts, and internal migration mechanics.
 
 ### `/var/lib/hyperhive/db/broker.sqlite` (host)
 
-Seven tables, all in one file — four queues, the schedule
-header/targets split, and the per-agent power-intent registry:
+Seven tables, all in one file — three queues, a small key/value
+table, the schedule header/targets split, and the per-agent
+power-intent registry:
 
 - `messages` — every inter-agent / operator-bound message.
   `sender / recipient / body / sent_at / delivered_at / acked_at /
-  in_reply_to`. `in_reply_to` links a reply to its parent row id;
-  the dashboard and per-agent inbox render these as threaded rows.
-- `reminders` — `mcp__hyperhive__remind` queue.
-  `agent / message / file_path / due_at / created_at / sent_at /
-  attempt_count / last_error`. `file_path` set when a body
-  exceeded the inline soft-cap and got auto-spilled to a file
-  under the agent's state dir; the worker delivers a short
-  pointer instead. `attempt_count` / `last_error` accumulate
-  on delivery-failed retries.
+  in_reply_to / priority`. `in_reply_to` links a reply to its parent
+  row id; the dashboard and per-agent inbox render these as threaded
+  rows.
+- `kv` — small persistent key/value store (`key PK / value`) for
+  host-side bookkeeping that doesn't warrant its own table.
+
+  ⚠️ The `mcp__hyperhive__remind` queue is **not** here any more: it
+  moved to a harness-local, per-agent store as part of the
+  loose-ends-v2 migration — see [`/harness/` contents
+  below](#state-dirs-per-agent) for where reminders (and todos, and
+  the questions mirror) actually live now.
 - `approvals` — the queue. `agent / kind (merge_config_pr | spawn |
   init_config | update_meta_inputs | schedule_prompt) /
   commit_ref / requested_at / status / resolved_at / note`.
@@ -98,8 +101,6 @@ Retention:
 - Approvals and questions are kept indefinitely — both are
   audit trails. `actions::destroy` and answered questions stay
   visible to anything that queries by id.
-- Reminder rows are kept after `sent_at` is set (audit trail);
-  no automatic vacuum today.
 - Scheduled prompts: one-shot rows are deleted on fire by the
   worker; recurring rows live until the operator cancels them
   (`cancel_schedule` MCP / dashboard ✗) which tombstones via
@@ -117,20 +118,26 @@ One table:
 - `events(id, ts, kind, payload_json)` — every `LiveEvent` the
   harness emits during turn loop execution.
 
-The harness writes; the host vacuums. `hive-c0re::events_vacuum`
-runs hourly and sweeps every existing agent harness dir. Retention
-is **type-scoped**: it deletes only the verbose `stream` rows (the
-raw claude `stream-json` deltas — one per text chunk / tool use, the
-bulk of the file's size) older than 14 days, and keeps every other
-kind (`turn_start`, `turn_end`, `note`, `status_changed`,
-`model_changed`, `token_usage_changed`, `turn_state_changed`)
-indefinitely — those are small and carry the semantic per-turn
-history the operator scrolls back through when debugging a
-regression. Age-only within the `stream` kind — no row cap — so a
-chatty turn doesn't lose its stream history sooner than a quiet one.
-Centralising retention on the host means a misbehaving harness can't
-disable its own vacuum and agents don't need any cleanup wiring of
-their own.
+The harness both writes and vacuums it — this used to be a host-side
+sweep, but hive-c0re runs as the unprivileged `hive-core` user under
+privsep and can't delete agent-owned files (host-side deletes hit
+`PermissionDenied` on the bash-task trio and a readonly-database error
+here), so cleanup moved in-container. `hive-agent`'s `vacuum::run`
+(`hive-agent/src/vacuum.rs`) sweeps hourly. Retention is
+**type-scoped**: it deletes only the verbose `stream` rows (the raw
+claude `stream-json` deltas — one per text chunk / tool use, the bulk
+of the file's size) older than 14 days, and keeps every other kind
+(`turn_start`, `turn_end`, `note`, `status_changed`, `model_changed`,
+`token_usage_changed`, `turn_state_changed`) indefinitely — those are
+small and carry the semantic per-turn history the operator scrolls
+back through when debugging a regression. Age-only within the
+`stream` kind — no row cap — so a chatty turn doesn't lose its stream
+history sooner than a quiet one. The trade-off (accepted): a
+misbehaving harness could now skip its own cleanup, which the old
+host-side sweep was meant to prevent — but a compromised harness is
+already inside the container trust boundary
+([`docs/security.md`](security.md)), and these are ephemeral local
+artifacts, so cleaning them up where they live is the honest fix.
 
 Path overridable via `HYPERHIVE_EVENTS_DB` (for dev / no-`/harness`
 setups). On open failure the `Bus` falls back to no-store mode
@@ -211,11 +218,15 @@ the actual failure and leave only the host journal holding the
 complete output. With this table the dashboard can surface the entire
 log.
 
-Two indices:
+Three indices:
 - `(agent, started_at)` — backs the per-agent latest-N lookup used
   by the agent card chip.
 - `(status, finished_at)` — backs the retention sweep that runs
   as part of the existing hourly vacuum.
+- `(node_id)` — added by a later migration so a build log row can be
+  looked up by the job-queue node it belongs to (a `hive_jobq` node is
+  immutable after insert, so the link is recorded on the log row
+  instead); legacy rows predating the column keep `node_id IS NULL`.
 
 Writes are best-effort: `append_stdout` / `append_stderr` / `finish`
 log a warning on sqlite error and let the build continue. A failed
@@ -239,7 +250,7 @@ and inbox messages queue unacked until it's removed (see
 
 Unusually, it's read and written from **both** sides of the harness
 bind-mount, and that's the whole design: the harness stats it
-in-container via `hive_agent::paths::paused_marker`, while hive-c0re
+in-container via `hive-agent`'s `paths::paused_marker`, while hive-c0re
 stats it on the host (`Coordinator::is_paused`) to populate the
 `paused` field on the agent card, and creates/removes it
 (`Coordinator::set_paused`) for `hivectl agent <name> pause|resume` and the
@@ -284,15 +295,26 @@ Under `/var/lib/hyperhive/agents/<name>/`:
   - `bash-tasks/` — task JSON + stdout/stderr files for
     background `mcp__bash__run` jobs. JSON files are
     `<id>.json` (status + tails), `<id>.out` / `<id>.err`
-    (full captured output). `hive-c0re::bash_tasks_vacuum` runs
-    hourly and deletes terminal task trios older than 48 hours;
-    non-terminal (still-running) tasks are never deleted by vacuum.
-  - `hyperhive-todos.sqlite` — loose-ends-v2 todo store. In-container
-    daemons (`hive-bash-daemon`, `hive-matrix-daemon`, `hive-forge-notify`)
-    upsert keyed todos here over the harness's in-agent socket
-    (`HIVE_AGENT_SOCKET`); the harness merges them into `get_loose_ends`
-    output and clears a row on `mark_todo_done`. Replaced the old
-    file-based `mcp-loose-ends/` scanner.
+    (full captured output). The harness's own hourly sweep
+    (`hive-agent`'s `vacuum::run`, same one that ages out `stream`
+    event rows above) deletes terminal task trios older than 48
+    hours; non-terminal (still-running) tasks are never deleted. This
+    used to be a host-side `hive-c0re` vacuum, moved in-container for
+    the same privsep-ownership reason as the events vacuum above.
+  - `hyperhive-state.sqlite` — consolidated loose-ends-v2 store: todos,
+    reminders, and a questions mirror, one small table each in a single
+    file (in-container daemons — `hive-bash-daemon`, `hive-matrix-daemon`,
+    `hive-forge-notify` — upsert keyed todos here over the harness's
+    in-agent socket, `HIVE_AGENT_SOCKET`; the harness merges them into
+    `get_loose_ends` output and clears a row on `mark_todo_done`).
+    Replaces three formerly-separate files
+    (`hyperhive-todos.sqlite`, `hyperhive-reminders.sqlite`, and the
+    old file-based `mcp-loose-ends/` scanner before that) — a one-time
+    boot migration (`db_migrate::run`) folds the legacy files into this
+    path the first time a harness boots after the upgrade. Also backs
+    the `mcp__hyperhive__remind` queue, which moved from a host-side
+    `broker.sqlite` table to this per-agent store as part of the same
+    migration.
 
     The harness itself is also a producer, not just the socket server:
     boot wiring's `spawn_todo_socket` starts `todo_server::run` (the
@@ -358,8 +380,11 @@ Contents:
   audit trail (one commit per successful deploy or hyperhive bump).
 - `topology.json` — parent/child agent graph
   (`{ "alice": "root", "bob": "alice", "root": null }`).
-  Written by `topology::set_parent`; read by the dashboard, the
-  renderer, and `<parent>` / `<children>` recipient resolution.
+  Written by `topology::apply_set_parent` (the pure move-validating
+  transform) via `meta::bulk_commit_topology` (the committer — see the
+  `Reparent` node in [`docs/coordinator.md`](coordinator.md)); read by
+  the dashboard, the renderer, and `<parent>` / `<children>` recipient
+  resolution.
 - `tool-groups.json` — per-agent MCP tool group grants
   (`{ "alice": ["messaging", "inbox", "execution"] }`). Written by
   `tool_groups::set_groups`; injected as `HIVE_TOOL_GROUPS` env
@@ -431,8 +456,12 @@ until an explicit opt-in upgrade.
   actually a subvolume, then the normal `remove_dir_all` sweep covers
   plain-dir agents + the applied dir.
 
-Per-subvolume disk-usage accounting and optional quotas are a
-follow-up (the qgroup work), not part of the base migration.
+Per-subvolume disk-usage accounting and optional quotas have since
+landed as the qgroup work: `hivectl quota-enable` turns on btrfs
+qgroup accounting hive-wide (opt-in, no-op on non-btrfs hosts), and
+`hivectl agent <name> quota show|set` reads/limits one agent's
+subvolume usage through the same hive-priv-mediated path as
+subvolume creation/deletion above.
 
 This is the same subvolume `hivectl agent <name> subvol snapshot push`
 sends to the swarm's snapshot store — see
@@ -506,10 +535,12 @@ auto-injected `extraMcpServers.matrix` entry read).
 **First-boot ordering**: hive-c0re provisions the matrix token AFTER
 agent containers come up. Without the path-trigger sibling
 (`systemd.paths.hive-matrix-daemon`, `PathExistsGlob =
-/agents/*/state/matrix-token`), the daemon would exit 0 quietly the
-first time it ran and the MCP would have no backend until the next
-restart. The `.path` unit makes the appearance of the token re-fire
-the service so the daemon comes alive in the same boot cycle as
+/agents/*/state/matrix-token*` — the trailing `*` also catches a
+secondary multi-account token like `matrix-token-ccc`), the daemon
+would exit 0 quietly the first time it ran and the MCP would have no
+backend until the next restart. The `.path` unit makes the appearance
+of the token re-fire the service so the daemon comes alive in the
+same boot cycle as
 provisioning. The same token watcher also drives avatar setting: on a
 restart the daemon re-runs each account's bring-up, which sets the
 avatar (see below).

From 62f3cc4b1926034d5eb83e22b6d2032d814866d7 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:24:53 +0200
Subject: [PATCH 59/64] docs(coordinator): fix stale DAG-history cap, wire
 request name, infra container list

---
 docs/coordinator.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/coordinator.md b/docs/coordinator.md
index 893cb908..9e231eb4 100644
--- a/docs/coordinator.md
+++ b/docs/coordinator.md
@@ -174,7 +174,7 @@ without a row are seeded from observed state on first touch (running ⇒
 `Up`); destroy removes the row.
 
 The admin-socket responses carry the submitted DAG ids; `hivectl` polls
-`HostRequest::QueueDag` (~1s) and prints a progress line per DAG — roll-up
+`HostRequest::QueueNodes` (~1s) and prints a progress line per DAG — roll-up
 glyph, template, agent, node chain — so
 CLI verbs block until their jobs finish (`--no-wait` opts out; failures exit
 non-zero). Nodes appended in-DAG (a `MetaLock` growing per-agent rebuild
@@ -259,8 +259,9 @@ whether any dedup needs reintroducing is tracked as a follow-up.
 Cancel only applies to still-fully-queued DAGs (an in-flight nix build isn't
 interruptible) — each op is one DAG now, so there are no child DAGs to cascade to.
 Roll-up state: `Failed` if any node failed, else `Running` / `Queued` /
-`Cancelled` / `Done`. The snapshot retains the 5 most recent terminal DAGs
-per template.
+`Cancelled` / `Done`. The snapshot retains the 50 most recent terminal
+DAGs — a flat cap over the whole sorted list, not per template, since
+the dashboard renders one recent-builds list and one number bounds it.
 
 ### Approvals
 
@@ -500,8 +501,8 @@ Two things to know about the weights:
   same value and the weight does *not* rank agents against each other.
   What `80` buys is that agents yield to everything **not** on this
   drop-in path: host services (nginx and dnsmasq among them) and the
-  infra containers (`hive-ci`, `hive-forge`, `hive-matrix`), which stay
-  at the kernel default of `100`.
+  infra containers (`hive-ci`, `hive-forge`, `hive-gateway`,
+  `hive-matrix`), which stay at the kernel default of `100`.
 - `IOWeight=` is only honoured when the backing device runs the BFQ
   scheduler or has blk-iocost QoS enabled. On a host using
   `none`/`mq-deadline`/`kyber` without iocost, systemd writes the value

From 1cc1ace6815048ec88c07099fe848a8386036f57 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:27:02 +0200
Subject: [PATCH 60/64] docs(approvals): fix stale internal refs verified
 against source

- meta::sync_agents signature (now takes &HiveEnv, not 3 loose params)
- lifecycle.rs -> lifecycle/host_config.rs bare-file ref
- nixosConfigurations.manager -> .ruth (no 'manager' name in flake.nix)
- manager socket path/owner: no /run/hyperhive/manager/ or manager_server,
  it's socket_server::start_manager on the standard per-agent runtime dir
- Spawn approval also fires ApprovalResolved (finish_approval always does,
  for every kind), not push_todo instead of a HelperEvent
- /agents/<n>/applied.git -> /applied/<n>/.git (matches the actual RO bind)
- lifecycle::rebuild / auto_update::rebuild_agent don't exist anymore;
  the reconcile verb is job_queue::templates::rebuild
---
 docs/approvals.md | 47 +++++++++++++++++++++++++++--------------------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/docs/approvals.md b/docs/approvals.md
index c3258656..8afa0bd2 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -343,9 +343,10 @@ and `meta::lock_update_hyperhive()` for the
 auto-update flake-rev bump (one shot before per-agent
 rebuilds, commits if the lock changed).
 
-`meta::sync_agents(hyperhive_flake, dashboard_port, &agents)`
-is the idempotent reconciler called by `spawn`, `destroy`,
-`rebuild`, and the startup migration. Renders `flake.nix`
+`meta::sync_agents(hive: &HiveEnv, agents: &[AgentSpec])` — `hive`
+carries `hyperhive_flake`, `dashboard_port`, and the rest of the
+per-hive config — is the idempotent reconciler called by `spawn`,
+`destroy`, `rebuild`, and the startup migration. Renders `flake.nix`
 from the agent list; if it differs from disk, runs
 `nix flake lock` + commits as `regenerate meta flake` (or
 `seed meta from N agent(s)` on the very first call).
@@ -489,8 +490,9 @@ approval card. See `docs/web-ui.md`.
 ### Submitting agent's view of config repos
 
 Every parent agent's container has its **direct children's** config
-repos bind-mounted **read-only** (topology-driven: `lifecycle.rs` calls
-`bind_child_agent_dirs` for each entry in
+repos bind-mounted **read-only** (topology-driven:
+`hive-c0re/src/lifecycle/host_config.rs` calls `bind_child_agent_dirs`
+for each entry in
 `topology::children_of(agent_name)`). It is a copy to *read* a child's
 current config — not an editing surface.
 
@@ -566,7 +568,7 @@ same as any other agent.
 
 Differences from sub-agents:
 
-- `flake.nix` extends `hyperhive.nixosConfigurations.manager`
+- `flake.nix` extends `hyperhive.nixosConfigurations.ruth`
   (vs `agent-base`).
 - Web UI port via `lifecycle::agent_web_port("ruth")` — same
   FNV-1a hash as every other agent (8100..8999 range).
@@ -577,8 +579,10 @@ Differences from sub-agents:
   authoritative applied repo (see "Root-agent view of applied" below).
 - First-deploy spawn bypasses the approval queue (the root agent is
   required infrastructure).
-- Per-agent socket lives at `/run/hyperhive/manager/`, owned by
-  `manager_server::start`.
+- The root agent's socket is bound by `socket_server::start_manager`,
+  pure transport with no dedicated helpers — it uses the same
+  per-agent runtime dir as any other agent (`/run/hyperhive/agents/ruth/`),
+  not a special manager-only path.
 
 **Migration note** (for older hosts): drop any `containers.root =
 { ... }` block from your host NixOS config. hyperhive creates and
@@ -605,13 +609,16 @@ rules, `ttl_seconds` expiry, and cancellation.
 `Coordinator::notify_submitter(approval_id, &HelperEvent)` routes the
 event to the agent that originally submitted the approval (looked up from
 the `submitter` column on the `approvals` table). The harness delivers it
-as a regular `system` inbox message so it drives a normal claude turn. A
+as a regular `system` inbox message so it drives a normal claude turn.
+`finish_approval` fires an `ApprovalResolved` HelperEvent this way for
+**every** approval kind's terminal state, `Spawn` included. A
 "FYI, check when convenient" event doesn't need a message — those go
 through `Coordinator::push_todo`/`push_todo_submitter` instead, a direct
 live dial of the target agent's in-container todo socket (same
-`UpsertTodo` request in-container producers use); the `Spawn` approval
-uses this path, not a `HelperEvent`. Legacy approval rows that predate the
-submitter column fall back to the
+`UpsertTodo` request in-container producers use); `finish_approval` fires
+one of these too for `InitConfig`/`Spawn`/`MergeConfigPr`, *in addition to*
+the `ApprovalResolved` HelperEvent above, not instead of it. Legacy
+approval rows that predate the submitter column fall back to the
 root agent. Variants (`hive_sh4re::manager::HelperEvent`):
 
 - `ApprovalResolved { id, agent, commit_ref, status, note }` —
@@ -651,10 +658,10 @@ hive-c0re-vouched commit sha. Optional `tag` carries the deploy
 bookkeeping tag — `deployed/<id>` on a successful build or
 `failed/<id>` on a failed one, planted by the `MergeConfigPr` deploy.
 Both fields are `Option`: `None` on the paths that don't deploy a new
-commit (spawn / init_config / meta-update / deny, and
-`auto_update::rebuild_agent` reapplying the existing main, or the
-dashboard `↻ R3BU1LD` button when the lock didn't move). When set,
-`git show <sha>` against `/agents/<n>/applied.git` inside the
+commit (spawn / init_config / meta-update / deny, and the auto-update
+sweep's `job_queue::templates::rebuild` reapplying the existing main,
+or the dashboard `↻ R3BU1LD` button when the lock didn't move). When set,
+`git show <sha>` against `/applied/<n>/.git` inside the
 bootstrap container yields the exact tree that was referenced.
 
 To add a new lifecycle notice: if it needs to drive an immediate turn
@@ -669,8 +676,8 @@ no new wire type needed.
 `hive-c0re serve` runs `auto_update::run` in a background task right
 after opening the coordinator. It enumerates managed containers and
 rebuilds any whose recorded hyperhive rev differs from the current
-one — sub-agents and the root agent go through the same `lifecycle::rebuild`
-path.
+one — sub-agents and the root agent go through the same
+`job_queue::templates::rebuild` DAG.
 
 "Rev" = canonical filesystem path of `cfg.hyperhiveFlake`. Marker
 file: `/var/lib/hyperhive/applied/.<name>.hyperhive-rev`. If the
@@ -679,8 +686,8 @@ auto-update is a no-op — rebuild manually.
 
 The dashboard surfaces pending updates per agent: a clickable
 "needs update ↻" badge appears whenever the marker differs from
-current rev. The badge POSTs `/api/rebuild/<name>`, calling the same
-`auto_update::rebuild_agent` path so manual triggers and the
+current rev. The badge POSTs `/api/rebuild/<name>`, which inserts the
+same `job_queue::templates::rebuild` DAG so manual triggers and the
 startup scan can't drift. When at least one container is stale, a
 top-level `↻ UPD4TE 4LL` button appears that loops over every
 stale container.

From c870e230bf9717b95edd3ef206dec13c16b9e821 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:27:08 +0200
Subject: [PATCH 61/64] docs(conventions): fix stale internal refs verified
 against source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- MAX_AGENT_NAME lives in lifecycle/mod.rs, not bare lifecycle.rs
- agent_server::handle_send -> socket_server::handle_send (no agent_server
  module exists)
- AgentMeta response is missing matrix_accounts in the field list
- tool-group table missing list_containers/ack_until (added since written)
  and the forge/web_tools groups entirely
- #[tool] fns live on AgentServer in hive-agent-mcp/src/mcp/mod.rs, not a
  HiveServer in a nonexistent hive-ag3nt/src/mcp.rs; ToolGroup::tools()
  lives in hive-sh4re/src/permissions.rs, not lib.rs
- Capability + as_str also moved to permissions.rs; capability-check
  handler list was stale (agent_server.rs/mcp.rs don't exist)
- async-forms listener is bindAsyncForms in frontend/packages/shared,
  not assets/tabs.js + assets/app.js
- 'rebuild is the reconcile verb' described a monolithic lifecycle::rebuild
  that no longer exists — it's job_queue::templates::rebuild building a DAG,
  and flake.nix is no longer regenerated host-side on rebuild at all
---
 docs/conventions.md | 55 ++++++++++++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/docs/conventions.md b/docs/conventions.md
index 839d6eaa..8c156d30 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -8,7 +8,7 @@ exist because something already went wrong without them.
 - 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 `lifecycle.rs` enforces the cap.
+- `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
   `cfg.dashboardPort` (default 7000).
@@ -83,7 +83,7 @@ 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
-  (`agent_server::handle_send` fans out via `Coordinator::broadcast_send`).
+  (`socket_server::handle_send` fans out via `Coordinator::broadcast_send`).
 - `operator` — the human at the dashboard. Messages accumulate in the
   inbox view; no agent ever `recv`'s them.
 - `<parent>` — the sender's parent per `topology.json`. Rewritten at
@@ -93,7 +93,7 @@ angle-bracket and asterisk shapes below are structurally safe.
   their parent without learning the label, so runtime reparenting
   propagates with zero agent-side restart.
 - `<children>` — fan-out to every direct descendant of the sender per
-  `topology.json`. Resolved in `agent_server::handle_send` via
+  `topology.json`. Resolved in `socket_server::handle_send` via
   `topology::children_of(sender)`: one message is delivered to each
   child, bypassing the allow-list check (structural fan-out targets are
   never user-listed peers). No-op for leaf agents (returns `Ok` when the
@@ -279,7 +279,7 @@ an agent. Self-introspection when `name = None` (replaces the older
 `Whoami` request); target query when `name = Some`.
 
 Response is `AgentMeta { name, running, hyperhive_rev,
-status_text, status_set_at, hive_name, swarm_name }`:
+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
@@ -299,6 +299,9 @@ status_text, status_set_at, hive_name, swarm_name }`:
   `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
 
@@ -323,14 +326,16 @@ binary flavor.
 
 | Group | Tools |
 |---|---|
-| `messaging` | `send`, `recv`, `ask`, `answer` |
+| `messaging` | `send`, `recv`, `ack_until`, `ask`, `answer` |
 | `meta` | `get_agent_meta` (`set_status` is always-on, see below) |
 | `inbox` | `get_loose_ends`, `cancel_loose_end`, `remind` |
 | `execution` | vestigial — `mcp__bash__run` / `mcp__bash__status` are always available unconditionally via `extraMcpServers`; this group's entries expand to non-existent `mcp__hyperhive__run` / `mcp__hyperhive__status` and have no effect. See `docs/tools/bash.md`. |
-| `lifecycle` | `kill`, `start`, `restart`, `update` *(privileged)* |
+| `lifecycle` | `kill`, `start`, `restart`, `update`, `list_containers` *(privileged)* |
 | `approvals` | `request_init_config`, `request_update_meta_inputs` *(privileged)* |
 | `scheduling` | `request_schedule_prompt`, `fire_schedule_now`, `cancel_schedule`, `edit_schedule`, `list_schedules` *(privileged)* |
 | `diagnostics` | `get_logs` *(privileged)* |
+| `forge` | `create_repo` — create git repos through hive-c0re (operator-gated merge) |
+| `web_tools` | none (gates the Claude built-ins `WebFetch`/`WebSearch`, not an MCP tool) |
 
 **Always-on tools** — `set_status`, `compact`, and `mark_todos_done` are
 exposed to every agent regardless of which groups it holds
@@ -363,10 +368,10 @@ from `tool-groups.json`). Unrecognised tokens are logged and skipped. Falls back
 to `ToolGroup::AGENT_DEFAULT` (`messaging`, `meta`, `inbox`, `execution`) when
 the var is absent or empty.
 
-**Updating the surface** — when a new `#[tool]` fn is added to `HiveServer`
-in `hive-ag3nt/src/mcp.rs`, add its name to the matching `ToolGroup::tools()`
-slice in `hive-sh4re/src/lib.rs`. That's the single source of truth;
-`mcp_config::allowed_mcp_tools` (in `hive-ag3nt/src/mcp_config.rs`) reads it at
+**Updating the surface** — when a new `#[tool]` fn is added to `AgentServer`
+in `hive-agent-mcp/src/mcp/mod.rs`, add its name to the matching `ToolGroup::tools()`
+slice in `hive-sh4re/src/permissions.rs`. That's the single source of truth;
+`mcp_config::allowed_mcp_tools` (in `hive-agent/src/mcp_config.rs`) reads it at
 session start.
 
 ## Capabilities
@@ -406,15 +411,18 @@ groups: an agent that could grant its own capabilities via a config commit would
 bypass the operator approval gate.
 
 **Adding a new capability** — add a variant to `Capability` in
-`hive-sh4re/src/lib.rs` + an arm to `as_str`. Add it to `Capability::ALL` (the
-source of truth for the permissions UI columns). Implement the access check in
-the relevant handler (`agent_server.rs`, `mcp.rs`, or a handler under
-`hive-c0re/src/dashboard/`).
+`hive-sh4re/src/permissions.rs` + an arm to `as_str`. Add it to `Capability::ALL`
+(the source of truth for the permissions UI columns). Implement the access
+check in the relevant handler (`hive-c0re/src/socket_server/mod.rs`,
+`hive-c0re/src/socket_server/lifecycle_handlers.rs`, `coordinator.rs`, or a
+handler under `hive-c0re/src/dashboard/`).
 
 ## Async forms
 
-Dashboard + per-agent mutating forms carry `data-async`; a delegated
-`submit` listener in `assets/tabs.js` (+ `assets/app.js` for the per-agent UI) intercepts, shows a spinner,
+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
@@ -429,11 +437,16 @@ via `snapshotOpenDetails` / `restoreOpenDetails`.
 
 ## `rebuild` is the reconcile verb
 
-`lifecycle::rebuild` idempotently rewrites
-`/etc/nixos-containers/<C>.conf` (`PRIVATE_NETWORK=0`, clears
-`HOST_ADDRESS` / `LOCAL_ADDRESS`, sets `EXTRA_NSPAWN_FLAGS`),
-regenerates `applied/<name>/flake.nix`, writes the systemd limits
-drop-in, then `nixos-container update` + stop + start.
+`job_queue::templates::rebuild` builds the DAG that reconciles a
+container to its wanted state: `write_dropins` (the nspawn-conf
+rewrite — `PRIVATE_NETWORK=0`, clears `HOST_ADDRESS` / `LOCAL_ADDRESS`,
+sets `EXTRA_NSPAWN_FLAGS` — plus the systemd resource-limits drop-in)
+is folded into the `Swap` node, then `nixos-container update` + stop +
+start runs across the `StopForUpdate → Swap → RebuildBookkeeping`
+brace and the tail `Reconcile` node. `flake.nix` itself is no longer
+regenerated host-side on rebuild — it's tracked in the agent's
+proposed/applied repos and rides along on every fetch (see
+`docs/approvals.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

From 6eb43ba2c51d691f7910eff8ce380e6659c2a303 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:17:32 +0200
Subject: [PATCH 62/64] docs(forge): fix ci-log source ordering and binary path
 claim

---
 docs/tools/forge.md | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/docs/tools/forge.md b/docs/tools/forge.md
index ce3ef548..e9228a0a 100644
--- a/docs/tools/forge.md
+++ b/docs/tools/forge.md
@@ -1,8 +1,8 @@
 # hive-forge CLI
 
 `hive-forge` is the Forgejo API wrapper available in every agent
-container (installed via `nix/agent-modules/forge.nix`; lives in `/hive-forge`
-as a proper Rust binary). Use it instead of ad-hoc curl pipelines.
+container (installed via `nix/agent-modules/forge.nix`, on `PATH` as a
+proper Rust binary). Use it instead of ad-hoc curl pipelines.
 
 ## Credentials and repo defaults
 
@@ -253,18 +253,21 @@ to discover valid label names before triaging or to audit the label set.
 - `ci-log --run <n> [--job i] [--step i] [--attempt n]` prints a CI
   run's job step logs. `<n>` is the run number from the run-page URL
   (same value `artifact-get` takes; `pr-status` surfaces it as a CI
-  context's target_url). Two log sources are tried in order: first the
-  web run-view **streamer** the run page polls (rich per-step framing,
-  honors `--step`) — but that reads the live `act_runner` task record,
-  which Forgejo prunes once a run completes; then, when the streamer is
-  pruned (500 / no lines), the **durable persisted-log download** the
-  run page's "view raw logs" link uses
-  (`…/runs/<n>/jobs/<job>/attempt/<a>/logs`), a flat whole-job log that
-  survives the prune (`--step` is not honored on this path). So quick /
-  older runs that the streamer can no longer serve still print instead
-  of erroring. `--job` selects the job (0-based, default 0); `--attempt`
-  picks the run attempt for the durable path (default 1; re-runs
-  increment it). `--json` wraps the output.
+  context's target_url). Two log sources, tried in **completeness
+  order**: the **durable persisted-log download** the run page's "view
+  raw logs" link uses (`…/runs/<n>/jobs/<job>/attempt/<a>/logs`, a flat
+  whole-job log) is tried first — complete once it exists, which covers
+  any run that has already finished; it's only absent while the job is
+  still running, in which case the verb falls back to the web run-view
+  **streamer** the run page polls (rich per-step framing, but only a
+  snapshot of the live `act_runner` task record, so a still-buffering
+  multi-minute phase can come back thin). Passing `--step` reverses
+  that order — only the streamer honors per-step framing (the persisted
+  log is flat), so `--step` goes straight to the streamer and an
+  out-of-range index surfaces as a hard error instead of silently
+  falling back. `--job` selects the job (0-based, default 0);
+  `--attempt` picks the run attempt for the durable path (default 1;
+  re-runs increment it). `--json` wraps the output.
 - `ci-rerun` re-runs CI without pushing an empty commit (the old
   retrigger path, which littered PR history). Forgejo has no token-usable
   REST endpoint to re-run an _existing_ run (the run-page rerun buttons

From 3e9d7c68d80eb77b87f1113d88f5a59da6e61148 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:17:32 +0200
Subject: [PATCH 63/64] docs(matrix): fix invite-wake mechanism and todo
 message format

---
 docs/tools/matrix.md | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md
index 896e742b..2a4a91f2 100644
--- a/docs/tools/matrix.md
+++ b/docs/tools/matrix.md
@@ -114,17 +114,21 @@ The same per-room breakdown is included in the `UnreadMatrix` entry
 returned by `get_loose_ends` so unread rooms surface in the
 loose-ends list between turns.
 
-**Invite wakes**: when the daemon's sync loop receives an
-`m.room.member` invite event, it upserts a todo (keyed `invite:<room>`)
-on the harness's in-agent socket, which drives a turn. The daemon does
-**not** auto-join — the agent calls `list_invites` to see pending
-invites and `resolve_invite` to accept or reject them.
+**Invite wakes**: the daemon sweeps `invited_rooms()` after every sync
+callback (deliberately not a one-shot `m.room.member` event handler —
+a one-shot signal that raced a socket-down window was dropped with no
+retry, leaving the agent deaf until manually prompted) and upserts a
+todo (keyed `invite:<room>`) for each pending invite on the harness's
+in-agent socket, which drives a turn. The daemon does **not**
+auto-join — the agent calls `list_invites` to see pending invites and
+`resolve_invite` to accept or reject them.
 
 **Pending invites as loose ends**: pending invites are upserted as
 keyed todos and appear in `get_loose_ends` output as
-`[matrix] pending invite: <room> — use list_invites to see,
-resolve_invite to accept or reject`. The keyed todo is cleared when a
-`resolve_invite` (or `join_room`) call resolves the invite.
+`[matrix] invited to <room> (<room_id>) — use list_invites to see
+pending invites, resolve_invite to accept or reject`. The keyed todo
+is cleared when a `resolve_invite` (or `join_room`) call resolves the
+invite.
 
 See [`docs/matrix.md`](../matrix.md) for the homeserver setup,
 provisioning flow, and federation config.

From 1e0ec9b5affd72b4b6f6f41766a1829903cbf69f Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:34:26 +0200
Subject: [PATCH 64/64] docs(conventions): fix one more stale hive-c0re.nix
 bare-file ref
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same bug class the facts sweep hunted for across everything else —
hive-c0re.nix is a module directory now
(nix/host-modules/hive-c0re/), environment.nix is where
HYPERHIVE_HIVE_DOMAIN is actually set. Caught doing a final grep
across the merged sweep for the known bad patterns before pushing.
---
 docs/conventions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/conventions.md b/docs/conventions.md
index 8c156d30..bbc97f2f 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -24,8 +24,8 @@ Four env vars cover the identity surface, read by
   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 `hive-c0re.nix` from
-  `services.hyperhive.domain`. When configured, `qualified_label()`
+  `darkest.space`), set by `nix/host-modules/hive-c0re/environment.nix`
+  from `services.hyperhive.domain`. When configured, `qualified_label()`
   returns `${label}@${domain}` (e.g. `iris@darkest.space`); when
   unset (single-hive deployments, dev/test) it degrades to just
   the short label so existing callers see no change. The