CLAUDE.md

@@ -63,16 +63,12 @@ hand-maintained per-file tree drifts out of sync with the code.
 ### Other top-level dirs
 
 - **`frontend/`** — npm workspaces → static dashboard + per-agent UI
-  dist, built hermetically by `nix/packages/frontend.nix`. Packages:
+  dist, built hermetically by `nix/frontend.nix`. Packages: `shared`
-  `shared` (terminal pane + Catppuccin palette), `dashboard` (the
+  (terminal pane + Catppuccin palette), `dashboard` (the operator SPA),
-  operator SPA), `agent` (the default per-container UI).
+  `agent` (the default per-container UI).
-- **`nix/`** — `host-modules/` (the host stack: hyperhive core options,
+- **`nix/`** — NixOS modules (`modules/hive-{c0re,forge,gateway,matrix,
-  `hive-{c0re,priv,forge,gateway,matrix,network,tls,ci}`, otel, swarm),
+  ci,network}.nix`) + per-container templates (`templates/{harness-base,
-  `agent-modules/` (the per-agent harness feature modules),
+  agent-base,manager,weston-vnc}.nix`) + the options-doc derivation.
-  `templates/{agent,ruth}.nix` (container entry points), `packages/`
-  (flake package outputs), `docs/` (the options-doc derivation), plus
-  `sources.nix` / `rust.nix` / `checks.nix` / `devshell.nix` /
-  `treefmt.nix` behind the thin `flake.nix`.
 - **`docs/`** — subsystem reference docs (see *Reading paths* below).
 - **`branding/`**, **`scripts/`** — static assets + helper scripts.
 

README.md

@@ -154,7 +154,7 @@ account), it prints the token to stdout and writes nothing.
 nix develop -c cargo check
 nix flake check        # rust + nix + toml fmt + clippy
 
-# deploy from a host config that imports hyperhive.nixosModules.default
+# deploy from a host config that imports hyperhive.nixosModules.hive-c0re
 nix flake update --update-input hyperhive
 sudo nixos-rebuild switch --flake .#<host>
 ```

docs/agent-hierarchy.md

@@ -166,7 +166,7 @@ Tree-shape version:
 `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
+`$HYPERHIVE_STATE_DIR`. The harness-base shell scripts
 (tea-login, forge-avatar-sync) simplified from glob+for loops to a
 direct `$HYPERHIVE_STATE_DIR/<token>` read.
 
@@ -215,15 +215,15 @@ nspawn agent. Open questions, not yet wired:
 ## Harness systemd unit shape
 
 One harness serve binary (`hive-agent`, with its `hive-agent-mcp` /
-`hive-agent-wake` siblings), one shared `nix/agent-modules/` tree, one
+`hive-agent-wake` siblings), one `harness-base.nix` template, one
 service unit (`systemd.services.hive-ag3nt`) 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).
 
-`agent.nix` and `ruth.nix` both import the shared `nix/agent-modules/`.
+`agent-base.nix` and `manager.nix` both import `harness-base.nix`.
-`ruth.nix` additionally sets forge defaults to suppress the
+`manager.nix` additionally sets forge defaults to suppress the
 subscription/participation firehose so ruth's inbox stays focused
 on direct mentions, reviews, and assignments.
 

docs/ci.md

@@ -181,6 +181,6 @@ GC on the coordinator host won't reclaim space on the builder.
 
 ## References
 
-- `nix/host-modules/hive-ci.nix`: runner configuration, auto-registration script, container setup.
+- `nix/modules/hive-ci.nix`: runner configuration, auto-registration script, container setup.
 - `.forgejo/workflows/ci.yml`: workflow definition.
 - `docs/gotchas.md`: nix sandboxing limitations in containers.

docs/gateway.md

@@ -89,7 +89,8 @@ now set unconditionally for every agent. The mechanism:
 
 1. **Agent side**. `HIVE_WEB_SOCKET=/run/hive-agent/<name>/web.sock`
    is set on every harness service env; `web_ui::serve` binds a
-   `UnixListener` at that path.
+   `UnixListener` at that path. The deprecated
+   `hyperhive.web.useUnixSocket` option is now a no-op.
 2. **Host side**. `hive-c0re` bind-mounts the per-agent subdir
    (`/run/hive-agent/<name>/`) into the agent's container. Dir
    bind, not file bind — file bind-mounts don't survive the

docs/gotchas.md

@@ -77,7 +77,7 @@ socket without needing a clean reinstall.
 ## `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`
+It's unfree, so `harness-base.nix` sets `config.allowUnfreePredicate`
 at the container level to whitelist `claude-code` specifically —
 scoped, only this one package. This is needed because each per-agent
 `nixosConfiguration` evaluates its own nixpkgs instance and the
@@ -204,7 +204,7 @@ containers don't get user-namespaces by default, so `nix build`
 invocations _inside_ the container can't set up the build sandbox
 and fail outright if the host daemon's
 `nix.settings.sandbox-fallback` is `false` (nixpkgs default).
-`nix/agent-modules/default.nix` does `lib.mkForce true` so builds
+`nix/templates/harness-base.nix` does `lib.mkForce true` so builds
 fall back to unsandboxed local builds rather than failing. Security
 implications: `docs/security.md`.
 
@@ -232,7 +232,7 @@ CI on drift).
 
 ## Split asset derivations away from the rust workspace
 
-`nix/packages/assets.nix` builds the branding SVG/PNG family + claude
+`nix/assets.nix` builds the branding SVG/PNG family + claude
 system-prompt template + claude-settings JSON as its own derivation,
 separate from the hive-ag3nt / hive-c0re crates. Reason: when the
 rust build's `src` was the whole repo tree, any tweak to
@@ -246,7 +246,7 @@ derivation's `nativeBuildInputs`.
 
 ## Weston VNC compositor (per-agent `hyperhive.gui.enable`)
 
-`nix/agent-modules/weston-vnc.nix` adds an optional Weston Wayland
+`nix/templates/weston-vnc.nix` adds an optional Weston Wayland
 compositor with the VNC backend, surfaced as
 `hyperhive.gui.enable = true` per-agent. The harness's
 `/screen/ws` WebSocket relay (`docs/web-ui/agent.md::Per-agent endpoints`)
@@ -284,7 +284,7 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
   inherit it.
 - **Fixed Wayland socket name (`--socket=wayland-0`)**: weston is
   launched with `--socket=wayland-0` so the socket path is
-  deterministic. `nix/agent-modules/weston-vnc.nix` exports `WAYLAND_DISPLAY=wayland-0`
+  deterministic. `harness-base.nix` exports `WAYLAND_DISPLAY=wayland-0`
   and `XDG_RUNTIME_DIR=/run/gui` as global system environment
   variables (gated on `hyperhive.gui.enable`) so every systemd service
   in the container inherits them. Without this, services starting
@@ -311,7 +311,7 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
   must never block on weston signalling readiness. A misconfigured
   weston degrades to a `Restart=on-failure` loop visible in
   `journalctl`, it does not abort the `nixos-container update`.
-  Same reasoning as the `tea-login` unit in `nix/agent-modules/forge.nix`.
+  Same reasoning as the `tea-login` unit in `harness-base.nix`.
 - **`[core] idle-time=0`**: disables weston's 300-second idle
   timeout. Without it the VNC desktop fades to black and
   desktop-shell shows its click-to-unlock screen — useless for an
@@ -323,9 +323,9 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
 ## 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
+`hostEval` (a stub NixOS system loading `hive-c0re.nix` with every
 hyperhive subsystem `mkForce false` so heavy build inputs stay out of
-the eval) and `agentEval` (evaluates `agent.nix` fresh for the
+the eval) and `agentEval` (evaluates `agent-base.nix` fresh for the
 per-agent options tree).
 
 Three output trees consumed by `flake.nix`, all **markdown**:
@@ -333,7 +333,7 @@ Three output trees consumed by `flake.nix`, all **markdown**:
 - `docs-host` — operator-facing host module options
   (`services.hyperhive.*`)
 - `docs-agent` — per-agent harness options (`hyperhive.*`
-  declared in `nix/agent-modules/`)
+  declared in `nix/templates/harness-base.nix`)
 - `docs` — bundle of `index.md` + `host.md` + `agent.md`
 
 Pipeline:
@@ -356,7 +356,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` + stub overlay
 
 Naively, the docs evaluation depends on `self` (the flake's store path),
 so every commit — even Rust-only or frontend-only changes — produces new
@@ -371,11 +371,11 @@ The fix (`nix/docs/default.nix`):
    context. The resulting store path is content-addressed from the nix/
    file contents only. Docs drvs only change when a `.nix` file changes.
 
-2. The package options the modules consume (`hyperhive.packages.*`,
+2. **`docsStubOverlay`** — replaces `self.overlays.default` with stub
-   `services.hyperhive.c0re.*`) carry no in-module defaults and every
+   packages (`pkgs.emptyFile` / `pkgs.emptyDirectory`) for the docs eval.
-   default that references them has a `defaultText`, so the doc walk
+   `nixosOptionsDoc` renders `defaultText` for all package options anyway;
-   never forces a package — no stubs needed, and the Rust/frontend
+   the stubs prevent attribute-missing eval errors without pulling in the
-   build closure stays out of the eval.
+   Rust or frontend build closure.
 
 3. Both `hostEval` and `agentEval` are evaluated from `nixSrc` paths
    (not `self`), so the docs drv dependency chain ends at `nixSrc`.

docs/matrix.md

@@ -214,7 +214,7 @@ which has two upstream gaps for fluffychat's web target:
 - `native_imaging`'s C source isn't built — emscripten isn't a
   flutter-builder native build input.
 
-Both fixed in `nix/host-modules/hive-matrix.nix` via two derivations:
+Both fixed in `nix/modules/hive-matrix.nix` via two derivations:
 
 - **`fluffychat-web-imaging`** builds `Imaging.{js,wasm}` from the
   `native_imaging` C source via `pkgs.emscripten`. Source comes

docs/network.md

@@ -4,11 +4,11 @@ Host-side bridge + per-agent private-netns isolation — always on
 whenever hyperhive is enabled. Configured via
 `services.hyperhive.network.*`.
 
-> Isolation is the only mode — there is no shared-netns fallback. The
+> **Historical note:** the bridge and private-netns isolation landed in
-> former `services.hyperhive.network.enable`,
+> two separate phases. `services.hyperhive.network.enable` and
-> `services.hyperhive.network.isolateContainers` and
+> `services.hyperhive.network.isolateContainers` are retained as
-> `services.hyperhive.network.upstreamDns` options were removed; a
+> deprecated no-op options so existing configs eval without change; both
-> config that still sets one fails eval with a removal message.
+> are ignored — isolation is the only mode.
 
 ## Container shape (where dnsmasq lives)
 
@@ -26,6 +26,7 @@ listener on `bridgeIp` is on the host's bridge interface.
     enable = true;
     domain = "darkest.space";
     # network.bridgeIp = "10.42.0.1";   # default
+    # network.upstreamDns = [ "1.1.1.1" "9.9.9.9" ];  # default
   };
 }
 ```
@@ -47,12 +48,9 @@ schemes pick their own.
 dnsmasq is **authoritative** for the hive's own zones — answers
 `<hive-domain>`, `forge.<hive-domain>`, `matrix.<hive-domain>`
 queries with the bridge IP (where nginx is reachable). Everything
-else is forwarded to the host's own resolvers: dnsmasq reads the
+else gets forwarded to `upstreamDns`. Containers don't need to know
-gateway container's `/etc/resolv.conf`, the host copy nixos-container
+the upstream — they query the bridge IP and dnsmasq does the right
-makes at each container start — a host resolver change is picked up
+thing per-name.
-on the next gateway restart. Containers don't need to know the
-upstream — they query the bridge IP and dnsmasq does the right thing
-per-name.
 
 `bind-interfaces` + `interface = [ bridgeName "lo" ]` means the
 listener only accepts queries from the bridge interface (plus lo for
@@ -131,7 +129,7 @@ address arithmetic.
 and `HOST_BRIDGE=<bridgeName>` via `lifecycle::set_nspawn_flags` when
 creating or updating containers. `LOCAL_ADDRESS` is left empty so the
 container's dhcpcd acquires an address from the bridge dnsmasq pool
-(`networking.useDHCP = true` in `nix/agent-modules/network.nix`). This applies uniformly
+(`networking.useDHCP = true` in `harness-base.nix`). This applies uniformly
 to all containers — agents and service containers alike.
 
 `HOST_ADDRESS` is the bridge gateway IP (the address part of
@@ -156,7 +154,7 @@ wiring is runtime:
 
 - `hive-priv` drops a marker file (`/etc/hyperhive-bridge-dns`, carrying the
   gateway IP) into each container's `/etc`.
-- the `hyperhive-isolated-dns` oneshot (`nix/agent-modules/network.nix`), gated on that
+- the `hyperhive-isolated-dns` oneshot (harness-base.nix), gated on that
   marker, rewrites `/etc/resolv.conf` to `nameserver <gateway-ip>` at boot.
   It is ordered `before` the harness (`hive-ag3nt`), the matrix daemon, and
   `tea-login` so the resolver is correct before the first DNS lookup.

docs/persistence.md

@@ -369,7 +369,7 @@ state dirs need a one-time data shuffle so they don't lose their claude
 session.
 
 `system.activationScripts.hive-agent-user-migrate` (in
-`nix/agent-modules/user.nix`) runs on every activation,
+`nix/templates/harness-base.nix`) runs on every activation,
 marker-guarded so the substantive moves only happen once per
 container lifetime:
 

docs/security.md

@@ -146,7 +146,7 @@ component can't traverse.
 Agent containers bind-mount the host's `nix-daemon` socket. The host daemon may
 have `sandbox-fallback = false` (strict NixOS defaults), which causes `nix build`
 inside nspawn containers to fail — containers lack kernel user namespaces, so nix
-cannot set up its build sandbox. the agent modules set `sandbox-fallback = true`
+cannot set up its build sandbox. `harness-base.nix` sets `sandbox-fallback = true`
 so that builds fall back to unsandboxed execution rather than failing outright.
 
 ### Threat model

docs/tools/bash.md

@@ -2,7 +2,7 @@
 
 Background shell execution via `hive-bash-mcp`. Tools land as
 `mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
-Available on every agent unconditionally — `nix/agent-modules/mcp.nix` always
+Available on every agent unconditionally — `harness-base.nix` always
 injects bash into `hyperhive.extraMcpServers` (with `allowedTools =
 ["*"]`), so `mcp__bash__*` is in `--allowedTools` for every claude
 invocation regardless of tool groups.
@@ -96,7 +96,7 @@ The bash tooling follows the same daemon + stdio-bridge pattern as the
 matrix MCP:
 
 - **`hive-bash-daemon`** — long-running process (one per agent container,
-  systemd service in `nix/agent-modules/mcp.nix`). Owns subprocess management,
+  systemd service in `harness-base.nix`). Owns subprocess management,
   output file writing, `mcp-loose-ends/` state, and wake signal delivery.
   Listens on `/run/hive-bash/socket` inside the container.
 

docs/tools/forge.md

@@ -1,7 +1,7 @@
 # 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`
+container (installed via `harness-base.nix`; lives in `/hive-forge`
 as a proper Rust binary). Use it instead of ad-hoc curl pipelines.
 
 ## Credentials and repo defaults

docs/turn-loop/claude-invocation.md

@@ -23,7 +23,7 @@ parsed from a turn (usage, cost, context window, resolved model) as
 
 Hive-enforced settings ship at `/etc/claude-code/managed-settings.json`
 (claude-code's canonical managed-settings path — precedence #1,
-read-only, un-overridable), wired in `nix/agent-modules/claude-settings.nix`
+read-only, un-overridable), wired in `nix/templates/harness-base.nix`
 from the `prompts/claude-settings.json` asset. `effortLevel` is
 deliberately not in that file — effort is controlled live via the
 `--effort` flag (`HIVE_DEFAULT_EFFORT` / the per-agent UI slider), which

docs/turn-loop/config.md

@@ -17,7 +17,7 @@ sentence into the agent's system prompt so it knows the docs exist and
 where to find them. The tree is served by `claude --add-dir` so the full
 markdown is readable during every turn.
 
-Enabled by default only for the root/manager agent (`nix/templates/ruth.nix`). Any
+Enabled by default only for the root/manager agent (`manager.nix`). Any
 agent can opt in by adding the line above to its `agent.nix`.
 
 The `docs/` source is a narrow flake input (`hyperhive-docs`) tracked

flake.nix

@@ -3,9 +3,9 @@
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
-    # Crane is stateless — no nixpkgs input to follow; `crane.mkLib
+    # Crane (replaces the former naersk-based build). Stateless — no nixpkgs input to
-    # pkgs` returns the lib at whatever pkgs we pass it (we use the
+    # follow; `crane.mkLib pkgs` returns the lib at whatever pkgs we
-    # project's pinned nixpkgs).
+    # pass it (we use the project's pinned nixpkgs).
     crane.url = "github:ipetkov/crane";
     treefmt-nix = {
       url = "github:numtide/treefmt-nix";
@@ -13,14 +13,6 @@
     };
   };
 
-  # Thin entry point — the real logic lives under nix/:
-  #   nix/sources.nix   filtered source views (meta-flake + docs inputs)
-  #   nix/rust.nix      shared crane wiring (cleanSrc, cargoArtifacts)
-  #   nix/packages/     every package output
-  #   nix/checks.nix    flake checks
-  #   nix/devshell.nix  dev shell
-  #   nix/treefmt.nix   formatter config
-  #   nix/host-modules/, nix/agent-modules/, nix/templates/  the NixOS module trees
   outputs =
     inputs@{
       self,
@@ -34,7 +26,61 @@
         "aarch64-linux"
         "x86_64-linux"
       ];
-      sources = import ./nix/sources.nix { inherit lib; };
+      # Explicit per-consumer source filter for the hyperhive flake path
+      # handed to hive-c0re (`hyperhiveFlake`, below). A filtered view of
+      # this repo that drops files no nix or cargo derivation reads —
+      # shell helper scripts and root-level markdown — so editing them
+      # does NOT change the store path and therefore does NOT force a
+      # rebuild of every agent container.
+      #
+      # Companion to the rust `cleanSrc` (crane's cargo-source filter):
+      # each real source is a named, explicitly-filtered derivation used
+      # as `src`, rather than an inline filter at the use site.
+      #
+      # Dropped: scripts/, docs/, root-level *.md (README/CLAUDE/TODO/…).
+      # Kept (build needs them): .nix, .rs, Cargo.*, branding/,
+      # frontend/, prompts/, flake.lock. docs/ is deliberately dropped:
+      # it is shipped to agent containers as its OWN narrow
+      # meta-flake input (`hyperhiveDocsSource`, below), threaded through
+      # hive-c0re → the meta flake → `hyperhive.docs.source`. Keeping docs/
+      # out of THIS source means a doc edit only re-hashes the docs input
+      # (a cheap re-link), not the whole flake source (which would rebuild
+      # every agent container). The old `nix/reference-docs.nix` build from
+      # `../docs` stays only for standalone `nix build .#reference-docs`
+      # from a full checkout — the meta path never evaluates it.
+      hyperhiveFlakeSource = lib.cleanSourceWith {
+        name = "hyperhive-flake-source";
+        src = ./.;
+        filter =
+          path: type:
+          let
+            # Repo-relative path (strip the absolute source-dir prefix).
+            rel = lib.removePrefix (toString ./. + "/") (toString path);
+          in
+          !(lib.hasPrefix "scripts/" rel || rel == "scripts")
+          && !(lib.hasPrefix "docs/" rel || rel == "docs")
+          && !(type == "regular" && !lib.hasInfix "/" rel && lib.hasSuffix ".md" rel);
+      };
+      # The repo `docs/` tree as a standalone narrow source. Its
+      # store path moves ONLY on doc edits, decoupled from
+      # `hyperhiveFlakeSource`. hive-c0re threads this to the meta flake as
+      # the `hyperhive-docs` input (same pattern as `hyperhiveFlake`); the
+      # harness resolves `$HIVE_DOCS_DIR` from it via `hyperhive.docs.source`.
+      # Evaluated here on the host where docs/ exists — it cannot be derived
+      # from inside the docs-stripped `hyperhiveFlakeSource`.
+      hyperhiveDocsSource = lib.cleanSourceWith {
+        name = "hyperhive-docs-source";
+        src = ./docs;
+      };
+      treefmt-config = {
+        projectRootFile = "flake.nix";
+        programs = {
+          keep-sorted.enable = true;
+          nixfmt.enable = true;
+          rustfmt.enable = true;
+          taplo.enable = true;
+        };
+      };
       forAllSystems =
         f:
         lib.genAttrs systems (
@@ -42,9 +88,70 @@
           f rec {
             inherit system;
             pkgs = nixpkgs.legacyPackages.${system};
-            treefmt-eval = treefmt-nix.lib.evalModule pkgs (import ./nix/treefmt.nix);
+            treefmt-eval = treefmt-nix.lib.evalModule pkgs treefmt-config;
             craneLib = crane.mkLib pkgs;
-            rust = import ./nix/rust.nix { inherit pkgs craneLib; };
+            # Narrowed source tree the rust derivations consume.
+            # `cleanCargoSource` is crane's standard "everything cargo
+            # cares about" filter (Cargo.toml/Cargo.lock + *.rs). All
+            # non-rust runtime assets — branding + the claude system
+            # prompt template + claude-settings.json — live in the
+            # separate `hyperhive-assets` derivation and are
+            # loaded by the binaries at runtime from `$HIVE_ASSETS_DIR`.
+            # The unit tests in `hive-ag3nt::prompt` read the same
+            # `prompts/system.md` directly from the workspace tree at
+            # *test* runtime (via `env!("CARGO_MANIFEST_DIR")` — a
+            # compile-time string, no file open at compile), so the
+            # prompt template doesn't have to be in this fileset to
+            # keep `cargo test` honest. Net effect: tweaks to any
+            # non-`*.rs` / non-`Cargo.*` file (README, branding,
+            # nix modules, frontend tree, OR `hive-ag3nt/prompts/*`)
+            # do NOT bust this src hash, so the rust derivations
+            # stay fully cached.
+            cleanSrc = craneLib.cleanCargoSource ./.;
+            # Build the workspace's dependency tree once, cached as
+            # its own derivation. `buildPackage` and `cargoClippy`
+            # both reuse this via `inherit cargoArtifacts;` so a
+            # workspace-only edit doesn't rebuild deps. All three
+            # derivations consume the same `cleanSrc` so the input
+            # hash stays consistent across the chain.
+            cargoArtifacts = craneLib.buildDepsOnly {
+              src = cleanSrc;
+              # Workspace Cargo.toml is virtual (no `[package].name`),
+              # so crane can't auto-derive a name. Spell it out
+              # explicitly here and below — keeps the derivation name
+              # stable across crane bumps + silences the placeholder
+              # warning. Same `pname` everywhere so dep + workspace +
+              # clippy share a clean naming family.
+              pname = "hyperhive-workspace";
+              version = "0.1.0";
+              inherit nativeBuildInputs;
+            };
+            # Shared between buildDepsOnly + buildPackage + cargoClippy
+            # so the three derivations see the same toolchain shape.
+            # git: naersk used to auto-include it; crane is more
+            # minimal, so we add it explicitly so hive-c0re's
+            # `lifecycle::tests::setup_proposed_*` (which shell out to
+            # `git init` + commit) pass under `cargo test` in the
+            # sandbox.
+            # `librsvg` used to live here for `hive-c0re/build.rs`'s
+            # rsvg-convert call — that whole codepath moved into the
+            # `hyperhive-assets` derivation, so the rust
+            # derivation no longer needs the dependency.
+            # `sqlite` required by matrix-sdk's `sqlite` feature
+            # (`hive-matrix-mcp` workspace member) — the
+            # matrix-sdk-sqlite + rusqlite stack links against system
+            # libsqlite3 by default.
+            # `cmake` builds `aws-lc-sys` (BoringSSL) from source — pulled in by
+            # the `rustls` (aws-lc-rs) crypto provider under the OTLP/reqwest
+            # stack in `hive-metric`. Without it the crane deps build fails on
+            # `cargo-package-reqwest-0.13.4`. Kept in the shared inputs since
+            # more metric/crypto deps are expected to land in the workspace.
+            nativeBuildInputs = [
+              pkgs.git
+              pkgs.sqlite
+              pkgs.pkg-config
+              pkgs.cmake
+            ];
           }
         );
     in
@@ -53,97 +160,271 @@
         {
           pkgs,
           craneLib,
-          rust,
+          cleanSrc,
+          cargoArtifacts,
+          nativeBuildInputs,
           ...
         }:
-        import ./nix/packages {
-          inherit
-            pkgs
-            craneLib
-            rust
-            self
-            nixpkgs
-            ;
-        }
-      );
-
-      nixosModules =
         let
-          # Package wiring for agent containers — the harness modules
+          docsAttrs = import ./nix/docs {
-          # consume hyperhive's own packages via the `hyperhive.packages`
+            inherit pkgs self;
-          # option (see nix/agent-modules/packages.nix); no overlay.
+            inherit (nixpkgs) lib;
-          # The `mkDefault` is applied PER KEY (`mapAttrs`), not to the
+            inherit (nixpkgs.lib) nixosSystem;
-          # whole attrset: definition-level priority filtering runs
-          # before `attrsOf`'s per-key merge, so a whole-set `mkDefault`
-          # would be discarded entirely the moment an agent.nix
-          # overrides a single key. Per-key priorities make an
-          # individual override win while every other key keeps the
-          # flake default.
-          agentPackages =
-            { lib, pkgs, ... }:
-            {
-              hyperhive.packages = lib.mapAttrs (_: lib.mkDefault) {
-                inherit (self.packages.${pkgs.stdenv.hostPlatform.system})
-                  hive-agent
-                  hive-agent-mcp
-                  hive-agent-wake
-                  hive-bash-daemon
-                  hive-bash-mcp
-                  hive-forge
-                  hive-matrix-daemon
-                  hive-matrix-mcp
-                  hive-metric
-                  assets
-                  frontend
-                  reference-docs
-                  ;
           };
+          # One package per daemon/harness/MCP-server binary — matches the
+          # `hivectl` / `hive-forge` split below rather than grouping them
+          # into a single derivation. Consumers (agent containers, host
+          # module, `nix profile install`) depend on exactly the binaries
+          # they need instead of an all-or-nothing bundle. All share
+          # `cargoArtifacts` (built once via `buildDepsOnly` above), so
+          # splitting doesn't cost extra rustc invocations — each call
+          # below just asks crane to build+link its one requested `--bin`.
+          #
+          # Tests are kept in the separate `checks.cargo-test` derivation
+          # (carries the hyperhive-assets build input for the prompt-template
+          # assertions in hive-ag3nt::prompt::tests). Keeping them out of the
+          # binary derivations means a prompt edit doesn't bust the cargo cache.
+          mkDaemonBin =
+            bin: description:
+            craneLib.buildPackage {
+              src = cleanSrc;
+              inherit cargoArtifacts nativeBuildInputs;
+              cargoExtraArgs = "--bin ${bin}";
+              pname = bin;
+              version = "0.1.0";
+              meta.description = description;
+              doCheck = false;
+            };
+          hiveC0rePkg = mkDaemonBin "hive-c0re" "hyperhive host coordinator daemon";
+          hivePrivPkg = mkDaemonBin "hive-priv" "hyperhive privileged root helper";
+          hiveAgentPkg = mkDaemonBin "hive-agent" "hyperhive in-container agent harness serve loop";
+          hiveAgentMcpPkg = mkDaemonBin "hive-agent-mcp" "hyperhive agent-surface MCP server";
+          hiveAgentWakePkg = mkDaemonBin "hive-agent-wake" "hyperhive external wake CLI — push a message into an agent's own inbox";
+          hiveBashDaemonPkg = mkDaemonBin "hive-bash-daemon" "hyperhive per-agent bash-task runner daemon";
+          hiveBashMcpPkg = mkDaemonBin "hive-bash-mcp" "hyperhive bash-task MCP bridge";
+          hiveMatrixDaemonPkg = mkDaemonBin "hive-matrix-daemon" "hyperhive per-agent matrix-sdk daemon";
+          hiveMatrixMcpPkg = mkDaemonBin "hive-matrix-mcp" "hyperhive matrix MCP bridge";
+          hiveMetricPkg = mkDaemonBin "hive-metric" "hyperhive agent-emitted custom metrics CLI";
+          # Operator CLI — ships `hivectl` (with shell completions and the
+          # `wg` wrapper) without the daemon binaries. Suitable for
+          # `nix profile install .#hivectl` / `environment.systemPackages
+          # = [ inputs.hyperhive.packages.${system}.hivectl ]` when the
+          # operator only wants the admin CLI. Shares `cargoArtifacts` with
+          # `daemonBins` so there is no double-rustc cost.
+          hivectlPkg = craneLib.buildPackage {
+            src = cleanSrc;
+            inherit cargoArtifacts;
+            cargoExtraArgs = "--bin hivectl";
+            pname = "hivectl";
+            version = "0.1.0";
+            meta.description = "hyperhive operator CLI";
+            doCheck = false;
+            # `installShellFiles` + `makeWrapper` scoped to this derivation
+            # only — daemon bins don't need them.
+            nativeBuildInputs = nativeBuildInputs ++ [
+              pkgs.installShellFiles
+              pkgs.makeWrapper
+            ];
+            # Ship shell completions (the binary's own `completions <shell>`
+            # verb is the single source of truth, so they never drift from
+            # the actual verbs). Wrap with wireguard-tools so `hivectl wg`
+            # subcommands work before `swarm.wireguard.enable` is set (wg
+            # init is the very first setup step). Completion generation runs
+            # before wrapProgram since wrapProgram renames the real binary.
+            postInstall = ''
+              installShellCompletion --cmd hivectl \
+                --bash <("$out/bin/hivectl" completions bash) \
+                --zsh <("$out/bin/hivectl" completions zsh) \
+                --fish <("$out/bin/hivectl" completions fish)
+              wrapProgram "$out/bin/hivectl" \
+                --prefix PATH : ${pkgs.wireguard-tools}/bin
+            '';
+          };
+          # Forgejo CLI — ships `hive-forge` without the rest of the
+          # workspace. Useful for operator workstations / CI environments
+          # that only need forge access. Shares `cargoArtifacts` with
+          # `daemonBins`.
+          hiveForgePkg = craneLib.buildPackage {
+            src = cleanSrc;
+            inherit cargoArtifacts nativeBuildInputs;
+            cargoExtraArgs = "--bin hive-forge";
+            pname = "hive-forge";
+            version = "0.1.0";
+            meta.description = "hyperhive Forgejo CLI";
+            doCheck = false;
           };
         in
         {
-          agent-base.imports = [
+          # All workspace binaries in one derivation via symlinkJoin.
-            ./nix/templates/agent.nix
+          # Each binary is compiled exactly once (one rustc per bin, all
-            agentPackages
+          # sharing `cargoArtifacts`); symlinkJoin assembles the outputs
+          # without any additional compilation. The NixOS module's
+          # `pkgs.hyperhive` (= this) and `nix build .#` both land here.
+          default = pkgs.symlinkJoin {
+            name = "hyperhive";
+            paths = [
+              hiveC0rePkg
+              hivePrivPkg
+              hiveAgentPkg
+              hiveAgentMcpPkg
+              hiveAgentWakePkg
+              hiveBashDaemonPkg
+              hiveBashMcpPkg
+              hiveMatrixDaemonPkg
+              hiveMatrixMcpPkg
+              hiveMetricPkg
+              hivectlPkg
+              hiveForgePkg
             ];
-          ruth.imports = [
+          };
-            ./nix/templates/ruth.nix
+          # Per-bin split packages. Agent containers depend on the
-            agentPackages
+          # individual bins they actually exec/PATH-need (see
-          ];
+          # `harness-base.nix`) instead of the `default` bundle — that
-          # The full host stack (nix/host-modules/default.nix aggregator) plus
+          # keeps `hivectl` (dials the *host* admin socket, unreachable
-          # the package/source wiring from this flake. The wiring is a
+          # from inside a container, drags in `wireguard-tools`) and a
-          # plain config module setting the `services.hyperhive.c0re.*`
+          # redundant `hive-forge` copy (already on agent PATH via
-          # package options via `lib.mkDefault` — no overlay involved, and
+          # `hive-forge-tools.nix`) out of every agent's closure.
-          # an operator override still wins. Intended usage:
+          hivectl = hivectlPkg;
+          hive-forge = hiveForgePkg;
+          hive-c0re = hiveC0rePkg;
+          hive-priv = hivePrivPkg;
+          hive-agent = hiveAgentPkg;
+          hive-agent-mcp = hiveAgentMcpPkg;
+          hive-agent-wake = hiveAgentWakePkg;
+          hive-bash-daemon = hiveBashDaemonPkg;
+          hive-bash-mcp = hiveBashMcpPkg;
+          hive-matrix-daemon = hiveMatrixDaemonPkg;
+          hive-matrix-mcp = hiveMatrixMcpPkg;
+          hive-metric = hiveMetricPkg;
+          # Bundled browser assets — see ./nix/frontend.nix. Output is
+          # $out/{dashboard,agent}/ which the Rust binaries serve via
+          # tower_http::ServeDir.
+          frontend = pkgs.callPackage ./nix/frontend.nix {
+            branding-svg = ./branding/hyperhive.svg;
+          };
+          # Static runtime assets the rust binaries read via
+          # `hive_sh4re::assets::*`: branding/* + prompts/*,
+          # plus the rendered agent-configs.png. Split out of the
+          # rust derivation so a tweak to e.g. system.md doesn't bust
+          # the cargo cache. Build input of the `cargo-test` check but
+          # NOT of `packages.default`, so the binary derivation stays
+          # cached when a prompt edit ripples through.
+          assets = pkgs.callPackage ./nix/assets.nix { };
+          # The repo docs/ markdown tree as a standalone derivation —
+          # agents read it in-container (added as a claude additional
+          # directory) and the website repo reuses it as a flake input,
+          # neither of which needs the branding/prompt assets. See
+          # nix/reference-docs.nix. (`docs` above is the auto-generated
+          # nix-options reference, a different artifact.)
+          reference-docs = pkgs.callPackage ./nix/reference-docs.nix { };
+          # XDG icon set + .desktop entries for hyperhive processes.
+          # Narrow input: only the branding SVG, so unrelated source changes
+          # don't bust this derivation's cache.
+          xdg-icons = pkgs.callPackage ./nix/packages/hive-xdg-icons.nix {
+            hyperhiveSvg = ./branding/hyperhive.svg;
+          };
+          # Pre-built per-container system closures. Exposed as packages
+          # so operators can `nix build .#agent-base-toplevel` (or wire
+          # them into their host system closure via the
+          # `preBuildAgentTemplates` option on the hive-c0re module —
+          # see nix/modules/hive-c0re.nix). Speeds up the first agent
+          # spawn dramatically because the heavy lifting (nixpkgs +
+          # claude-code + hive-ag3nt binary) is already in the store
+          # when the meta evaluator goes to build the container.
+          #
+          # nixosConfigurations are pinned to x86_64-linux (nixos-
+          # containers only run native arch), so these toplevels are
+          # only useful on an x86_64-linux host — flake check across
+          # systems still tolerates evaluating them on aarch64 because
+          # they're plain derivations, but `nix build` from a non-x86
+          # host would only succeed via a remote x86 builder.
+          agent-base-toplevel = self.nixosConfigurations.agent-base.config.system.build.toplevel;
+          ruth-toplevel = self.nixosConfigurations.ruth.config.system.build.toplevel;
+
+          # Auto-generated nix options reference for hyperhive.
+          # `docs` bundles host + agent pages into one tree; the split
+          # outputs are useful when consumers only want one surface.
+          # All three are pure markdown — no rust or frontend deps in
+          # the closure, so `nix build .#docs` is cheap.
+          docs = docsAttrs.bundle;
+          docs-host = docsAttrs.host;
+          docs-agent = docsAttrs.agent;
+        }
+      );
+
+      overlays = {
+        default = final: prev: {
+          hyperhive = self.packages.${prev.stdenv.hostPlatform.system}.default;
+          # Per-binary daemon/harness/MCP-server packages, exposed via the
+          # overlay so container nix evaluations can depend on exactly the
+          # bin(s) they need instead of the full `hyperhive` bundle — see
+          # `packages.<system>.hive-*` above and their use in
+          # `harness-base.nix`.
+          hive-c0re = self.packages.${prev.stdenv.hostPlatform.system}.hive-c0re;
+          hive-priv = self.packages.${prev.stdenv.hostPlatform.system}.hive-priv;
+          hive-agent = self.packages.${prev.stdenv.hostPlatform.system}.hive-agent;
+          hive-agent-mcp = self.packages.${prev.stdenv.hostPlatform.system}.hive-agent-mcp;
+          hive-agent-wake = self.packages.${prev.stdenv.hostPlatform.system}.hive-agent-wake;
+          hive-bash-daemon = self.packages.${prev.stdenv.hostPlatform.system}.hive-bash-daemon;
+          hive-bash-mcp = self.packages.${prev.stdenv.hostPlatform.system}.hive-bash-mcp;
+          hive-matrix-daemon = self.packages.${prev.stdenv.hostPlatform.system}.hive-matrix-daemon;
+          hive-matrix-mcp = self.packages.${prev.stdenv.hostPlatform.system}.hive-matrix-mcp;
+          hive-metric = self.packages.${prev.stdenv.hostPlatform.system}.hive-metric;
+          # Bundled frontend dist (see ./nix/frontend.nix). Output is
+          # $out/{dashboard,agent}/; consumers pick the surface they
+          # need. Exposed via the overlay so containers' nix evaluations
+          # can reach it as `pkgs.hyperhive-frontend` once the overlay
+          # is applied (manager + agent containers both apply it via
+          # `mkContainer` further down).
+          hyperhive-frontend = self.packages.${prev.stdenv.hostPlatform.system}.frontend;
+          # Static runtime assets. Exposed alongside the binary
+          # so the harness module can wire $HIVE_ASSETS_DIR straight
+          # to `${pkgs.hyperhive-assets}/share/hyperhive`.
+          hyperhive-assets = self.packages.${prev.stdenv.hostPlatform.system}.assets;
+          # Standalone docs/ tree (see nix/reference-docs.nix). Exposed
+          # via the overlay so the harness module can build the
+          # in-container agent docs dir from it.
+          hyperhive-docs = self.packages.${prev.stdenv.hostPlatform.system}.reference-docs;
+        };
+      };
+
+      nixosModules = {
+        agent-base = ./nix/templates/agent-base.nix;
+        ruth = ./nix/templates/manager.nix;
+        # The hive-c0re module wants `pkgs.hyperhive` for its default
+        # `services.hyperhive.c0re.package`. To avoid making operators apply an
+        # overlay (which would also pollute their host pkgs with our
+        # build), we thread the package straight from this flake's
+        # `packages.<system>.default` via a `hyperhivePackage` argument.
+        hive-c0re = import ./nix/modules/hive-c0re.nix {
+          hyperhivePackage = system: self.packages.${system}.default;
+          hyperhiveFrontend = system: self.packages.${system}.frontend;
+          hyperhiveAssets = system: self.packages.${system}.assets;
+          hyperhiveXdgIcons = system: self.packages.${system}.xdg-icons;
+          hyperhiveFlake = "${hyperhiveFlakeSource}";
+          # Narrow docs/ source, threaded as its own meta-flake input so
+          # doc edits don't re-hash the whole flake source.
+          hyperhiveDocs = "${hyperhiveDocsSource}";
+          # Per-container toplevels — wired into `system.extraDependencies`
+          # when `services.hyperhive.c0re.preBuildAgentTemplates` is on so the
+          # host system closure pre-fetches the heavy build inputs.
+          # Defined only for x86_64-linux because nixosConfigurations are
+          # hardcoded to that system; the option's default keeps the
+          # extra deps gated so aarch64 hosts don't accidentally pull
+          # them in via cross-build.
+          agentBaseToplevel = self.packages.x86_64-linux.agent-base-toplevel;
+          managerToplevel = self.packages.x86_64-linux.ruth-toplevel;
+        };
+        hive-ci = ./nix/modules/hive-ci.nix;
+        hive-forge = ./nix/modules/hive-forge.nix;
+        # Convenience alias: one import covers the full hyperhive host
+        # stack (hive-c0re + hive-forge, since hive-c0re already pulls
+        # in hive-forge). Intended usage:
         #
         #   imports = [ hyperhive.nixosModules.default ];
         #   services.hyperhive.enable = true;
         #
-          default =
+        default = self.nixosModules.hive-c0re;
-            { lib, pkgs, ... }:
-            {
-              imports = [ ./nix/host-modules ];
-              services.hyperhive.c0re = {
-                package = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.default;
-                frontend = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.frontend;
-                assets = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.assets;
-                xdgIcons = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.xdg-icons;
-                hyperhiveFlake = lib.mkDefault "${sources.hyperhiveFlakeSource}";
-                # Narrow docs/ source, threaded as its own meta-flake input
-                # so doc edits don't re-hash the whole flake source.
-                hyperhiveDocs = lib.mkDefault "${sources.hyperhiveDocsSource}";
-                # Per-container toplevels — wired into
-                # `system.extraDependencies` when
-                # `services.hyperhive.c0re.preBuildAgentTemplates` is on so
-                # the host system closure pre-fetches the heavy build
-                # inputs. x86_64-linux only (nixosConfigurations are
-                # hardcoded to that system); the gate keeps aarch64 hosts
-                # from pulling them in via cross-build.
-                agentBaseToplevel = lib.mkDefault self.packages.x86_64-linux.agent-base-toplevel;
-                managerToplevel = lib.mkDefault self.packages.x86_64-linux.ruth-toplevel;
-              };
-            };
-          hive-ci = ./nix/host-modules/hive-ci.nix;
-          hive-forge = ./nix/host-modules/hive-forge;
       };
 
       nixosConfigurations =
@@ -152,7 +433,14 @@
             module:
             nixpkgs.lib.nixosSystem {
               system = "x86_64-linux";
-              modules = [ module ];
+              modules = [
+                module
+                {
+                  nixpkgs.overlays = [
+                    self.overlays.default
+                  ];
+                }
+              ];
             };
         in
         {
@@ -160,7 +448,23 @@
           ruth = mkContainer self.nixosModules.ruth;
         };
 
-      devShells = forAllSystems ({ pkgs, rust, ... }: import ./nix/devshell.nix { inherit pkgs rust; });
+      devShells = forAllSystems (
+        { pkgs, ... }:
+        {
+          default = pkgs.mkShell {
+            packages = with pkgs; [
+              cargo
+              clippy
+              librsvg # rsvg-convert — hive-c0re/build.rs invokes it
+              pkg-config
+              rust-analyzer
+              rustc
+              rustfmt
+              sqlite
+            ];
+          };
+        }
+      );
 
       formatter = forAllSystems ({ treefmt-eval, ... }: treefmt-eval.config.build.wrapper);
 
@@ -170,18 +474,84 @@
           system,
           treefmt-eval,
           craneLib,
-          rust,
+          cleanSrc,
+          cargoArtifacts,
+          nativeBuildInputs,
           ...
         }:
-        import ./nix/checks.nix {
+        {
-          inherit
+          formatting = treefmt-eval.config.build.check self;
-            pkgs
+          # Clippy as a check via crane's first-class `cargoClippy`
-            craneLib
+          # builder. Reuses the shared `cargoArtifacts` (deps already
-            rust
+          # built) and runs `cargo clippy --workspace --all-targets`
-            self
+          # directly — no `overrideAttrs` hack needed, because crane
-            system
+          # parses `cargoClippyExtraArgs` correctly (naersk's
-            treefmt-eval
+          # `mode = "clippy"` used to mangle the `--` separator, which
-            ;
+          # is why the old wiring went through overrideAttrs).
+          #
+          # `-D warnings` makes the default/correctness/style lints a
+          # hard CI gate. `-A clippy::pedantic` then drops the pedantic
+          # group from that gate: pedantic is the "extra, opinionated"
+          # group the clippy team grows freely, so denying it means
+          # every toolchain bump that adds a new pedantic lint breaks CI
+          # with zero code changes. The `pedantic = warn`
+          # workspace lint (Cargo.toml) keeps it as advisory signal in
+          # local `cargo clippy` — it just no longer blocks the build.
+          # (`-A` rather than `-W` here: `-W clippy::pedantic` would
+          # re-enable the specific pedantic lints the workspace lints
+          # table allows, e.g. `must_use_candidate`.)
+          clippy = craneLib.cargoClippy {
+            src = cleanSrc;
+            inherit cargoArtifacts nativeBuildInputs;
+            pname = "hyperhive-workspace";
+            version = "0.1.0";
+            cargoClippyExtraArgs = "--workspace --all-targets -- -D warnings";
+          };
+          # `cargo test --workspace` lifted out of `buildPackage` so the
+          # `hyperhive-assets` dep (which `hive-ag3nt::prompt::tests`
+          # needs via `HIVE_ASSETS_DIR` to assert against the actual
+          # production prompt template) is scoped to this one check
+          # instead of bleeding into the binary derivation's input
+          # hash. Net: editing `hive-ag3nt/prompts/system.md` still
+          # rebuilds this test check (correct — the tests assert
+          # against its wording), but `packages.default` and the
+          # per-container toplevels stay fully cached.
+          cargo-test = craneLib.cargoTest {
+            src = cleanSrc;
+            inherit cargoArtifacts nativeBuildInputs;
+            pname = "hyperhive-workspace";
+            version = "0.1.0";
+            cargoTestExtraArgs = "--workspace";
+            HIVE_ASSETS_DIR = "${self.packages.${system}.assets}/share/hyperhive";
+          };
+          # Nix options docs evaluation. Cheap: pulls in
+          # `nixosOptionsDoc` + the host module's stub eval, no rust or
+          # frontend deps. CI fails fast if a module change breaks
+          # option declarations or the doc rendering. Reuses the
+          # `packages.<system>.docs` derivation so the per-system eval
+          # of `nix/docs/default.nix` happens once.
+          inherit (self.packages.${system}) docs;
+          # `hivectl` CLI reference freshness check. The committed
+          # markdown at `docs/tools/hivectl-cli.md` is the rendered
+          # output of the hidden `hivectl markdown-docs` subcommand
+          # (clap-markdown walks the binary's own command tree). This
+          # check regenerates it from the built binary and fails if the
+          # committed copy drifted — so a verb / flag / help-string edit
+          # that forgets to refresh the doc is caught in CI. Reuses the
+          # already-built `packages.<system>.default` (no extra compile).
+          # Regenerate locally with:
+          #   nix build .#default
+          #   ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md
+          hivectl-docs = pkgs.runCommand "hivectl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
+            ${self.packages.${system}.default}/bin/hivectl markdown-docs > generated.md
+            if ! diff -u ${./docs/tools/hivectl-cli.md} generated.md; then
+              echo "" >&2
+              echo "ERROR: docs/tools/hivectl-cli.md is out of date — regenerate it:" >&2
+              echo "  nix build .#default && ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md" >&2
+              exit 1
+            fi
+            touch "$out"
+          '';
         }
       );
     };

hive-ag3nt/src/events.rs

@@ -489,7 +489,7 @@ pub fn configured_effort() -> Option<&'static str> {
 
 /// Context-window size in tokens for a given model name.
 ///
-/// Canonical per-model sizes are declared in the harness nix modules as
+/// Canonical per-model sizes are declared in `harness-base.nix` as
 /// `hyperhive.contextWindowTokens` and injected as
 /// `HIVE_CONTEXT_WINDOW_TOKENS_<KEY_UPPER>` env vars — so this function
 /// normally just reads them. The Rust code carries no model knowledge;

hive-ag3nt/src/mcp_config.rs

@@ -14,7 +14,7 @@ pub const SERVER_NAME: &str = "hyperhive";
 /// Default loopback port the built-in hyperhive MCP surface is served on
 /// (streamable HTTP, via the persistent `hive-mcp-http` daemon). Overridable
 /// via `hyperhive.mcp.httpPort`; **must match that option's default** in
-/// `nix/templates/harness/`. Safe as a single fixed value across all
+/// `nix/templates/harness-base.nix`. Safe as a single fixed value across all
 /// agents because each container runs in its own private network namespace,
 /// so `127.0.0.1:<port>` is per-container-private (no cross-agent collision).
 pub const DEFAULT_MCP_HTTP_PORT: u16 = 8790;
@@ -246,13 +246,13 @@ pub fn builtin_tools_arg() -> String {
 }
 
 /// Where the NixOS module writes the per-agent extra-MCP spec (see
-/// `nix/templates/harness/`). Each entry becomes an additional
+/// `nix/templates/harness-base.nix`). Each entry becomes an additional
 /// `mcpServers.<key>` block in the rendered claude config + a
 /// `mcp__<key>__<tool>` pattern in `--allowedTools`.
 const EXTRA_MCP_PATH: &str = "/etc/hyperhive/extra-mcp.json";
 
 /// Where the NixOS module writes the per-agent send allow-list (see
-/// `nix/templates/harness/`). Empty list = unrestricted (the
+/// `nix/templates/harness-base.nix`). Empty list = unrestricted (the
 /// default). Non-empty list constrains `mcp__hyperhive__send`'s `to`
 /// field; the manager is always implicitly permitted regardless of
 /// the list contents.

hive-c0re/src/lifecycle/host_config.rs

@@ -158,7 +158,7 @@ async fn set_nspawn_flags(
     // Claude credentials land at `/home/<agent>/.claude` so the
     // `claude` CLI (which reads `$HOME/.claude`) finds them. The
     // harness service's environment sets `HOME` to the same path
-    // (`agent.nix` / `ruth.nix` templates), so no `--setenv` plumbing
+    // (`agent-base.nix` / `manager.nix`), so no `--setenv` plumbing
     // is needed here — the bind alone is enough.
     let claude_mount = container_claude_mount(agent_name);
 

hive-c0re/src/lifecycle/mod.rs

@@ -169,7 +169,7 @@ pub fn agent_uid_gid(agent_name: &str) -> Option<(u32, u32)> {
 /// uid/gid via [`agent_uid_gid`] and shells out to `std::os::unix::fs::chown`.
 /// Silently no-ops when the container isn't built yet (`None` from
 /// [`agent_uid_gid`]) and logs at debug on chown syscall failure — the
-/// activation script in the harness user module is the steady-state safety
+/// activation script in `harness-base.nix` is the steady-state safety
 /// net. Used by per-agent state writers in `forge` + `matrix` so the
 /// agent can read the file without waiting for the next container
 /// rebuild.

hive-c0re/src/meta.rs

@@ -701,7 +701,7 @@ struct OtelConfig {
 /// Read the hive-wide OTEL config from env, or `None` when OTEL is off.
 /// Mirrors `hive_ca_source` — host state surfaced to the meta renderer
 /// so it can bake build-time `hyperhive.otel.*` config into each agent
-/// (the per-agent options the harness modules consume). Returns `None`
+/// (the per-agent options harness-base.nix consumes). Returns `None`
 /// when the endpoint signal is absent so the renderer emits no
 /// `hyperhive.otel.*` lines and agents keep the disabled default.
 fn otel_config() -> Option<OtelConfig> {
@@ -914,7 +914,7 @@ where
     // re-locks THIS input instead of re-hashing the whole `hyperhive`
     // source. Threaded to each agent below as `hyperhive.docs.source`.
     // Empty = hive-c0re not built with the option wired up (legacy);
-    // agents then keep the harness default (`hyperhive.packages.reference-docs`).
+    // agents then keep the harness-base default (`pkgs.hyperhive-docs`).
     if !docs_flake.is_empty() {
         // `flake = false`: the docs/ tree is a plain source (no flake.nix),
         // so nix must treat it as raw source, not evaluate it as a flake.
@@ -971,8 +971,8 @@ where
 "#,
     );
     // Point the in-container docs dir (`$HIVE_DOCS_DIR`) at the narrow
-    // `hyperhive-docs` input instead of the harness default
+    // `hyperhive-docs` input instead of the harness-base default
-    // (`hyperhive.packages.reference-docs`, built from the now-docs-stripped source).
+    // (`pkgs.hyperhive-docs`, built from the now-docs-stripped source).
     // `inputs."hyperhive-docs"` is reachable via the outputs `@inputs`
     // capture. Emitted only when the input exists (docs_flake non-empty).
     if !docs_flake.is_empty() {
@@ -1000,7 +1000,7 @@ where
         );
     }
     // Hive-wide OTEL stats export (`services.hyperhive.otel.*`): inject the
-    // build-time `hyperhive.otel.*` config the harness modules consume (its
+    // build-time `hyperhive.otel.*` config harness-base.nix consumes (its
     // otelEnv + otelExecStart wrapper + LoadCredential). Host-driven, so
     // the same config lands on every agent; emitted only when enabled.
     // Mirrors the CA-cert injection above — host state -> build-time agent
@@ -1055,7 +1055,7 @@ where
               # `iris`, `root`, …). UID auto-assigned by NixOS; the
               # per-agent override here is what makes
               # `hyperhive.user.name` match the agent's identity
-              # instead of the harness default of `"agent"`.
+              # instead of the harness-base default of `"agent"`.
               hyperhive.user.name = name;
               programs.git.config.user = {
                 name = name;
@@ -1416,7 +1416,7 @@ mod tests {
             "old-style follows must not appear when flake args are set:\n{out}"
         );
         // the narrow docs source is its own non-flake input, and each
-        // agent's docs dir resolves from it rather than hyperhive.packages.reference-docs.
+        // agent's docs dir resolves from it rather than pkgs.hyperhive-docs.
         assert!(
             out.contains("hyperhive-docs.url = \"path:/nix/store/bbbb-hyperhive-docs-source\""),
             "expected hyperhive-docs input url:\n{out}"
@@ -1434,7 +1434,7 @@ mod tests {
     #[test]
     fn render_flake_omits_docs_input_when_docs_flake_empty() {
         // Legacy / not-wired-up: empty docs_flake emits no docs input and
-        // leaves each agent on the harness default (hyperhive.packages.reference-docs).
+        // leaves each agent on the harness-base default (pkgs.hyperhive-docs).
         let out = render_flake(
             "github:example/hyperhive",
             "",
@@ -1674,7 +1674,7 @@ mod tests {
         // services.hyperhive.otel.* -> HYPERHIVE_OTEL_* on hive-c0re's unit
         // -> injected as build-time hyperhive.otel.* into every agent. With
         // no endpoint signal, no hyperhive.otel lines are emitted (agents
-        // keep the the harness modules disabled default).
+        // keep the harness-base disabled default).
         //
         // SAFETY: single-threaded mutation of process env vars no other
         // test asserts on; restored before returning.

hive-c0re/src/paths.rs

@@ -42,7 +42,7 @@ pub const HOST_SOCKET: &str = "/run/hyperhive/host.sock";
 
 /// `/run/hive-agent` — per-agent runtime socket dir root (web + bound
 /// markers), one subdir per agent.
-// nix: agent container bind-mount / `RuntimeDirectory` (the harness nix modules) — must match.
+// nix: agent container bind-mount / `RuntimeDirectory` (harness-base.nix) — must match.
 pub const AGENT_SOCKET_DIR: &str = "/run/hive-agent";
 
 /// Default broker db path (`db/broker.sqlite`). Exposed as a `&str` for
@@ -162,7 +162,7 @@ pub fn agent_sockets_file() -> PathBuf {
 /// bind-mounted into each container as `/agents/<name>`). A `&str` (the
 /// dashboard state-file allow-list uses it for `strip_prefix` /
 /// `starts_with` checks), so it stays a const; [`agents_root`] wraps it.
-// nix: agent container bind-mount source (harness modules / agent.nix template) — must match.
+// nix: agent container bind-mount source (harness-base.nix / agent-base.nix) — must match.
 // sh4re: `hive_sh4re::priv_proto::AGENT_STATE_ROOT` is the same value and must stay in sync;
 //        the privsep boundary prevents importing across the crate.
 pub const AGENTS_ROOT: &str = "/var/lib/hyperhive/agents";
@@ -200,7 +200,7 @@ pub fn applied_rev_marker(name: &str) -> PathBuf {
 }
 
 /// `meta/` — the meta flake working tree (inputs, `flake.lock`, `.git`).
-// nix: bind-mounted read-only into agent containers as `/meta` (the harness nix modules) — must match.
+// nix: bind-mounted read-only into agent containers as `/meta` (harness-base.nix) — must match.
 #[must_use]
 pub fn meta_root() -> PathBuf {
     state_root().join("meta")
@@ -222,7 +222,7 @@ pub fn meta_git_index_lock() -> PathBuf {
 /// `shared/` — the cross-agent `/shared` scratch space. A `&str` (the
 /// dashboard state-file allow-list uses it for prefix checks), so it
 /// stays a const; [`shared_root`] wraps it.
-// nix: bind-mounted into every agent container as `/shared` (the harness nix modules) — must match.
+// nix: bind-mounted into every agent container as `/shared` (harness-base.nix) — must match.
 pub const SHARED_ROOT: &str = "/var/lib/hyperhive/shared";
 
 #[must_use]
@@ -233,7 +233,7 @@ pub fn shared_root() -> PathBuf {
 /// `knowledge/` — local checkout of the `internal/knowledge` repo. A
 /// `&str` (used as a git `-C` arg / clone target throughout the knowledge
 /// worker), so it stays a const rather than a `PathBuf` fn.
-// nix: bind-mounted read-only into agent containers as `/knowledge` (the harness nix modules) — must match.
+// nix: bind-mounted read-only into agent containers as `/knowledge` (harness-base.nix) — must match.
 pub const KNOWLEDGE_DIR: &str = "/var/lib/hyperhive/knowledge";
 
 /// `gateway/` — generated nginx include fragments for the gateway vhost.

nix/agent-modules/agent-service.nix

@@ -1,245 +0,0 @@
-# The hive-ag3nt harness service itself, plus the per-agent knobs it
-# reads from its environment: model selection, effort level,
-# compaction watermark, and the extra reverse-proxies of the per-agent
-# web UI.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-  homeDir = "/home/${userName}";
-in
-{
-  options.hyperhive.model = lib.mkOption {
-    type = lib.types.str;
-    default = "haiku";
-    example = "sonnet";
-    description = ''
-      Claude model for this agent. Sets the `HIVE_DEFAULT_MODEL`
-      environment variable; the harness applies it at boot and it takes
-      priority over any persisted runtime override. The operator can still
-      switch the model at runtime via the per-agent web UI — that choice
-      is tracked in the state dir for the current session but is reset by
-      any rebuild that changes this option.
-
-      Valid values are the short model names that `claude --model` accepts:
-      `"haiku"`, `"sonnet"`, `"opus"` (or any future identifier). Context
-      window sizes are looked up at runtime from the
-      `HIVE_CONTEXT_WINDOW_TOKENS_<KEY_UPPER>` env vars injected by the
-      meta flake; override sizes via `services.hyperhive.c0re.contextWindowTokens`
-      on the host.
-    '';
-  };
-
-  options.hyperhive.availableModels = lib.mkOption {
-    type = lib.types.listOf lib.types.str;
-    default = [
-      "haiku"
-      "sonnet"
-      "opus"
-    ];
-    example = [
-      "sonnet"
-      "opus"
-    ];
-    description = ''
-      Models offered in the per-agent web UI's model quick-picker. Rendered
-      into the `HIVE_AVAILABLE_MODELS` environment variable (comma-separated)
-      which the harness surfaces to the agent UI, so the picker lists exactly
-      these models instead of a hardcoded set.
-
-      Configure hive-wide by setting a shared default (e.g. in your
-      `agent.nix` shared defaults) or per-agent to narrow the menu — for example a
-      haiku-only agent can hide `opus` and `sonnet`. The *current* model is
-      still set by `hyperhive.model` and remains switchable at runtime via the
-      UI; this option only controls which choices the picker presents.
-
-      Values are the short model names that `claude --model` accepts:
-      `"haiku"`, `"sonnet"`, `"opus"` (or any future identifier).
-    '';
-  };
-
-  options.hyperhive.effortLevel = lib.mkOption {
-    type = lib.types.enum [
-      "low"
-      "medium"
-      "high"
-      "xhigh"
-      "max"
-    ];
-    default = "medium";
-    example = "high";
-    description = ''
-      Baseline claude effort level for this agent. Rendered into the
-      `HIVE_DEFAULT_EFFORT` environment variable; the harness resolves
-      effort as operator-override-file → this env → built-in `"medium"`,
-      and passes the result to `claude --effort` at turn launch.
-
-      Ascending scale: `"low"` (minimal thinking budget), `"medium"`
-      (default — balanced), `"high"` (platform default), `"xhigh"`
-      (recommended for autonomous coding on capable models), `"max"`
-      (maximum thinking budget, highest cost). The operator can override
-      at runtime per-agent via the web UI (applied on the next session);
-      any rebuild that changes this option resets that override.
-    '';
-  };
-
-  options.hyperhive.autoCompact = lib.mkOption {
-    type = lib.types.bool;
-    default = true;
-    description = ''
-      Enable proactive watermark-based compaction. When `true` (the
-      default) the harness automatically runs a notes-checkpoint turn
-      followed by `/compact` once the context window crosses 75% of
-      the model's limit, keeping later turns from hitting the hard
-      overflow path. Set to `false` to disable proactive compaction
-      entirely (`HIVE_COMPACT_WATERMARK_TOKENS=0`); the reactive path
-      (compact-on-overflow when the session is already past the limit)
-      still applies.
-
-      Disable for agents that run large-context models (sonnet/opus)
-      where the heuristic fires too early and discards useful history
-      before the session is actually close to the limit.
-    '';
-  };
-
-  options.hyperhive.extraWebProxies = lib.mkOption {
-    type = lib.types.attrsOf lib.types.str;
-    default = { };
-    example = lib.literalExpression ''{ "stats" = "http://127.0.0.1:3737"; }'';
-    description = ''
-      Transparent reverse-proxies mounted under `/extra/` in the per-agent web UI.
-      Each attribute name becomes the sub-path and the value is the upstream.
-      E.g. `{ "stats" = "http://127.0.0.1:3737"; }` mounts a proxy at
-      `/agent/<name>/extra/stats/` that forwards to port 3737 with the prefix
-      stripped. All user-declared proxies live under `/extra/` so they can
-      never conflict with native agent endpoints (`/api/*`, `/events/*`, etc.).
-
-      The upstream value is either an `http(s)://` URL or a Unix domain
-      socket, spelled `unix:<path>` (e.g. `unix:/run/myapp/http.sock`) — for
-      agents whose secondary web server only listens on a UDS.
-
-      Intended for agents that run secondary web servers in the same container.
-      Static assets served by the secondary app must use relative paths to
-      resolve correctly under the sub-path prefix.
-
-      Sets the `HIVE_EXTRA_WEB_PROXIES` environment variable (JSON object)
-      on the harness service unit.
-    '';
-  };
-
-  config = {
-    assertions = [
-      # hyperhive.model must be a non-empty string — an empty value causes
-      # the harness to pass an invalid model flag to claude.
-      {
-        assertion = config.hyperhive.model != "";
-        message = "hyperhive.model must not be empty (set it to e.g. \"haiku\" or \"sonnet\")";
-      }
-      # The current model must appear in the quick-picker menu, otherwise the
-      # UI would offer no way back to the model the agent is actually running.
-      {
-        assertion =
-          config.hyperhive.availableModels == [ ]
-          || builtins.elem config.hyperhive.model config.hyperhive.availableModels;
-        message =
-          "hyperhive.model (\"${config.hyperhive.model}\") must be one of "
-          + "hyperhive.availableModels ([ ${lib.concatStringsSep " " config.hyperhive.availableModels} ]) "
-          + "— add it to the list or change the model.";
-      }
-    ];
-
-    # HIVE_DEFAULT_MODEL seeds the initial model selection when no
-    # persisted model choice exists in the state dir.
-    environment.variables = {
-      HIVE_DEFAULT_MODEL = config.hyperhive.model;
-      # Comma-separated menu for the per-agent UI model quick-picker
-      # (see hyperhive.availableModels). The harness surfaces it to the
-      # frontend; an empty value falls back to the built-in default list.
-      HIVE_AVAILABLE_MODELS = lib.concatStringsSep "," config.hyperhive.availableModels;
-      # Per-agent baseline effort (see hyperhive.effortLevel). The
-      # harness resolves operator-override-file → this env → "medium"
-      # and passes it to claude --effort at turn launch.
-      HIVE_DEFAULT_EFFORT = config.hyperhive.effortLevel;
-    }
-    // lib.optionalAttrs (!config.hyperhive.autoCompact) {
-      # Zero watermark disables proactive compaction; the reactive path
-      # (compact-on-overflow) still fires when the session is truly full.
-      HIVE_COMPACT_WATERMARK_TOKENS = "0";
-    };
-
-    # Harness systemd unit. Unit shape (PATH wrapper-dir trick, env vars,
-    # RuntimeDirectory, User=, standalone-eval fallbacks):
-    # docs/agent-hierarchy.md::Harness systemd unit shape. PATH /bin
-    # auto-append behaviour: docs/gotchas.md::systemd.services.*.path
-    # appends /bin to every entry.
-    systemd.services.hive-ag3nt =
-      let
-        binary = "hive-agent";
-      in
-      {
-        description = "${binary} harness";
-        wantedBy = [ "multi-user.target" ];
-        after = [ "network.target" ];
-        # `/run/wrappers` before `/run/current-system/sw` so setuid
-        # `sudo` resolves first. Passing the bare prefixes (no trailing
-        # `/bin`) is intentional — see docs pointer above.
-        path = [
-          "/run/wrappers"
-          "/run/current-system/sw"
-        ];
-        environment = {
-          SHELL = "${pkgs.bashInteractive}/bin/bash";
-          HOME = homeDir;
-          HIVE_STATIC_DIR = "${config.hyperhive.frontend.mergedDist}";
-          HIVE_ASSETS_DIR = "${config.hyperhive.packages.assets}/share/hyperhive";
-          # Unix-socket path for the harness web UI. All agents always bind
-          # here; there is no TCP fallback. Path matches
-          # `hive_c0re::agent_sockets::socket_path_for(name)` so lifecycle
-          # bind-mounts and gateway upstream config stay in sync.
-          HIVE_WEB_SOCKET = "/run/hive-agent/${userName}/web.sock";
-          # Loopback URL of the persistent `hive-mcp-http` daemon that
-          # `render_claude_config` points claude at for the built-in
-          # surface (HTTP is the sole transport — no per-turn stdio child).
-          # Kept in sync with the `hive-mcp-http` unit's `--http` port
-          # (see ./mcp.nix) via the same option. Always set — network
-          # isolation is unconditional, so a fixed per-container port is
-          # collision-free.
-          HYPERHIVE_MCP_HTTP_PORT = toString config.hyperhive.mcp.httpPort;
-        }
-        // lib.optionalAttrs config.hyperhive.gui.enable {
-          # Tells the harness which fixed VNC port weston bound, and (by
-          # its presence) that gui is enabled — the harness `/screen/ws`
-          # relay reads this instead of a runtime marker file. The port is
-          # container-local + fixed (network isolation is unconditional),
-          # so the same value for every gui agent is fine. See
-          # ./weston-vnc.nix::hyperhive.gui.vncPort.
-          HIVE_GUI_VNC_PORT = toString config.hyperhive.gui.vncPort;
-        }
-        // lib.optionalAttrs (config.hyperhive.extraWebProxies != { }) {
-          # JSON object {"<path>": "<upstream>"} for the transparent
-          # reverse-proxies. See `hyperhive.extraWebProxies` option
-          # and `web_ui/proxy.rs::extra_proxy_service`.
-          HIVE_EXTRA_WEB_PROXIES = builtins.toJSON config.hyperhive.extraWebProxies;
-        };
-        serviceConfig = {
-          ExecStart = "${config.hyperhive.packages.hive-agent}/bin/${binary}";
-          # Pin the journal identity to the binary name (otherwise systemd
-          # derives SyslogIdentifier from the ExecStart basename).
-          SyslogIdentifier = binary;
-          Restart = "on-failure";
-          RestartSec = 2;
-          # Per-service runtime dir owned by `User=` below; the harness
-          # writes its regenerated claude-{mcp-config,settings,system-prompt}
-          # files here (`paths::config_dir`). Separate from /run/hive,
-          # which holds hive-c0re's mcp.sock.
-          RuntimeDirectory = "hive-config";
-          User = userName;
-          Group = userName;
-        };
-      };
-  };
-}

nix/agent-modules/bash-env.nix

@@ -1,134 +0,0 @@
-# Shell-environment feature hooks: the `_bashEnvFragments`
-# accumulator, the `/etc/hyperhive/bash-env.sh` file it renders to,
-# and the cargo `--message-format short` injector that contributes to
-# it. Loaded via `$BASH_ENV` for non-interactive shells (claude's
-# `Bash` tool runs `bash -c`) and via `programs.bash` for interactive
-# ones.
-{
-  lib,
-  config,
-  ...
-}:
-{
-  # Internal accumulator for shell snippets that should land in
-  # `/etc/hyperhive/bash-env.sh`. Per-feature hooks set this via
-  # `lib.mkIf` gated on their own option; the lines type merges
-  # all contributions across modules into one file. Generic by
-  # design so future hooks don't need to rename this file or
-  # invent a parallel dispatcher.
-  options.hyperhive._bashEnvFragments = lib.mkOption {
-    type = lib.types.lines;
-    default = "";
-    internal = true;
-    description = ''
-      Shell snippets concatenated into `/etc/hyperhive/bash-env.sh`.
-      Feature hooks contribute via `lib.mkIf` gated on their own
-      option. When empty, the file isn't created, `BASH_ENV` stays
-      unset, and the interactive bashrc hook is omitted — zero cost
-      when no feature is on. Internal — set indirectly via the
-      per-feature options that own the gate (e.g.
-      `hyperhive.cargo.shortMessages`).
-    '';
-  };
-
-  options.hyperhive.cargo.shortMessages = lib.mkOption {
-    type = lib.types.bool;
-    default = true;
-    example = false;
-    description = ''
-      Auto-inject `--message-format short` on cargo compile
-      subcommands (`build`, `check`, `clippy`, `test`, `run`,
-      `doc`, `bench`, `install`, `rustc`, `fix`) when claude (or
-      anything else) invokes `cargo` inside this container.
-      Saves tokens + context — the verbose default output floods
-      the response window with per-crate progress lines that
-      carry no signal beyond the warning/error summary.
-
-      Implementation: contributes a `cargo` shell function to
-      `/etc/hyperhive/bash-env.sh` (see `hyperhive._bashEnvFragments`).
-      Loaded via `BASH_ENV` for non-interactive shells (`bash -c` —
-      what the claude `Bash` tool runs) and sourced from
-      `programs.bash.interactiveShellInit` for interactive shells.
-      The function:
-
-      - handles the `+toolchain` selector prefix (`cargo +nightly
-        build` works);
-      - passes through cleanly when the caller already specified
-        `--message-format` (any form);
-      - leaves non-compile subcommands (`new`, `add`, `search`,
-        third-party `cargo-*` subcommands) untouched so they
-        don't error on the unknown flag.
-
-      Set to `false` for agents that need full cargo output (e.g.
-      tooling that parses `--message-format json` programmatically
-      and doesn't pass the flag explicitly).
-    '';
-  };
-
-  config = {
-    # Cargo `--message-format short` injector. `command cargo …` falls
-    # back to the un-wrapped binary in PATH (the rust toolchain's cargo
-    # — either from `environment.systemPackages` or from whatever
-    # `nix develop` shell the agent's working in).
-    hyperhive._bashEnvFragments = lib.mkIf config.hyperhive.cargo.shortMessages ''
-      # Auto-injects --message-format short on cargo compile
-      # subcommands so per-crate progress lines don't flood
-      # claude's context. Bypassed when the caller already passes
-      # --message-format (any form).
-      cargo() {
-        # Strip leading +toolchain selectors (cargo +nightly …).
-        local pre=()
-        while [ "''${1:0:1}" = "+" ] && [ -n "''${1:-}" ]; do
-          pre+=("$1")
-          shift
-        done
-        case "''${1:-}" in
-          build|check|clippy|test|run|doc|bench|install|rustc|fix)
-            local sub="$1"
-            shift
-            local arg
-            for arg in "$@"; do
-              case "$arg" in
-                --message-format|--message-format=*)
-                  command cargo "''${pre[@]}" "$sub" "$@"
-                  return $?
-                  ;;
-              esac
-            done
-            command cargo "''${pre[@]}" "$sub" --message-format short "$@"
-            ;;
-          *)
-            command cargo "''${pre[@]}" "$@"
-            ;;
-        esac
-      }
-    '';
-
-    # Single bash-env file with all configured shell fragments.
-    # Wiring is gated on at least one fragment being active so a
-    # fully feature-disabled agent has neither the file nor the
-    # `BASH_ENV` / interactive sourcing — zero cost in that case.
-    environment.etc."hyperhive/bash-env.sh" = lib.mkIf (config.hyperhive._bashEnvFragments != "") {
-      text = config.hyperhive._bashEnvFragments;
-    };
-
-    # Non-interactive bash invocations (claude's `Bash` tool runs
-    # `bash -c`) source $BASH_ENV at startup — drops every active
-    # feature hook's snippet into scope without touching
-    # `/etc/profile` (login-only).
-    environment.variables = lib.mkIf (config.hyperhive._bashEnvFragments != "") {
-      BASH_ENV = "/etc/hyperhive/bash-env.sh";
-    };
-
-    # Interactive shells don't honour BASH_ENV — wire the same file
-    # in via the bashrc hook so operator SSH sessions get the same
-    # hook surface as claude's non-interactive calls. Gated on at
-    # least one fragment being active so we don't write a no-op
-    # source line into `/etc/bashrc` on fully-feature-disabled agents.
-    programs.bash.interactiveShellInit = lib.mkIf (config.hyperhive._bashEnvFragments != "") ''
-      if [ -r /etc/hyperhive/bash-env.sh ]; then
-        . /etc/hyperhive/bash-env.sh
-      fi
-    '';
-  };
-}

nix/agent-modules/claude-settings.nix

@@ -1,376 +0,0 @@
-# Everything that shapes claude-code's own configuration inside the
-# container: the managed settings json (base env + OTEL), the
-# onboarding/trust seed, the runtime OTEL auth-header injection, and
-# the plugin/marketplace install lists the harness reads at boot.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-  homeDir = "/home/${userName}";
-  # Hive-wide OpenTelemetry config (host-driven; baked in per-agent by
-  # meta.rs `otel_config`).
-  otelCfg = config.hyperhive.otel;
-  # Hive/swarm display names are forwarded into each agent's build by
-  # meta.rs as `environment.variables` (per-agent, build-time strings),
-  # so they can be baked into the resource attributes below without a
-  # runtime shell. Absent (option unset) → "unknown".
-  hiveDisplayName = config.environment.variables.HYPERHIVE_HIVE_NAME or "unknown";
-  swarmDisplayName = config.environment.variables.HYPERHIVE_SWARM_NAME or "unknown";
-  # Base claude-code environment applied to every agent regardless of OTEL.
-  # Shipped via the managed settings `env` block so claude and `hivectl
-  # choom` both inherit them without a launch wrapper.
-  baseClaudeEnv = {
-    # Suppress analytics, survey pings, and other non-essential outbound
-    # traffic — agents are headless and don't need any of that.
-    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
-    DO_NOT_TRACK = "1";
-    # Disable claude's self-update machinery; package management is nix's job.
-    DISABLE_AUTOUPDATER = "1";
-    DISABLE_UPDATES = "1";
-    # Keep plugin updates synchronized on install; prefer HTTPS for fetches.
-    CLAUDE_CODE_PLUGIN_PREFER_HTTPS = "1";
-    CLAUDE_CODE_SYNC_PLUGIN_INSTALL = "1";
-    FORCE_AUTOUPDATE_PLUGINS = "1";
-    # Suppress the "install GitHub app" prompt — not applicable in-hive.
-    DISABLE_INSTALL_GITHUB_APP_COMMAND = "1";
-    # Disable Anthropic's hosted claude.ai MCP servers; the hive supplies its own.
-    ENABLE_CLAUDEAI_MCP_SERVERS = "0";
-    # Resume an interrupted turn on reconnect (recovers from transient MCP flaps).
-    CLAUDE_CODE_RESUME_INTERRUPTED_TURN = "1";
-    # Use the simpler system prompt variant suited to headless operation.
-    CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT = "1";
-    # Tag remote-control sessions with "<hive>-<agent>" for identification.
-    CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX = "${hiveDisplayName}-${userName}";
-  };
-  # OTEL environment Claude Code reads to export metrics/logs/traces.
-  # Shipped via the managed claude settings json (below), which claude
-  # auto-discovers for BOTH the harness turn-loop and `hivectl choom` —
-  # so telemetry parity is declarative, with no launch wrapper. The
-  # auth header (`otel.headersCredential`) is deliberately NOT included
-  # here: it's a secret and this file lives in the world-readable nix
-  # store. It's injected at *runtime* into the agent's `0600`
-  # `~/.claude/settings.json` by the `hive-otel-header` oneshot below
-  # (claude merges the `env` from the user settings on top of these
-  # managed ones), so the token is read from disk at start and never
-  # touches the store.
-  otelSettingsEnv = {
-    CLAUDE_CODE_ENABLE_TELEMETRY = "1";
-    # Attach feedback-survey data to the OTEL pipeline.
-    CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL = "1";
-    OTEL_METRICS_EXPORTER = "otlp";
-    OTEL_LOGS_EXPORTER = "otlp";
-    OTEL_TRACES_EXPORTER = "otlp";
-    OTEL_EXPORTER_OTLP_PROTOCOL = otelCfg.protocol;
-    OTEL_EXPORTER_OTLP_ENDPOINT = otelCfg.endpoint;
-    # Force CUMULATIVE temporality — Claude Code defaults to DELTA,
-    # which Prometheus/Mimir-family backends (incl. grafana-lgtm)
-    # silently drop without a deltatocumulative processor.
-    OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE = "cumulative";
-    OTEL_RESOURCE_ATTRIBUTES =
-      "service.name=hyperhive-agent,agent=${userName},hive=${hiveDisplayName},swarm=${swarmDisplayName}"
-      + lib.optionalString (otelCfg.extraResourceAttributes != "") ",${otelCfg.extraResourceAttributes}";
-    # Include the Claude Code version label in emitted metrics.
-    OTEL_METRICS_INCLUDE_VERSION = "1";
-  }
-  // lib.optionalAttrs (otelCfg.metricIntervalMs != null) {
-    OTEL_METRIC_EXPORT_INTERVAL = toString otelCfg.metricIntervalMs;
-  };
-in
-{
-  # OTEL stats export is configured ONCE at host level via
-  # `services.hyperhive.otel.*` (see nix/host-modules/hive-c0re.nix) and
-  # injected into every agent's build by the meta-flake renderer
-  # (`hive-c0re/src/meta.rs::otel_config`). These per-agent options are
-  # the build-time implementation surface that injection writes into;
-  # they are not meant to be set directly in an agent.nix. Marked
-  # `internal` so the host option is the only documented operator knob.
-  options.hyperhive.otel = {
-    enable = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      internal = true;
-      description = ''
-        Export this agent's Claude Code stats (token usage, cost, tool
-        calls) to an OTLP endpoint via Claude Code's built-in
-        OpenTelemetry. Each agent's harness exports directly to the
-        collector, so it keeps working even when hive-c0re is down.
-        Host-driven: set `services.hyperhive.otel.enable` instead.
-      '';
-    };
-
-    endpoint = lib.mkOption {
-      type = lib.types.str;
-      default = "";
-      internal = true;
-      description = ''
-        OTLP collector endpoint, set as `OTEL_EXPORTER_OTLP_ENDPOINT`.
-        Host-driven via `services.hyperhive.otel.endpoint`.
-      '';
-    };
-
-    protocol = lib.mkOption {
-      type = lib.types.enum [
-        "http/protobuf"
-        "http/json"
-        "grpc"
-      ];
-      default = "http/protobuf";
-      internal = true;
-      description = ''
-        OTLP wire protocol, set as `OTEL_EXPORTER_OTLP_PROTOCOL`.
-        Host-driven via `services.hyperhive.otel.protocol`.
-      '';
-    };
-
-    headersCredential = lib.mkOption {
-      # `str`, not `path`: a `path`-typed *relative* literal (e.g.
-      # `./otel-headers`) is hash-copied into the world-readable nix store
-      # at eval time, which would defeat the whole point of this option.
-      # Keep it a string and require an absolute runtime path so the secret
-      # is only ever read from disk by systemd at start, never nix-stored.
-      type = lib.types.nullOr lib.types.str;
-      default = null;
-      internal = true;
-      description = ''
-        Absolute path to an operator-provided secret file whose contents
-        become `OTEL_EXPORTER_OTLP_HEADERS` (e.g.
-        `Authorization=Bearer <token>`). Host-driven via
-        `services.hyperhive.otel.headersCredential`.
-
-        The rest of the OTEL config ships in the world-readable managed
-        claude settings json, but the header is a secret, so it's handled
-        separately: hive-c0re forwards this file into the container's
-        systemd credential store, and the `hive-otel-header` oneshot
-        reads it at runtime (`LoadCredential`) and writes it into the
-        agent's `0600` `~/.claude/settings.json` `env` block. The token
-        is read from disk at start and never copied into the nix store or
-        the world-readable settings file.
-      '';
-    };
-
-    extraResourceAttributes = lib.mkOption {
-      type = lib.types.str;
-      default = "";
-      internal = true;
-      description = ''
-        Extra comma-separated entries appended to
-        `OTEL_RESOURCE_ATTRIBUTES` after the built-in
-        `service.name` / `agent` / `hive` / `swarm` labels.
-        Host-driven via `services.hyperhive.otel.extraResourceAttributes`.
-      '';
-    };
-
-    metricIntervalMs = lib.mkOption {
-      type = lib.types.nullOr lib.types.ints.positive;
-      default = null;
-      internal = true;
-      description = ''
-        Metric export interval in milliseconds, set as
-        `OTEL_METRIC_EXPORT_INTERVAL`. Null leaves Claude Code's 60s
-        default. Host-driven via `services.hyperhive.otel.metricIntervalMs`.
-      '';
-    };
-
-    debug = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      internal = true;
-      description = ''
-        Emit OTEL SDK diagnostics to stderr (`CLAUDE_CODE_OTEL_DIAG_STDERR=1`).
-        Host-driven via `services.hyperhive.otel.debug`.
-      '';
-    };
-  };
-
-  options.hyperhive.claudeMarketplaces = lib.mkOption {
-    type = lib.types.listOf lib.types.str;
-    default = [ "anthropics/claude-plugins-official" ];
-    example = [
-      "anthropics/claude-plugins-official"
-      "anthropics/claude-plugins-community"
-    ];
-    description = ''
-      Claude Code plugin marketplaces to add at harness boot. Each
-      entry is passed to `claude plugin marketplace add <source>`
-      (`owner/repo`, full git URL, or local path). Idempotent —
-      re-adding an existing marketplace is treated as success.
-      Required before `hyperhive.claudePlugins` entries that
-      reference a marketplace (e.g. `foo@claude-plugins-official`).
-      Rendered to `/etc/hyperhive/claude-marketplaces.json`.
-
-      Defaults to Anthropic's official marketplace; agents get it
-      out of the box without any per-agent.nix wiring.
-    '';
-  };
-
-  options.hyperhive.claudePlugins = lib.mkOption {
-    type = lib.types.listOf lib.types.str;
-    default = [ ];
-    example = [
-      "formatter@my-marketplace"
-      "thinking-tools@anthropics"
-    ];
-    description = ''
-      Claude Code plugins to install at harness boot. Each entry is
-      passed verbatim to `claude plugin install <spec>` once per
-      container start, before the turn loop opens. `claude plugin
-      install` is expected to be idempotent, so reinstalling on every
-      boot is cheap. Failures log a warning but do not abort boot — a
-      missing plugin is preferable to a non-serving agent. Rendered to
-      `/etc/hyperhive/claude-plugins.json`; the harness reads it via
-      `plugins::install_configured`.
-    '';
-  };
-
-  options.hyperhive.claudePluginsAutoUpdate = lib.mkOption {
-    type = lib.types.bool;
-    default = false;
-    description = ''
-      When true, the harness runs `claude plugin marketplace update`
-      before installing plugins at boot, pulling the latest index from
-      all configured marketplaces. Disabled by default — most agents
-      want pinned plugin versions and the network round-trip adds to
-      boot time. Enable for agents that should always install the latest
-      available version of their plugins.
-    '';
-  };
-
-  config = {
-    environment.etc."hyperhive/claude-plugins.json".text =
-      builtins.toJSON config.hyperhive.claudePlugins;
-
-    environment.etc."hyperhive/claude-marketplaces.json".text =
-      builtins.toJSON config.hyperhive.claudeMarketplaces;
-
-    environment.etc."hyperhive/claude-plugins-auto-update.json".text =
-      builtins.toJSON config.hyperhive.claudePluginsAutoUpdate;
-
-    # Hive-enforced claude settings. claude-code auto-discovers managed
-    # settings at this canonical Linux path (precedence #1, read-only,
-    # un-overridable by user/project/CLI) — so the harness doesn't pass
-    # `--settings` or copy the blob per turn. effortLevel is
-    # deliberately NOT shipped here: effort is controlled live via the
-    # `--effort` CLI flag (HIVE_DEFAULT_EFFORT / the per-agent UI slider),
-    # which managed scope would otherwise override and lock.
-    # Hive-enforced settings merged with a per-agent `env` block at BUILD
-    # time via `jq` (not eval-time `readFile`, which would be import-from-
-    # derivation). The `env` block is always present: `baseClaudeEnv` sets
-    # behaviour flags and the remote-control session prefix for every agent;
-    # `otelSettingsEnv` is merged on top when OTEL is enabled. claude-code
-    # auto-discovers this file in every context (harness turn-loop AND
-    # `hivectl choom`) so no launch wrapper is needed.
-    environment.etc."claude-code/managed-settings.json".source =
-      let
-        baseSettings = "${config.hyperhive.packages.assets}/share/hyperhive/prompts/claude-settings.json";
-        # Merge base env (always) with OTEL env (when enabled). jq is always
-        # run — `baseClaudeEnv` contains per-agent values (e.g.
-        # CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX) that can't live in the
-        # static store asset.
-        allEnv =
-          baseClaudeEnv
-          // lib.optionalAttrs otelCfg.enable otelSettingsEnv
-          // lib.optionalAttrs (otelCfg.enable && otelCfg.debug) {
-            # SDK diagnostics — noisy; only on when services.hyperhive.otel.debug = true.
-            CLAUDE_CODE_OTEL_DIAG_STDERR = "1";
-          };
-      in
-      pkgs.runCommand "managed-settings.json" { nativeBuildInputs = [ pkgs.jq ]; } ''
-        jq --argjson env ${lib.escapeShellArg (builtins.toJSON allEnv)} \
-          '. + { env: $env }' ${baseSettings} > "$out"
-      '';
-
-    # Inject the OTEL auth header (a secret) into the agent's *user*
-    # claude settings at runtime, keeping it out of the world-readable
-    # managed settings json above and out of the nix store entirely.
-    # hive-c0re forwards the operator's `headersCredential` file into
-    # this container's systemd credential store; this oneshot reads it
-    # via `LoadCredential` at start and merges `OTEL_EXPORTER_OTLP_HEADERS`
-    # into `~/.claude/settings.json` (0600, agent-owned). claude layers
-    # the user `env` on top of the managed one, so both the harness
-    # turn-loop and `hivectl choom` (same agent user) pick it up. Ordering
-    # is best-effort (`before`, not a hard dep): if it fails the harness
-    # still starts and telemetry just exports unauthenticated.
-    systemd.services.hive-otel-header =
-      lib.mkIf (config.hyperhive.otel.enable && config.hyperhive.otel.headersCredential != null)
-        {
-          description = "Inject the OTEL auth header into the agent's claude user settings";
-          wantedBy = [ "multi-user.target" ];
-          before = [ "hive-ag3nt.service" ];
-          serviceConfig = {
-            Type = "oneshot";
-            RemainAfterExit = true;
-            User = userName;
-            Group = userName;
-            LoadCredential = [ "otel-headers" ];
-            ExecStart = pkgs.writeShellScript "hive-otel-header" ''
-              set -eu
-              umask 077
-              hdr="$CREDENTIALS_DIRECTORY/otel-headers"
-              [ -r "$hdr" ] || exit 0
-              dir=${homeDir}/.claude
-              settings="$dir/settings.json"
-              mkdir -p "$dir"
-              base='{}'
-              [ -s "$settings" ] && base="$(cat "$settings")"
-              printf '%s' "$base" | ${pkgs.jq}/bin/jq \
-                --rawfile h "$hdr" \
-                '.env = ((.env // {}) + { OTEL_EXPORTER_OTLP_HEADERS: ($h | rtrimstr("\n")) })' \
-                > "$settings.tmp"
-              mv "$settings.tmp" "$settings"
-              chmod 0600 "$settings"
-            '';
-          };
-        };
-
-    # Seed claude's onboarding + per-project trust state once. claude only
-    # marks `hasCompletedOnboarding` (global) and the project trust dialog
-    # as accepted when run *interactively*; the harness only ever runs it
-    # headless (`--print`) and `claude auth login` doesn't set them either.
-    # So the first interactive launch (`hivectl choom`) would drop the
-    # operator into the onboarding/trust walkthrough despite valid OAuth
-    # creds. This oneshot is the single place hyperhive touches
-    # `~/.claude.json`: it runs before the harness (so nothing races it),
-    # is idempotent (skips when the flags are already set), and is
-    # best-effort (`before`, not a hard dep — a failed seed leaves the file
-    # untouched and the harness still starts). Credentials live in the
-    # separate `~/.claude/.credentials.json`, so this never touches secrets.
-    systemd.services.hive-claude-onboarding = {
-      description = "Seed claude onboarding + project-trust so choom skips the walkthrough";
-      wantedBy = [ "multi-user.target" ];
-      before = [ "hive-ag3nt.service" ];
-      serviceConfig = {
-        Type = "oneshot";
-        RemainAfterExit = true;
-        User = userName;
-        Group = userName;
-        ExecStart = pkgs.writeShellScript "hive-claude-onboarding" ''
-          set -eu
-          umask 077
-          cfg=${homeDir}/.claude.json
-          dir=/agents/${userName}/state
-          base='{}'
-          [ -s "$cfg" ] && base="$(cat "$cfg")"
-          # Idempotent: nothing to do when already onboarded + trusted.
-          if printf '%s' "$base" | ${pkgs.jq}/bin/jq -e \
-              --arg d "$dir" \
-              '.hasCompletedOnboarding == true and (.projects[$d].hasTrustDialogAccepted == true)' \
-              >/dev/null 2>&1; then
-            exit 0
-          fi
-          printf '%s' "$base" | ${pkgs.jq}/bin/jq \
-            --arg d "$dir" \
-            '.hasCompletedOnboarding = true
-             | .projects[$d].hasTrustDialogAccepted = true
-             | .projects[$d].hasCompletedProjectOnboarding = true' \
-            > "$cfg.tmp"
-          mv "$cfg.tmp" "$cfg"
-          chmod 0600 "$cfg"
-        '';
-      };
-    };
-  };
-}

nix/agent-modules/dashboard-links.nix

@@ -1,73 +0,0 @@
-# Extra navigation links surfaced on the hive-c0re dashboard card for
-# this agent: the option and the oneshot that writes them into the
-# state dir where hive-c0re reads them.
-{
-  lib,
-  config,
-  ...
-}:
-{
-  options.hyperhive.dashboardLinks = lib.mkOption {
-    type = lib.types.listOf (
-      lib.types.submodule {
-        options = {
-          label = lib.mkOption {
-            type = lib.types.str;
-            description = "Display label for the link.";
-          };
-          icon = lib.mkOption {
-            type = lib.types.str;
-            default = "";
-            description = "Optional icon emoji or short glyph.";
-          };
-          url = lib.mkOption {
-            type = lib.types.str;
-            description = "Full URL (may include a different port, e.g. http://localhost:9001/stats).";
-          };
-        };
-      }
-    );
-    default = [ ];
-    example = lib.literalExpression ''
-      [
-        { label = "Stats"; icon = "📊"; url = "http://localhost:9001/stats"; }
-      ]
-    '';
-    description = ''
-      Extra navigation links surfaced on the hive-c0re dashboard card for
-      this agent. Declare any additional web UI pages the agent exposes —
-      stats pages, custom UIs, etc. hive-c0re reads the JSON file this
-      option produces at each container-view snapshot and attaches the
-      links to the agent card without any code changes.
-    '';
-  };
-
-  config = {
-    # Write declared dashboardLinks to the state dir so hive-c0re can
-    # read them without accessing the container's /etc/ from the host.
-    # Best-effort oneshot (always exit 0):
-    # docs/conventions.md::Best-effort oneshot services.
-    systemd.services.hive-dashboard-links = lib.mkIf (config.hyperhive.dashboardLinks != [ ]) {
-      description = "write declarative dashboardLinks to agent state dir";
-      wantedBy = [ "multi-user.target" ];
-      serviceConfig = {
-        Type = "oneshot";
-        RemainAfterExit = true;
-        # Pin the journal identity (else it's the `script` store-path wrapper).
-        SyslogIdentifier = "hive-dashboard-links";
-      };
-      environment.LINKS_JSON = builtins.toJSON config.hyperhive.dashboardLinks;
-      script = ''
-        # Sub-agents have their state dir bind-mounted at /agents/<name>/state.
-        # Use a glob — exactly one match per container at runtime.
-        STATE_DIR=$(echo /agents/*/state)
-        if [ ! -d "$STATE_DIR" ]; then
-          echo "hive-dashboard-links: no state dir found at /agents/*/state; skipping"
-          exit 0
-        fi
-        printf '%s' "$LINKS_JSON" > "$STATE_DIR/hyperhive-dashboard-links.json"
-        echo "hive-dashboard-links: wrote $(printf '%s' "$LINKS_JSON" | wc -c) bytes to $STATE_DIR/hyperhive-dashboard-links.json"
-      '';
-    };
-  };
-}

nix/agent-modules/default.nix

@@ -1,220 +0,0 @@
-# Shared scaffolding for every hyperhive harness container.
-# `../templates/agent.nix` and `../templates/ruth.nix` both import
-# agents use the same service unit regardless of which entry-point
-# they came from.
-#
-# This is the core module: container plumbing (boot/nix/nixpkgs),
-# base tooling, and the cross-cutting `hyperhive.icon` option. Each
-# feature lives in its own sibling module (imported below) that
-# declares its own `hyperhive.*` options + config.
-{
-  pkgs,
-  lib,
-  config,
-  # Flake inputs routed through _module.args by the agent flake.nix.
-  # Default to {} so the module evaluates cleanly even when the agent
-  # flake doesn't set up the routing pattern (e.g. during standalone
-  # nixos-rebuild without a flake wrapper).
-  flakeInputs ? { },
-  ...
-}:
-{
-  imports = [
-    ./agent-service.nix
-    ./bash-env.nix
-    ./claude-settings.nix
-    ./dashboard-links.nix
-    ./docs.nix
-    ./forge.nix
-    ./frontend.nix
-    ./github.nix
-    ./matrix.nix
-    ./mcp.nix
-    ./network.nix
-    ./packages.nix
-    ./user.nix
-    ./weston-vnc.nix
-    (lib.mkRemovedOptionModule [ "hyperhive" "web" "useUnixSocket" ] ''
-      Unix socket mode is always enabled for all agents. Remove the
-      setting from your agent.nix.
-    '')
-    (lib.mkRemovedOptionModule [ "hyperhive" "allowedBashPatterns" ] ''
-      The built-in Bash tool is fully disabled; agents use
-      mcp__bash__run instead. Remove the setting from your agent.nix.
-    '')
-  ];
-
-  options.hyperhive.icon = lib.mkOption {
-    type = lib.types.nullOr lib.types.path;
-    default = null;
-    example = lib.literalExpression "./icon.svg";
-    description = ''
-      Path to an SVG file used as this agent's icon — shown on the
-      dashboard and the per-agent web UI (header + favicon). Commit
-      the SVG into the agent's config repo next to `agent.nix` and
-      reference it as a relative path (`./icon.svg`).
-
-      When null (the default) the agent falls back to the shared
-      hyperhive logo. The harness serves the icon (configured or
-      default) at `GET /icon` on the per-agent web port.
-    '';
-  };
-
-  config = {
-    assertions = [
-      # Guard the inputs-routed-as-output pattern: the agent flake.nix is
-      # expected to set `_module.args.flakeInputs = builtins.removeAttrs inputs ["self"]`.
-      # If `self` leaks into flakeInputs the agent gets a spurious attrset
-      # entry that can shadow real inputs and is almost certainly a bug.
-      # Guard with `or {}` so standalone evaluation stays clean when
-      # flakeInputs is absent from _module.args.
-      {
-        assertion = !(builtins.hasAttr "self" (config._module.args.flakeInputs or { }));
-        message = ''
-          hyperhive: `flakeInputs` must not contain "self".
-          In your agent flake.nix, use:
-            _module.args.flakeInputs = builtins.removeAttrs inputs [ "self" ];
-        '';
-      }
-      # hyperhive.icon must reference an SVG file when set.
-      {
-        assertion = config.hyperhive.icon == null || lib.hasSuffix ".svg" (toString config.hyperhive.icon);
-        message = "hyperhive.icon must point to an .svg file";
-      }
-    ];
-
-    # Operator-set per-agent icon (hyperhive.icon). When configured, the
-    # SVG lands at /etc/hyperhive/icon.svg; the harness serves it at
-    # GET /icon, falling back to the bundled hyperhive logo when absent.
-    # Consumed by forge-avatar-sync (./forge.nix) and the matrix avatar
-    # sync (./matrix.nix) too.
-    environment.etc."hyperhive/icon.svg" = lib.mkIf (config.hyperhive.icon != null) {
-      source = config.hyperhive.icon;
-    };
-
-    boot.isNspawnContainer = true;
-
-    # Use a disk-backed /tmp instead of the default tmpfs so large scratch
-    # writes (nix-develop shells, cargo build dirs, multi-GB downloads) land
-    # on disk rather than eating container RAM.  The tmpfs default mounts
-    # ~3.2 GB of RAM per container; disk-backed /tmp is effectively unlimited
-    # and cheaper for agents that do heavy build work.
-    #
-    # cleanOnBoot defaults to false in nixpkgs — set it explicitly so /tmp is
-    # cleared on each container start (D! tmpfiles rule), preserving the
-    # ephemeral-per-boot semantics agents expect from a tmpfs /tmp, just
-    # without the RAM cost.
-    boot.tmp.useTmpfs = false;
-    boot.tmp.cleanOnBoot = true;
-
-    # Every agent gets flakes + the modern `nix` CLI out of the box.
-    # Equivalent to passing `--extra-experimental-features 'nix-command
-    # flakes'` on every invocation. Agents shell out to `nix build` /
-    # `nix flake` constantly (devshells, ad-hoc evals, fetching their
-    # own MCP-server flakes); without this they hit the "experimental
-    # feature not enabled" wall on the first try.
-    nix.settings.experimental-features = [
-      "nix-command"
-      "flakes"
-    ];
-
-    # `lib.mkForce` overrides nixpkgs's normal-priority `false` so
-    # in-container `nix build` invocations fall back to unsandboxed
-    # local builds rather than failing on the missing user-namespace.
-    # See `docs/gotchas.md::Containerized nix-daemon needs
-    # sandbox-fallback = true` + `docs/security.md` for the rationale.
-    #
-    # Note: with NIX_REMOTE=daemon below this becomes a no-op for the
-    # common case — daemon-routed builds run on the host where sandboxing
-    # works. It stays as a belt-and-suspenders fallback for any context
-    # that bypasses the daemon (e.g. direct nix-store invocations).
-    nix.settings.sandbox-fallback = lib.mkForce true;
-
-    # Route ALL nix invocations in this container through the host
-    # nix-daemon socket, regardless of whether the caller is root or
-    # non-root. Without this, root contexts (PID 1, systemd services
-    # running as root) default to store=auto which resolves to the LOCAL
-    # store — bypassing the shared daemon, its remote builders, and the
-    # host's prebuilt derivation cache, causing spurious full rebuilds.
-    #
-    # systemd.globalEnvironment sets DefaultEnvironment in systemd.conf,
-    # so every unit started by PID 1 inherits NIX_REMOTE=daemon.
-    # Non-root nix clients already default to the daemon socket, so this
-    # is a no-op for them; it only matters for root services that would
-    # otherwise silently use the local store.
-    systemd.globalEnvironment.NIX_REMOTE = "daemon";
-
-    # `claude-code` is unfree. Each per-agent container's nixosConfiguration
-    # evaluates its own `nixpkgs` instance, so the operator's host-level
-    # `nixpkgs.config.allowUnfreePredicate` does not propagate into here —
-    # we have to allow it inside the container's config as well.
-    nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (pkgs.lib.getName pkg) [ "claude-code" ];
-
-    # Core tooling every agent gets. Per-bin split packages (see
-    # nix/packages/default.nix + ./packages.nix) rather than the full
-    # `hyperhive` bundle — that bundle also carries `hivectl` (a
-    # host-admin CLI that dials the *host* admin socket — useless and
-    # unreachable from inside a container — wrapped with
-    # `wireguard-tools` for `hivectl wg`). The daemon/harness/MCP bins
-    # the harness execs (hive-agent{,-mcp}, hive-bash-daemon,
-    # hive-matrix-daemon, hive-bash-mcp, hive-matrix-mcp) are wired via
-    # their own ExecStart/command lines in the sibling modules — they
-    # don't need to be on PATH too. Only these two are actually looked
-    # up on PATH by claude/shell code inside the container:
-    # `hive-agent-wake` (external wake CLI, docs/turn-loop/mcp.md) and
-    # `hive-metric` (agent-emitted custom metrics CLI,
-    # docs/observability.md).
-    environment.systemPackages = [
-      config.hyperhive.packages.hive-agent-wake
-      config.hyperhive.packages.hive-metric
-    ]
-    ++ (with pkgs; [
-      claude-code
-      bashInteractive
-      coreutils-full
-      # procps for pkill — used by the web UI's /api/cancel to SIGINT the
-      # in-flight claude turn.
-      procps
-      # jq: JSON processing in shell — useful for parsing API responses,
-      # forge REST calls, sqlite output, etc.
-      jq
-      # curl: HTTP client for forge REST API and other web requests.
-      curl
-    ]);
-
-    # HIVE_ASSETS_DIR points at the project's static runtime assets
-    # (branding + claude prompts; see `nix/packages/assets.nix`). Set
-    # here so both the harness binary and any user-shell `cargo run`
-    # inside the container resolve them from the same path.
-    # SHELL must be set so claude's Bash tool finds a POSIX shell.
-    # HIVE_CONTEXT_WINDOW_TOKENS_* are injected by the meta flake from the
-    # host-level `services.hyperhive.c0re.contextWindowTokens` option — not
-    # set here.
-    environment.variables = {
-      HIVE_ASSETS_DIR = "${config.hyperhive.packages.assets}/share/hyperhive";
-      SHELL = "${pkgs.bashInteractive}/bin/bash";
-      # Route interactive-shell nix invocations through the host daemon.
-      # Redundant with /etc/profile.d/nix-daemon.sh but ensures it's set
-      # regardless of which profile files are sourced.
-      NIX_REMOTE = "daemon";
-    };
-
-    # Git is needed by claude's Bash tool (for the agent <-> manager config
-    # request flow) and by hive-c0re's own setup_applied / setup_proposed.
-    # The per-agent `applied/<name>/flake.nix` overrides `user.name` and
-    # `user.email` with the agent's identity — values here are `mkDefault`
-    # so the per-agent override wins without needing `mkForce`.
-    programs.git = {
-      enable = true;
-      config = {
-        user = {
-          name = lib.mkDefault "hyperhive";
-          email = lib.mkDefault "hyperhive@local";
-        };
-        init.defaultBranch = lib.mkDefault "main";
-      };
-    };
-
-    system.stateVersion = "25.11";
-  };
-}

nix/agent-modules/docs.nix

@@ -1,50 +0,0 @@
-# In-container hyperhive reference docs: the `hyperhive.docs.*`
-# options and the `$HIVE_DOCS_DIR` wiring the harness reads.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-{
-  options.hyperhive.docs.enable = lib.mkEnableOption ''
-    make the hyperhive reference docs (the repo `docs/` tree, shipped
-    read-only as the standalone `hyperhive-docs` derivation) available
-    in-container. When enabled the harness exposes the docs dir to claude
-    via `claude --add-dir`, so the markdown is readable at
-    `$HIVE_DOCS_DIR/`, and appends a single pointer sentence to the agent's
-    system prompt so it knows the docs exist (see
-    `hive-ag3nt::prompt::render`). Default-on for the root/manager agent
-    (see `../templates/ruth.nix`), off elsewhere; any agent can flip it from its
-    `agent.nix`.
-  '';
-
-  options.hyperhive.docs.source = lib.mkOption {
-    type = lib.types.path;
-    default = config.hyperhive.packages.reference-docs;
-    defaultText = lib.literalMD "`hyperhive.packages.reference-docs` (built from the repo `docs/` tree)";
-    description = ''
-      Store path of the reference-docs tree exposed at `$HIVE_DOCS_DIR`
-      when `hyperhive.docs.enable` is set. Defaults to the flake's
-      `reference-docs` package (the `nix/packages/reference-docs.nix`
-      build) so a standalone container build from a full checkout
-      works unchanged. The generated meta flake overrides this with the
-      narrow `hyperhive-docs` flake input so a doc edit only
-      re-locks that input instead of rebuilding the container from a
-      re-hashed `hyperhive` source.
-    '';
-  };
-
-  config = {
-    environment.variables = lib.mkIf config.hyperhive.docs.enable {
-      # The harness reads HIVE_DOCS_DIR and passes it to claude as
-      # `--add-dir` so the docs are readable, and appends a single
-      # pointer sentence to the system prompt
-      # (hive-ag3nt::prompt::render) telling the agent the docs exist.
-      # Source is `hyperhive.docs.source` (the narrow `hyperhive-docs`
-      # meta-flake input, or `pkgs.hyperhive-docs` for standalone
-      # builds). See hive-ag3nt::turn.
-      HIVE_DOCS_DIR = "${config.hyperhive.docs.source}";
-    };
-  };
-}

nix/agent-modules/forge.nix

@@ -1,191 +0,0 @@
-# In-container forge (Forgejo) integration: the `tea` CLI login
-# oneshot, the `hive-forge` verb CLI on PATH, and the icon → forge
-# avatar sync.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-  homeDir = "/home/${userName}";
-  # Same 512×512 rasterization of the agent icon the matrix avatar
-  # sync uses (./matrix.nix — identical derivation, same store path).
-  # Only forced when an icon is configured (the avatar-sync unit below
-  # is gated on `hyperhive.icon != null`).
-  iconPng = pkgs.runCommand "hive-agent-icon.png" { nativeBuildInputs = [ pkgs.librsvg ]; } ''
-    rsvg-convert -f png -w 512 -h 512 ${config.hyperhive.icon} -o $out
-  '';
-in
-{
-  options.hyperhive.forge.url = lib.mkOption {
-    type = lib.types.str;
-    default = "http://localhost:3000";
-    example = "http://forge.internal:3000";
-    description = ''
-      Base URL of the hyperhive-managed Forgejo. Used at container
-      boot by a oneshot systemd unit that calls
-      `tea login add --url <this> --token "$(cat $HYPERHIVE_STATE_DIR/forge-token)"`
-      (= `/agents/<name>/state/forge-token`) so the agent's claude can
-      shell out to `tea` without an extra auth dance. No-op when the
-      forge-token file is missing (i.e. hive-forge isn't running on
-      the host).
-    '';
-  };
-
-  config = {
-    assertions = [
-      # hyperhive.forge.url must look like an HTTP URL when non-default.
-      {
-        assertion =
-          config.hyperhive.forge.url == ""
-          || lib.hasPrefix "http://" config.hyperhive.forge.url
-          || lib.hasPrefix "https://" config.hyperhive.forge.url;
-        message = "hyperhive.forge.url must be an http:// or https:// URL (got: \"${config.hyperhive.forge.url}\")";
-      }
-    ];
-
-    environment.systemPackages = [
-      # tea: gitea/forgejo CLI client. Configured at boot by the
-      # tea-login oneshot below if /state/forge-token is present, so
-      # claude can `tea repos create`, `tea pulls create`, etc.
-      pkgs.tea
-      # hive-forge <verb>: CLI wrapping common Forgejo REST API operations
-      # (view, pr, issue, comment, assign, close, labels, branches, etc.).
-      # The per-bin split package — narrow closure, no hivectl/wireguard.
-      config.hyperhive.packages.hive-forge
-    ];
-
-    # One-shot: tea config.yml from the seeded forge token. Shape
-    # contract (always exit 0, no set -e, skip-silently, re-runnable):
-    # docs/conventions.md::Best-effort oneshot services.
-    systemd.services.tea-login = {
-      description = "configure tea CLI from hive-forge token (best-effort)";
-      wantedBy = [ "multi-user.target" ];
-      after = [ "local-fs.target" ];
-      serviceConfig = {
-        Type = "oneshot";
-        RemainAfterExit = true;
-        # Pin the journal identity (else it's the `script` store-path wrapper).
-        SyslogIdentifier = "tea-login";
-      };
-      path = [
-        pkgs.curl
-        pkgs.jq
-        pkgs.coreutils
-      ];
-      environment.HOME_DIR = homeDir;
-      environment.AGENT_USER = userName;
-      script = ''
-                # No `set -e`: best-effort posture (see docs pointer above).
-                FORGE_URL=${lib.escapeShellArg config.hyperhive.forge.url}
-                # $HYPERHIVE_STATE_DIR is system-wide via the meta flake.
-                TOKEN_FILE="$HYPERHIVE_STATE_DIR/forge-token"
-                if [ ! -f "$TOKEN_FILE" ]; then
-                  echo "tea-login: no forge-token at $TOKEN_FILE; skipping"
-                  exit 0
-                fi
-                TOKEN=$(cat "$TOKEN_FILE")
-                # Resolve the agent username from the forge API.
-                USER=$(curl -sf --max-time 5 \
-                  -H "Authorization: token $TOKEN" \
-                  "$FORGE_URL/api/v1/user" \
-                  | jq -r '.login // empty' 2>/dev/null || true)
-                if [ -z "$USER" ]; then
-                  echo "tea-login: could not resolve username from forge API; skipping"
-                  exit 0
-                fi
-                # Config under the agent user's home, chown'd to them;
-                # service stays root-owned (see docs pointer above).
-                CONFIG="$HOME_DIR/.config/tea/config.yml"
-                mkdir -p "$(dirname "$CONFIG")" || true
-                cat > "$CONFIG" << EOF
-        logins:
-            - name: forge
-              url: $FORGE_URL
-              token: $TOKEN
-              default: true
-              ssh_host: ""
-              ssh_key: ""
-              insecure: false
-              ssh_agent: false
-              user: $USER
-        preferences:
-            editor: false
-            flag_defaults:
-                remote: ""
-        EOF
-                chown -R "$AGENT_USER:$AGENT_USER" "$HOME_DIR/.config" 2>/dev/null || true
-                echo "tea-login: configured for $FORGE_URL as $USER (config at $CONFIG)"
-      '';
-    };
-
-    # Path-trigger sibling: re-fires forge-avatar-sync the moment
-    # `<state>/forge-token` appears. Mirrors the hive-matrix-daemon
-    # token-watcher pattern — on first agent deployment the container
-    # boots before hive-c0re has provisioned the forge-token, so the
-    # service fires too early and exits with "no forge-token found".
-    # Without this path unit, RemainAfterExit=true would prevent systemd
-    # from ever re-running the service. See
-    # docs/persistence.md::forge-avatar-sync.
-    systemd.paths.forge-avatar-sync = lib.mkIf (config.hyperhive.icon != null) {
-      description = "trigger forge-avatar-sync when forge-token appears";
-      wantedBy = [ "multi-user.target" ];
-      pathConfig.PathExistsGlob = "/agents/*/state/forge-token";
-    };
-
-    # One-shot: hyperhive.icon → Forgejo profile avatar. Shape contract:
-    # docs/conventions.md::Best-effort oneshot services.
-    # RemainAfterExit = false so the .path trigger above can re-fire
-    # this unit when the forge-token arrives after boot. The PNG is
-    # rasterized at build time (`iconPng`, shared shape with the matrix
-    # avatar sync), so the unit only exists when an icon is configured
-    # and needs no librsvg at runtime — Forgejo's Go image library
-    # can't decode SVG, hence PNG.
-    systemd.services.forge-avatar-sync = lib.mkIf (config.hyperhive.icon != null) {
-      description = "sync agent icon to Forgejo user avatar (best-effort)";
-      wantedBy = [ "multi-user.target" ];
-      after = [ "tea-login.service" ];
-      serviceConfig = {
-        Type = "oneshot";
-        RemainAfterExit = false;
-        # Pin the journal identity (else it's the `script` store-path wrapper).
-        SyslogIdentifier = "forge-avatar-sync";
-      };
-      path = [
-        pkgs.curl
-        pkgs.coreutils
-        pkgs.jq
-      ];
-      script = ''
-        FORGE_URL=${lib.escapeShellArg config.hyperhive.forge.url}
-        # $HYPERHIVE_STATE_DIR is set system-wide by the meta flake
-        # (systemd.globalEnvironment) to `/agents/<name>/state`.
-        TOKEN_FILE="$HYPERHIVE_STATE_DIR/forge-token"
-        if [ ! -f "$TOKEN_FILE" ]; then
-          echo "forge-avatar-sync: no forge-token found; skipping"
-          exit 0
-        fi
-        TOKEN=$(cat "$TOKEN_FILE")
-        IMAGE=$(base64 -w 0 < ${iconPng})
-        # Forgejo POST /user/avatar expects {"image":"<base64>"} — just the
-        # raw base64 string, NOT a data URI (data:image/png;base64,...).
-        # Use jq to build the payload so the large base64 value is safely quoted.
-        PAYLOAD=$(jq -n --arg img "$IMAGE" '{image:$img}')
-        RESP=$(curl -sf --max-time 10 \
-          -X POST "$FORGE_URL/api/v1/user/avatar" \
-          -H "Authorization: token $TOKEN" \
-          -H "Content-Type: application/json" \
-          -d "$PAYLOAD" \
-          -w "\n%{http_code}" 2>/dev/null || true)
-        CODE=$(printf '%s' "$RESP" | tail -1)
-        if [ "$CODE" = "204" ] || [ "$CODE" = "200" ]; then
-          echo "forge-avatar-sync: avatar uploaded (HTTP $CODE)"
-        else
-          echo "forge-avatar-sync: upload returned HTTP $CODE — skipping (non-fatal)"
-        fi
-      '';
-    };
-  };
-}

nix/agent-modules/frontend.nix

@@ -1,156 +0,0 @@
-# Per-agent web UI static tree: the shipped frontend dist, the
-# operator-extendable `extraFiles` overlay, and the merged tree the
-# harness serves via `HIVE_STATIC_DIR`.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-{
-  options.hyperhive.frontend.dist = lib.mkOption {
-    type = lib.types.package;
-    default = config.hyperhive.packages.frontend;
-    defaultText = lib.literalMD "`hyperhive.packages.frontend` (the flake's frontend dist)";
-    description = ''
-      The shipped frontend dist (built by `nix/packages/frontend.nix`).
-      Output layout: `dashboard/` (used by hive-c0re on the host) and
-      `agent/` (used here, layered with `extraFiles` below at
-      activation time). Override to ship a fully custom per-agent SPA;
-      the JSON contract (`/api/state`, `/events/stream`, the action
-      endpoints) is the source of truth for any replacement.
-    '';
-  };
-
-  options.hyperhive.frontend.mergedDist = lib.mkOption {
-    type = lib.types.package;
-    readOnly = true;
-    description = ''
-      Computed: the merged static tree consumed by the harness via
-      `HIVE_STATIC_DIR`. Composed at evaluation time by copying
-      `hyperhive.frontend.dist`'s `agent/` subdir as the base, then
-      layering each `extraFiles` entry on top. Read-only — do not set directly.
-    '';
-  };
-
-  options.hyperhive.frontend.extraFiles = lib.mkOption {
-    type = lib.types.attrsOf (
-      lib.types.submodule (
-        { name, ... }:
-        {
-          options = {
-            source = lib.mkOption {
-              type = lib.types.path;
-              description = ''
-                Source file or directory to layer over the default
-                agent dist. A path (relative to `agent.nix` or
-                absolute) — nix copies its contents into the merged
-                static tree.
-              '';
-            };
-            target = lib.mkOption {
-              # First char must be alphanumeric/underscore (rules out
-              # leading `/`, leading `.`, leading `-`); inner chars
-              # include `.` and `/` so nested layouts like
-              # `"games/bitburner"` work. This is the shape check —
-              # the `..`-segment traversal check is the assertion in
-              # `config.assertions` below (regex alone can't reject
-              # mid-path `..` segments without lookahead, which nix
-              # POSIX regex doesn't support).
-              type = lib.types.strMatching "^[A-Za-z0-9_][A-Za-z0-9_./-]*$";
-              default = name;
-              defaultText = lib.literalMD "the attribute name";
-              description = ''
-                Destination path within the merged static tree, used
-                as both the served URL prefix (`/<target>/...`) and
-                the on-disk layout in the merged derivation. Defaults
-                to the attribute name. Use forward slashes for
-                nested layouts (e.g. `"games/bitburner"`).
-
-                Constrained shape: must start with an alphanumeric or
-                `_`, and only contain alphanumerics, `_`, `.`, `/`,
-                `-`. `..` segments are separately rejected at config
-                eval time.
-              '';
-            };
-          };
-        }
-      )
-    );
-    default = { };
-    example = lib.literalExpression ''
-      {
-        bitburner = {
-          source = ./bitburner-dist;
-          # served at GET /bitburner/...
-        };
-      }
-    '';
-    description = ''
-      Per-agent additions layered on top of the default frontend
-      dist. Each entry copies its `source` into the served static
-      tree under `target`. Useful for shipping a self-contained
-      agent-specific surface alongside the standard agent UI (e.g.
-      the bitburner agent's game page at `/bitburner/`).
-
-      The default agent UI remains served at `/`; entries here only
-      add new routes and never replace the default. Overwrite
-      semantics are **hard-fail**: if `target` collides with an
-      existing file or directory in the default dist (or with a
-      prior entry's target), the `mergedDist` build aborts with
-      `refusing to overwrite existing path '<target>' in the
-      default dist`. To override a default file, fork the dist via
-      `hyperhive.frontend.dist` instead — `extraFiles` is for
-      pure additions.
-
-      `target` must be a relative path inside the static dir. An
-      assertion rejects leading `/` and `..` segments at config
-      eval time (string-concat-into-paths safety, even though
-      agent.nix goes through operator review before deploy).
-    '';
-  };
-
-  config = {
-    assertions = [
-      # hyperhive.frontend.extraFiles[*].target is concatenated into
-      # $out during the mergedDist build. The option's strMatching
-      # type already rejects leading `/`, leading `.`, and the
-      # weirder characters; this assertion catches mid-path `..`
-      # segments (e.g. `foo/../etc/passwd`) that the type's regex
-      # can't easily express without lookahead. agent.nix is
-      # operator-reviewed, so this is belt-and-braces — but it's the
-      # kind of mistake that's easy to make and hard to spot.
-      {
-        assertion = lib.all (entry: !(builtins.any (seg: seg == "..") (lib.splitString "/" entry.target))) (
-          lib.attrValues config.hyperhive.frontend.extraFiles
-        );
-        message = ''
-          hyperhive.frontend.extraFiles: `target` must not contain
-          `..` path segments.
-        '';
-      }
-    ];
-
-    # Merged frontend static tree. Base = `${frontend.dist}/agent/`,
-    # then each `extraFiles` entry is laid on top at its `target`
-    # path. The runCommand derivation aborts on overwrite so a
-    # filename collision with the default dist surfaces as a build
-    # failure rather than a silent override (operator gets a clear
-    # nix error rather than a confusing 404 / silent dist swap).
-    hyperhive.frontend.mergedDist = pkgs.runCommand "hyperhive-agent-frontend-merged" { } (
-      ''
-        mkdir -p $out
-        cp -r ${config.hyperhive.frontend.dist}/agent/. $out/
-        chmod -R u+w $out
-      ''
-      + lib.concatMapStrings (entry: ''
-        mkdir -p $(dirname $out/${entry.target})
-        if [ -e $out/${entry.target} ]; then
-          echo "hyperhive.frontend.extraFiles: refusing to overwrite existing path '${entry.target}' in the default dist" >&2
-          exit 1
-        fi
-        cp -r ${entry.source} $out/${entry.target}
-      '') (lib.attrValues config.hyperhive.frontend.extraFiles)
-    );
-  };
-}

nix/agent-modules/github.nix

@@ -1,89 +0,0 @@
-# GitHub integration (hyperhive.github.enable): a `gh` wrapper + a git
-# credential helper, both reading the PAT from the agent's
-# `github-token` state file at invocation, so a dashboard-pasted token
-# takes effect with no rebuild. The token PATH is baked in at build
-# time (nix knows `userName`) — NOT read from `$HIVE_GITHUB_TOKEN_FILE`,
-# because claude's Bash tool runs `bash -c` in a minimal env that
-# doesn't source `/etc/set-environment`, so the env var isn't present
-# where `gh`/`git` actually run. The token value never enters the nix
-# store (only its path). github.com only; git auths as `x-access-token`
-# + PAT.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-  ghWrapper = pkgs.writeShellScriptBin "gh" ''
-    if [ -r "/agents/${userName}/state/github-token" ]; then
-      GH_TOKEN="$(cat "/agents/${userName}/state/github-token")"
-      export GH_TOKEN
-    fi
-    exec ${pkgs.gh}/bin/gh "$@"
-  '';
-  gitCredHelper = pkgs.writeShellScriptBin "git-credential-hive-github" ''
-    # git credential-helper protocol: only the `get` action needs an answer.
-    [ "''${1:-}" = "get" ] || exit 0
-    if [ -r "/agents/${userName}/state/github-token" ]; then
-      # GitHub ignores the username for PAT auth — `x-access-token` is the
-      # conventional placeholder; the PAT is the password.
-      printf 'username=x-access-token\n'
-      printf 'password=%s\n' "$(cat "/agents/${userName}/state/github-token")"
-    fi
-  '';
-in
-{
-  options.hyperhive.github.enable = lib.mkOption {
-    type = lib.types.bool;
-    default = true;
-    description = ''
-      Install the GitHub integration in this agent: a `gh` CLI wrapper and a
-      git credential helper for `https://github.com`, both authenticated from
-      an operator-supplied personal access token (PAT). The PAT is written to
-      `<state>/github-token` out of band --- the dashboard credentials tab or
-      `hivectl github set-token` --- so giving an agent GitHub is a runtime
-      paste, no per-agent config or rebuild. The wrappers read the token file
-      at invocation, so a freshly-pasted PAT takes effect immediately; until
-      one exists, `gh` / `git push` just fail unauthenticated.
-
-      github.com only. git authenticates as `x-access-token` + the PAT (GitHub
-      ignores the username for PAT auth); `gh` derives its identity from the
-      token. Keep the PAT minimally scoped: the agent has passwordless sudo, so
-      a compromised agent can act within the token's scopes --- scope is the
-      real blast-radius limiter.
-
-      On by default. Host-driven: set `services.hyperhive.github.enable = false`
-      to turn the integration off hive-wide (meta.rs propagates the override
-      into every agent).
-    '';
-  };
-
-  config = {
-    # No bare pkgs.gh here — the wrapper *is* `gh` and hardcodes the
-    # real binary path, so it can't be shadowed.
-    environment.systemPackages = lib.optionals config.hyperhive.github.enable [
-      ghWrapper
-      gitCredHelper
-    ];
-
-    # Wire the GitHub credential helper for `git push` over HTTPS. Host-scoped
-    # to `https://github.com`, so it never touches the forge (localhost:3000)
-    # or any other remote. The helper reads the PAT from the agent's
-    # `github-token` state file at invocation and auths as `x-access-token` +
-    # the PAT. System /etc/gitconfig merges under the agent's ~/.gitconfig
-    # (safe.directory), so this is additive.
-    # Nested-path binding + mkIf (matching the other `environment.etc."…"`
-    # entries in the harness modules) — a whole-set `environment.etc = {…}`
-    # here would collide with them at the nix level ("attribute already
-    # defined").
-    environment.etc."gitconfig" = lib.mkIf config.hyperhive.github.enable {
-      text = ''
-        [credential "https://github.com"]
-        helper = hive-github
-        username = x-access-token
-      '';
-    };
-  };
-}

nix/agent-modules/matrix.nix

@@ -1,298 +0,0 @@
-# Per-agent matrix integration: the `hyperhive.matrix.*` +
-# `hyperhive.matrixAccounts` options, the long-running
-# hive-matrix-daemon, its token-arrival path trigger, and the
-# auto-injected stdio MCP bridge entry.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-  # Single source of truth for the default matrix homeserver URL, shared
-  # by the `hyperhive.matrix.url` option default and the daemon-unit guard
-  # that decides whether to set a unit-level HIVE_MATRIX_URL (so the two
-  # cannot drift). Matches the daemon's own built-in default
-  # (`paths::DEFAULT_HOMESERVER`).
-  matrixUrlDefault = "http://localhost:8008";
-  # Rasterize the operator-set agent icon (`hyperhive.icon`, an SVG) to a
-  # 512x512 PNG so the matrix daemon can upload it as each account's avatar
-  # over the live authenticated Client (see hive-matrix-mcp::client::sync_avatar).
-  # Only forced when an icon is configured — the `HIVE_ICON_PNG` daemon-env
-  # entry is gated on `hyperhive.icon != null`, so this binding stays lazy
-  # when no icon is set.
-  iconPng = pkgs.runCommand "hive-agent-icon.png" { nativeBuildInputs = [ pkgs.librsvg ]; } ''
-    rsvg-convert -f png -w 512 -h 512 ${config.hyperhive.icon} -o $out
-  '';
-in
-{
-  options.hyperhive.matrix.enable = lib.mkOption {
-    type = lib.types.bool;
-    default = true;
-    description = ''
-      Enable per-agent matrix integration via `hive-matrix-mcp`.
-      When true (the default), the harness:
-
-      - runs `hive-matrix-daemon` as a systemd unit that holds a
-        matrix-sdk Client + sync against the homeserver at
-        `HIVE_MATRIX_URL` (default `http://localhost:8008` — the
-        in-host tuwunel from `nix/host-modules/hive-matrix.nix`). The
-        daemon auto-skips when `<state>/matrix-token` is missing,
-        and a `systemd.paths` watcher restarts it the moment
-        hive-c0re provisions the token (same path-trigger shape
-        as `forge-avatar-sync`).
-      - exposes the matrix tool surface (send_message, send_dm,
-        send_reaction, send_reply, mark_read, list_rooms,
-        list_room_members, read_room) to claude via an auto-injected
-        `extraMcpServers.matrix` entry. Claude spawns the stdio
-        `hive-matrix-mcp` bridge per turn, which forwards each tool
-        call to the daemon over `/run/hive-matrix/socket`.
-      - wakes the agent on incoming room events via a short teaser
-        Wake signal (`[matrix] <sender> in <room>: <first 100c>…`)
-        to the hyperhive control socket; the full event stays
-        unread server-side until `read_room` consumes it.
-
-      Set to `false` for agents that should NOT have matrix tools at
-      all (e.g. agents on a host without `hyperhive.matrix.enable` on
-      the meta side). When token file is absent the daemon and MCP
-      both no-op cleanly anyway, so `false` is rarely necessary.
-    '';
-  };
-
-  options.hyperhive.matrix.url = lib.mkOption {
-    type = lib.types.str;
-    default = matrixUrlDefault;
-    example = "https://matrix.darkest.space";
-    description = ''
-      Matrix homeserver URL the agent's `hive-matrix-daemon` connects
-      to. At runtime hive-c0re forwards the isolation-aware URL
-      (`matrix.<domain>` via the gateway) so isolated agents reach
-      the homeserver without crossing host loopback. Override
-      per-agent when an agent should talk to an external homeserver
-      instead (e.g. a federation-only setup or a remote hive's
-      tuwunel reached via a vpn).
-    '';
-  };
-
-  options.hyperhive.matrixAccounts = lib.mkOption {
-    type = lib.types.attrsOf (
-      lib.types.submodule {
-        options = {
-          tokenFile = lib.mkOption {
-            type = lib.types.str;
-            example = "/agents/dmatrix/state/matrix-token-ccc";
-            description = ''
-              Path to this account's bearer-token file. The daemon reads
-              the token from here to restore the matrix session; how the
-              file gets populated is the provisioner's concern (an
-              operator-supplied secret for an external account). The
-              daemon skips an extra account whose token file is absent.
-            '';
-          };
-          sessionDir = lib.mkOption {
-            type = lib.types.str;
-            example = "/agents/dmatrix/state/matrix-sdk-state-ccc";
-            description = ''
-              Per-account matrix-sdk sqlite store directory (crypto keys
-              + event cache). Must differ between accounts so their
-              sessions do not collide.
-            '';
-          };
-          homeserver = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "https://matrix.example.org";
-            description = ''
-              Homeserver URL for this account. When null (the default),
-              the account falls back to `hyperhive.matrix.url`. Set it for
-              an account on a different homeserver than the agent's
-              default (e.g. an external public-matrix account).
-            '';
-          };
-        };
-      }
-    );
-    default = { };
-    example = lib.literalExpression ''
-      {
-        ccc = {
-          tokenFile = "/agents/dmatrix/state/matrix-token-ccc";
-          sessionDir = "/agents/dmatrix/state/matrix-sdk-state-ccc";
-          homeserver = "https://matrix.example.org";
-        };
-      }
-    '';
-    description = ''
-      Declare *additional* matrix accounts served by the single
-      `hive-matrix-daemon` (one matrix-sdk Client + sync loop each),
-      beyond the agent's built-in hive-internal account. The
-      attribute name keys each account (unique by construction) and is
-      the handle the matrix MCP tools target via their `account`
-      argument.
-
-      The **hive-internal account is always present and is the primary**:
-      it is named `main`, synthesized by the daemon from
-      `hyperhive.matrix.url` + `<state>/matrix-token` +
-      `<state>/matrix-sdk-state`, and is the account a tool call acts as
-      when it omits `account`. You never declare it here --- this option
-      is only for the extras (e.g. an external public-matrix account).
-
-      Leave empty (the default) for the common single-account case: the
-      agent then has only `main`. When non-empty, the extras are
-      serialized to the daemon's `HIVE_MATRIX_ACCOUNTS` environment
-      variable and the daemon appends them after `main`. Requires
-      `hyperhive.matrix.enable` (there is no `main` to extend otherwise).
-    '';
-  };
-
-  config = {
-    assertions = [
-      # Extra matrix accounts only make sense alongside the hive-internal
-      # `main` account they extend, which exists only when matrix is
-      # enabled.
-      {
-        assertion = config.hyperhive.matrixAccounts == { } || config.hyperhive.matrix.enable;
-        message =
-          "hyperhive.matrixAccounts requires hyperhive.matrix.enable = true "
-          + "(the extras extend the hive-internal `main` account, which only "
-          + "exists when matrix is enabled).";
-      }
-      # `main` is reserved for the synthesized hive-internal account; a
-      # declared extra by that name would silently collide with it.
-      {
-        assertion = !builtins.hasAttr "main" config.hyperhive.matrixAccounts;
-        message =
-          "hyperhive.matrixAccounts cannot contain a key named \"main\" "
-          + "--- that name is reserved for the hive-internal account.";
-      }
-      # Token files must land at the `matrix-token*` name the daemon
-      # path-watcher globs (`/agents/*/state/matrix-token*`), or the account
-      # never gets picked up live (it loads only on a full daemon restart).
-      # Enforce the basename prefix so a deviating name (e.g.
-      # `matrix-catgirl-token`) is caught at build time, not silently.
-      {
-        assertion = lib.all (a: lib.hasPrefix "matrix-token" (baseNameOf a.tokenFile)) (
-          lib.attrValues config.hyperhive.matrixAccounts
-        );
-        message =
-          "every hyperhive.matrixAccounts.<name>.tokenFile basename must start with "
-          + "\"matrix-token\" so the daemon path-watcher glob "
-          + "(/agents/*/state/matrix-token*) picks it up live. Offending: "
-          + lib.concatStringsSep ", " (
-            lib.mapAttrsToList (n: a: "${n}=${baseNameOf a.tokenFile}") (
-              lib.filterAttrs (
-                _n: a: !lib.hasPrefix "matrix-token" (baseNameOf a.tokenFile)
-              ) config.hyperhive.matrixAccounts
-            )
-          )
-          + ".";
-      }
-    ];
-
-    # Auto-inject the matrix stdio MCP bridge alongside the bash entry
-    # from ./mcp.nix. `lib.mkDefault` so the operator's own agent.nix
-    # can override the entry.
-    hyperhive.extraMcpServers = lib.mkIf config.hyperhive.matrix.enable {
-      matrix = lib.mkDefault {
-        command = "${config.hyperhive.packages.hive-matrix-mcp}/bin/hive-matrix-mcp";
-        args = [ ];
-        # Same socket path the hive-matrix-daemon service binds
-        # via its `RuntimeDirectory = "hive-matrix"`. Keeps the
-        # bridge + daemon in sync without baking the path into
-        # the Rust default — the env override wins for both.
-        env.HIVE_MATRIX_SOCKET = "/run/hive-matrix/socket";
-        allowedTools = [ "*" ];
-      };
-    };
-
-    # Long-running matrix-sdk client + sync per agent. Holds the unix
-    # socket the stdio `hive-matrix-mcp` bridge connects to + emits
-    # hyperhive wake signals on incoming room events via
-    # `/run/hive/mcp.sock`. See
-    # `docs/persistence.md::Matrix per-agent daemon + token-arrival
-    # trigger` for the socket-path / first-boot-ordering rationale.
-    systemd.services.hive-matrix-daemon = lib.mkIf config.hyperhive.matrix.enable {
-      description = "long-running matrix-sdk Client + MCP daemon socket";
-      wantedBy = [ "multi-user.target" ];
-      after = [ "network-online.target" ];
-      wants = [ "network-online.target" ];
-      environment = {
-        HIVE_MATRIX_SOCKET = "/run/hive-matrix/socket";
-        RUST_LOG = "info";
-      }
-      # Homeserver URL: by default the daemon inherits the host-forwarded
-      # HIVE_MATRIX_URL (set by hive-c0re to `matrix.<domain>` via the
-      # gateway, since agents run in private netns and can't reach host
-      # loopback directly), falling back to the daemon's built-in
-      # localhost default if the forward is absent. A per-agent
-      # `hyperhive.matrix.url` override (non-default) is set unit-level
-      # so it wins over the forwarded value; at the default we
-      # deliberately DON'T set it so the forwarded value isn't shadowed.
-      // lib.optionalAttrs (config.hyperhive.matrix.url != matrixUrlDefault) {
-        HIVE_MATRIX_URL = config.hyperhive.matrix.url;
-      }
-      # Multi-account: serialize the *extra* accounts to the JSON the
-      # daemon parses (`accounts::configured`). Only set when extras are
-      # declared; the daemon always synthesizes the primary `main`
-      # (hive-internal) account itself from the per-agent paths and
-      # prepends it, so we emit extras only. Each entry is in the
-      # daemon's `AccountCfg` serde shape: name (the attr key) /
-      # token_file / state_dir / optional homeserver.
-      // lib.optionalAttrs (config.hyperhive.matrixAccounts != { }) {
-        HIVE_MATRIX_ACCOUNTS = builtins.toJSON (
-          lib.mapAttrsToList (
-            name: a:
-            {
-              inherit name;
-              token_file = a.tokenFile;
-              state_dir = a.sessionDir;
-            }
-            // lib.optionalAttrs (a.homeserver != null) { inherit (a) homeserver; }
-          ) config.hyperhive.matrixAccounts
-        );
-      }
-      # Rasterized agent icon path for the daemon's avatar sync. Only set
-      # when an icon is configured; absent → the daemon skips avatar setting
-      # (hive-matrix-mcp::client::sync_avatar returns early on unset env).
-      // lib.optionalAttrs (config.hyperhive.icon != null) {
-        HIVE_ICON_PNG = "${iconPng}";
-      };
-      serviceConfig = {
-        ExecStart = "${config.hyperhive.packages.hive-matrix-daemon}/bin/hive-matrix-daemon";
-        SyslogIdentifier = "hive-matrix-daemon";
-        Restart = "on-failure";
-        RestartSec = 5;
-        User = userName;
-        Group = userName;
-        RuntimeDirectory = "hive-matrix";
-        # Keep /run/hive-matrix across restarts. With the default
-        # `RuntimeDirectoryPreserve=no`, a `switch-to-configuration`
-        # restart races the outgoing instance's stop-time cleanup
-        # (which deletes the dir) against the incoming instance's
-        # start (which creates it + binds the socket inside it). The
-        # cleanup can win and delete the dir out from under the fresh
-        # daemon, which then fails to mkdir under root-owned /run and
-        # exits — looping on Restart=on-failure until the next boot.
-        # `yes` stops systemd removing it on stop; it still creates it
-        # on first start, and it lives on tmpfs so it's gone at
-        # container reboot regardless. See hive-bash-daemon (./mcp.nix).
-        RuntimeDirectoryPreserve = "yes";
-      };
-    };
-
-    # Re-fire the daemon when the matrix token appears (hive-c0re
-    # provisions it after agent containers come up). Without this
-    # the daemon would exit 0 silently on first boot and the MCP
-    # would have no backend until next restart. See
-    # `docs/persistence.md` (same section as above).
-    systemd.paths.hive-matrix-daemon = lib.mkIf config.hyperhive.matrix.enable {
-      description = "trigger hive-matrix-daemon when a matrix token appears";
-      wantedBy = [ "multi-user.target" ];
-      # `matrix-token*` (not just `matrix-token`) so a secondary
-      # multi-account token (e.g. `matrix-token-ccc`) landing also
-      # re-fires the daemon to pick up the freshly-provisioned account.
-      pathConfig.PathExistsGlob = "/agents/*/state/matrix-token*";
-    };
-  };
-}

nix/agent-modules/mcp.nix

@@ -1,240 +0,0 @@
-# The MCP tool surface: the built-in hyperhive server (persistent
-# streamable-http daemon), the bash-task backend daemon + its
-# auto-injected stdio bridge, the `extraMcpServers` option they hang
-# off, and the send-recipient allowlist.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-in
-{
-  options.hyperhive.allowedRecipients = lib.mkOption {
-    type = lib.types.listOf lib.types.str;
-    default = [ ];
-    example = [
-      "alice"
-      "manager"
-    ];
-    description = ''
-      Names this agent is allowed to `send` to via
-      `mcp__hyperhive__send`. Empty list (the default) means
-      unrestricted — the agent can message any peer, the
-      operator, or the manager. Non-empty list constrains the
-      surface: only the listed names + the manager (always
-      allowed) get through; anything else returns an error
-      string to claude without touching the broker. The
-      operator (`operator`) needs to be in the list if the
-      agent should be able to surface output on the
-      dashboard.
-
-      Useful for sandboxing untrusted sub-agents — set
-      `[ "manager" ]` to scope them to manager-only chatter.
-      The manager itself is always exempt; this option only
-      affects sub-agent `send`.
-    '';
-  };
-
-  options.hyperhive.extraMcpServers = lib.mkOption {
-    type = lib.types.attrsOf (
-      lib.types.submodule {
-        options = {
-          command = lib.mkOption {
-            type = lib.types.str;
-            description = "Absolute path to the MCP server binary. Use `\${pkgs.foo}/bin/foo` or `/run/current-system/sw/bin/foo`.";
-          };
-          args = lib.mkOption {
-            type = lib.types.listOf lib.types.str;
-            default = [ ];
-            description = "Args passed to the MCP server binary.";
-          };
-          env = lib.mkOption {
-            type = lib.types.attrsOf lib.types.str;
-            default = { };
-            description = "Environment variables for the MCP server child process.";
-          };
-          allowedTools = lib.mkOption {
-            type = lib.types.listOf lib.types.str;
-            default = [ "*" ];
-            example = [
-              "send_message"
-              "join_room"
-            ];
-            description = ''
-              Tool names this MCP server is auto-approved to call via
-              `--allowedTools`. Single entry `"*"` (the default) means
-              "every tool from this server" — convenient but trusting.
-              Tighten to a specific list when you only want a subset.
-              Names are bare (e.g. `send_message`); the harness prepends
-              `mcp__<server-key>__` at build time.
-            '';
-          };
-        };
-      }
-    );
-    default = { };
-    example = lib.literalExpression ''
-      {
-        matrix = {
-          command = "/run/current-system/sw/bin/mcp-matrix";
-          args = [ "--config" "/state/matrix.toml" ];
-          env.MATRIX_HOMESERVER = "https://matrix.example.org";
-          allowedTools = [ "send_message" "join_room" ];
-        };
-      }
-    '';
-    description = ''
-      Extra MCP servers claude sees alongside the hyperhive tool surface.
-      Keys are the server names (claude addresses tools as
-      `mcp__<key>__<tool>`). Rendered to `/etc/hyperhive/extra-mcp.json`
-      at activation time; the harness reads that file at boot and merges
-      it into `--mcp-config` + `--allowedTools`. Take effect on the
-      agent's next harness restart (no operator approval needed beyond
-      whatever brought the new agent.nix into deployed/*).
-    '';
-  };
-
-  options.hyperhive.mcp.httpPort = lib.mkOption {
-    type = lib.types.port;
-    default = 8790;
-    example = 8791;
-    description = ''
-      Loopback port the built-in hyperhive MCP surface is served on. HTTP
-      is the *sole* transport for the built-in surface: a
-      long-lived `hive-mcp-http` systemd unit runs
-      `hive-agent-mcp --http 127.0.0.1:<port>` and `render_claude_config`
-      points claude at the stable `http://127.0.0.1:<port>/mcp` URL. That
-      URL survives the per-turn claude re-spawn (and a host-side hive-c0re
-      restart — each tool call dials the control socket fresh), so there
-      is no per-turn MCP re-registration race (a resumed stdio child could
-      emit its first tool call before that turn's async
-      `initialize`/`tools-list` completed, stranding the agent with `No
-      such tool` — the http endpoint eliminates that). Extra MCP servers
-      (matrix/bash) stay stdio bridges regardless.
-
-      Bound loopback-only; the rmcp streamable-http transport's default
-      `allowed_hosts` (`localhost` / `127.0.0.1` / `::1`) rejects Host
-      headers from anywhere else, so no auth token is required for a
-      container-local endpoint.
-
-      Failure-mode note: with no stdio fallback, if `hive-mcp-http` is
-      down claude hits a dead URL until the unit restarts (guarded by
-      `Restart=always`, `RestartSec=3`). Intended shape: no per-turn race
-      while up, a bounded self-healing gap while restarting.
-
-      Safe as a single fixed default across all agents: each container
-      runs in its own private network namespace (isolation is always-on —
-      see docs/network.md), so `127.0.0.1:<port>` is per-container-private
-      and cannot collide across agents. Override only if a container-local
-      service already occupies this port.
-
-      Must match `mcp_config::DEFAULT_MCP_HTTP_PORT` (the harness always
-      exports `HYPERHIVE_MCP_HTTP_PORT`, so the const is only a fallback).
-    '';
-  };
-
-  config = {
-    # Auto-inject the built-in bash MCP server — always present, every
-    # agent needs bash tools. `lib.mkDefault` so the operator's own
-    # agent.nix can override the entry. (The matrix sibling lives in
-    # ./matrix.nix, gated on hyperhive.matrix.enable.)
-    hyperhive.extraMcpServers.bash = lib.mkDefault {
-      command = "${config.hyperhive.packages.hive-bash-mcp}/bin/hive-bash-mcp";
-      args = [ ];
-      env.HIVE_BASH_SOCKET = "/run/hive-bash/socket";
-      allowedTools = [ "*" ];
-    };
-
-    environment.etc."hyperhive/extra-mcp.json".text = builtins.toJSON config.hyperhive.extraMcpServers;
-
-    environment.etc."hyperhive/send-allow.json".text =
-      builtins.toJSON config.hyperhive.allowedRecipients;
-
-    # Bash task runner daemon — long-running process that owns subprocess
-    # monitoring + completion wake signals. Always enabled (every agent
-    # needs bash tools). The stdio MCP bridge `hive-bash-mcp` connects
-    # to this daemon's socket per turn.
-    # Socket dir: /run/hive-bash/ — RuntimeDirectory keeps it on tmpfs.
-    systemd.services.hive-bash-daemon = {
-      description = "bash task runner daemon for hive-bash-mcp";
-      wantedBy = [ "multi-user.target" ];
-      # The daemon runs every bash task via `Command::new("bash")` and the
-      # commands themselves (hive-forge, git, jq, …) resolve from PATH.
-      # A standalone daemon has no inherited agent PATH, so without this
-      # `bash` itself isn't found (spawn fails with ENOENT, the task is
-      # marked done in 0s with no output / no .out/.err). Mirror the
-      # harness unit's PATH: NixOS appends `/bin` to each entry →
-      # /run/wrappers/bin (setuid sudo) + /run/current-system/sw/bin
-      # (bash, coreutils, hive-forge, …).
-      path = [
-        "/run/wrappers"
-        "/run/current-system/sw"
-      ];
-      environment = {
-        HIVE_BASH_SOCKET = "/run/hive-bash/socket";
-        HIVE_CONTROL_SOCKET = "/run/hive/mcp.sock";
-        RUST_LOG = "info";
-        # HYPERHIVE_HARNESS_DIR and HYPERHIVE_STATE_DIR are already
-        # injected via systemd.globalEnvironment by the meta flake
-        # (set to /agents/<name>/harness and /agents/<name>/state
-        # respectively). The daemon uses these to derive its task +
-        # loose-ends dir paths; without them it falls back to deriving
-        # harness/ as a sibling of state/, which produces the same
-        # value but is less robust if the two vars ever diverge.
-      };
-      serviceConfig = {
-        ExecStart = "${config.hyperhive.packages.hive-bash-daemon}/bin/hive-bash-daemon";
-        SyslogIdentifier = "hive-bash-daemon";
-        Restart = "on-failure";
-        RestartSec = 3;
-        User = userName;
-        Group = userName;
-        RuntimeDirectory = "hive-bash";
-        # Keep /run/hive-bash across restarts. With the default
-        # `RuntimeDirectoryPreserve=no`, a post-rebuild restart races
-        # stop-time dir cleanup against the fresh daemon's socket-dir
-        # creation; the daemon loses, fails `mkdir /run/hive-bash`
-        # (Permission denied, non-root in /run), and loops on
-        # Restart=on-failure until the next container boot — i.e. the
-        # bash daemon "doesn't come up post-rebuild". Same shape as
-        # hive-matrix-daemon (./matrix.nix).
-        RuntimeDirectoryPreserve = "yes";
-      };
-    };
-
-    # Persistent streamable-http MCP daemon for the built-in hyperhive
-    # surface — the *sole* transport for that surface; always
-    # wired. Long-lived so claude reconnects to the stable URL each turn
-    # instead of respawning + re-registering a stdio subprocess (the
-    # per-turn MCP registration race). It dials the control socket
-    # (`/run/hive/mcp.sock`, the harness binaries' default) fresh on every
-    # tool call, so a host-side hive-c0re restart is transparent.
-    # `before = hive-ag3nt` so the URL is already listening by the time
-    # the harness renders the first turn's config; the harness/claude also
-    # reconnect on their own, so ordering is a latency nicety not a hard
-    # correctness dep.
-    systemd.services.hive-mcp-http = {
-      description = "persistent streamable-http MCP daemon for the hyperhive surface";
-      wantedBy = [ "multi-user.target" ];
-      before = [ "hive-ag3nt.service" ];
-      environment.RUST_LOG = "info";
-      serviceConfig = {
-        ExecStart = "${config.hyperhive.packages.hive-agent-mcp}/bin/hive-agent-mcp --http 127.0.0.1:${toString config.hyperhive.mcp.httpPort}";
-        SyslogIdentifier = "hive-mcp-http";
-        # `always` (not `on-failure`): this endpoint is load-bearing — the
-        # sole hyperhive-MCP transport, so a down window is total
-        # hyperhive-MCP loss with no stdio fallback and no per-turn
-        # self-heal (the URL just stays dead). `always` also covers any
-        # unforeseen clean-return path and restarts after a stray SIGTERM
-        # stops it out from under the harness.
-        Restart = "always";
-        RestartSec = 3;
-        User = userName;
-        Group = userName;
-      };
-    };
-  };
-}

nix/agent-modules/network.nix

@@ -1,82 +0,0 @@
-# In-container network plumbing: DHCP on the bridge veth, resolvconf
-# taken out of the loop, and the oneshot that points resolv.conf at
-# the hive bridge resolver.
-{
-  pkgs,
-  lib,
-  ...
-}:
-{
-  # Take resolvconf + dhcpcd out of the /etc/resolv.conf loop so the
-  # bridge resolver the oneshot below writes actually sticks. At their
-  # NixOS defaults, resolvconf regenerates resolv.conf from host-tracking
-  # *after* the oneshot has pointed it at the bridge (dhcpcd re-triggers
-  # that when the veth comes up under isolation) — silently clobbering the
-  # bridge nameserver back to the host resolver, which isn't authoritative
-  # for the hive's own zones, so `forge.<domain>` stops resolving. We
-  # disable resolvconf and tell dhcpcd not to touch resolv.conf (without
-  # disabling dhcpcd itself, so the veth still gets its address); then
-  # the hyperhive-isolated-dns oneshot owns resolv.conf. (Same "take
-  # resolvconf out of the loop" approach the matrix container uses.)
-  # All agent containers receive their bridge IP via DHCP from the hive
-  # dnsmasq pool (see nix/host-modules/hive-gateway.nix). useDHCP runs dhcpcd
-  # on every interface (just eth0 in practice — the nspawn bridge veth).
-  config = {
-    networking.useDHCP = true;
-    networking.resolvconf.enable = false;
-    networking.dhcpcd.extraConfig = "nohook resolv.conf";
-
-    # Point resolv.conf at the hive bridge resolver when the container is
-    # network-isolated. nixos-container copies the *host's* /etc/resolv.conf
-    # into the container at every start — but the host resolver (e.g.
-    # 127.0.0.53) is unreachable from a private netns and isn't
-    # authoritative for the hive's own zones (forge.<domain> etc.). The
-    # bridge dnsmasq (gateway IP) is. hive-priv drops the marker
-    # `/etc/hyperhive-bridge-dns` (containing the gateway IP) since
-    # isolation is always on; the oneshot reads it and rewrites
-    # resolv.conf on every boot. Ordered before the first DNS consumer
-    # (tea-login) and the network targets so name resolution works for
-    # the very first turn.
-    systemd.services.hyperhive-isolated-dns = {
-      description = "point resolv.conf at the hive bridge resolver (isolated containers)";
-      wantedBy = [ "multi-user.target" ];
-      after = [ "local-fs.target" ];
-      # Ordered before every network consumer that does DNS on first
-      # boot. `hive-ag3nt` (the harness) is the load-bearing one: its
-      # first-turn api.anthropic.com lookup must not race the resolv.conf
-      # rewrite (it only declares `after network.target`, so without this
-      # edge the harness can start before we've fixed resolv.conf and the
-      # first turn errors — self-heals next turn, but better not to flap).
-      # `hive-matrix-daemon` likewise syncs over the network; the `before`
-      # is a harmless no-op when matrix is disabled (the unit is absent).
-      before = [
-        "network-online.target"
-        "tea-login.service"
-        "hive-ag3nt.service"
-        "hive-matrix-daemon.service"
-      ];
-      unitConfig.ConditionPathExists = "/etc/hyperhive-bridge-dns";
-      serviceConfig = {
-        Type = "oneshot";
-        RemainAfterExit = true;
-        # Pin the journal identity; without it systemd derives it from the
-        # generated `script` store-path wrapper (an opaque `<hash>-…-start`).
-        SyslogIdentifier = "hyperhive-isolated-dns";
-      };
-      path = [ pkgs.coreutils ];
-      script = ''
-        set -eu
-        gw=$(tr -d '[:space:]' < /etc/hyperhive-bridge-dns)
-        if [ -z "$gw" ]; then
-          echo "hyperhive-isolated-dns: empty marker; leaving resolv.conf as-is"
-          exit 0
-        fi
-        # resolv.conf is a regular file copied from the host by
-        # nixos-container; replace it (rm first in case it's a symlink).
-        rm -f /etc/resolv.conf
-        printf 'nameserver %s\n' "$gw" > /etc/resolv.conf
-        echo "hyperhive-isolated-dns: resolv.conf -> nameserver $gw"
-      '';
-    };
-  };
-}

nix/agent-modules/packages.nix

@@ -1,22 +0,0 @@
-# The hyperhive-built packages the harness modules consume, threaded
-# in explicitly as an option — no overlay. The flake's
-# `nixosModules.{agent-base,ruth}` set this to the flake's own package
-# outputs via `lib.mkDefault`, so a per-agent override of an
-# individual key still wins.
-{ lib, ... }:
-{
-  options.hyperhive.packages = lib.mkOption {
-    type = lib.types.attrsOf lib.types.package;
-    internal = true;
-    description = ''
-      hyperhive package outputs consumed by the harness modules: the
-      per-binary daemon/CLI packages (`hive-agent`, `hive-agent-mcp`,
-      `hive-agent-wake`, `hive-bash-daemon`, `hive-bash-mcp`,
-      `hive-forge`, `hive-matrix-daemon`, `hive-matrix-mcp`,
-      `hive-metric`) plus the `assets`, `frontend` and
-      `reference-docs` trees. Wired by the flake's agent-base/ruth
-      nixosModules to `hyperhive.packages.<system>.*`; override an
-      individual key per-agent to swap in a patched binary.
-    '';
-  };
-}

nix/agent-modules/user.nix

@@ -1,215 +0,0 @@
-# Per-agent unix user: the `hyperhive.user.*` options, the user/group
-# declarations, passwordless sudo, and the first-boot migration that
-# chowns the bind-mounted state dirs to the agent user.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  userName = config.hyperhive.user.name;
-  homeDir = "/home/${userName}";
-in
-{
-  # Per-agent unix user the harness + co-process daemons run as.
-  # Defaults to `"agent"` so a standalone evaluation (e.g.
-  # `nix flake check` against `nixosConfigurations.agent-base`) builds
-  # cleanly; the meta-flake's per-agent module rebinds this to the
-  # agent name (`"damocles"`, `"iris"`, …) so each container has a
-  # uniquely-named user matching its agent label. UID auto-assigned
-  # by NixOS (the auto-allocation range for normal users); no hard-
-  # coded UID.
-  options.hyperhive.user.name = lib.mkOption {
-    type = lib.types.strMatching "^[a-z_][a-z0-9_-]{0,30}$";
-    default = "agent";
-    example = "iris";
-    description = ''
-      Unix user the harness service runs as inside the container.
-      The meta-flake overrides this to the agent's own name so the
-      user inside the container matches the agent label (`HIVE_LABEL`).
-      Stand-alone evaluation defaults to `"agent"` so module evaluation
-      without the meta-flake wrapper still builds.
-
-      Constraints match `useradd`'s NAME_REGEX: lowercase / `_` start,
-      total length ≤ 31, no special characters. UID is auto-assigned
-      by NixOS unless `hyperhive.user.uid` is explicitly set.
-    '';
-  };
-
-  options.hyperhive.user.uid = lib.mkOption {
-    type = lib.types.nullOr lib.types.int;
-    default = null;
-    example = 1100;
-    description = ''
-      Optional fixed UID for the per-agent unix user. `null` (default)
-      lets NixOS auto-assign from the normal-user range (≥ 1000),
-      which is the right default for most deployments — the UID stays
-      stable across container rebuilds because each container only has
-      one normal user and the assignment is written into the container's
-      `/etc/passwd` at activation time.
-
-      Set an explicit value only when the host needs a predictable UID
-      for the agent's state files — e.g. if an operator script
-      references files by numeric UID, or to keep ownership stable
-      across full container destroy + recreate on a fresh host.
-
-      Values must be in `[1000, 60000)`. Using UIDs < 1000 clashes with
-      system accounts and is rejected by NixOS.
-    '';
-  };
-
-  options.hyperhive.user.gid = lib.mkOption {
-    type = lib.types.nullOr lib.types.int;
-    default = null;
-    example = 1100;
-    description = ''
-      Optional fixed GID for the per-agent unix group. `null` (default)
-      lets NixOS auto-assign. Usually set alongside `hyperhive.user.uid`
-      to the same value (the conventional Unix pattern for per-user
-      groups where uid == gid), but can be set independently.
-    '';
-  };
-
-  options.hyperhive.user.passwordlessSudo = lib.mkOption {
-    type = lib.types.bool;
-    default = true;
-    example = false;
-    description = ''
-      Grant `${config.hyperhive.user.name}` passwordless sudo
-      (`NOPASSWD: ALL`). True by default so claude's `Bash` tool
-      keeps working for tools that expect root inside the container
-      (`systemctl`, package managers in dev shells, etc.) — the
-      same surface the previous root-user shape had, just elevated
-      explicitly instead of implicitly.
-
-      Flip to `false` for agents that should be strictly
-      unprivileged. Anything claude shells out to that needs root
-      will then fail loudly with the standard sudo error rather
-      than silently succeeding — easier to spot the leak.
-    '';
-  };
-
-  config = {
-    assertions = [
-      {
-        assertion =
-          config.hyperhive.user.uid == null
-          || (config.hyperhive.user.uid >= 1000 && config.hyperhive.user.uid < 60000);
-        message = ''
-          hyperhive.user.uid must be in [1000, 60000) — values below
-          1000 clash with system accounts; values ≥ 60000 are reserved
-          by NixOS for dynamic allocation. Leave unset (null) to let
-          NixOS auto-assign.
-        '';
-      }
-      {
-        assertion =
-          config.hyperhive.user.gid == null
-          || (config.hyperhive.user.gid >= 1000 && config.hyperhive.user.gid < 60000);
-        message = ''
-          hyperhive.user.gid must be in [1000, 60000) — same range
-          constraint as hyperhive.user.uid.
-        '';
-      }
-    ];
-
-    # The container activation script (hive-agent-user-migrate) chowns
-    # the bind-mounted state dir — including credential files written
-    # by hive-c0re before the container was built — to this user on
-    # every boot, so agent processes can always read their own tokens.
-    users.users.${userName} = {
-      isNormalUser = true;
-      home = homeDir;
-      createHome = true;
-      group = userName;
-      extraGroups = lib.optional config.hyperhive.user.passwordlessSudo "wheel";
-      # Matches /bin/bash on NixOS — the harness's claude shell-outs
-      # expect a POSIX shell at $SHELL; bashInteractive is already
-      # the system default for the root user too.
-      shell = pkgs.bashInteractive;
-    }
-    // lib.optionalAttrs (config.hyperhive.user.uid != null) {
-      uid = config.hyperhive.user.uid;
-    };
-    users.groups.${userName} =
-      { }
-      // lib.optionalAttrs (config.hyperhive.user.gid != null) {
-        gid = config.hyperhive.user.gid;
-      };
-
-    # `NOPASSWD: ALL` for the agent user. Lets claude's Bash tool
-    # keep working with anything that expected root (systemctl,
-    # nix-env, etc.) without prompting. Flip
-    # `hyperhive.user.passwordlessSudo = false` to drop both
-    # the wheel-group membership and this sudoers entry; anything
-    # that needs root then fails loudly instead of silently
-    # succeeding.
-    security.sudo.extraRules = lib.mkIf config.hyperhive.user.passwordlessSudo [
-      {
-        users = [ userName ];
-        commands = [
-          {
-            command = "ALL";
-            options = [ "NOPASSWD" ];
-          }
-        ];
-      }
-    ];
-
-    # First-boot migration to the per-agent unix user — creates the
-    # home dir, chowns the bind-mounted state + `~/.claude/`, and
-    # (marker-guarded) moves any leftover `/root/.claude` content
-    # from the previous root-run shape. See
-    # `docs/persistence.md::First-boot agent-user migration` for the
-    # step-by-step rationale; this script implements it.
-    system.activationScripts.hive-agent-user-migrate = lib.stringAfter [ "users" "specialfs" ] ''
-      homeDir=${lib.escapeShellArg homeDir}
-      userName=${lib.escapeShellArg userName}
-      mkdir -p "$homeDir"
-      chown "$userName:$userName" "$homeDir"
-      marker=/var/lib/hive-agent-user-migrated
-      if [ ! -e "$marker" ] && [ -d /root/.claude ] && [ "$(ls -A /root/.claude 2>/dev/null)" ]; then
-        mkdir -p "$homeDir/.claude"
-        if cp -an /root/.claude/. "$homeDir/.claude/" 2>/dev/null; then
-          rm -rf /root/.claude
-          echo "hive-agent-user-migrate: moved /root/.claude → $homeDir/.claude"
-        fi
-      fi
-      mkdir -p "$(dirname "$marker")"
-      : > "$marker"
-      # Scope state + harness chowns to THIS container's own dirs only.
-      # The glob `/agents/*/state` also matches child-agent state dirs that
-      # are bind-mounted into parent containers, which would clobber the
-      # ownership those dirs' own activation scripts set — producing
-      # intermittent EACCES for the child agent's harness between a parent
-      # rebuild and the child's next activation. Config dirs are kept broad
-      # because the parent legitimately owns child proposed-config repos.
-      if [ -d "/agents/$userName/state" ]; then
-        chown -hR "$userName:$userName" "/agents/$userName/state" 2>/dev/null || true
-      fi
-      if [ -d "/agents/$userName/harness" ]; then
-        chown -hR "$userName:$userName" "/agents/$userName/harness" 2>/dev/null || true
-      fi
-      # The proposed-config repo is RW-mounted into the editing (parent/
-      # manager) agent and owned by it; hive-c0re only pulls from it. Heal
-      # it to this user too — same as state/harness. In an agent's own
-      # container its config is RO-mounted, so the chown there just fails
-      # harmlessly (|| true).
-      for configDir in /agents/*/config; do
-        [ -d "$configDir" ] || continue
-        chown -hR "$userName:$userName" "$configDir" 2>/dev/null || true
-      done
-      if [ -d "$homeDir/.claude" ]; then
-        chown -hR "$userName:$userName" "$homeDir/.claude" 2>/dev/null || true
-        # 0755 so hive-core (a different unix user) can list the dir and
-        # detect a valid claude session. Credential files inside are 0600
-        # so secrets stay private regardless of the directory mode.
-        # ensure_claude_dir sets 0755 on creation but cannot re-chmod after
-        # hive-agent-user-migrate chowns the dir to the agent user; this
-        # activation script runs as root and handles the correction.
-        chmod 755 "$homeDir/.claude" 2>/dev/null || true
-      fi
-    '';
-  };
-}

nix/assets.nix

@@ -12,7 +12,7 @@
 #   $out/share/hyperhive/branding/{hyperhive,agent-configs}.{svg,png}
 #   $out/share/hyperhive/prompts/{system.md, claude-settings.json}
 #
-# The repo docs/ tree is a SEPARATE derivation (./reference-docs.nix)
+# The repo docs/ tree is a SEPARATE derivation (nix/reference-docs.nix)
 # so agents can consume the docs without the branding+prompt assets and
 # the website repo can reuse it — see that file.
 
@@ -22,13 +22,13 @@ stdenv.mkDerivation {
   # Narrow `srcs` (branding/ + hive-ag3nt/prompts/) is what decouples
   # this derivation's input hash from the rest of the tree.
   srcs = [
-    ../../branding
+    ../branding
-    ../../hive-ag3nt/prompts
+    ../hive-ag3nt/prompts
   ];
   unpackPhase = ''
     runHook preUnpack
-    cp -r ${../../branding} branding
+    cp -r ${../branding} branding
-    cp -r ${../../hive-ag3nt/prompts} prompts
+    cp -r ${../hive-ag3nt/prompts} prompts
     chmod -R u+w branding prompts
     runHook postUnpack
   '';

nix/checks.nix

@@ -1,87 +0,0 @@
-# Flake checks: formatting, the clippy gate, the workspace test run,
-# the nix-options docs eval, and the hivectl CLI-reference freshness
-# check. Imported per system from flake.nix.
-{
-  pkgs,
-  craneLib,
-  rust,
-  self,
-  system,
-  treefmt-eval,
-}:
-let
-  inherit (rust) cleanSrc cargoArtifacts nativeBuildInputs;
-in
-{
-  formatting = treefmt-eval.config.build.check self;
-
-  # Clippy via crane's first-class `cargoClippy` builder. Reuses the
-  # shared `cargoArtifacts` (deps already built) and runs
-  # `cargo clippy --workspace --all-targets` directly.
-  #
-  # `-D warnings` makes the default/correctness/style lints a
-  # hard CI gate. `-A clippy::pedantic` then drops the pedantic
-  # group from that gate: pedantic is the "extra, opinionated"
-  # group the clippy team grows freely, so denying it means
-  # every toolchain bump that adds a new pedantic lint breaks CI
-  # with zero code changes. The `pedantic = warn`
-  # workspace lint (Cargo.toml) keeps it as advisory signal in
-  # local `cargo clippy` — it just no longer blocks the build.
-  # (`-A` rather than `-W` here: `-W clippy::pedantic` would
-  # re-enable the specific pedantic lints the workspace lints
-  # table allows, e.g. `must_use_candidate`.)
-  clippy = craneLib.cargoClippy {
-    src = cleanSrc;
-    inherit cargoArtifacts nativeBuildInputs;
-    pname = "hyperhive-workspace";
-    version = "0.1.0";
-    cargoClippyExtraArgs = "--workspace --all-targets -- -D warnings";
-  };
-
-  # `cargo test --workspace` lifted out of the package builds so the
-  # `hyperhive-assets` dep (which `hive-ag3nt::prompt::tests`
-  # needs via `HIVE_ASSETS_DIR` to assert against the actual
-  # production prompt template) is scoped to this one check
-  # instead of bleeding into the binary derivations' input
-  # hash. Net: editing `hive-ag3nt/prompts/system.md` still
-  # rebuilds this test check (correct — the tests assert
-  # against its wording), but `packages.default` and the
-  # per-container toplevels stay fully cached.
-  cargo-test = craneLib.cargoTest {
-    src = cleanSrc;
-    inherit cargoArtifacts nativeBuildInputs;
-    pname = "hyperhive-workspace";
-    version = "0.1.0";
-    cargoTestExtraArgs = "--workspace";
-    HIVE_ASSETS_DIR = "${self.packages.${system}.assets}/share/hyperhive";
-  };
-
-  # Nix options docs evaluation. Cheap: pulls in `nixosOptionsDoc` +
-  # the host module's stub eval, no rust or frontend deps. CI fails
-  # fast if a module change breaks option declarations or the doc
-  # rendering. Reuses the `packages.<system>.docs` derivation so the
-  # per-system eval of nix/docs/default.nix happens once.
-  inherit (self.packages.${system}) docs;
-
-  # `hivectl` CLI reference freshness check. The committed
-  # markdown at `docs/tools/hivectl-cli.md` is the rendered
-  # output of the hidden `hivectl markdown-docs` subcommand
-  # (clap-markdown walks the binary's own command tree). This
-  # check regenerates it from the built binary and fails if the
-  # committed copy drifted — so a verb / flag / help-string edit
-  # that forgets to refresh the doc is caught in CI. Reuses the
-  # already-built `packages.<system>.default` (no extra compile).
-  # Regenerate locally with:
-  #   nix build .#default
-  #   ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md
-  hivectl-docs = pkgs.runCommand "hivectl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
-    ${self.packages.${system}.default}/bin/hivectl markdown-docs > generated.md
-    if ! diff -u ${../docs/tools/hivectl-cli.md} generated.md; then
-      echo "" >&2
-      echo "ERROR: docs/tools/hivectl-cli.md is out of date — regenerate it:" >&2
-      echo "  nix build .#default && ./result/bin/hivectl markdown-docs > docs/tools/hivectl-cli.md" >&2
-      exit 1
-    fi
-    touch "$out"
-  '';
-}

nix/devshell.nix

@@ -1,18 +0,0 @@
-# Dev shell: the rust toolchain plus the exact native build inputs
-# the crane derivations use (git, sqlite, pkg-config, cmake — see
-# ../rust.nix), so a plain `cargo build` / `cargo test` in the shell
-# sees the same toolchain shape as CI.
-{ pkgs, rust }:
-{
-  default = pkgs.mkShell {
-    packages =
-      rust.nativeBuildInputs
-      ++ (with pkgs; [
-        cargo
-        clippy
-        rust-analyzer
-        rustc
-        rustfmt
-      ]);
-  };
-}

nix/docs/default.nix

@@ -23,20 +23,39 @@ let
     name = "hyperhive-nix-src";
   };
 
+  # Stub overlay that satisfies pkgs.hyperhive-* references in module
+  # option defaults without depending on self's Rust / frontend builds.
+  # nixosOptionsDoc renders `defaultText` for these options anyway; the
+  # stubs just prevent attribute-missing eval errors.
+  docsStubOverlay = _final: _prev: {
+    hyperhive = pkgs.emptyFile;
+    hyperhive-frontend = pkgs.emptyDirectory;
+    hyperhive-assets = pkgs.emptyDirectory;
+    hyperhive-docs = pkgs.emptyDirectory;
+  };
+
   # Stub host system: every hyperhive subsystem `mkForce false` so
   # heavy build inputs (matrix container, forge, etc.) stay out of
   # the eval — only option *declarations* matter for the doc walk.
-  # Import the host-module aggregator from the content-addressed
+  # Import hive-c0re.nix from the content-addressed nixSrc with stub
-  # nixSrc; the package options (`services.hyperhive.c0re.package`
+  # package args so the eval doesn't depend on self's Rust builds.
-  # etc.) carry no in-module defaults, but with hyperhive disabled
-  # nothing reads them, so no stubs are needed.
   hostEval = nixosSystem {
     system = pkgs.stdenv.hostPlatform.system;
     modules = [
-      "${nixSrc}/host-modules"
+      (import "${nixSrc}/modules/hive-c0re.nix" {
+        hyperhivePackage = _system: pkgs.emptyFile;
+        hyperhiveFrontend = _system: pkgs.emptyFile;
+        hyperhiveAssets = _system: pkgs.emptyDirectory;
+        hyperhiveFlake = "";
+        hyperhiveDocs = "";
+        hyperhiveXdgIcons = _system: pkgs.emptyFile;
+        agentBaseToplevel = pkgs.emptyFile;
+        managerToplevel = pkgs.emptyFile;
+      })
       (
         { lib, ... }:
         {
+          nixpkgs.overlays = [ docsStubOverlay ];
           fileSystems."/" = {
             device = "/dev/null";
             fsType = "tmpfs";
@@ -51,14 +70,13 @@ let
   };
 
   # Agent module eval from the content-addressed nixSrc.  Relative
-  # imports inside agent.nix (the ../agent-modules dir) resolve
+  # imports inside agent-base.nix (e.g. ./harness-base.nix) resolve
-  # correctly against the nixSrc directory tree. `hyperhive.packages`
+  # correctly against the nixSrc directory tree.
-  # stays unset — every option default that references it carries a
-  # `defaultText`, so the doc walk never forces the packages.
   agentEval = nixosSystem {
     system = pkgs.stdenv.hostPlatform.system;
     modules = [
-      "${nixSrc}/templates/agent.nix"
+      "${nixSrc}/templates/agent-base.nix"
+      { nixpkgs.overlays = [ docsStubOverlay ]; }
     ];
   };
 
@@ -155,7 +173,7 @@ let
       `hyperhive.nixosModules.default` to operator host configurations
       (`services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*`).
     - [per-agent options](agent.md) — options declared in
-      `nix/agent-modules/`, visible from every `agent.nix`
+      `nix/templates/harness-base.nix`, visible from every `agent.nix`
       (`hyperhive.model`, `hyperhive.allowedRecipients`,
       `hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
       `hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).

nix/frontend.nix

@@ -33,7 +33,7 @@
 buildNpmPackage {
   pname = "hyperhive-frontend";
   version = "0.0.0";
-  src = ../../frontend;
+  src = ../frontend;
 
   # Computed from `frontend/package-lock.json` via
   #   prefetch-npm-deps frontend/package-lock.json

nix/host-modules/default.nix

@@ -1,26 +0,0 @@
-# The full hyperhive host stack, pulled together in one place — this
-# is what the flake exports as `nixosModules.default` (wrapped with
-# the package/source wiring; see flake.nix). One import covers
-# everything; `services.hyperhive.enable = true` turns the stack on.
-#
-# The forge is mandatory — hive-c0re mirrors every agent's applied
-# config repo into it and it's the canonical store for the meta flake
-# + `internal/*` repos, so there's no enable toggle; it deploys with
-# hyperhive itself. hive-matrix is opt-in (off by default). All
-# subsystems rely on `services.hyperhive.domain`, which is required
-# (asserted in hive-network.nix) whenever hyperhive is enabled.
-{
-  imports = [
-    ./hyperhive.nix
-    ./hive-c0re
-    ./hive-ci.nix
-    ./hive-forge
-    ./hive-gateway
-    ./hive-matrix.nix
-    ./hive-network.nix
-    ./hive-priv.nix
-    ./hive-tls.nix
-    ./otel.nix
-    ./swarm.nix
-  ];
-}

nix/host-modules/hive-c0re/default.nix

@@ -1,218 +0,0 @@
-# The hive-c0re coordinator daemon (runs as the unprivileged
-# `hive-core` user), socket-activated at /run/hyperhive/host.sock.
-# Layout: ./options.nix (option declarations), ./theme.nix (stylix
-# frontend theming → `servedFrontend`), ./environment.nix (the daemon
-# unit's env attrset). The root privileged helper it delegates to is
-# its own module (../hive-priv.nix).
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  cfg = config.services.hyperhive.c0re;
-
-  # Privsep splits ownership across users, so git/libgit2's dubious-
-  # ownership guard trips on legitimate cross-user reads: hive-priv (root)
-  # fetches the hive-core-owned meta/applied repos via nix, and hive-c0re
-  # (hive-core) fetches the agent-owned proposed-config repos. Both
-  # processes are trusted and can already read the files; this gitconfig
-  # only satisfies the ownership guard. libgit2 honours the literal `*`
-  # (mid-path globs aren't supported, so per-agent repos can't be listed);
-  # in practice these processes only ever touch hyperhive's own repos.
-  safeDirGitconfig = pkgs.writeText "hyperhive-safe-gitconfig" ''
-    [safe]
-    directory = *
-  '';
-
-  # The `hive-c0re serve` config JSON. Keys are snake_case to match the
-  # `ServeConfig` serde shape the daemon deserialises (the
-  # container-injected HiveEnv fields, flattened, plus the hive-c0re-local
-  # model_prices table); per-flag overrides still work for ad-hoc
-  # invocations.
-  #
-  # Written to `/etc/hyperhive/serve.json` (managed by
-  # `environment.etc`) rather than embedded as a store-path argument in
-  # ExecStart. This keeps ExecStart byte-stable across deploys that only
-  # change hyperhive module files (gateway, frontend, unrelated nix
-  # modules) so systemd does NOT restart hive-c0re — and therefore does
-  # NOT trigger a startup sweep that rebuilds every agent — unless the
-  # c0re binary itself changes.
-  serveConfigJson = builtins.toJSON {
-    hyperhive_flake = cfg.hyperhiveFlake;
-    hyperhive_docs_flake = cfg.hyperhiveDocs;
-    nixpkgs_flake = cfg.nixpkgsFlake;
-    dashboard_port = cfg.dashboardPort;
-    operator_pronouns = cfg.operatorPronouns;
-    context_window_tokens = cfg.contextWindowTokens;
-    agent_cpu_quota = cfg.agentCpuQuota;
-    agent_memory_max = cfg.agentMemoryMax;
-    model_prices = cfg.modelPrices;
-    build_slots = cfg.buildSlots;
-  };
-in
-{
-  imports = [
-    ./options.nix
-    ./theme.nix
-  ];
-
-  config = lib.mkIf cfg.enable {
-    environment.systemPackages = [
-      cfg.package
-      pkgs.git
-      # XDG icons + .desktop entries so desktop environments can match
-      # hyperhive processes to their icon (task managers, CPU monitors, etc.).
-      cfg.xdgIcons
-    ];
-
-    # Serve config at a stable /etc path so hive-c0re's ExecStart
-    # doesn't embed a volatile store-path argument. See serveConfigJson
-    # above for the rationale.
-    environment.etc."hyperhive/serve.json".text = serveConfigJson;
-
-    # Pull the per-container toplevels into the host system closure.
-    # `system.extraDependencies` adds paths to the system build
-    # without referencing them at runtime — nixos-rebuild fetches /
-    # builds them, they end up in /nix/store, and the first
-    # nixos-container update + start for an agent has nothing left to
-    # do. Gated because the closure is sizeable and pinned to x86_64.
-    system.extraDependencies = lib.optionals cfg.preBuildAgentTemplates [
-      cfg.agentBaseToplevel
-      cfg.managerToplevel
-    ];
-
-    # Unprivileged coordinator user. hive-c0re runs as this user;
-    # privileged operations are delegated to hive-priv which runs as
-    # root, socket-activated at /run/hive/priv.sock (./hive-priv.nix).
-    users.users.hive-core = {
-      isSystemUser = true;
-      group = "hive-core";
-      description = "hive-c0re coordinator daemon user";
-    };
-    users.groups.hive-core = { };
-
-    # The gateway nginx is always the sole external entry point (it runs
-    # alongside hyperhive), so the per-agent web-port range stays closed on
-    # the host firewall. See `docs/gateway.md::Firewall posture (host-level)`.
-
-    # NB: `services.hyperhive.domain` is required when hyperhive is
-    # enabled — the canonical assertion lives in `hive-network.nix` (the
-    # hive resolver is authoritative for `<domain>` and agents reach the
-    # forge/matrix through the gateway by it). So the daemon environment
-    # (./environment.nix) can treat it as non-null.
-    systemd.services.hive-c0re = {
-      description = "hyperhive coordinator daemon";
-      wantedBy = [ "multi-user.target" ];
-      # Socket unit must start before the service so hive-c0re receives the
-      # pre-bound fd via LISTEN_FDS (socket activation). Without this
-      # dependency, nixos-rebuild switch activates hive-c0re.socket while
-      # hive-c0re.service is already running (started by multi-user.target),
-      # and systemd refuses with "Socket service already active". Adding
-      # requires+after causes systemd to stop the service, start the socket,
-      # then restart the service -- clean transition on every config apply.
-      requires = [ "hive-c0re.socket" ];
-      after = [ "hive-c0re.socket" ];
-      path = [
-        pkgs.git
-        "/run/current-system/sw"
-      ];
-      environment = import ./environment.nix { inherit lib config pkgs; };
-      serviceConfig = {
-        ExecStart = "${cfg.package}/bin/hive-c0re --socket /run/hyperhive/host.sock serve --config /etc/hyperhive/serve.json";
-        SyslogIdentifier = "hive-c0re";
-        # Migrate hive-c0re's *own* state to the service user after an
-        # upgrade from a root-run install (systemd's StateDirectory only
-        # chowns the top-level dir, not pre-existing files inside it). The
-        # `+` prefix runs as root despite User = hive-core; `-` tolerates
-        # failure. coreutils ships `chown` but no `sh`, so invoke the
-        # binaries directly rather than through a shell.
-        #
-        # CRITICAL: exclude the per-agent `agents/` subtree. Its contents
-        # (each agent's `claude/` OAuth creds, `state/`, `harness/`,
-        # `config/`) are owned by the per-agent / manager users, and each
-        # container's `hive-agent-user-migrate` activation script chowns
-        # them back to that user on boot. Blanket-chowning them to hive-core
-        # makes every agent's `~/.claude` unreadable — logging them all out
-        # with no way to log back in. So chown everything *except* agents/,
-        # plus the `agents/` dir node itself (not its contents) so c0re can
-        # still create new per-agent subdirs.
-        ExecStartPre = [
-          # Install the safe.directory gitconfig at $HOME/.gitconfig
-          # (HOME = /var/lib/hyperhive) so c0re's `git fetch`/`rev-parse`
-          # against the agent-owned proposed repos pass the ownership guard.
-          # Placed before the chown below so it's chowned to hive-core too.
-          "+-${pkgs.coreutils}/bin/cp ${safeDirGitconfig} /var/lib/hyperhive/.gitconfig"
-          "+-${pkgs.findutils}/bin/find /var/lib/hyperhive -mindepth 1 -maxdepth 1 -not -name agents -exec ${pkgs.coreutils}/bin/chown -R hive-core:hive-core {} +"
-          "+-${pkgs.coreutils}/bin/chown hive-core:hive-core /var/lib/hyperhive/agents"
-        ];
-        Restart = "on-failure";
-        RestartSec = 2;
-        User = "hive-core";
-        Group = "hive-core";
-        SupplementaryGroups = [ "systemd-journal" ];
-        RuntimeDirectory = "hyperhive";
-        RuntimeDirectoryMode = "0750";
-        RuntimeDirectoryPreserve = "yes";
-        StateDirectory = "hyperhive";
-        StateDirectoryMode = "0750";
-        # Sandboxing. hive-c0re is unprivileged (runs as hive-core, never
-        # setuid), makes HTTP requests to forge/matrix/Anthropic (keeps INET),
-        # and delegates all privileged ops to hive-priv via a Unix socket.
-        # These directives deny the subset of kernel capabilities it
-        # provably doesn't need without restricting its network or
-        # filesystem access (RestrictAddressFamilies deferred — needs a
-        # watched deploy to verify no AF_UNIX/AF_INET gaps in socket paths).
-        NoNewPrivileges = true; # already runs as unprivileged user
-        PrivateTmp = true; # uses StateDirectory for tmpfiles, not /tmp
-        ProtectHome = true; # HOME = /var/lib/hyperhive; no /home/* access needed
-        # "strict" makes the entire filesystem read-only except for
-        # StateDirectory (/var/lib/hyperhive) and RuntimeDirectory
-        # (/run/hyperhive), which systemd keeps writable. No
-        # ReadWritePaths needed beyond the managed directories because:
-        # - nix is invoked directly (lifecycle, meta, flake_check), but
-        #   NIX_REMOTE=daemon routes all store writes through the host
-        #   daemon — hive-c0re never writes to /nix itself.
-        # - flake.lock ops land in the meta worktree under StateDirectory
-        #   (kept writable by systemd).
-        # - nix build worktrees live in PrivateTmp, not /tmp.
-        # - /etc writes (bind-mount edits) go through hive-priv via the
-        #   privileged socket; /etc/hyperhive/serve.json is read-only.
-        ProtectSystem = "strict";
-        ProtectKernelTunables = true; # no sysctl writes
-        ProtectKernelLogs = true; # reads logs via systemd-journal group, not /dev/kmsg
-        ProtectControlGroups = true; # cgroup writes go through hive-priv, not c0re directly
-        RestrictNamespaces = true; # namespace creation goes through hive-priv
-        LockPersonality = true; # no personality changes needed
-        RestrictRealtime = true; # no real-time scheduling
-      };
-    };
-
-    # Socket unit for the hive-c0re admin socket. systemd creates and holds
-    # `/run/hyperhive/host.sock` before hive-c0re starts, then passes the fd
-    # via LISTEN_FDS (socket activation). Benefits: `hivectl` can connect
-    # the moment the socket unit is active — no racy retry window — and a
-    # hive-c0re restart never drops the socket inode, so queued commands
-    # drain cleanly.
-    #
-    # `hive-c0re serve` reads LISTEN_FDS via the `listenfd` crate and
-    # accepts the fd in preference to its own `bind()` path. When invoked
-    # directly (dev, CI, without the socket unit) LISTEN_FDS is absent and
-    # the traditional bind path runs unchanged — no regression.
-    systemd.sockets.hive-c0re = {
-      description = "hive-c0re admin socket";
-      wantedBy = [ "sockets.target" ];
-      socketConfig = {
-        # Must match the `--socket` arg passed to `hive-c0re serve`.
-        ListenStream = "/run/hyperhive/host.sock";
-        # 0660 root:root — `hivectl` is a host-only tool run as root.
-        SocketMode = "0660";
-        # Parent dir inherits the RuntimeDirectory mode (0750) set on the
-        # service unit; DirectoryMode is only consulted when the dir is
-        # absent at socket-unit activation.
-        DirectoryMode = "0750";
-      };
-    };
-  };
-}

nix/host-modules/hive-c0re/environment.nix

@@ -1,180 +0,0 @@
-# Environment of the hive-c0re daemon unit — a plain function file
-# (not a module) returning the env attrset, imported by ./default.nix.
-# Everything meta.rs forwards into agent containers or reads for the
-# meta-flake render is assembled here.
-{
-  lib,
-  config,
-  pkgs,
-}:
-let
-  cfg = config.services.hyperhive.c0re;
-in
-{
-  # nix (the prebuild `nix build`, flake-check, and meta eval) writes
-  # its fetcher/eval cache under $HOME/.cache. As a system user
-  # hive-core has no home, so HOME defaults to the unwritable
-  # /var/empty and Lix fails to initialise its cache. Point HOME at
-  # the writable StateDirectory.
-  HOME = "/var/lib/hyperhive";
-  HYPERHIVE_GIT = "${pkgs.git}/bin/git";
-  # No HIVE_STATIC_DIR: the gateway static-serves the dashboard dist
-  # (see the hive-gateway module); this router is API-only.
-  # Path to the base agent frontend dist. hive-c0re's
-  # gateway_nginx.rs uses this to generate split location
-  # blocks in agents.conf — static HTML/CSS/JS served from the
-  # nix store directly; dynamic API paths still proxied to the
-  # agent daemon. The nix store is shared across nspawn
-  # containers, so this path is reachable from inside the
-  # gateway container's nginx.
-  HIVE_AGENT_FRONTEND_DIR = "${cfg.servedFrontend}/agent";
-  # Path to the static runtime asset tree (branding + claude
-  # prompts). `hive_sh4re::assets::*` reads paths underneath.
-  # `forge.rs` reads the avatar PNGs from here on startup.
-  HIVE_ASSETS_DIR = "${cfg.assets}/share/hyperhive";
-  # Whether this hive runs ruthless — no root/manager agent at all
-  # (`auto_update::ensure_root_agent`). Default false = root
-  # auto-managed; true makes the sweep a no-op.
-  HYPERHIVE_RUTHLESS = lib.boolToString config.services.hyperhive.ruthless;
-}
-// {
-  # Identity env vars threaded into c0re's own service env and
-  # forwarded by meta.rs into every sub-agent's harness env —
-  # full chain in docs/conventions.md::Hive identity. `domain` is
-  # required (asserted in hive-network.nix), so it's always set.
-  HYPERHIVE_HIVE_DOMAIN = config.services.hyperhive.domain;
-}
-// lib.optionalAttrs (config.services.hyperhive.hiveName != null) {
-  HYPERHIVE_HIVE_NAME = config.services.hyperhive.hiveName;
-}
-// lib.optionalAttrs (config.services.hyperhive.swarmName != null) {
-  HYPERHIVE_SWARM_NAME = config.services.hyperhive.swarmName;
-}
-// lib.optionalAttrs (!config.services.hyperhive.github.enable) {
-  # GitHub integration is on by default; only signal the OFF override to
-  # meta.rs, which then injects `hyperhive.github.enable = false` into
-  # every agent. See services.hyperhive.github.enable.
-  HYPERHIVE_GITHUB_DISABLED = "1";
-}
-// lib.optionalAttrs config.services.hyperhive.otel.enable (
-  # Hive-wide OTEL config -> read by meta.rs::otel_config and
-  # injected as build-time `hyperhive.otel.*` into every agent.
-  # Endpoint presence is the enable signal on the meta side; the
-  # optional fields are only emitted when set so absent values
-  # don't render no-op env lines.
-  let
-    otel = config.services.hyperhive.otel;
-  in
-  {
-    HYPERHIVE_OTEL_ENDPOINT = otel.endpoint;
-    HYPERHIVE_OTEL_PROTOCOL = otel.protocol;
-  }
-  // lib.optionalAttrs (otel.extraResourceAttributes != "") {
-    HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES = otel.extraResourceAttributes;
-  }
-  // lib.optionalAttrs (otel.headersCredential != null) {
-    HYPERHIVE_OTEL_HEADERS_CREDENTIAL = otel.headersCredential;
-  }
-  // lib.optionalAttrs (otel.metricIntervalMs != null) {
-    HYPERHIVE_OTEL_METRIC_INTERVAL_MS = toString otel.metricIntervalMs;
-  }
-  // lib.optionalAttrs otel.debug {
-    HYPERHIVE_OTEL_DEBUG = "1";
-  }
-)
-// {
-  # In-cluster forge URL — the gateway vhost (`forge.<domain>`), which
-  # nginx proxies to forgejo. Used both for internal API calls in
-  # hive-c0re (forge/mod.rs `forge_http_base()`) and forwarded to
-  # agents via meta.rs for their forge-notify client. The forge is
-  # mandatory, so this is unconditional (the whole env block is already
-  # gated on hyperhive being enabled). See `docs/gateway.md::HIVE_FORGE_URL`.
-  HIVE_FORGE_URL = "http://${config.services.hyperhive.forge.domain}";
-}
-// lib.optionalAttrs config.services.hyperhive.matrix.enable {
-  # In-cluster matrix homeserver URL for each agent's
-  # hive-matrix-daemon — the gateway vhost (`matrix.<domain>`). The
-  # gatewayHost null-guard falls back to loopback so a domain-less
-  # config still evals. Forwarded to agents by meta.rs alongside
-  # HIVE_FORGE_URL; shares the same env-forwarding ordering caveat
-  # (value baked at config-generation time).
-  HIVE_MATRIX_URL =
-    if config.services.hyperhive.matrix.gatewayHost != null then
-      "http://${config.services.hyperhive.matrix.gatewayHost}"
-    else
-      "http://127.0.0.1:${toString config.services.hyperhive.matrix.httpPort}";
-}
-// lib.optionalAttrs config.services.hyperhive.matrix.gui.enable {
-  # Availability flags read by the dashboard's `/api/state`.
-  # Matrix GUI lives entirely on the gateway nginx (matrix tab
-  # only shows when both flags are on). Gateway routing detail:
-  # docs/gateway.md::Vhost map.
-  HIVE_MATRIX_GUI_ENABLED = "1";
-}
-// {
-  # The gateway always runs, so the dashboard always builds
-  # same-origin `/agent/<name>/` links (never the direct
-  # `<host>:<port>` TCP fallback). Kept as an env flag so the
-  # dashboard doesn't need to learn the gateway is unconditional.
-  HIVE_GATEWAY_ENABLED = "1";
-}
-// lib.optionalAttrs config.services.hyperhive.forge.behindGateway {
-  # Public URL of the forge vhost served by hive-gateway. The
-  # dashboard uses this to build browser-facing forge links
-  # instead of hardcoding `<hostname>:3000`, which breaks when
-  # the operator accesses the dashboard through the gateway
-  # (forge sub-domain has no port; direct port URL would be
-  # wrong). Absent when `behindGateway = false` — dashboard
-  # falls back to `<hostname>:3000`.
-  HIVE_FORGE_PUBLIC_URL = "https://${config.services.hyperhive.forge.domain}";
-}
-//
-  lib.optionalAttrs
-    (
-      config.services.hyperhive.matrix.gui.enable && config.services.hyperhive.matrix.gatewayHost != null
-    )
-    {
-      # Browser-facing matrix GUI (fluffychat) URL — the gateway
-      # vhost (`matrix.<domain>`). Surfaced via the daemon's `Urls`
-      # request for `hivectl open matrix`. Absent when the GUI is off
-      # or no gatewayHost is set (no browser-reachable matrix vhost).
-      HIVE_MATRIX_PUBLIC_URL = "https://${config.services.hyperhive.matrix.gatewayHost}/";
-    }
-// lib.optionalAttrs (config.services.hyperhive.swarm.peers != { }) {
-  # Peer hives serialised as a JSON array of {domain, cert_fingerprint,
-  # wireguard_address?} objects. Consumed by hive-ag3nt::identity::peers()
-  # + the dashboard's peer_hives StateSnapshot field (P33RS tab). Domain
-  # is the attrset key; cert_fingerprint is null for CA-trusted peers;
-  # wireguard_address is omitted when not part of the mesh.
-  HYPERHIVE_PEERS = builtins.toJSON (
-    lib.mapAttrsToList (
-      domain: p:
-      {
-        inherit domain;
-        cert_fingerprint = p.certFingerprint;
-      }
-      // lib.optionalAttrs (p.wireguardAddress != null) {
-        wireguard_address = p.wireguardAddress;
-      }
-    ) config.services.hyperhive.swarm.peers
-  );
-}
-//
-  lib.optionalAttrs
-    (lib.any (p: p.caCert != null) (lib.attrValues config.services.hyperhive.swarm.peers))
-    {
-      # Peer-hive root CA file paths (colon-joined), one per peer that
-      # declares `swarm.peers.<domain>.caCert`. hive-c0re's meta-flake
-      # renderer (meta.rs) embeds each next to every agent's flake and
-      # adds it to `security.pki.certificateFiles`, so a peer CA is
-      # trusted everywhere the hive's own internal CA (`hive-ca.pem`)
-      # is — i.e. by every agent. The matrix container trusts the same
-      # CAs separately for federation TLS. The `caCert` files are
-      # copied into the nix store at build, so these are store paths —
-      # nothing mutable lives on the host.
-      HIVE_PEER_CA_PATHS = lib.concatStringsSep ":" (
-        lib.filter (c: c != null) (
-          lib.mapAttrsToList (_domain: p: p.caCert) config.services.hyperhive.swarm.peers
-        )
-      );
-    }

nix/host-modules/hive-c0re/options.nix

@@ -1,319 +0,0 @@
-# Option declarations for `services.hyperhive.c0re.*` — the c0re
-# daemon's knobs plus the package/source options the flake's
-# `nixosModules.default` wires to its own outputs (they carry no
-# in-module defaults; see ../../../flake.nix). The read-only
-# `servedFrontend` option lives in ./theme.nix with the stylix wiring
-# that computes it.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-{
-  options.services.hyperhive.c0re = {
-    enable = lib.mkOption {
-      type = lib.types.bool;
-      default = config.services.hyperhive.enable;
-      defaultText = lib.literalExpression "config.services.hyperhive.enable";
-      description = "Enable hive-c0re coordinator daemon (auto-enabled by services.hyperhive.enable).";
-    };
-    package = lib.mkOption {
-      type = lib.types.package;
-      defaultText = lib.literalExpression "hyperhive.packages.\${system}.default";
-      description = ''
-        hyperhive workspace package. Provides `/bin/hive-c0re`
-        (coordinator daemon + admin-socket CLI) and `/bin/hivectl`
-        (operator-facing host CLI for ad-hoc administration). Wired to
-        this flake's `packages.<system>.default` by
-        `nixosModules.default` (via `lib.mkDefault`, so setting it here
-        wins).
-      '';
-    };
-    frontend = lib.mkOption {
-      type = lib.types.package;
-      defaultText = lib.literalExpression "hyperhive.packages.\${system}.frontend";
-      description = ''
-        Bundled frontend dist (see `nix/packages/frontend.nix`). Output
-        has `dashboard/` and `agent/` subdirectories — hive-c0re serves
-        `dashboard/` via `tower_http::ServeDir` from the path passed
-        in `HIVE_STATIC_DIR`. Override to ship a custom dashboard SPA;
-        the JSON contract (`/api/state`, the SSE streams, the action
-        endpoints) is the source of truth for any replacement.
-      '';
-    };
-    assets = lib.mkOption {
-      type = lib.types.package;
-      defaultText = lib.literalExpression "hyperhive.packages.\${system}.assets";
-      description = ''
-        Bundled static runtime assets (see `nix/packages/assets.nix`): the
-        project's branding family + the claude system-prompt template +
-        claude-settings JSON. Output has `share/hyperhive/{branding,prompts}/`;
-        passed to hive-c0re's systemd unit via `HIVE_ASSETS_DIR`
-        (`hive_sh4re::assets::*` resolve paths underneath). Override to
-        ship customised branding or prompts without rebuilding the
-        rust derivation.
-      '';
-    };
-    xdgIcons = lib.mkOption {
-      type = lib.types.package;
-      defaultText = lib.literalExpression "hyperhive.packages.\${system}.xdg-icons";
-      description = ''
-        XDG icon set + .desktop entries for hyperhive processes (see
-        `nix/packages/hive-xdg-icons.nix`), installed into the host
-        system packages so desktop environments can match hyperhive
-        processes to their icon.
-      '';
-    };
-    hyperhiveFlake = lib.mkOption {
-      type = lib.types.str;
-      defaultText = lib.literalMD "the hyperhive flake's own filtered source store path";
-      description = ''
-        URL of the hyperhive flake (no fragment). Inlined into each
-        per-agent `flake.nix` at `inputs.hyperhive.url`. The per-agent
-        flake then pulls `hyperhive.nixosConfigurations.agent-base` to
-        build the container. Wired by `nixosModules.default` to this
-        flake's own filtered source — only override if you want agents
-        tracking a different ref.
-      '';
-    };
-    hyperhiveDocs = lib.mkOption {
-      type = lib.types.str;
-      defaultText = lib.literalMD "the docs/ tree's own store path";
-      description = ''
-        URL of the narrow `docs/` source (no fragment). Inlined into the
-        generated meta `flake.nix` at `inputs.hyperhive-docs.url` and
-        threaded to each agent as `hyperhive.docs.source`, from which the
-        harness resolves `$HIVE_DOCS_DIR`. Its own store path — separate
-        from `hyperhiveFlake` — so a doc edit only re-locks this input
-        instead of rebuilding every agent container.
-      '';
-    };
-    agentBaseToplevel = lib.mkOption {
-      type = lib.types.package;
-      defaultText = lib.literalExpression "hyperhive.packages.x86_64-linux.agent-base-toplevel";
-      description = ''
-        Pre-built agent-base container system closure, pulled into the
-        host system closure when `preBuildAgentTemplates` is on. Wired
-        by `nixosModules.default`; only evaluated when that option is
-        enabled.
-      '';
-    };
-    managerToplevel = lib.mkOption {
-      type = lib.types.package;
-      defaultText = lib.literalExpression "hyperhive.packages.x86_64-linux.ruth-toplevel";
-      description = ''
-        Pre-built manager (ruth) container system closure — see
-        `agentBaseToplevel`.
-      '';
-    };
-    nixpkgsFlake = lib.mkOption {
-      type = lib.types.str;
-      default = "path:${pkgs.path}";
-      defaultText = lib.literalMD "`\"path:\${pkgs.path}\"`";
-      description = ''
-        Store-path URL for the `nixpkgs` input in the generated meta
-        flake. The meta flake declares this as a top-level input and
-        wires `inputs.hyperhive.inputs.nixpkgs.follows = "nixpkgs"` so
-        every agent container evaluates with this exact nixpkgs.
-
-        Defaults to `"path:''${pkgs.path}"` — the store path of the
-        nixpkgs the host NixOS module was evaluated with. When the
-        operator sets `inputs.hyperhive.inputs.nixpkgs.follows =
-        "nixpkgs"` in their host flake, `pkgs.path` resolves to the
-        host's own nixpkgs, so agents transparently track the same
-        channel as the host.
-
-        Override to pin agents to a specific nixpkgs version regardless
-        of the host's channel.
-      '';
-    };
-    dashboardPort = lib.mkOption {
-      type = lib.types.port;
-      default = 7000;
-      description = "TCP port the hive-c0re dashboard listens on.";
-    };
-    operatorPronouns = lib.mkOption {
-      type = lib.types.str;
-      default = "she/her";
-      example = "they/them";
-      description = ''
-        Operator pronouns, free text. Threaded into every agent
-        container as the `HIVE_OPERATOR_PRONOUNS` env var; the
-        harness substitutes it into the agent / manager system
-        prompt at boot so claude refers to the operator naturally
-        in third person ("ask her", "tell them", etc.). Changes
-        propagate to running agents on the next `↻ R3BU1LD` —
-        forwards as a meta flake env-var bump, no per-agent
-        approval needed.
-      '';
-    };
-    preBuildAgentTemplates = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      example = true;
-      description = ''
-        Pre-fetch the per-container system closures (agent-base +
-        manager toplevels) into the host's /nix/store as part of this
-        host's NixOS build, instead of letting the first agent spawn
-        do all the work.
-
-        Enabling this adds roughly the full nixpkgs runtime closure +
-        claude-code + the harness binary to your system closure size
-        (low single-digit GB), but the first `nixos-container start`
-        for any agent then completes in seconds instead of minutes
-        because nothing's left to fetch.
-
-        Off by default because the toplevels are pinned to
-        `x86_64-linux` (nixos-containers run native arch). Enabling
-        on an aarch64 host would force nix to build the x86 closure
-        via cross or a remote builder, which is rarely what you want.
-        Flip to `true` on an x86_64 host when you care more about
-        first-spawn latency than host store size — or just
-        `nix build .#agent-base-toplevel` once manually to warm the
-        store.
-      '';
-    };
-    contextWindowTokens = lib.mkOption {
-      type = lib.types.attrsOf lib.types.int;
-      default = {
-        haiku = 200000;
-        sonnet = 1000000;
-        opus = 1000000;
-      };
-      example = {
-        haiku = 150000;
-        sonnet = 900000;
-      };
-      description = ''
-        Per-model context-window sizes in tokens. Each key is a
-        model-family short name matched case-insensitively as a
-        substring of the active model name at runtime (e.g. `"sonnet"`
-        matches `"claude-sonnet-4-5"`). The defaults cover the known
-        Anthropic families; add entries for new models or override
-        existing ones here to change the window for all agents at once.
-
-        Passed to `hive-c0re serve` as JSON and injected into every
-        container's harness service environment as
-        `HIVE_CONTEXT_WINDOW_TOKENS_<KEY_UPPER>`. Changes propagate
-        on the next `↻ R3BU1LD` — no per-agent approval needed.
-      '';
-    };
-
-    modelPrices = lib.mkOption {
-      type = lib.types.attrsOf (
-        lib.types.submodule {
-          options = {
-            input = lib.mkOption {
-              type = lib.types.numbers.nonnegative;
-              description = "USD per million input tokens.";
-            };
-            output = lib.mkOption {
-              type = lib.types.numbers.nonnegative;
-              description = "USD per million output tokens.";
-            };
-            cache_read = lib.mkOption {
-              type = lib.types.numbers.nonnegative;
-              description = "USD per million cache-read tokens.";
-            };
-            cache_write = lib.mkOption {
-              type = lib.types.numbers.nonnegative;
-              description = "USD per million cache-creation (write) tokens.";
-            };
-          };
-        }
-      );
-      # Current Anthropic list prices for the Claude 4.x family (Opus
-      # 4.x, Sonnet 4.x, Haiku 4.5); cache_write is the 1-hour cache-TTL
-      # price (the default through the Claude subscription the agents run
-      # on). Keep in sync with `builtin_prices` in
-      # hive-c0re/src/hive_stats.rs.
-      default = {
-        opus = {
-          input = 5.0;
-          output = 25.0;
-          cache_read = 0.5;
-          cache_write = 10.0;
-        };
-        sonnet = {
-          input = 3.0;
-          output = 15.0;
-          cache_read = 0.3;
-          cache_write = 6.0;
-        };
-        haiku = {
-          input = 1.0;
-          output = 5.0;
-          cache_read = 0.1;
-          cache_write = 2.0;
-        };
-      };
-      example = {
-        sonnet = {
-          input = 3.0;
-          output = 15.0;
-          cache_read = 0.3;
-          cache_write = 6.0;
-        };
-      };
-      description = ''
-        Per-model USD prices (per **million** tokens) used for the
-        hive-wide cost *estimate* on the dashboard's ST4TS tab. Each key
-        is a model-family short name matched case-insensitively as a
-        substring of the active model id at runtime (e.g. `"sonnet"`
-        matches `"claude-sonnet-4-5"`); the longest matching key wins, so
-        a specific entry beats a generic family name. Any model not
-        covered by this table falls back to hive-c0re's built-in
-        estimate.
-
-        The defaults track Anthropic list pricing at the time of
-        writing — override them here to keep the estimate current
-        without a code change. Passed to `hive-c0re serve` as JSON via
-        `--model-prices`; read only by hive-c0re itself (not injected
-        into containers). Changes apply on the next host rebuild.
-      '';
-    };
-
-    agentCpuQuota = lib.mkOption {
-      type = lib.types.str;
-      default = "200%";
-      example = "400%";
-      description = ''
-        systemd `CPUQuota=` applied to every agent container via a
-        `container@h-<name>.service.d/` drop-in written on each
-        spawn/rebuild. Expressed as a percentage of one CPU core —
-        `"200%"` allows each agent to use up to 2 cores. Bump this if
-        agents are hitting CPU limits during builds or heavy tool use.
-
-        For a hive-wide cap across all containers, set
-        `systemd.slices.machine.serviceConfig.CPUQuota` in your NixOS
-        config (all nspawn containers live in `machine.slice`).
-      '';
-    };
-
-    agentMemoryMax = lib.mkOption {
-      type = lib.types.str;
-      default = "4G";
-      example = "8G";
-      description = ''
-        systemd `MemoryMax=` applied to every agent container via the
-        same drop-in as `agentCpuQuota`.
-      '';
-    };
-
-    buildSlots = lib.mkOption {
-      type = lib.types.ints.positive;
-      default = 1;
-      example = 2;
-      description = ''
-        Number of nix-heavy job-queue nodes (container prebuilds,
-        profile swaps, first-spawn creates, meta lock bumps) hive-c0re
-        runs concurrently. The default of 1 serializes all heavy nix
-        work; raise it on hosts with the cores/RAM to build several
-        agent toplevels at once. Per-agent correctness is independent
-        of this count — each agent's container-affecting operations are
-        serialized by its lifecycle lease regardless.
-      '';
-    };
-  };
-}

nix/host-modules/hive-c0re/theme.nix

@@ -1,79 +0,0 @@
-# Stylix theme integration (zero-op auto-detect). When the operator's
-# host config has stylix enabled, generate a base16 `colors.css` from
-# its palette and overlay it onto the bundled frontend dist so the
-# dashboard re-themes with no operator action and no npm/esbuild
-# rebuild (a pure file-copy over the prebuilt dist). `colors.css` is
-# the entire swap contract — `theme.css` derives every semantic var
-# from the 16 base16 slots (see docs/web-ui/css-vars.md). The guarded
-# access makes this a clean no-op when stylix isn't imported into the
-# host config. Exposed as the read-only `c0re.servedFrontend` option.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  cfg = config.services.hyperhive.c0re;
-  stylixThemeColors =
-    if (config.stylix.enable or false) && ((config.lib.stylix or { }) ? colors) then
-      config.lib.stylix.colors.withHashtag
-    else
-      null;
-  themedColorsCss =
-    c:
-    pkgs.writeText "hyperhive-colors.css" ''
-      :root {
-        --base00: ${c.base00};
-        --base01: ${c.base01};
-        --base02: ${c.base02};
-        --base03: ${c.base03};
-        --base04: ${c.base04};
-        --base05: ${c.base05};
-        --base06: ${c.base06};
-        --base07: ${c.base07};
-        --base08: ${c.base08};
-        --base09: ${c.base09};
-        --base0A: ${c.base0A};
-        --base0B: ${c.base0B};
-        --base0C: ${c.base0C};
-        --base0D: ${c.base0D};
-        --base0E: ${c.base0E};
-        --base0F: ${c.base0F};
-      }
-    '';
-  # Overlay the generated colors.css onto both dist subtrees. Both the
-  # dashboard (served by hive-c0re via HIVE_STATIC_DIR) and the agent UIs
-  # (served by the gateway from HIVE_AGENT_FRONTEND_DIR — static files
-  # straight from the store) read their colors.css from this host-side
-  # tree, so swapping both re-themes both surfaces.
-  #
-  # Not covered here: an agent reached directly on its own harness web
-  # server (no gateway) serves from its per-agent `mergedDist`, built in
-  # the agent's own nixosSystem with no access to the host's stylix
-  # colours — theming that path needs the base16 palette forwarded
-  # host→agent, tracked separately.
-  themedFrontend =
-    c:
-    pkgs.runCommand "hyperhive-frontend-themed" { } ''
-      cp -r ${cfg.frontend} $out
-      chmod -R u+w $out
-      install -m644 ${themedColorsCss c} $out/dashboard/static/colors.css
-      install -m644 ${themedColorsCss c} $out/agent/static/colors.css
-    '';
-in
-{
-  options.services.hyperhive.c0re.servedFrontend = lib.mkOption {
-    type = lib.types.package;
-    internal = true;
-    readOnly = true;
-    default = if stylixThemeColors != null then themedFrontend stylixThemeColors else cfg.frontend;
-    defaultText = lib.literalExpression "<stylix-themed overlay of `frontend`>";
-    description = ''
-      Internal, read-only: `frontend` re-themed with the active stylix
-      palette (or `frontend` verbatim when unthemed); has `dashboard/`
-      and `agent/`. Exposed so the hive-gateway module can static-serve
-      `dashboard/` as an nginx root instead of proxying to hive-c0re.
-    '';
-  };
-}

nix/host-modules/hive-gateway/default.nix

@@ -1,291 +0,0 @@
-# Single nginx in front of every hyperhive web surface — dashboard,
-# per-agent UIs (sub-path), forge + matrix (sub-domain), .well-known
-# delegations — plus the hive-internal dnsmasq resolver, co-located in
-# the same `hive-gateway` container (shared host netns, state-free).
-# Full vhost map + discovery flow + design rationale in
-# `docs/gateway.md`. Layout: ./options.nix (option declarations),
-# ./vhosts.nix (the nginx virtual-host tree), ./error-pages.nix
-# (styled static pages), ./dnsmasq.nix (resolver + DHCP config).
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  cfg = config.services.hyperhive.gateway;
-  hyperhiveDomain = config.services.hyperhive.domain;
-  matrixCfg = config.services.hyperhive.matrix;
-  forgeCfg = config.services.hyperhive.forge;
-  networkCfg = config.services.hyperhive.network;
-
-  # Dashboard SPA dist, static-served by nginx. Read in OUTER scope so
-  # `config` is the host's (inside the container block it'd be the
-  # container's).
-  dashboardDist = "${config.services.hyperhive.c0re.servedFrontend}/dashboard";
-
-  # Self-signed TLS is the implicit floor: when neither an operator cert
-  # (`tls.certDir`) nor ACME (`tls.acme.enable`) is configured, the gateway
-  # generates + serves a hive-CA-signed leaf (see hive-tls.nix). There is no
-  # explicit toggle and no http-only mode — matrix discovery requires https,
-  # so the gateway always terminates TLS.
-  # `cfg.useSelfSigned` (options.nix) is the derived single source of truth.
-  useSelfSigned = cfg.useSelfSigned;
-in
-{
-  imports = [ ./options.nix ];
-
-  config = lib.mkIf config.services.hyperhive.enable {
-    assertions = [
-      {
-        assertion = !(cfg.tls.acme.enable && cfg.tls.certDir != null);
-        message = ''
-          services.hyperhive.gateway.tls.acme.enable = true and
-          tls.certDir are mutually exclusive. Pick one TLS mode.
-        '';
-      }
-      {
-        assertion = !cfg.tls.acme.enable || cfg.tls.acme.email != null;
-        message = ''
-          services.hyperhive.gateway.tls.acme.enable = true requires
-          services.hyperhive.gateway.tls.acme.email to be set —
-          Let's Encrypt needs a contact address for the ACME account.
-        '';
-      }
-    ];
-
-    # Ensure bind-mount sources exist at host boot before the gateway
-    # container's first start. nspawn would auto-create missing dirs;
-    # tmpfiles rules make the intent explicit and cover the fresh-boot
-    # window before c0re has run.
-    #
-    # /run/hive-agent — per-agent UDS socket dir, written by c0re's
-    # set_nspawn_flags when agents start. Owned by `hive-core` (the
-    # unprivileged coordinator user): c0re does the
-    # `create_dir_all(/run/hive-agent/<name>)` itself, so a root-owned
-    # parent would EACCES on the very first agent create on a fresh host
-    # (hive-priv only chowns the subdir afterwards, it doesn't make it).
-    # /var/lib/hyperhive — hyperhive state dir, created by c0re on
-    # first run. Also pre-seed agents.conf with an empty-but-valid
-    # header so nginx can start + include the file before c0re writes
-    # its first real content (f = create-if-absent, no overwrite).
-    systemd.tmpfiles.rules = [
-      "d /run/hive-agent 0755 hive-core hive-core - -"
-      "d /var/lib/hyperhive 0755 root root - -"
-      "d /var/lib/hyperhive/gateway 0755 root root - -"
-      "f /var/lib/hyperhive/gateway/agents.conf 0644 root root - # Generated by hive-c0re — do not edit.\n"
-      # Pre-create the htpasswd file so nginx can open it even before any
-      # users have been added. An empty file causes all auth checks to
-      # return 401 (no valid credentials), which is the correct no-users
-      # behaviour. `f` = create-if-absent, never overwrite.
-      "f /var/lib/hyperhive/gateway/gateway.htpasswd 0644 root root - -"
-    ];
-
-    containers.hive-gateway = {
-      autoStart = true;
-      ephemeral = false;
-      # Share host netns — nginx then binds host-level ports directly,
-      # `localhost` upstream resolution reaches hive-c0re without any
-      # port-forward dance, and the firewall config below is the only
-      # layer that matters.
-      privateNetwork = false;
-      # dnsmasq refuses to start once a dhcp-range is configured unless it
-      # holds CAP_NET_ADMIN (DNS-only mode doesn't need it). Private-network
-      # containers retain NET_ADMIN implicitly, but this container shares the
-      # host netns (above), so nspawn's default bounding set drops it — grant
-      # it explicitly. Note this is NET_ADMIN over the *host* netns; the
-      # gateway container is trusted infra (it already terminates TLS and
-      # fronts every vhost), so no new trust boundary is crossed.
-      additionalCapabilities = [ "CAP_NET_ADMIN" ];
-      # Bind-mount the per-agent socket dir so nginx inside the gateway
-      # container can `connect(2)` to the UDS upstreams.
-      # Read-only (we just connect; harness writes the socket inside
-      # the agent's own container). Host-side dir is pre-created by a
-      # tmpfiles rule so nspawn always finds a source at boot.
-      bindMounts."/run/hive-agent" = {
-        hostPath = "/run/hive-agent";
-        isReadOnly = true;
-      };
-      # Bind-mount ONLY the gateway-specific subdir of the hyperhive
-      # state dir. Scoped to /var/lib/hyperhive/gateway/ rather than
-      # the whole parent so the gateway container can't read forge
-      # tokens or other files that may live at the parent level.
-      # c0re writes agents.conf under this subdir and triggers an nginx
-      # reload from the host via systemd-run after each write.
-      # Pre-created by a tmpfiles rule.
-      bindMounts."/run/hive-state" = {
-        hostPath = "/var/lib/hyperhive/gateway";
-        isReadOnly = true;
-      };
-      # Operator-provided TLS cert dir (e.g. Let's Encrypt / ACME).
-      # Only mounted when `tls.certDir` is set; when it is, the self-signed
-      # floor is off (so the `/run/hive-ca` mount below is absent). nginx
-      # reads cert + key from `/run/hive-tls/<certName>` and `<keyName>`.
-      bindMounts."/run/hive-tls" = lib.mkIf (cfg.tls.certDir != null) {
-        hostPath = cfg.tls.certDir;
-        isReadOnly = true;
-      };
-      # Self-signed mode: the host `hive-tls-ca` service generates a hive
-      # CA + a leaf signed by it under `services.hyperhive.tls.stateDir`.
-      # Bind-mount that dir read-only so the in-container import service
-      # (below) can copy the leaf into nginx's state dir with the right
-      # owner/mode. Source files: `gateway.pem` + `gateway-key.pem`.
-      bindMounts."/run/hive-ca" = lib.mkIf useSelfSigned {
-        hostPath = config.services.hyperhive.tls.stateDir;
-        isReadOnly = true;
-      };
-      config =
-        { pkgs, ... }:
-        let
-          tlsDir = "/var/lib/hive-gateway/tls";
-          # TLS cert + key paths inside the container.
-          # - self-signed (default): imported hive-CA-signed leaf in the
-          #   persistent state dir.
-          # - tls.certDir set: operator-provided cert bind-mounted at /run/hive-tls.
-          tlsCert =
-            if cfg.tls.certDir != null then "/run/hive-tls/${cfg.tls.certName}" else "${tlsDir}/cert.pem";
-          tlsKey =
-            if cfg.tls.certDir != null then "/run/hive-tls/${cfg.tls.keyName}" else "${tlsDir}/key.pem";
-          nginxTree = import ./vhosts.nix {
-            inherit
-              lib
-              cfg
-              forgeCfg
-              matrixCfg
-              hyperhiveDomain
-              dashboardDist
-              tlsCert
-              tlsKey
-              ;
-            errorPages = import ./error-pages.nix { inherit pkgs; };
-          };
-        in
-        {
-          system.stateVersion = "26.05";
-
-          # Keep the host-copied /etc/resolv.conf intact. nixos-container
-          # copies the host's file in at every container start, but
-          # resolvconf's host-tracking mode then regenerates it — to an
-          # empty file, since the host file doesn't cross the boundary
-          # after start (the same failure the matrix container hit).
-          # With resolvconf off, nothing touches the copy: nginx's own
-          # lookups (ACME) and dnsmasq's follow-the-host upstream
-          # default (see ./dnsmasq.nix) both read the host's resolvers.
-          networking.resolvconf.enable = false;
-
-          # ACME (Let's Encrypt) integration. nginx vhosts set
-          # `enableACME = true` via the vhost builder; this provides the
-          # shared ACME config (acceptTerms + email). The gateway
-          # container has shared host netns so outbound ACME requests
-          # work without extra routing config. Certs are stored in the
-          # container's persistent state (`ephemeral = false`).
-          security.acme = lib.mkIf cfg.tls.acme.enable {
-            acceptTerms = true;
-            defaults.email = cfg.tls.acme.email;
-          };
-
-          # Import the host-generated leaf cert before nginx starts.
-          # The hive CA + gateway leaf are generated on the HOST by
-          # `hive-tls-ca` (see `hive-tls.nix`) and bind-mounted read-only
-          # at `/run/hive-ca`; this service copies the leaf into nginx's
-          # state dir with the owner/mode nginx needs, rather than reading
-          # the bind-mount directly (the host key is 0600 root:root and a
-          # cross-namespace bind-mount can't be relaxed in place). nginx
-          # `Requires=` this via `requiredBy`, so it refuses to start until
-          # the copy succeeds. ALWAYS runs (no ConditionPathExists) and is
-          # idempotent — necessary to reconcile broken state from prior
-          # failed boots (a 0700 dir from a stale UMask, a truncated copy
-          # from an interrupted oneshot, etc.). The leaf covers the bare
-          # hive domain plus `forge.`, `matrix.` and `*.${hyperhiveDomain}`
-          # so all sub-domains validate under the same cert + the hive CA.
-          # See `docs/gateway.md` ("Self-signed TLS").
-          systemd.services.hive-gateway-self-signed-cert = lib.mkIf useSelfSigned {
-            description = "Import host-generated TLS leaf for hive-gateway";
-            wantedBy = [ "multi-user.target" ];
-            before = [ "nginx.service" ];
-            requiredBy = [ "nginx.service" ];
-            serviceConfig = {
-              Type = "oneshot";
-              RemainAfterExit = true;
-              # Pin the journal identity (else it's the `script` store-path wrapper).
-              SyslogIdentifier = "hive-gateway-self-signed-cert";
-            };
-            path = [ pkgs.coreutils ];
-            script = ''
-              set -eu
-              mkdir -p ${tlsDir}
-              # 0755 on BOTH the cert dir and its parent so the nginx
-              # user can traverse the full path. The parent
-              # `/var/lib/hive-gateway` lands at 0700 by default (systemd
-              # StateDirectory / mkdir umask depending on which service
-              # created it first), which on its own blocks traversal.
-              # Re-applied every boot in case a prior run left a tighter
-              # mode behind.
-              chmod 0755 ${builtins.dirOf tlsDir}
-              chmod 0755 ${tlsDir}
-              # Copy the host leaf in. `install` writes atomically with the
-              # target mode; run as root (container root == host root,
-              # privateUsers=false) so the 0600 root:root host key is
-              # readable. Key ends up root:nginx 0640 so nginx-pre-start
-              # (which runs `nginx -t` as the nginx user, not root) can
-              # read it — a 0600 root:root key passes the master load but
-              # fails the pre-start config test with `BIO_new_file() …
-              # Permission denied`, blocking the unit. Cert is world-read.
-              install -m 0644 /run/hive-ca/gateway.pem ${tlsCert}
-              install -m 0640 -g nginx /run/hive-ca/gateway-key.pem ${tlsKey}
-            '';
-          };
-
-          # nginx reload is triggered from the HOST side by hive-c0re
-          # via `systemctl -M hive-gateway reload nginx` after each
-          # agents.conf write — letting systemd resolve the nginx binary
-          # path avoids exit-203 EXEC failures. A path unit watching the
-          # bind-mounted file inside the container does not work: an
-          # IN_MOVED_TO from an atomic rename on the host does not
-          # propagate across the nspawn mount-namespace boundary. The
-          # host-side trigger is the correct approach.
-
-          services.nginx = {
-            enable = true;
-            recommendedProxySettings = true;
-            recommendedTlsSettings = true;
-            recommendedGzipSettings = true;
-            recommendedOptimisation = true;
-            inherit (nginxTree) appendHttpConfig virtualHosts;
-          };
-
-          services.dnsmasq = import ./dnsmasq.nix {
-            inherit
-              lib
-              networkCfg
-              forgeCfg
-              matrixCfg
-              hyperhiveDomain
-              ;
-          };
-        };
-    };
-
-    networking.firewall = lib.mkIf cfg.openFirewall {
-      allowedTCPPorts = [
-        cfg.port
-        # The gateway always terminates TLS (self-signed floor), so
-        # `httpsPort` is always opened alongside the plain-http `port`.
-        cfg.httpsPort
-      ];
-    };
-
-    # `/etc/hosts` entries for local dev — bare hive domain + any
-    # sub-domain modules that are on. `lib.unique` dedupes if any
-    # sub-domain happens to equal another. See `docs/gateway.md`
-    # ("Local dev").
-    networking.hosts = lib.mkIf cfg.localHostsEntry {
-      "127.0.0.1" = lib.unique (
-        [ hyperhiveDomain ]
-        ++ lib.optional (config.services.hyperhive.forge.behindGateway or false
-        ) config.services.hyperhive.forge.domain
-        ++ lib.optional (matrixCfg.enable && matrixCfg.gatewayHost != null) matrixCfg.gatewayHost
-      );
-    };
-  };
-}

nix/host-modules/hive-gateway/dnsmasq.nix

@@ -1,61 +0,0 @@
-# Hive-internal DNS resolver + DHCP, co-located in the gateway
-# container — single front-door for both DNS and HTTP, saves a
-# sibling container. Listens on the bridge interface from
-# `services.hyperhive.network`; authoritative for the hive domain +
-# sub-domains, forwards everything else upstream. Returns the
-# `services.dnsmasq` value for the container config (see
-# ./default.nix); the DHCP pool bounds are computed by hive-network.
-{
-  lib,
-  networkCfg,
-  forgeCfg,
-  matrixCfg,
-  hyperhiveDomain,
-}:
-{
-  enable = true;
-  # Don't substitute the container's /etc/resolv.conf — the gateway
-  # uses the host's resolver for its own outbound traffic; dnsmasq is
-  # purely for incoming queries from agent containers.
-  resolveLocalQueries = false;
-  settings = {
-    # Bind only on the bridge interface (and lo for health-checks).
-    # Outside hosts can't even see the listener.
-    interface = [
-      networkCfg.bridgeName
-      "lo"
-    ];
-    bind-interfaces = true;
-    port = 53;
-    # Hive authoritative records — answer queries for the hive domain
-    # + its sub-domains with the bridge IP, where nginx is reachable
-    # from every container netns.
-    #
-    # The forge / matrix entries are redundant in the common case
-    # where `forge.domain` / `matrix.gatewayHost` are sub-domains of
-    # `hyperhive.domain` — dnsmasq's `/<domain>/` rule already matches
-    # sub-domains. Kept explicit because operators can override either
-    # to a cross-domain hostname (e.g. `forge.domain =
-    # "git.example.com"`); listing them explicitly keeps that case
-    # routed without needing an extra config block.
-    address = [
-      "/${hyperhiveDomain}/${networkCfg.bridgeIp}"
-    ]
-    ++ lib.optional ((forgeCfg.behindGateway or false)) "/${forgeCfg.domain}/${networkCfg.bridgeIp}"
-    ++ lib.optional (
-      matrixCfg.enable && matrixCfg.gatewayHost != null
-    ) "/${matrixCfg.gatewayHost}/${networkCfg.bridgeIp}";
-    # DHCP pool covering all usable host addresses on the bridge
-    # subnet — bounds computed by hive-network.nix from
-    # bridgeIp/bridgePrefixLength. All containers (agents and service
-    # containers such as hive-ci) receive their IPs dynamically.
-    dhcp-range = "${networkCfg.dhcpRangeStart},${networkCfg.dhcpRangeEnd},1h";
-    dhcp-leasefile = "/var/lib/dnsmasq/dnsmasq.leases";
-    # No explicit upstream: non-hive queries follow dnsmasq's
-    # resolv.conf default — the gateway container's `/etc/resolv.conf`,
-    # which nixos-container copies from the host at every start, so the
-    # hive always uses the host's resolvers. resolvconf is disabled in
-    # the container (see ./default.nix) so nothing regenerates that
-    # copy.
-  };
-}

nix/host-modules/hive-gateway/error-pages.nix

@@ -1,71 +0,0 @@
-# Static error/help pages the gateway serves for routes it has
-# special-cased, all rendered from one Catppuccin-styled template.
-# Useful pages instead of nginx's default 404/502 — see
-# `docs/gateway.md::Per-agent error pages` for the design rationale +
-# page-vs-status semantics. Consumed by ./vhosts.nix.
-{ pkgs }:
-let
-  mkPage =
-    {
-      name,
-      title,
-      accent,
-      body,
-    }:
-    pkgs.writeText "hive-gateway-${name}.html" ''
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="utf-8">
-        <title>${title} ◆ hyperhive</title>
-        <style>
-          body { background: #1e1e2e; color: #cdd6f4; font: 14px/1.5 -apple-system, system-ui, sans-serif; margin: 0; padding: 4rem 1rem; text-align: center; }
-          h1 { color: ${accent}; font-size: 1.5rem; margin: 0 0 0.5rem; }
-          p { max-width: 36rem; margin: 0.5rem auto; color: #a6adc8; }
-          code { background: #313244; color: #f5c2e7; padding: 0.1rem 0.35rem; border-radius: 0.2rem; font-size: 0.92em; }
-          pre { background: #181825; color: #cdd6f4; text-align: left; display: inline-block; padding: 0.75rem 1.25rem; border-radius: 0.4rem; margin: 0.75rem 0; font-size: 0.88em; line-height: 1.6; }
-          a { color: #89b4fa; }
-          .hint { color: #a6adc8; font-size: 0.9em; margin-top: 1.5rem; }
-        </style>
-      </head>
-      <body>
-        <h1>◆ ${title}</h1>
-        ${body}
-      </body>
-      </html>
-    '';
-in
-{
-  notFound = mkPage {
-    name = "agent-not-found";
-    title = "agent not found";
-    accent = "#cba6f7";
-    body = ''
-      <p>No agent matches the requested <code>/agent/&lt;name&gt;/</code> path on this hive.</p>
-      <p>Operator: check the agent name in <a href="/">the dashboard</a>.</p>
-    '';
-  };
-
-  unreachable = mkPage {
-    name = "agent-unreachable";
-    title = "agent unreachable";
-    accent = "#f9e2af";
-    body = ''
-      <p>The agent's harness web server isn't responding. Container restarting, or the agent crashed.</p>
-      <p>Operator: <a href="/">dashboard</a> → check the container status / journal; the page will recover on retry once the harness is back up.</p>
-    '';
-  };
-
-  unauthorized = mkPage {
-    name = "unauthorized";
-    title = "unauthorized";
-    accent = "#f38ba8";
-    body = ''
-      <p>This hive is protected by HTTP Basic auth. Valid credentials are required.</p>
-      <p class="hint">Operator: add a user with <code>hivectl gateway create-user</code>:</p>
-      <pre>hivectl gateway create-user \
-      &lt;username&gt; --password-stdin</pre>
-      <p class="hint">Then reload your browser and enter the credentials when prompted.</p>
-    '';
-  };
-}

nix/host-modules/hive-gateway/options.nix

@@ -1,299 +0,0 @@
-# Option declarations for `services.hyperhive.gateway.*`. The gateway
-# is always run alongside hyperhive (it's the single nginx in front of
-# every surface and the only thing exposed to the outside); there is
-# no enable flag. An operator who wants their own reverse proxy in
-# front points it at the gateway's `port`.
-{
-  lib,
-  config,
-  ...
-}:
-let
-  cfg = config.services.hyperhive.gateway;
-in
-{
-  imports = [
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "gateway" "selfSignedTls" ] ''
-      Self-signed TLS is the implicit default whenever neither
-      tls.certDir nor tls.acme is configured, and there is no http-only
-      mode. Remove the setting; configure `tls.certDir` or `tls.acme`
-      to override the self-signed default.
-    '')
-  ];
-
-  options.services.hyperhive.gateway = {
-    port = lib.mkOption {
-      type = lib.types.port;
-      default = 80;
-      example = 8080;
-      description = ''
-        TCP port the gateway listens on. Default 80 (canonical web
-        port). nginx inside the container binds <1024 because the
-        container's init runs as root; if 80 is already taken on the
-        host (existing nginx, traefik, etc.) override to an unused
-        port like 8080 or move the conflicting service.
-      '';
-    };
-
-    upstreamHost = lib.mkOption {
-      type = lib.types.str;
-      default = "127.0.0.1";
-      description = ''
-        Host the gateway proxies non-static requests to. Defaults to
-        `127.0.0.1` because the gateway container shares the host
-        netns, so loopback resolves directly to hive-c0re.
-      '';
-    };
-
-    upstreamPort = lib.mkOption {
-      type = lib.types.port;
-      default = 7000;
-      description = ''
-        TCP port the gateway proxies non-static requests to. Defaults
-        to `7000` (hive-c0re's out-of-the-box dashboard port). Operators
-        who change `services.hyperhive.c0re.dashboardPort` should set
-        `upstreamPort` to match — kept as a hardcoded default rather
-        than a cross-reference to keep this module's options eval
-        independent of c0re's option tree shape.
-      '';
-    };
-
-    openFirewall = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      example = true;
-      description = ''
-        Open `port` in the host firewall. Off by default (secure-by-default).
-        Flip to `true` to expose the gateway to
-        the operator's browser / external clients — required for any
-        out-of-host reach, since the agents themselves talk to
-        hive-c0re via the per-agent unix sockets and don't need the
-        nginx vhost. Leave off when running behind another reverse
-        proxy (e.g. caddy / traefik on the host) that handles TLS
-        termination + forwards to `port`.
-
-        **Note**: this used to default to `true`. Add
-        `services.hyperhive.gateway.openFirewall = true;` to your host
-        config if external reach stopped working after a recent upgrade.
-      '';
-    };
-
-    localHostsEntry = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      example = true;
-      description = ''
-        Add an `/etc/hosts` entry mapping `services.hyperhive.domain`
-        to `127.0.0.1` on the host. Useful for local deployments +
-        tests where there's no real DNS for `services.hyperhive.domain`
-        but the operator (or browser-based tests) want to hit
-        `http://''${services.hyperhive.domain}` to exercise the
-        gateway shape. Off by default — operators running with real
-        DNS shouldn't have a stale `/etc/hosts` entry sticking
-        around. Requires `services.hyperhive.domain` to be set.
-      '';
-    };
-
-    useSelfSigned = lib.mkOption {
-      type = lib.types.bool;
-      internal = true;
-      readOnly = true;
-      default = cfg.tls.certDir == null && !cfg.tls.acme.enable;
-      defaultText = lib.literalExpression "tls.certDir == null && !tls.acme.enable";
-      description = ''
-        Read-only derived flag: `true` when the gateway serves the
-        self-signed (hive-CA-signed) leaf — i.e. neither `tls.certDir` nor
-        `tls.acme.enable` is configured. Single source of truth for the
-        self-signed condition; consumed by the `hive-tls` and `hive-ci`
-        modules so the derivation isn't duplicated. Internal — not meant to
-        be set by operators (use `tls.certDir` / `tls.acme` to override the
-        self-signed default).
-      '';
-    };
-
-    httpsPort = lib.mkOption {
-      type = lib.types.port;
-      default = 443;
-      example = 8443;
-      description = ''
-        TCP port for the TLS-terminated vhosts. Default 443. The gateway
-        always terminates TLS (self-signed is the implicit floor when no
-        `tls.certDir` / ACME is configured), so this port is always active
-        alongside the plain-http `port`.
-      '';
-    };
-
-    tls = {
-      certDir = lib.mkOption {
-        type = lib.types.nullOr lib.types.path;
-        default = null;
-        example = lib.literalExpression ''"/var/lib/acme/example.com"'';
-        description = ''
-          Path to a host directory containing a TLS certificate and
-          private key for nginx. When set, nginx listens on `httpsPort`
-          and uses this cert, overriding the self-signed default — the
-          auto-generated hive-CA-signed leaf is skipped entirely.
-
-          The directory is bind-mounted read-only into the gateway
-          container at `/run/hive-tls/`. nginx reads
-          `<certDir>/<tls.certName>` and `<certDir>/<tls.keyName>`.
-          Default filenames (`cert.pem` / `key.pem`) match the output
-          layout of nixpkgs's `security.acme` module.
-
-          Typical ACME setup:
-          ```nix
-          security.acme.certs."example.com" = { ... };
-          services.hyperhive.gateway.tls.certDir =
-            config.security.acme.certs."example.com".directory;
-          ```
-
-          When using an external CA cert, peer hives can declare this
-          hive in `services.hyperhive.swarm.peers` without
-          `certFingerprint` — the standard CA bundle validates.
-
-          Mutual exclusion with `tls.acme.enable` — set one or the other,
-          not both.
-        '';
-      };
-
-      certName = lib.mkOption {
-        type = lib.types.str;
-        default = "cert.pem";
-        description = ''
-          Filename of the TLS certificate within `tls.certDir`. Defaults
-          to `cert.pem` which matches nixpkgs's `security.acme` output.
-        '';
-      };
-
-      keyName = lib.mkOption {
-        type = lib.types.str;
-        default = "key.pem";
-        description = ''
-          Filename of the TLS private key within `tls.certDir`. Defaults
-          to `key.pem` which matches nixpkgs's `security.acme` output.
-        '';
-      };
-
-      acme = {
-        enable = lib.mkOption {
-          type = lib.types.bool;
-          default = false;
-          example = true;
-          description = ''
-            Let nginx inside the gateway container obtain and renew TLS
-            certificates automatically via ACME (Let's Encrypt). When
-            enabled, each vhost calls out to Let's Encrypt using the
-            HTTP-01 challenge on `port` (default 80) and stores certs
-            inside the gateway container's persistent state dir.
-
-            Requirements:
-            - `services.hyperhive.domain` must be set and publicly
-              DNS-resolvable to this host.
-            - `services.hyperhive.gateway.openFirewall = true` so
-              Let's Encrypt can reach `/.well-known/acme-challenge/`.
-            - `tls.acme.email` must be set (ACME account contact).
-
-            Mutual exclusion: `tls.certDir` set together with
-            `tls.acme.enable = true` fails at eval — pick one TLS source.
-
-            Typical setup:
-            ```nix
-            services.hyperhive.gateway = {
-              openFirewall  = true;
-              tls.acme = {
-                enable = true;
-                email  = "admin@example.com";
-              };
-            };
-            ```
-
-            After enabling, peer hives can omit `certFingerprint` in
-            `swarm.peers` — Let's Encrypt certs are CA-trusted
-            by default.
-          '';
-        };
-
-        email = lib.mkOption {
-          type = lib.types.nullOr lib.types.str;
-          default = null;
-          example = "admin@example.com";
-          description = ''
-            Email address for the ACME account registration with
-            Let's Encrypt. Required when `tls.acme.enable = true`.
-            Let's Encrypt sends expiry warnings to this address.
-          '';
-        };
-      };
-    };
-
-    auth = {
-      enable = lib.mkEnableOption ''
-        HTTP basic auth on the gateway using an htpasswd file. When
-        enabled, every request to the gateway's main vhost requires a
-        valid username and password. nginx's built-in `auth_basic`
-        module validates credentials against
-        `/var/lib/hyperhive/gateway/gateway.htpasswd` on the host
-        (exposed as `/run/hive-state/gateway.htpasswd` inside the
-        container via the existing gateway state bind-mount). Off by default.
-
-        Manage users with `hivectl gateway create-user`, `delete-user`,
-        and `list-users` — see `hivectl gateway --help` for usage.
-        The htpasswd file is created automatically when auth is enabled;
-        add at least one user before enabling to avoid locking everyone out.
-      '';
-
-      realm = lib.mkOption {
-        type = lib.types.strMatching "[^\"$]*";
-        default = "hyperhive";
-        example = "my-hive";
-        description = ''
-          HTTP Basic auth `realm` value sent in the `WWW-Authenticate`
-          header when credentials are absent or rejected. Must not
-          contain `"` or `$` (nginx string metacharacters).
-        '';
-      };
-    };
-
-    hsts = {
-      enable = lib.mkOption {
-        type = lib.types.bool;
-        default = false;
-        description = ''
-          Add `Strict-Transport-Security` to all gateway vhosts.
-
-          Disabled by default: HSTS pins HTTPS in the browser's HSTS
-          preload list; enabling it on a deployment that later loses TLS
-          will lock browsers out until the max-age expires. Only enable
-          this when you are certain TLS is permanent.
-
-          The gateway always terminates TLS (self-signed floor), so
-          HSTS is always served over https when enabled — but mind the
-          warning above: HSTS pins https in the browser, so only enable it
-          when TLS is permanent for this deployment.
-        '';
-      };
-
-      maxAge = lib.mkOption {
-        type = lib.types.ints.positive;
-        default = 31536000;
-        example = 86400;
-        description = ''
-          Value for the `max-age` directive in seconds.
-          Default: 31536000 (1 year), which is the value required for
-          HSTS preload list submission. Use a shorter value (e.g. 86400)
-          while testing so browsers forget the pin quickly.
-        '';
-      };
-
-      includeSubDomains = lib.mkOption {
-        type = lib.types.bool;
-        default = true;
-        description = ''
-          Whether to include `includeSubDomains` in the HSTS header.
-          Only disable this if the gateway host has sub-domains that
-          intentionally serve plain HTTP.
-        '';
-      };
-    };
-  };
-}

nix/host-modules/hive-gateway/vhosts.nix

@@ -1,347 +0,0 @@
-# nginx virtual-host tree for the gateway container: the `_` default
-# server (dashboard, per-agent routing, matrix discovery), the forge
-# and matrix sub-domain vhosts, and the Accept-header SPA map for the
-# matrix GUI. Pure function — called from ./default.nix inside the
-# container config with the outer-scope config values as arguments;
-# returns `{ virtualHosts, appendHttpConfig }`.
-{
-  lib,
-  cfg, # services.hyperhive.gateway
-  forgeCfg,
-  matrixCfg,
-  hyperhiveDomain,
-  dashboardDist,
-  errorPages, # ./error-pages.nix: { notFound, unreachable, unauthorized }
-  tlsCert,
-  tlsKey,
-}:
-let
-  # The gateway always terminates TLS: self-signed is the implicit
-  # floor when neither `tls.certDir` nor ACME is set, so there is no
-  # http-only mode. Listen addresses every vhost shares — plain http
-  # on `cfg.port` plus TLS on `cfg.httpsPort`. See `docs/gateway.md`
-  # ("TLS modes").
-  vhostListen = [
-    {
-      addr = "0.0.0.0";
-      port = cfg.port;
-    }
-    {
-      addr = "0.0.0.0";
-      port = cfg.httpsPort;
-      ssl = true;
-    }
-  ];
-  # nixos `services.nginx.virtualHosts.<name>` ssl attrs merged
-  # into each vhost. For ACME mode: `enableACME` + `addSSL` —
-  # NixOS's ACME integration manages the cert lifecycle and sets
-  # ssl_certificate automatically. For self-signed / certDir:
-  # explicit cert paths.
-  vhostTls =
-    if cfg.tls.acme.enable then
-      {
-        addSSL = true;
-        enableACME = true;
-      }
-    else
-      {
-        addSSL = true;
-        sslCertificate = tlsCert;
-        sslCertificateKey = tlsKey;
-      };
-
-  # Public-facing scheme + port-suffix for URLs the gateway
-  # mints into responses (well-known JSON, the deprecated
-  # `<hive>/matrix/*` 301 redirect, future absolute-URL needs):
-  # always `https://<host>` (matrix-spec compliance) — the canonical
-  # 443 elides the port. See `docs/gateway.md` ("Self-signed TLS").
-  publicScheme = "https";
-  publicPort = cfg.httpsPort;
-  publicPortSuffix = if publicPort == 443 then "" else ":${toString publicPort}";
-
-  # Security headers added at the server scope on every vhost.
-  # nginx's add_header inheritance rule: a location that defines its
-  # own add_header does NOT inherit the server-level ones. Any
-  # location with its own add_header (e.g. CORS on /.well-known or
-  # /_matrix/) must repeat the security headers explicitly — see those
-  # locations below. HTML-serving and proxy locations that carry no
-  # add_header of their own pick these up from the server scope
-  # automatically.
-  hstsDirectives = lib.concatStringsSep "; " (
-    [ "max-age=${toString cfg.hsts.maxAge}" ]
-    ++ lib.optional cfg.hsts.includeSubDomains "includeSubDomains"
-  );
-  securityHeaders = ''
-    add_header X-Frame-Options "SAMEORIGIN" always;
-    add_header X-Content-Type-Options "nosniff" always;
-    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
-    ${lib.optionalString cfg.hsts.enable ''add_header Strict-Transport-Security "${hstsDirectives}" always;''}
-  '';
-
-  # Forge sub-domain vhost. `server_name = forge.domain`, proxies
-  # all `/` → forgejo. Tuned for git: `client_max_body_size 1G`,
-  # `proxy_read_timeout 1h` (multi-GB clones). SSH stays direct on
-  # `forge.sshPort`. See `docs/gateway.md`. Empty attrset when the
-  # forge isn't behind the gateway.
-  forgeVhost = lib.optionalAttrs (forgeCfg.behindGateway or false) {
-    "${forgeCfg.domain}" = vhostTls // {
-      listen = vhostListen;
-      extraConfig = securityHeaders;
-      locations."/" = {
-        proxyPass = "http://127.0.0.1:${toString forgeCfg.httpPort}/";
-        proxyWebsockets = true;
-        extraConfig = ''
-          proxy_buffering off;
-          client_max_body_size 1G;
-          proxy_read_timeout 1h;
-          proxy_send_timeout 1h;
-        '';
-      };
-    };
-  };
-
-  # Matrix sub-domain vhost. `server_name = matrixCfg.gatewayHost`.
-  # `/_matrix/*` → tuwunel (CORS *, 50M body cap, 1h long-poll
-  # timeout). `/` serves fluffychat or 404 if GUI off. nginx
-  # longer-prefix-wins puts `/_matrix/` ahead of `/`. See
-  # `docs/gateway.md`. Empty attrset when matrix has no gateway host.
-  matrixVhost = lib.optionalAttrs (matrixCfg.enable && matrixCfg.gatewayHost != null) {
-    "${matrixCfg.gatewayHost}" = vhostTls // {
-      listen = vhostListen;
-      extraConfig = securityHeaders;
-      locations = {
-        "/_matrix/" = {
-          proxyPass = "http://127.0.0.1:${toString matrixCfg.httpPort}";
-          proxyWebsockets = true;
-          extraConfig = ''
-            proxy_buffering off;
-            client_max_body_size 50M;
-            proxy_read_timeout 1h;
-            proxy_send_timeout 1h;
-            ${securityHeaders}
-            add_header Access-Control-Allow-Origin *;
-          '';
-        };
-      }
-      // lib.optionalAttrs (matrixCfg.gui.enable) (
-        {
-          # fluffychat at sub-domain root, SPA-fallback via
-          # the Accept-header `$matrix_spa_target` map.
-          "/" = {
-            alias = "${matrixCfg.gui.package}/";
-            extraConfig = ''
-              try_files $uri $uri/ $matrix_spa_target =404;
-            '';
-          };
-        }
-        // {
-          # FluffyChat boot-config pre-fill so the client's
-          # `.well-known/matrix/client` lookup hits the
-          # right delegation endpoint. `domain` is required, so
-          # this is always present.
-          "= /config.json" = {
-            extraConfig = ''
-              default_type application/json;
-              return 200 '{"defaultHomeserver":"${hyperhiveDomain}"}';
-            '';
-          };
-        }
-      )
-      // lib.optionalAttrs (!matrixCfg.gui.enable) {
-        "/" = {
-          return = "404";
-        };
-      };
-    };
-  };
-
-  # `<hive>/matrix/*` → 301 → `matrix.<hive>/$1` (legacy deep-link
-  # shim during the fluffychat sub-domain move). See `docs/gateway.md`.
-  matrixRedirectLocations =
-    lib.optionalAttrs (matrixCfg.enable && matrixCfg.gui.enable && matrixCfg.gatewayHost != null)
-      (
-        let
-          target = "${publicScheme}://${matrixCfg.gatewayHost}${publicPortSuffix}";
-        in
-        {
-          "/matrix/" = {
-            extraConfig = ''
-              rewrite ^/matrix/(.*)$ ${target}/$1 permanent;
-            '';
-          };
-        }
-      );
-
-  # `.well-known/matrix/{client,server}` discovery JSON. Points
-  # clients at `matrixCfg.gatewayHost` when set; falls back to direct
-  # `<hive>:<httpPort>`. CORS `*` per matrix spec. The `m.server`
-  # port-8448 carve-out is documented inline. See `docs/gateway.md`.
-  wellKnownLocations = lib.optionalAttrs matrixCfg.enable (
-    let
-      clientBaseUrl =
-        if matrixCfg.gatewayHost != null then
-          "${publicScheme}://${matrixCfg.gatewayHost}${publicPortSuffix}"
-        else
-          "${publicScheme}://${hyperhiveDomain}:${toString matrixCfg.httpPort}";
-      # `m.server` is NOT a URL: per the matrix server-server spec
-      # (Resolving Server Names) a delegated host with NO port resolves
-      # to the federation default 8448 (after the SRV check) — the
-      # https-implies-443 rule does NOT apply here. So the port must be
-      # explicit even when it's the HTTPS default; `publicPortSuffix`
-      # (which drops :443) is right for the client base_url above but
-      # wrong for federation delegation. Without this, peers federate to
-      # <gatewayHost>:8448 (closed) while the endpoint actually lives on
-      # the gateway's 443 vhost. See docs/gateway.md discovery flow.
-      serverHostPort =
-        if matrixCfg.gatewayHost != null then
-          "${matrixCfg.gatewayHost}:${toString publicPort}"
-        else
-          "${hyperhiveDomain}:${toString matrixCfg.httpPort}";
-    in
-    {
-      "= /.well-known/matrix/client" = {
-        extraConfig = ''
-          default_type application/json;
-          ${securityHeaders}
-          add_header Access-Control-Allow-Origin *;
-          return 200 '{"m.homeserver":{"base_url":"${clientBaseUrl}"}}';
-        '';
-      };
-      "= /.well-known/matrix/server" = {
-        extraConfig = ''
-          default_type application/json;
-          return 200 '{"m.server":"${serverHostPort}"}';
-        '';
-      };
-    }
-  );
-
-  # `/agent/` catch-all 404 + the two internal error-page targets it
-  # points at. Per-agent `location /agent/<name>/` blocks live in the
-  # runtime-generated `/run/hive-state/agents.conf` (included via
-  # `extraConfig` on the vhost); nginx longest-prefix-match makes a
-  # real `/agent/<name>/` beat this catch-all. `internal` keeps the
-  # error pages reachable only through nginx's error handling.
-  agentLocations = {
-    "/agent/" = {
-      extraConfig = ''
-        error_page 404 = /__hive_agent_not_found;
-        return 404;
-      '';
-    };
-    "= /__hive_agent_not_found" = {
-      extraConfig = ''
-        internal;
-        alias ${errorPages.notFound};
-        default_type text/html;
-      '';
-    };
-    "= /__hive_agent_unreachable" = {
-      extraConfig = ''
-        internal;
-        alias ${errorPages.unreachable};
-        default_type text/html;
-      '';
-    };
-  };
-
-  # Shared auth block — separate locations don't inherit auth_basic, so
-  # each dashboard location (`/`, `/api/`) needs it or that surface is
-  # unauthed. `/webhook/` is intentionally excluded: Forgejo cannot
-  # send HTTP Basic credentials with webhook deliveries, and the HMAC
-  # secret (`X-Hub-Signature-256`) protects those endpoints instead.
-  dashboardAuth = lib.optionalString cfg.auth.enable ''
-    auth_basic "${cfg.auth.realm}";
-    auth_basic_user_file /run/hive-state/gateway.htpasswd;
-    # `=401` keeps the status 401 so the login dialog shows; the
-    # internal page explains `hivectl gateway create-user`.
-    error_page 401 =401 /__hive_auth_unauthorized;
-  '';
-
-  # Dashboard: nginx static-serves the dist, c0re is API-only. Routing
-  # is by PATH, never content-type. c0re serves exactly two prefixes —
-  # `/api/` (all dashboard data + actions + the SSE streams) and
-  # `/webhook/` (knowledge push + config-PR approval triggers, HMAC-
-  # guarded) — so those proxy to c0re and everything else serves the
-  # dist with an SPA fallback to index.html. Path routing is
-  # deterministic where an Accept-header split would make the SAME url
-  # behave differently by content-type (e.g. `/api/state` fetched with
-  # `Accept: text/html` wrongly getting index.html). A new top-level
-  # c0re route prefix (beyond /api + /webhook) needs a matching
-  # location added here.
-  dashboardProxyLocation = {
-    "/" = {
-      root = dashboardDist;
-      extraConfig = ''
-        try_files $uri /index.html;
-        ${dashboardAuth}
-      '';
-    };
-    "/api/" = {
-      proxyPass = "http://${cfg.upstreamHost}:${toString cfg.upstreamPort}";
-      proxyWebsockets = true;
-      extraConfig = ''
-        # off + 1d keep the SSE streams (/api/dashboard/stream,
-        # /api/build-logs/id/{id}/stream) live.
-        proxy_buffering off;
-        proxy_read_timeout 1d;
-        ${dashboardAuth}
-      '';
-    };
-    "/webhook/" = {
-      # No dashboardAuth here: Forgejo cannot send HTTP Basic credentials
-      # with webhook deliveries. HMAC (X-Hub-Signature-256) is the auth
-      # for these endpoints; hive-c0re verifies it in the handler.
-      proxyPass = "http://${cfg.upstreamHost}:${toString cfg.upstreamPort}";
-    };
-  };
-in
-{
-  # Accept-header SPA map for the matrix GUI only (see docs/gateway.md
-  # "SPA fallback"): text/html → index.html, else a sentinel so
-  # try_files falls through to 404. The dashboard doesn't use an
-  # Accept-header map — it routes by path (see dashboardProxyLocation).
-  appendHttpConfig = lib.optionalString (matrixCfg.enable && matrixCfg.gui.enable) ''
-    map $http_accept $matrix_spa_target {
-      default              "/__matrix_spa_no_html_fallback";
-      "~*text/html"        "/index.html";
-    }
-  '';
-
-  virtualHosts = {
-    "_" = vhostTls // {
-      listen = vhostListen;
-      locations =
-        matrixRedirectLocations
-        // wellKnownLocations
-        // agentLocations
-        // dashboardProxyLocation
-        // lib.optionalAttrs cfg.auth.enable {
-          # Internal-only target for the 401 error_page above.
-          # `internal` prevents direct client access; `alias` serves
-          # the pre-built HTML from the Nix store.
-          "= /__hive_auth_unauthorized" = {
-            extraConfig = ''
-              internal;
-              alias ${errorPages.unauthorized};
-              default_type text/html;
-            '';
-          };
-        };
-      # Per-agent location blocks, generated at runtime by
-      # hive-c0re and written to /var/lib/hyperhive/gateway/agents.conf
-      # on the host. The bind-mount at /run/hive-state/ exposes
-      # that file here. nginx parses `include` at config-load
-      # time so a reload (triggered by c0re via systemd-run
-      # after each agents.conf write) picks up new or removed
-      # agents without a nixos-rebuild. nginx's longest-prefix-
-      # match rule ensures `/agent/<name>/` from this file beats
-      # the `/agent/` catch-all above.
-      extraConfig = securityHeaders + ''
-        include /run/hive-state/agents.conf;
-      '';
-    };
-  }
-  // forgeVhost
-  // matrixVhost;
-}

nix/host-modules/hive-priv.nix

@@ -1,157 +0,0 @@
-# hive-priv — the narrow root privileged helper hive-c0re delegates
-# to, socket-activated at /run/hive/priv.sock. See docs/boundary.md
-# for the operator/agent trust-boundary design.
-{
-  pkgs,
-  lib,
-  config,
-  ...
-}:
-let
-  cfg = config.services.hyperhive.c0re;
-
-  # Same safe.directory gitconfig as the c0re unit (see ./hive-c0re)
-  # — hive-priv (root) runs nix, which fetches the hive-core-owned
-  # meta/applied repos; libgit2 refuses cross-user reads without it.
-  safeDirGitconfig = pkgs.writeText "hyperhive-safe-gitconfig" ''
-    [safe]
-    directory = *
-  '';
-in
-{
-  config = lib.mkIf cfg.enable {
-    # Socket unit for hive-priv — the narrow root helper that executes
-    # privileged operations on behalf of hive-c0re. Systemd creates and
-    # holds `/run/hive/priv.sock` before the first connection arrives.
-    #
-    # Mode 0660 hive-core:hive-core: only the hive-c0re service user can
-    # connect. hive-priv (server) runs as root and validates every request
-    # against a strict allowlist before executing any privileged op.
-    systemd.sockets.hive-priv = {
-      description = "hive-priv privileged helper socket";
-      wantedBy = [ "sockets.target" ];
-      socketConfig = {
-        ListenStream = "/run/hive/priv.sock";
-        SocketMode = "0660";
-        SocketGroup = "hive-core";
-        # Create /run/hive/ if absent; 0755 so the hive-core user can
-        # traverse into it to reach the socket.
-        DirectoryMode = "0755";
-      };
-    };
-
-    # Service unit for hive-priv. Runs as root — it genuinely needs root to
-    # invoke `nixos-container`, write `/etc/nixos-containers/`, write
-    # systemd drop-ins in `/run/systemd/system/`, and call `chown(2)`.
-    # Every request is validated against a strict container-name allowlist
-    # inside the binary; the attack surface is narrow by design.
-    #
-    # Socket-activated: systemd starts hive-priv on the first connection
-    # (no earlier). LISTEN_FDS + LISTEN_PID are set by systemd; hive-priv
-    # reads them to accept the pre-bound socket fd instead of binding its
-    # own.
-    systemd.services.hive-priv = {
-      description = "hive-priv privileged helper";
-      # No wantedBy — socket-activated exclusively. The socket unit is the
-      # entry point; systemd starts this service on first connect.
-      after = [ "hive-priv.socket" ];
-      requires = [ "hive-priv.socket" ];
-      # `nixos-container` is a perl script that shells out by bare name to
-      # nix / nix-env / nix-instantiate (create + update), machinectl +
-      # systemctl (start/stop), and find / rm / umount / chattr (destroy);
-      # only nsenter + su are hardcoded. Give the helper exactly those —
-      # not the whole system profile — on top of the systemd/coreutils/
-      # findutils already in the default unit PATH. Without `nixos-container`
-      # on PATH every container op fails ENOENT, which `build_all` silently
-      # swallows into an empty list ("no managed containers").
-      #
-      # `nix` itself shells out by bare name too: `git` whenever it has to
-      # fetch/re-resolve a git-source flake input (an agent.nix with a
-      # `git+https://…` input, or a stale flake.lock whose node URL no longer
-      # matches the flake's declared input → nix re-resolves at eval), and
-      # `ssh` to dispatch to remote builders (`nix.buildMachines` /
-      # `ssh-ng://`). Without these on PATH `nixos-container update` dies with
-      # `executing "git": No such file or directory` / `Could not find
-      # executable 'ssh'` — the agent build fails before it starts.
-      path = [
-        pkgs.nixos-container
-        pkgs.nix # nix, nix-env, nix-instantiate — create + update
-        pkgs.gitMinimal # git — nix fetches/re-resolves git-source flake inputs
-        pkgs.openssh # ssh — nix dispatches builds to remote builders
-        pkgs.util-linux # umount (nsenter is hardcoded in the script)
-        pkgs.e2fsprogs # chattr
-        pkgs.btrfs-progs # btrfs subvolume create/delete — Ensure/DeleteAgentSubvolume
-      ];
-      environment = {
-        # `nixos-container update/create` runs `nix`, which writes its
-        # fetcher/eval cache under $HOME/.cache. With ProtectHome and no
-        # explicit HOME this lands on the unwritable /var/empty and Lix
-        # errors out. Point HOME at the StateDirectory below (persistent,
-        # so the cache survives across rebuilds).
-        HOME = "/var/lib/hive-priv";
-        # hive-priv runs as root. Root nix defaults to store=auto which
-        # resolves to the LOCAL store — bypassing the host daemon, its
-        # remote builders, and prebuilt derivation outputs. Force daemon
-        # routing so nixos-container update and the nix prebuild see the
-        # same store and substituters as every other build context.
-        NIX_REMOTE = "daemon";
-      };
-      serviceConfig = {
-        ExecStart = "${cfg.package}/bin/hive-priv";
-        SyslogIdentifier = "hive-priv";
-        Type = "simple";
-        User = "root";
-        PrivateTmp = true;
-        ProtectHome = true;
-        # Harden the file system view: strict makes the entire hierarchy
-        # read-only by default; ReadWritePaths carves out exactly the
-        # paths hive-priv must write to at runtime.
-        #
-        # Why each entry is needed:
-        #   /etc/nixos-containers  — writes <container>.conf (bind mounts,
-        #                            network isolation, nspawn flags)
-        #   /run/hive-agent        — chown/chmod per-agent socket directories
-        #   /run/systemd           — container@ unit drop-ins (resource limits)
-        #                            + machinectl / systemd-machined state
-        #   /run/lock              — `nixos-container` opens a lock file at
-        #                            /run/lock/nixos-container to serialise
-        #                            create/destroy. Under ProtectSystem=strict
-        #                            /run is read-only, so without this the very
-        #                            first `nixos-container create` (ruth, on a
-        #                            fresh host) dies with "Read-only file
-        #                            system" before any container exists.
-        #   /var/lib/nixos-containers — container rootfs written by nixos-container
-        #   /var/lib/hyperhive     — agent state files written by WriteAgentForgeToken
-        #                            / WriteAgentMatrixToken (tokens under agents/<n>/state/)
-        #   /nix                   — nix store + profile updates during
-        #                            container create/update
-        ProtectSystem = "strict";
-        ReadWritePaths = [
-          "/etc/nixos-containers"
-          "/run/hive-agent"
-          "/run/systemd"
-          "/run/lock"
-          "/var/lib/nixos-containers"
-          "/var/lib/hyperhive"
-          "/nix"
-        ];
-        # Writable HOME for nix's caches (see environment.HOME above).
-        StateDirectory = "hive-priv";
-        # With ProtectSystem=strict the root filesystem is read-only inside
-        # hive-priv. When `nixos-container create/update` invokes nix, nix
-        # creates a temporary result symlink in its working directory. Without
-        # an explicit WorkingDirectory the cwd is / (inherited from systemd),
-        # which is read-only under strict, causing:
-        #   error: creating symlink "/.tmp.tmp-..." -> ...: Read-only file system
-        # Point the working directory at the writable StateDirectory so nix
-        # drops its temp symlink there instead.
-        WorkingDirectory = "/var/lib/hive-priv";
-        # nix (run here as root for `nixos-container update --flake
-        # /var/lib/hyperhive/meta#<agent>`) fetches the hive-core-owned
-        # meta/applied repos; libgit2 refuses them without safe.directory.
-        # See safeDirGitconfig above.
-        ExecStartPre = "+-${pkgs.coreutils}/bin/cp ${safeDirGitconfig} /var/lib/hive-priv/.gitconfig";
-      };
-    };
-  };
-}

nix/host-modules/hyperhive.nix

@@ -1,109 +0,0 @@
-# Top-level, cross-cutting hyperhive options: the master enable
-# switch, the hive's identity (domain + display names), and hive-wide
-# feature toggles read by several subsystem modules. Imported by the
-# ./default.nix aggregator.
-{
-  lib,
-  ...
-}:
-{
-  # Top-level hyperhive enable flag. When true, automatically enables
-  # hive-c0re and the on-by-default hyperhive subsystems.
-  options.services.hyperhive.enable = lib.mkEnableOption "hyperhive — the agent swarm coordinator";
-
-  # Canonical hive DNS domain shared by every subsystem that needs a
-  # stable hostname. Typed nullOr (default null) so the option always
-  # exists, but it's REQUIRED whenever hyperhive is enabled — an
-  # assertion in hive-network.nix fails eval when it's unset, since
-  # matrix bakes it in on first boot and the gateway/forge/agent URLs all
-  # derive from it (no safe default). Full identity-surface
-  # context (HYPERHIVE_HIVE_DOMAIN / HIVE_NAME / SWARM_NAME env-var
-  # chain → identity.rs → claude prompt): docs/conventions.md::
-  # Hive identity (label + domain + display names).
-  options.services.hyperhive.domain = lib.mkOption {
-    type = lib.types.nullOr lib.types.str;
-    default = null;
-    example = "darkest.space";
-    description = ''
-      Canonical host domain for hyperhive subsystems that need a
-      stable name (currently: `services.hyperhive.matrix.serverName`
-      derives from this, defaulting to
-      `matrix.''${services.hyperhive.domain}` when `serverName` is
-      null). **Required** when `services.hyperhive.enable` — eval fails
-      with a helpful message if it's unset (it's baked into matrix on
-      first boot and drives the gateway/forge/agent URLs, with no safe
-      default; changing it later is destructive). Exposed to agents as
-      `HYPERHIVE_HIVE_DOMAIN`; consumed by
-      `hive-ag3nt::identity::hive_domain()` for `<name>@<domain>`
-      qualified labels.
-    '';
-  };
-
-  # Human display names for hive + swarm. Distinct from the DNS
-  # domain above (machine-readable) — see
-  # docs/conventions.md::Hive identity for the
-  # domain-vs-name-vs-swarm distinction + the env-var
-  # propagation chain.
-  options.services.hyperhive.hiveName = lib.mkOption {
-    type = lib.types.nullOr lib.types.str;
-    default = null;
-    example = "pr1ma";
-    description = ''
-      Human-readable name of this single-host hive instance.
-      Distinct from `services.hyperhive.domain` (the machine-
-      addressable DNS name): the domain may carry the hive name as
-      its leftmost label by convention, but this option is the
-      canonical readable identity. Exposed to agents as
-      `HYPERHIVE_HIVE_NAME`; surfaced in the dashboard chrome and
-      per-agent system prompt when set. Null falls back to the
-      default behaviour (chrome shows the domain, prompt doesn't
-      mention a hive name).
-    '';
-  };
-
-  options.services.hyperhive.swarmName = lib.mkOption {
-    type = lib.types.nullOr lib.types.str;
-    default = null;
-    example = "constellat1on";
-    description = ''
-      Human-readable name of the wider swarm this hive belongs to.
-      Hives at different DNS domains can share a swarm name when
-      they federate together. Exposed to agents as
-      `HYPERHIVE_SWARM_NAME`; surfaced in the dashboard chrome and
-      per-agent system prompt when set.
-    '';
-  };
-
-  # Whether this hive runs "ruthless" — with no root/manager agent at
-  # all. Some hives don't want a root agent — see issue tracker
-  # "scope concept: special agents".
-  options.services.hyperhive.ruthless = lib.mkOption {
-    type = lib.types.bool;
-    default = false;
-    example = true;
-    description = ''
-      Run this hive "ruthless" — with no root (manager) agent at all (no
-      ruth). When `true`, hive-c0re skips the root-agent auto-management
-      sweep entirely (it otherwise creates the root agent's container when
-      missing and restarts it when present but stopped). Defaults to
-      `false` (the root agent is auto-managed as required
-      infrastructure). Exposed to hive-c0re as `HYPERHIVE_RUTHLESS`.
-    '';
-  };
-
-  options.services.hyperhive.github.enable = lib.mkOption {
-    type = lib.types.bool;
-    default = true;
-    example = false;
-    description = ''
-      Hive-wide switch for the per-agent GitHub integration (the `gh` CLI
-      wrapper + git credential helper, per `hyperhive.github.enable`). On by
-      default: every agent gets the integration, inert until a PAT is
-      provisioned via the dashboard credentials tab or `hivectl github
-      set-token`. Set `false` to turn it off for the whole hive --- the
-      meta-flake renderer (`hive-c0re/src/meta.rs`) then injects
-      `hyperhive.github.enable = false` into every agent. Exposed to hive-c0re
-      as `HYPERHIVE_GITHUB_DISABLED` (set only when the integration is off).
-    '';
-  };
-}

nix/host-modules/otel.nix

@@ -1,117 +0,0 @@
-# Hive-wide OTEL stats export. Set ONCE here at host level; the
-# meta-flake renderer (`hive-c0re/src/meta.rs::otel_config`) reads the
-# HYPERHIVE_OTEL_* env exported off hive-c0re's unit (see
-# ./hive-c0re) and injects the matching `hyperhive.otel.*` build-time
-# config into EVERY agent (mirroring the CA-cert injection), so each
-# agent's harness exports its own Claude Code stats directly to the
-# collector. There is no per-agent opt-in — this is the single switch
-# for the whole hive.
-{
-  lib,
-  config,
-  ...
-}:
-{
-  options.services.hyperhive.otel = {
-    enable = lib.mkEnableOption ''
-      hive-wide export of every agent's Claude Code stats (token usage,
-      cost, tool calls) to an OTLP endpoint via Claude Code's built-in
-      OpenTelemetry. One switch for all agents; each harness exports
-      directly to the collector, so it keeps working even when hive-c0re
-      is down
-    '';
-
-    endpoint = lib.mkOption {
-      type = lib.types.str;
-      default = "";
-      example = "https://collector.example.com/otel";
-      description = ''
-        OTLP collector endpoint, set as `OTEL_EXPORTER_OTLP_ENDPOINT`
-        for every agent. Required when `enable` is true.
-      '';
-    };
-
-    protocol = lib.mkOption {
-      type = lib.types.enum [
-        "http/protobuf"
-        "http/json"
-        "grpc"
-      ];
-      default = "http/protobuf";
-      description = ''
-        OTLP wire protocol, set as `OTEL_EXPORTER_OTLP_PROTOCOL`.
-      '';
-    };
-
-    headersCredential = lib.mkOption {
-      # `str`, not `path`: a `path`-typed relative literal is hash-copied
-      # into the world-readable nix store at eval time, defeating the
-      # point. Keep it a string + require an absolute runtime path so the
-      # secret is only ever read from disk by systemd at start.
-      type = lib.types.nullOr lib.types.str;
-      default = null;
-      example = "/run/secrets/otel-headers";
-      description = ''
-        Absolute path to an operator-provided secret file whose contents
-        become `OTEL_EXPORTER_OTLP_HEADERS` (e.g.
-        `Authorization=Bearer <token>`). hive-c0re forwards this host
-        file into each agent container's credential store via
-        systemd-nspawn `--load-credential=otel-headers:<path>`; the inner
-        harness unit inherits it by name (`LoadCredential`), so the token
-        is never copied into the nix store, the generated config, a bind
-        mount, or argv. Must be absolute. Leave null if the endpoint
-        needs no auth header. A configured-but-missing file is skipped
-        with a log warning (OTEL still exports, without the auth header).
-      '';
-    };
-
-    extraResourceAttributes = lib.mkOption {
-      type = lib.types.str;
-      default = "";
-      example = "deployment.environment=prod";
-      description = ''
-        Extra comma-separated entries appended to
-        `OTEL_RESOURCE_ATTRIBUTES` after the built-in
-        `service.name` / `agent` / `hive` / `swarm` labels.
-      '';
-    };
-
-    debug = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      description = ''
-        Emit OTEL SDK diagnostic messages to every agent's stderr by
-        setting `CLAUDE_CODE_OTEL_DIAG_STDERR=1`. Useful when
-        troubleshooting collector connectivity or endpoint config;
-        leave off in normal operation to avoid noise in agent logs.
-        Only meaningful when `enable` is true.
-      '';
-    };
-
-    metricIntervalMs = lib.mkOption {
-      type = lib.types.nullOr lib.types.ints.positive;
-      default = null;
-      example = 10000;
-      description = ''
-        Metric export interval in milliseconds, set as
-        `OTEL_METRIC_EXPORT_INTERVAL` for every agent. Claude Code's
-        default is 60000 (60s). Leave `null` to use that default.
-
-        Each agent runs claude as a short-lived per-turn process; claude
-        force-flushes metrics on shutdown, so this is not required for
-        metrics to be exported, but a lower value gives more frequent
-        intermediate flushes within long turns. Cosmetic, not a
-        correctness knob.
-      '';
-    };
-  };
-
-  config = lib.mkIf config.services.hyperhive.c0re.enable {
-    assertions = lib.optionals config.services.hyperhive.otel.enable [
-      {
-        assertion = config.services.hyperhive.otel.endpoint != "";
-        message = "services.hyperhive.otel.enable is true but services.hyperhive.otel.endpoint is empty.";
-      }
-    ];
-  };
-}

nix/host-modules/swarm.nix

@@ -1,246 +0,0 @@
-# Swarm peering: the peer-hive declarations and the optional
-# WireGuard inter-hive mesh. The peers are serialised into hive-c0re's
-# environment (HYPERHIVE_PEERS / HIVE_PEER_CA_PATHS — see ./hive-c0re)
-# and consumed by identity.rs + the dashboard's P33RS tab; the mesh
-# config below is host-level networking.
-{
-  lib,
-  config,
-  ...
-}:
-{
-  # Peer hives in the same swarm. Each entry declares a remote hive
-  # reachable from this host.
-  options.services.hyperhive.swarm.peers = lib.mkOption {
-    type = lib.types.attrsOf (
-      lib.types.submodule {
-        options = {
-          certFingerprint = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "sha256:b1946ac92492d2347c6235b4d2611184a3f5b6cae6c19d6e3c2f0a8e7d4c9f12";
-            description = ''
-              Expected TLS certificate fingerprint for this peer's HTTPS
-              endpoint. Null = trust the system CA bundle (for Let's
-              Encrypt peers). Set to pin a self-signed cert.
-
-              Format: the literal `sha256:` followed by exactly 64
-              hex digits (case-insensitive, no colon separators) — the
-              SHA-256 digest of the peer's DER-encoded leaf certificate.
-              Generate with `openssl x509 -noout -fingerprint -sha256`,
-              then strip the colons and prepend `sha256:`. A malformed
-              value is ignored with a warning rather than weakening
-              trust. See docs/swarm.md for the full recipe.
-
-              Scopes only to hive-c0re's own peer HTTPS checks — it does
-              NOT help Matrix federation (tuwunel validates against its
-              container trust bundle). For a self-signed peer whose root
-              CA you want trusted hive-wide (every agent + Matrix
-              federation), set `caCert` below.
-            '';
-          };
-
-          caCert = lib.mkOption {
-            type = lib.types.nullOr lib.types.path;
-            default = null;
-            example = "./peers/edge-ca.pem";
-            description = ''
-              Path to this peer hive's root CA certificate (PEM). When
-              set, the CA is embedded (at build time, into the nix store
-              — no runtime file on the host) and trusted **everywhere the
-              hive's own internal CA is**: it rides alongside `hive-ca.pem`
-              in each agent's `security.pki.certificateFiles` (via the
-              meta-flake renderer), and is added to the Matrix homeserver
-              container's trust bundle so tuwunel validates *federation*
-              TLS from a self-signed peer hive whose cert chains to it.
-              This is the CA-trust path that `certFingerprint`
-              (leaf-pinning, c0re-only) can't cover, and is what unblocks
-              Matrix federation with a self-signed peer hive. Trust stays
-              inside the hive (agents + the Matrix container), never the
-              host system trust store. Mutually complementary with
-              `certFingerprint`; set `caCert` for the federation case. See
-              docs/swarm.md.
-            '';
-          };
-
-          wireguardPublicKey = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "base64pubkey=";
-            description = ''
-              WireGuard public key for this peer host. Required when
-              `services.hyperhive.swarm.wireguard.enable = true` and
-              you want this peer reachable over the mesh. Null = TLS-
-              only peering (public internet, no mesh tunnel).
-            '';
-          };
-
-          wireguardEndpoint = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "203.0.113.1:51820";
-            description = ''
-              WireGuard endpoint for this peer in `host:port` form.
-              Required when the peer host is behind a firewall and
-              this host needs to initiate the tunnel. Null = this host
-              waits for the peer to connect (peer-initiates; peer must
-              have an endpoint pointing back at this host).
-            '';
-          };
-
-          wireguardAddress = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "10.100.0.2/32";
-            description = ''
-              IP address (with prefix) of the peer host on the
-              WireGuard mesh. Used as the `allowedIPs` for the peer's
-              WireGuard config entry and injected into `HYPERHIVE_PEERS`
-              so hive-c0re can route intra-swarm traffic to the mesh
-              address rather than the public domain. Required to include
-              the peer in the WireGuard mesh (peers missing this field
-              are silently excluded from `wg-hive`).
-            '';
-          };
-        };
-      }
-    );
-    default = { };
-    example = {
-      "lab.example.com" = {
-        certFingerprint = "sha256:b1946ac92492d2347c6235b4d2611184a3f5b6cae6c19d6e3c2f0a8e7d4c9f12";
-      };
-      "edge.corp" = { };
-    };
-    description = ''
-      Peer hives in the same swarm. The attrset key is the peer's DNS
-      domain — used for dashboard links and Matrix federation discovery.
-      Null `certFingerprint` trusts the system CA bundle; set it to pin
-      a self-signed TLS cert. Add `wireguardPublicKey` + `wireguardAddress`
-      (and optionally `wireguardEndpoint`) to include the peer in the
-      WireGuard mesh when `swarm.wireguard.enable = true`.
-    '';
-  };
-
-  # WireGuard mesh config for the local host.
-  # When enabled, a `wg-hive` interface connects to all peers that have
-  # `wireguardPublicKey` declared. Peers reachable over the mesh are
-  # preferred for inter-hive traffic (no public TLS round-trip needed);
-  # peers without a public key still work via normal HTTPS.
-  options.services.hyperhive.swarm.wireguard = {
-    enable = lib.mkOption {
-      type = lib.types.bool;
-      default = false;
-      description = ''
-        Enable the WireGuard inter-hive mesh. When true, a `wg-hive`
-        interface is brought up connecting to all swarm peers that
-        declare a `wireguardPublicKey`. Requires
-        `privateKeyFile` to be set.
-      '';
-    };
-
-    privateKeyFile = lib.mkOption {
-      type = lib.types.nullOr lib.types.path;
-      default = null;
-      example = "/etc/wireguard/hive.key";
-      description = ''
-        Path to the host's WireGuard private key file. The file must
-        be readable by root and should have mode 0400. Generate with
-        `wg genkey > /etc/wireguard/hive.key`. Required when
-        `swarm.wireguard.enable = true`.
-      '';
-    };
-
-    address = lib.mkOption {
-      type = lib.types.str;
-      default = "";
-      example = "10.100.0.1/24";
-      description = ''
-        IP address (with prefix) of this host on the WireGuard mesh.
-        Use a /24 (or broader) prefix so the routing table covers all
-        peer /32 routes. Example: `"10.100.0.1/24"` for a 256-host mesh.
-      '';
-    };
-
-    listenPort = lib.mkOption {
-      type = lib.types.port;
-      default = 51820;
-      description = ''
-        UDP port the local WireGuard interface listens on. Must be
-        reachable from peer hosts when they initiate the tunnel.
-        Default: 51820 (standard WireGuard port).
-      '';
-    };
-
-    persistentKeepalive = lib.mkOption {
-      type = lib.types.nullOr lib.types.int;
-      default = 25;
-      example = 25;
-      description = ''
-        Seconds between keepalive packets sent to each peer. Useful
-        when this host (or a peer) is behind NAT — keeps the UDP hole
-        open. Set to null to disable. Default: 25 seconds.
-      '';
-    };
-  };
-
-  # Gated on the c0re daemon being enabled — the mesh is part of the
-  # coordinator host's networking.
-  config = lib.mkIf config.services.hyperhive.c0re.enable {
-    assertions = lib.optionals config.services.hyperhive.swarm.wireguard.enable [
-      {
-        assertion = config.services.hyperhive.swarm.wireguard.privateKeyFile != null;
-        message = ''
-          services.hyperhive.swarm.wireguard.enable requires
-          services.hyperhive.swarm.wireguard.privateKeyFile to be set.
-          Generate a key: wg genkey > /etc/wireguard/hive.key
-        '';
-      }
-      {
-        assertion = config.services.hyperhive.swarm.wireguard.address != "";
-        message = ''
-          services.hyperhive.swarm.wireguard.enable requires
-          services.hyperhive.swarm.wireguard.address to be set
-          (e.g. "10.100.0.1/24").
-        '';
-      }
-    ];
-
-    # WireGuard inter-hive mesh. Brings up a `wg-hive` interface and
-    # connects to each peer that has `wireguardPublicKey` set.
-    networking.wireguard.interfaces = lib.mkIf config.services.hyperhive.swarm.wireguard.enable (
-      let
-        wgCfg = config.services.hyperhive.swarm.wireguard;
-        meshPeers = lib.filterAttrs (
-          _: p: p.wireguardPublicKey != null && p.wireguardAddress != null
-        ) config.services.hyperhive.swarm.peers;
-      in
-      {
-        wg-hive = {
-          ips = [ wgCfg.address ];
-          listenPort = wgCfg.listenPort;
-          privateKeyFile = wgCfg.privateKeyFile;
-          peers = lib.mapAttrsToList (
-            _domain: p:
-            {
-              publicKey = p.wireguardPublicKey;
-              allowedIPs = [ p.wireguardAddress ];
-            }
-            // lib.optionalAttrs (p.wireguardEndpoint != null) {
-              endpoint = p.wireguardEndpoint;
-            }
-            // lib.optionalAttrs (wgCfg.persistentKeepalive != null) {
-              persistentKeepalive = wgCfg.persistentKeepalive;
-            }
-          ) meshPeers;
-        };
-      }
-    );
-
-    # Open the WireGuard UDP port on the host firewall when the mesh is
-    # on (host-level networking — not inside containers).
-    networking.firewall.allowedUDPPorts = lib.mkIf config.services.hyperhive.swarm.wireguard.enable [
-      config.services.hyperhive.swarm.wireguard.listenPort
-    ];
-  };
-}

nix/modules/hive-ci.nix

@@ -127,10 +127,10 @@ let
       fi
       CORE_TOKEN=$(cat ${coreTokenPath})
       # Capture the HTTP status so a stale/invalid core token (401/403) is
-      # distinguished from a transient forge hiccup. A bare
+      # distinguished from a transient forge hiccup. With the old bare
-      # `curl -sf | jq` would let a forge-core-token that is stale for
+      # `curl -sf | jq`, a forge-core-token that's stale for the current
-      # the current forge (e.g. after a forge rebuild) 401 silently on
+      # forge (e.g. after a forge rebuild) 401s and fails silently every
-      # every attempt for the full 60s loop and exit with a misleading
+      # attempt for the full 60s loop, then exits with a misleading
       # "core token absent or forge unreachable" — masking the real cause.
       # Fail fast + loudly on 401/403 so the failure mode is legible and
       # the operator/hive-c0re knows to re-mint forge-core-token.

nix/modules/hive-forge.nix

@@ -12,20 +12,25 @@ let
   # ROOT_URL forgejo advertises in clone links + outbound URLs. When
   # served behind the gateway, `cfg.domain` doubles as both the
   # forgejo `DOMAIN` setting AND the gateway vhost server-name, so
-  # ROOT_URL just uses it directly. The gateway always terminates TLS
+  # ROOT_URL just uses it directly (dropping the port suffix on the
-  # (self-signed is the implicit floor when neither `tls.certDir` nor
+  # canonical port for the scheme — 80 for http, 443 for https). The
-  # ACME is configured), so behind the gateway the forge is always
+  # gateway always terminates TLS now — self-signed is the implicit floor
-  # advertised over `https` on `httpsPort` — the canonical 443 elides
+  # when neither `tls.certDir` nor ACME is configured — so behind the
-  # the port suffix. When direct (`behindGateway = false`), keep the
+  # gateway the forge is always advertised over `https` on `httpsPort`.
+  # When direct (gateway off or `behindGateway = false`), keep the
   # host:httpPort shape so direct browser access still produces correct
   # links. Operators can still override via `cfg.rootUrl` for bespoke
   # shapes.
+  gatewayTls = true;
   defaultRootUrl =
     if cfg.behindGateway then
       let
-        portSuffix = if gatewayCfg.httpsPort == 443 then "" else ":${toString gatewayCfg.httpsPort}";
+        scheme = if gatewayTls then "https" else "http";
+        port = if gatewayTls then gatewayCfg.httpsPort else gatewayCfg.port;
+        canonicalPort = if gatewayTls then 443 else 80;
+        portSuffix = if port == canonicalPort then "" else ":${toString port}";
       in
-      "https://${cfg.domain}${portSuffix}/"
+      "${scheme}://${cfg.domain}${portSuffix}/"
     else
       "http://${cfg.domain}:${toString cfg.httpPort}/";
   effectiveRootUrl = if cfg.rootUrl != null then cfg.rootUrl else defaultRootUrl;
@@ -313,16 +318,16 @@ in
           staticRootWithTheme = pkgs.runCommand "forgejo-static-with-theme" { } ''
             cp -r --no-preserve=mode,ownership ${cfg.package.data}/. $out/
             mkdir -p $out/public/assets/css
-            cp ${./theme-catppuccin-vibec0re.css} \
+            cp ${../forge-theme/theme-catppuccin-vibec0re.css} \
                $out/public/assets/css/theme-catppuccin-vibec0re.css
             # Replace the default Forgejo logo + favicon with the hyperhive
             # mark. Files in public/assets/img/ are served before built-ins.
             mkdir -p $out/public/assets/img
-            cp ${../../../branding/hyperhive.svg} $out/public/assets/img/logo.svg
+            cp ${../../branding/hyperhive.svg} $out/public/assets/img/logo.svg
-            cp ${../../../branding/hyperhive.svg} $out/public/assets/img/favicon.svg
+            cp ${../../branding/hyperhive.svg} $out/public/assets/img/favicon.svg
-            cp ${../../../branding/hyperhive.png} $out/public/assets/img/logo.png
+            cp ${../../branding/hyperhive.png} $out/public/assets/img/logo.png
-            cp ${../../../branding/hyperhive.png} $out/public/assets/img/favicon.png
+            cp ${../../branding/hyperhive.png} $out/public/assets/img/favicon.png
-            cp ${../../../branding/hyperhive.png} $out/public/assets/img/avatar_default.png
+            cp ${../../branding/hyperhive.png} $out/public/assets/img/avatar_default.png
           '';
         in
         {

nix/modules/hive-matrix.nix

@@ -366,31 +366,39 @@ in
           # gets the host file across the shared-netns boundary), so it
           # regenerates an empty file and tuwunel dies at boot.
           #
-          # Trusting resolvconf to honour `networking.nameservers` doesn't
+          # The earlier fix turned host-tracking off and trusted resolvconf
-          # work either — that's a RUNTIME resolvconf behaviour, not
+          # to honour `networking.nameservers` — but that's a RUNTIME
-          # verifiable at eval time, and it still comes up empty in
+          # resolvconf behaviour, not verifiable at eval time, and it STILL
-          # practice. So take resolvconf out of the loop entirely and
+          # came up empty in practice. So take resolvconf out of the
-          # write a STATIC `/etc/resolv.conf` from `bridgeIp` that nothing
+          # loop entirely and write a STATIC `/etc/resolv.conf` from
-          # regenerates. Eval-proven: the generated
+          # `bridgeIp` that nothing regenerates. Eval-proven: the generated
           # `environment.etc."resolv.conf".text` is `nameserver <bridgeIp>`.
           # This container always shares the host netns
           # (`privateNetwork = false`), so it reaches `bridgeIp` regardless
-          # of agent-container isolation. See `docs/network.md`.
+          # of agent-container isolation. Network module off → inherit the host's
-          networking = {
+          # resolv.conf. See `docs/network.md`.
+          networking = lib.mkMerge [
+            (lib.mkIf networkCfg.enable {
               # resolvconf is taken out of the loop entirely; the static
               # `environment.etc."resolv.conf"` below is the sole source of
               # the resolver file (no `nameservers` — nothing would read it).
               useHostResolvConf = lib.mkForce false;
               resolvconf.enable = lib.mkForce false;
-          };
+            })
+            (lib.mkIf (!networkCfg.enable) {
+              useHostResolvConf = true;
+            })
+          ];
 
           # resolvconf is disabled above, so write the static resolver file
           # explicitly — NixOS won't synthesise one from `nameservers` once
           # resolvconf is off, and this is the file tuwunel parses at boot.
-          environment.etc."resolv.conf".text = ''
+          environment.etc = lib.mkIf networkCfg.enable {
+            "resolv.conf".text = ''
               nameserver ${networkCfg.bridgeIp}
               options edns0
             '';
+          };
 
           services.matrix-tuwunel = {
             enable = true;
@@ -436,20 +444,21 @@ in
       ];
     };
 
-    # The matrix container's resolver is the dnsmasq that runs in the
+    # When the hive network module is on, the matrix container's resolver
-    # gateway container (bound at `bridgeIp`). Order the matrix
+    # is the dnsmasq that runs in the gateway container (bound at
-    # container start after the gateway container so the resolver is up
+    # `bridgeIp`). Order the matrix container start after the gateway
-    # before tuwunel's first federation lookups. tuwunel boots fine
+    # container so the resolver is up before tuwunel's first federation
-    # without this — it configures the resolver from `/etc/resolv.conf`
+    # lookups. tuwunel boots fine without this — it configures the resolver
-    # at startup and only queries on-demand (the boot failure this
+    # from `/etc/resolv.conf` at startup and only queries on-demand (the
-    # module guards against is an *empty* resolv.conf, a parse error,
+    # boot failure this module fixes was an *empty* resolv.conf, a parse
-    # not a connectivity one) — so this is robustness, not a boot
+    # error, not a connectivity one) — so this is robustness, not a boot
-    # requirement. Soft `after` ordering (not `requires`) keeps the
+    # requirement. Soft `after` ordering (not `requires`) keeps the matrix
-    # matrix container's lifecycle decoupled from the gateway's. The
+    # container's lifecycle decoupled from the gateway's. The gateway
-    # gateway always runs alongside hyperhive, so the gateway container
+    # always runs alongside hyperhive, so the gateway container unit always
-    # unit always exists here. (Declarative `containers.<n>` →
+    # exists here. (Declarative `containers.<n>` → `container@<n>.service` — the
-    # `container@<n>.service` — the nspawn template NixOS generates.)
+    # nspawn template NixOS generates, confirmed from the live
-    systemd.services."container@hive-matrix".after = [
+    # `container@hive-matrix.service` host unit.)
+    systemd.services."container@hive-matrix".after = lib.mkIf networkCfg.enable [
       "container@hive-gateway.service"
     ];
   };

nix/modules/hive-network.nix

@@ -5,54 +5,34 @@
 }:
 let
   cfg = config.services.hyperhive.network;
-
-  # IPv4 helpers for the DHCP-pool computation below — nix integers
-  # are 64-bit so all /0-/32 values are safe.
-  ipToInt =
-    ip:
-    builtins.foldl' (acc: x: acc * 256 + x) 0 (
-      map lib.strings.toIntBase10 (lib.strings.splitString "." ip)
-    );
-  intToIp =
-    n:
-    let
-      a = n / 16777216;
-      b = (n - a * 16777216) / 65536;
-      c = (n - a * 16777216 - b * 65536) / 256;
-      d = n - a * 16777216 - b * 65536 - c * 256;
-    in
-    "${toString a}.${toString b}.${toString c}.${toString d}";
-  # 2^n via recursion (nix has no pow builtin).
-  pow2 = n: if n == 0 then 1 else 2 * (pow2 (n - 1));
-  hostCount = pow2 (32 - cfg.bridgePrefixLength);
-  # Mask off host bits to get the network base address.
-  networkBase = builtins.bitAnd (ipToInt cfg.bridgeIp) (4294967295 - hostCount + 1);
 in
 {
   # Hive-internal network — host-side bridge + per-agent DNS resolver.
   # Always active when hyperhive is enabled: agent containers run in
   # private netns behind the bridge. Full design: docs/network.md.
 
-  imports = [
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "network" "enable" ] ''
-      The hive network (bridge + dnsmasq resolver + private-netns
-      isolation) is always on whenever hyperhive is enabled. Remove the
-      setting.
-    '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "network" "isolateContainers" ] ''
-      Network isolation is the only mode and is always on whenever
-      hyperhive is enabled; the shared-netns path was removed. Remove
-      the setting.
-    '')
-    (lib.mkRemovedOptionModule [ "services" "hyperhive" "network" "upstreamDns" ] ''
-      The hive resolver always follows the host's resolvers now
-      (dnsmasq reads the gateway container's /etc/resolv.conf, the
-      host copy made at container start). Configure upstream DNS on
-      the host itself instead.
-    '')
-  ];
-
   options.services.hyperhive.network = {
+    enable = lib.mkOption {
+      type = lib.types.bool;
+      default = config.services.hyperhive.enable;
+      defaultText = lib.literalExpression "config.services.hyperhive.enable";
+      example = false;
+      description = ''
+        **DEPRECATED — ignored.** The hive network (bridge + dnsmasq
+        resolver + private-netns isolation) is now always on whenever
+        hyperhive is enabled; setting this to `false` warns and has no
+        effect. Retained as a no-op so existing configs eval; will be
+        removed in a future release.
+
+        The network requires `services.hyperhive.domain` to be set — the
+        dnsmasq resolver is authoritative for `<hive-domain>` and its
+        sub-domains. A bridge interface (`bridgeName`) appears on the host
+        with `bridgeIp` assigned, the hive-gateway container runs a dnsmasq
+        on that IP, and each agent container runs in a private netns with a
+        veth pair on the bridge.
+      '';
+    };
+
     bridgeName = lib.mkOption {
       type = lib.types.str;
       default = "hive-br0";
@@ -91,6 +71,26 @@ in
       '';
     };
 
+    upstreamDns = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [
+        "1.1.1.1"
+        "9.9.9.9"
+      ];
+      example = [
+        "192.168.1.1"
+        "8.8.8.8"
+      ];
+      description = ''
+        Upstream DNS servers dnsmasq forwards non-hive queries to.
+        Defaults to Cloudflare + Quad9. Override for operators on
+        private networks who need a specific resolver (corporate
+        DNS, pi-hole, etc.). The hive resolver itself stays
+        authoritative for `<hive-domain>` and its sub-domains
+        regardless of upstream choice.
+      '';
+    };
+
     exposeHostPorts = lib.mkOption {
       type = lib.types.listOf lib.types.port;
       default = [ ];
@@ -117,41 +117,26 @@ in
       '';
     };
 
-    # DHCP pool covering all usable host addresses on the bridge
+    isolateContainers = lib.mkOption {
-    # subnet, computed from bridgeIp/bridgePrefixLength: .2 (first
+      type = lib.types.bool;
-    # usable after the .1 gateway) to .(hostCount-2) (last usable
+      default = true;
-    # before broadcast). All containers — agents and service
+      example = true;
-    # containers alike — receive their IPs dynamically from this pool;
-    # there are no hash-derived static assignments. Consumed by the
-    # dnsmasq that runs in the gateway container (hive-gateway module).
-    dhcpRangeStart = lib.mkOption {
-      type = lib.types.str;
-      internal = true;
-      readOnly = true;
-      default = intToIp (networkBase + 2);
-      defaultText = lib.literalMD "first usable bridge address after the gateway";
       description = ''
-        Read-only computed first address of the bridge DHCP pool.
+        **DEPRECATED — ignored.** Network isolation is now the only mode and
+        is always on whenever hyperhive is enabled; the shared-netns path was
+        removed. This option is retained as a no-op so existing configs eval;
+        setting it to `false` warns and has no effect. It will be removed in
+        a future release.
       '';
     };
-
-    dhcpRangeEnd = lib.mkOption {
-      type = lib.types.str;
-      internal = true;
-      readOnly = true;
-      default = intToIp (networkBase + hostCount - 2);
-      defaultText = lib.literalMD "last usable bridge address before broadcast";
-      description = ''
-        Read-only computed last address of the bridge DHCP pool.
-      '';
-    };
-
   };
 
   config = lib.mkMerge [
     # The hive network + container isolation are unconditional whenever
-    # hyperhive is enabled: the shared-netns mode was removed, so there
+    # hyperhive is enabled: the shared-netns mode was removed, so there is
-    # is one mode (private netns behind the bridge).
+    # one mode (private netns behind the bridge). `network.enable` and
+    # `isolateContainers` are kept as deprecated no-op options (see the
+    # warnings block below) so existing configs that set them still eval.
     (lib.mkIf config.services.hyperhive.enable {
       assertions = [
         {
@@ -239,5 +224,27 @@ in
     (lib.mkIf (config.services.hyperhive.enable && cfg.exposeHostPorts != [ ]) {
       networking.firewall.interfaces.${cfg.bridgeName}.allowedTCPPorts = cfg.exposeHostPorts;
     })
+
+    # Deprecation surface for the removed toggles. Both options are kept so
+    # existing configs that set them to `true` still eval cleanly; setting
+    # either to `false` no longer does anything (network + isolation are
+    # unconditional now), so warn rather than silently ignore.
+    {
+      # Only warn when hyperhive itself is enabled — otherwise `cfg.enable`
+      # defaults to `false` (tracking `hyperhive.enable`) and we'd fire a
+      # spurious deprecation warning on a host that doesn't run hyperhive.
+      warnings = lib.optionals config.services.hyperhive.enable (
+        lib.optional (!cfg.enable) ''
+          services.hyperhive.network.enable = false is deprecated and ignored
+          — the hive network is now always on (private-netns isolation is the
+          only mode). Remove the setting.
+        ''
+        ++ lib.optional (!cfg.isolateContainers) ''
+          services.hyperhive.network.isolateContainers = false is deprecated
+          and ignored — network isolation is now the only mode and is always
+          on. Remove the setting.
+        ''
+      );
+    }
   ];
 }

nix/modules/hive-tls.nix

@@ -18,61 +18,23 @@ let
   # module's single source of truth (`gateway.useSelfSigned`): true when
   # neither an operator cert (`tls.certDir`) nor ACME is set.
   active = hyperhiveCfg.enable && gatewayCfg.useSelfSigned;
-
-  # The leaf-signing action shared by the boot-time `hive-tls-ca`
-  # generation and the weekly `hive-tls-resign` renewal: fresh key +
-  # CSR, SAN ext-file, sign under the (stable) CA, tighten modes.
-  # Takes the TLS state dir as `$1`; each caller keeps its own
-  # when-to-sign condition. The leaf covers the bare hive domain plus
-  # `forge.`, `matrix.` and `*.<domain>` so all sub-domains validate
-  # under the same cert + the hive CA.
-  signLeafScript = pkgs.writeShellScript "hive-tls-sign-leaf" ''
-    set -euo pipefail
-    d="$1"
-    ca="$d/ca.pem"
-    cak="$d/ca-key.pem"
-    leaf="$d/gateway.pem"
-    leafk="$d/gateway-key.pem"
-    csr="$(mktemp "$d/gateway.csr.XXXXXX")"
-    ext="$(mktemp "$d/leaf.ext.XXXXXX")"
-    trap 'rm -f "$csr" "$ext"' EXIT
-
-    openssl req -newkey rsa:4096 -nodes -sha256 \
-      -keyout "$leafk" -out "$csr" \
-      -subj "/CN=${domain}"
-
-    # printf (not a heredoc) so the ext-file lines carry no leading
-    # whitespace once nix has stripped the indented-string indent.
-    {
-      printf 'subjectAltName=DNS:%s,DNS:forge.%s,DNS:matrix.%s,DNS:*.%s\n' \
-        ${lib.escapeShellArg domain} ${lib.escapeShellArg domain} \
-        ${lib.escapeShellArg domain} ${lib.escapeShellArg domain}
-      printf 'basicConstraints=critical,CA:FALSE\n'
-      printf 'keyUsage=critical,digitalSignature,keyEncipherment\n'
-      printf 'extendedKeyUsage=serverAuth\n'
-    } > "$ext"
-
-    openssl x509 -req -in "$csr" -CA "$ca" -CAkey "$cak" \
-      -CAcreateserial -days ${toString cfg.leafValidityDays} -sha256 \
-      -extfile "$ext" -out "$leaf"
-    chmod 0600 "$leafk"
-    chmod 0644 "$leaf"
-  '';
 in
 {
   # Host-side TLS trust root for the self-signed gateway mode.
   #
-  # A bare self-signed leaf would be its own trust anchor, so every
+  # `gateway.selfSignedTls` historically generated a *bare* self-signed
-  # regeneration would be a new anchor and every consumer (agents,
+  # leaf inside the gateway container at first boot. A bare leaf is its
-  # federation peers) would have to re-trust on each rotation — and a
+  # own trust anchor, so every regeneration is a new anchor and every
-  # runtime-generated, in-container cert can't be wired into an agent's
+  # consumer (agents, federation peers) would have to re-trust on each
-  # build-time trust store at all.
+  # rotation — and a runtime-generated, in-container cert can't be wired
+  # into an agent's build-time trust store at all.
   #
-  # So the anchor is a long-lived **hive CA** held on the host. The
+  # This module moves the anchor to a long-lived **hive CA** held on the
-  # gateway serves a **leaf** signed by that CA (via the `tls.certDir`
+  # host. The gateway serves a **leaf** signed by that CA (via the
-  # bind-mount path); agents and federation peers trust the *CA* once,
+  # existing `tls.certDir` bind-mount path); agents and federation peers
-  # and leaf rotation never re-breaks them. See `docs/gateway.md`
+  # trust the *CA* once, and leaf rotation never re-breaks them. See
-  # ("Self-signed TLS").
+  # `docs/gateway.md` ("Self-signed TLS") and issue-tracker discussion of
+  # agent web-UI reachability.
 
   options.services.hyperhive.tls = {
     stateDir = lib.mkOption {
@@ -172,7 +134,30 @@ in
         if [ ! -s "$leaf" ] || [ ! -s "$leafk" ] \
             || ! openssl x509 -in "$leaf" -noout -checkend 2592000 >/dev/null 2>&1; then
           echo "signing fresh gateway leaf at $leaf"
-          ${signLeafScript} "$d"
+          csr="$(mktemp "$d/gateway.csr.XXXXXX")"
+          ext="$(mktemp "$d/leaf.ext.XXXXXX")"
+          trap 'rm -f "$csr" "$ext"' EXIT
+
+          openssl req -newkey rsa:4096 -nodes -sha256 \
+            -keyout "$leafk" -out "$csr" \
+            -subj "/CN=${domain}"
+
+          # printf (not a heredoc) so the ext-file lines carry no leading
+          # whitespace once nix has stripped the indented-string indent.
+          {
+            printf 'subjectAltName=DNS:%s,DNS:forge.%s,DNS:matrix.%s,DNS:*.%s\n' \
+              ${lib.escapeShellArg domain} ${lib.escapeShellArg domain} \
+              ${lib.escapeShellArg domain} ${lib.escapeShellArg domain}
+            printf 'basicConstraints=critical,CA:FALSE\n'
+            printf 'keyUsage=critical,digitalSignature,keyEncipherment\n'
+            printf 'extendedKeyUsage=serverAuth\n'
+          } > "$ext"
+
+          openssl x509 -req -in "$csr" -CA "$ca" -CAkey "$cak" \
+            -CAcreateserial -days ${toString cfg.leafValidityDays} -sha256 \
+            -extfile "$ext" -out "$leaf"
+          chmod 0600 "$leafk"
+          chmod 0644 "$leaf"
         fi
       '';
     };
@@ -191,8 +176,9 @@ in
     # container start). A host-side `systemctl -M hive-gateway` call
     # triggers the re-import + reload, mirroring how hive-c0re reloads the
     # gateway after each agents.conf write. A path unit *inside* the
-    # container cannot do this: IN_MOVED_TO from an atomic rename on the
+    # container was tried first but does not work: IN_MOVED_TO from an
-    # host does not propagate across the nspawn mount-namespace boundary.
+    # atomic rename on the host does not propagate across the nspawn
+    # mount-namespace boundary.
     #
     # `|| true` on propagation so a stopped gateway never fails the unit —
     # its next boot will import the already-rotated leaf anyway.
@@ -216,7 +202,10 @@ in
       script = ''
         set -euo pipefail
         d=${lib.escapeShellArg cfg.stateDir}
+        ca="$d/ca.pem"
+        cak="$d/ca-key.pem"
         leaf="$d/gateway.pem"
+        leafk="$d/gateway-key.pem"
 
         # Re-sign only when the leaf is within half its validity of expiry.
         # The weekly cadence catches this window well before the leaf lapses.
@@ -230,7 +219,28 @@ in
         echo "gateway leaf missing or near expiry — re-signing under current CA"
         before="$(sha256sum "$leaf" 2>/dev/null || true)"
 
-        ${signLeafScript} "$d"
+        csr="$(mktemp "$d/gateway.csr.XXXXXX")"
+        ext="$(mktemp "$d/leaf.ext.XXXXXX")"
+        trap 'rm -f "$csr" "$ext"' EXIT
+
+        openssl req -newkey rsa:4096 -nodes -sha256 \
+          -keyout "$leafk" -out "$csr" \
+          -subj "/CN=${domain}"
+
+        {
+          printf 'subjectAltName=DNS:%s,DNS:forge.%s,DNS:matrix.%s,DNS:*.%s\n' \
+            ${lib.escapeShellArg domain} ${lib.escapeShellArg domain} \
+            ${lib.escapeShellArg domain} ${lib.escapeShellArg domain}
+          printf 'basicConstraints=critical,CA:FALSE\n'
+          printf 'keyUsage=critical,digitalSignature,keyEncipherment\n'
+          printf 'extendedKeyUsage=serverAuth\n'
+        } > "$ext"
+
+        openssl x509 -req -in "$csr" -CA "$ca" -CAkey "$cak" \
+          -CAcreateserial -days ${toString cfg.leafValidityDays} -sha256 \
+          -extfile "$ext" -out "$leaf"
+        chmod 0600 "$leafk"
+        chmod 0644 "$leaf"
 
         after="$(sha256sum "$leaf" 2>/dev/null || true)"
         if [ "$before" != "$after" ]; then

nix/packages/default.nix

@@ -1,183 +0,0 @@
-# All flake package outputs. Imported per system from flake.nix; the
-# shared rust build wiring (cleanSrc / cargoArtifacts /
-# nativeBuildInputs) comes in via `rust` (see ../rust.nix).
-{
-  pkgs,
-  craneLib,
-  rust,
-  self,
-  nixpkgs,
-}:
-let
-  inherit (pkgs) lib;
-  inherit (rust) cleanSrc cargoArtifacts nativeBuildInputs;
-
-  docsAttrs = import ../docs {
-    inherit pkgs self;
-    inherit (nixpkgs) lib;
-    inherit (nixpkgs.lib) nixosSystem;
-  };
-
-  # Every per-binary package: name → description. The single source of
-  # truth for the bin list — it drives the per-bin extractor packages
-  # and the `default` bundle, so adding a binary is one entry here.
-  daemonBins = {
-    hive-c0re = "hyperhive host coordinator daemon";
-    hive-priv = "hyperhive privileged root helper";
-    hive-agent = "hyperhive in-container agent harness serve loop";
-    hive-agent-mcp = "hyperhive agent-surface MCP server";
-    hive-agent-wake = "hyperhive external wake CLI — push a message into an agent's own inbox";
-    hive-bash-daemon = "hyperhive per-agent bash-task runner daemon";
-    hive-bash-mcp = "hyperhive bash-task MCP bridge";
-    hive-matrix-daemon = "hyperhive per-agent matrix-sdk daemon";
-    hive-matrix-mcp = "hyperhive matrix MCP bridge";
-    hive-metric = "hyperhive agent-emitted custom metrics CLI";
-    hive-forge = "hyperhive Forgejo CLI";
-  };
-
-  # ONE compile of the whole workspace (every bin, sharing the
-  # prebuilt `cargoArtifacts` dep cache). The per-bin packages below
-  # are cheap copy-extractors over this, so workspace lib crates
-  # (hive-sh4re, hive-claude, …) compile exactly once instead of once
-  # per bin derivation.
-  #
-  # Tests are kept in the separate `checks.cargo-test` derivation
-  # (carries the hyperhive-assets build input for the prompt-template
-  # assertions in hive-ag3nt::prompt::tests). Keeping them out of this
-  # derivation means a prompt edit doesn't bust the cargo cache.
-  workspaceBuild = craneLib.buildPackage {
-    src = cleanSrc;
-    inherit cargoArtifacts nativeBuildInputs;
-    pname = "hyperhive-workspace";
-    version = "0.1.0";
-    doCheck = false;
-  };
-
-  # Per-bin extractor: COPIES one binary out of the workspace build.
-  # A copy, not a symlink — a symlink would keep the whole workspace
-  # output (and thus every other binary) in the consumer's runtime
-  # closure, defeating the point of the per-bin split. The copied
-  # binary's RPATH references only the libs it links, so nix's
-  # reference scan gives each package a narrow closure.
-  mkBinPackage =
-    bin: description:
-    pkgs.runCommand bin
-      {
-        meta = {
-          inherit description;
-          mainProgram = bin;
-        };
-      }
-      ''
-        install -Dm755 ${workspaceBuild}/bin/${bin} $out/bin/${bin}
-      '';
-
-  # Operator CLI — extractor plus shell completions and the `wg`
-  # wrapper. Suitable for `nix profile install .#hivectl` /
-  # `environment.systemPackages = [ …packages.<system>.hivectl ]`
-  # when the operator only wants the admin CLI.
-  # Completions come from the binary's own `completions <shell>` verb
-  # (the single source of truth, so they never drift from the actual
-  # verbs). The wireguard-tools wrap makes `hivectl wg` subcommands
-  # work before `swarm.wireguard.enable` is set (wg init is the very
-  # first setup step). Completion generation runs before wrapProgram
-  # since wrapProgram renames the real binary.
-  hivectlPkg =
-    pkgs.runCommand "hivectl"
-      {
-        nativeBuildInputs = [
-          pkgs.installShellFiles
-          pkgs.makeWrapper
-        ];
-        meta = {
-          description = "hyperhive operator CLI";
-          mainProgram = "hivectl";
-        };
-      }
-      ''
-        install -Dm755 ${workspaceBuild}/bin/hivectl $out/bin/hivectl
-        installShellCompletion --cmd hivectl \
-          --bash <("$out/bin/hivectl" completions bash) \
-          --zsh <("$out/bin/hivectl" completions zsh) \
-          --fish <("$out/bin/hivectl" completions fish)
-        wrapProgram "$out/bin/hivectl" \
-          --prefix PATH : ${pkgs.wireguard-tools}/bin
-      '';
-
-  # Per-bin split packages. Agent containers depend on the individual
-  # bins they actually exec/PATH-need (see harness-base.nix) instead
-  # of the `default` bundle — that keeps `hivectl` (dials the *host*
-  # admin socket, unreachable from inside a container, drags in
-  # `wireguard-tools`) and redundant binaries out of every agent's
-  # closure.
-  binPkgs = lib.mapAttrs mkBinPackage daemonBins // {
-    hivectl = hivectlPkg;
-  };
-in
-{
-  # All workspace binaries in one derivation — a symlinkJoin over the
-  # per-bin packages, pure assembly with no extra compilation. The
-  # host module's `services.hyperhive.c0re.package` and `nix build .#`
-  # both land here.
-  default = pkgs.symlinkJoin {
-    name = "hyperhive";
-    paths = lib.attrValues binPkgs;
-  };
-}
-// binPkgs
-// {
-  # Bundled browser assets — see ./frontend.nix. Output is
-  # $out/{dashboard,agent}/ which the Rust binaries serve via
-  # tower_http::ServeDir.
-  frontend = pkgs.callPackage ./frontend.nix {
-    branding-svg = ../../branding/hyperhive.svg;
-  };
-  # Static runtime assets the rust binaries read via
-  # `hive_sh4re::assets::*`: branding/* + prompts/*, plus the
-  # rendered agent-configs.png. Split out of the rust derivation so
-  # a tweak to e.g. system.md doesn't bust the cargo cache. Build
-  # input of the `cargo-test` check but NOT of `packages.default`,
-  # so the binary derivation stays cached when a prompt edit ripples
-  # through.
-  assets = pkgs.callPackage ./assets.nix { };
-  # The repo docs/ markdown tree as a standalone derivation —
-  # agents read it in-container (added as a claude additional
-  # directory) and the website repo reuses it as a flake input,
-  # neither of which needs the branding/prompt assets. See
-  # ./reference-docs.nix. (`docs` below is the auto-generated
-  # nix-options reference, a different artifact.)
-  reference-docs = pkgs.callPackage ./reference-docs.nix { };
-  # XDG icon set + .desktop entries for hyperhive processes.
-  # Narrow input: only the branding SVG, so unrelated source changes
-  # don't bust this derivation's cache.
-  xdg-icons = pkgs.callPackage ./hive-xdg-icons.nix {
-    hyperhiveSvg = ../../branding/hyperhive.svg;
-  };
-
-  # Pre-built per-container system closures. Exposed as packages
-  # so operators can `nix build .#agent-base-toplevel` (or wire
-  # them into their host system closure via the
-  # `preBuildAgentTemplates` option on the hive-c0re module —
-  # see nix/host-modules/hive-c0re.nix). Speeds up the first agent
-  # spawn dramatically because the heavy lifting (nixpkgs +
-  # claude-code + hive-ag3nt binary) is already in the store
-  # when the meta evaluator goes to build the container.
-  #
-  # nixosConfigurations are pinned to x86_64-linux (nixos-
-  # containers only run native arch), so these toplevels are
-  # only useful on an x86_64-linux host — flake check across
-  # systems still tolerates evaluating them on aarch64 because
-  # they're plain derivations, but `nix build` from a non-x86
-  # host would only succeed via a remote x86 builder.
-  agent-base-toplevel = self.nixosConfigurations.agent-base.config.system.build.toplevel;
-  ruth-toplevel = self.nixosConfigurations.ruth.config.system.build.toplevel;
-
-  # Auto-generated nix options reference for hyperhive.
-  # `docs` bundles host + agent pages into one tree; the split
-  # outputs are useful when consumers only want one surface.
-  # All three are pure markdown — no rust or frontend deps in
-  # the closure, so `nix build .#docs` is cheap.
-  docs = docsAttrs.bundle;
-  docs-host = docsAttrs.host;
-  docs-agent = docsAttrs.agent;
-}

nix/packages/hive-forge-tools.nix

@@ -0,0 +1,35 @@
+{ pkgs, lib }:
+# hive-forge — Forgejo CLI wrapper for hyperhive.
+#
+# Previously a ~600-line bash script. Rewritten as a proper Rust
+# binary in `/hive-forge` so we get:
+#   - typed clap subcommands (`hive-forge <verb> --help` instead of
+#     reading the case statement),
+#   - one reqwest client with consistent error surfaces (no more
+#     `curl --fail-with-body` repeated per verb),
+#   - sane shell quoting (no more HEREDOC-eaten-by-positional traps),
+#   - and a single test surface.
+#
+# This Nix file is now a thin extractor: it pulls just the
+# `hive-forge` binary out of the hyperhive workspace package so
+# agents that already imported this file via
+# `pkgs.callPackage ../packages/hive-forge-tools.nix { }` keep
+# working, getting only the verb they need on PATH (not the full
+# `hive-c0re` / `hive` surface).
+#
+# Requires the hyperhive overlay (see `flake.nix`'s `overlays.default`)
+# so `pkgs.hyperhive` resolves.
+let
+  _ = lib; # placeholder; kept so callers don't break when reading the args.
+in
+pkgs.runCommand "hive-forge"
+  {
+    meta = {
+      description = "Forgejo CLI wrapper for hyperhive (Rust)";
+      mainProgram = "hive-forge";
+    };
+  }
+  ''
+    mkdir -p $out/bin
+    ln -s ${pkgs.hyperhive}/bin/hive-forge $out/bin/hive-forge
+  ''

nix/reference-docs.nix

@@ -19,7 +19,7 @@ stdenv.mkDerivation {
   version = "0.1.0";
   # Narrow src (just docs/) keeps this derivation's input hash decoupled
   # from the rest of the tree — a doc edit only re-hashes this.
-  src = ../../docs;
+  src = ../docs;
 
   # No build: pure markdown, nothing to compile or render.
   dontBuild = true;

nix/rust.nix

@@ -1,59 +0,0 @@
-# Shared crane wiring for the rust workspace: the cargo source
-# filter, the once-built dependency artifacts, and the native build
-# inputs every rust derivation (packages + checks) consumes.
-# Imported per system from flake.nix.
-{ pkgs, craneLib }:
-let
-  inherit (pkgs) lib;
-in
-rec {
-  # Shared between buildDepsOnly + buildPackage + cargoClippy/cargoTest
-  # so every derivation in the chain sees the same toolchain shape.
-  # git: hive-c0re's `lifecycle::tests::setup_proposed_*` shell out to
-  # `git init` + commit under `cargo test` in the sandbox.
-  # sqlite: matrix-sdk's `sqlite` feature (`hive-matrix-mcp` workspace
-  # member) — the matrix-sdk-sqlite + rusqlite stack links against
-  # system libsqlite3 by default.
-  # cmake: builds `aws-lc-sys` (BoringSSL) from source — pulled in by
-  # the `rustls` (aws-lc-rs) crypto provider under the OTLP/reqwest
-  # stack in `hive-metric`.
-  nativeBuildInputs = [
-    pkgs.git
-    pkgs.sqlite
-    pkgs.pkg-config
-    pkgs.cmake
-  ];
-
-  # Narrowed source tree the rust derivations consume: everything
-  # cargo cares about (Cargo.toml/Cargo.lock + *.rs/*.toml), selected
-  # via `lib.fileset` rather than crane's `cleanCargoSource` filter —
-  # filesets drop directories that contain no selected files, so
-  # adding or renaming a non-rust directory (nix modules, docs, …)
-  # does NOT bust this src hash (an empty dir under a plain source
-  # filter would). All non-rust runtime assets — branding + the claude
-  # prompt template + claude-settings.json — live in the separate
-  # `hyperhive-assets` derivation and are loaded by the binaries at
-  # runtime from `$HIVE_ASSETS_DIR`. Net effect: only `*.rs` /
-  # `*.toml` / `Cargo.lock` edits rebuild the rust derivations.
-  cleanSrc = lib.fileset.toSource {
-    root = ../.;
-    fileset = craneLib.fileset.commonCargoSources ../.;
-  };
-
-  # Build the workspace's dependency tree once, cached as its own
-  # derivation. Package builds and checks reuse this via
-  # `inherit cargoArtifacts;` so a workspace-only edit doesn't rebuild
-  # deps. All consumers use the same `cleanSrc` so the input hash
-  # stays consistent across the chain.
-  cargoArtifacts = craneLib.buildDepsOnly {
-    src = cleanSrc;
-    # Workspace Cargo.toml is virtual (no `[package].name`), so crane
-    # can't auto-derive a name. Spell it out explicitly — keeps the
-    # derivation name stable across crane bumps + silences the
-    # placeholder warning. Same `pname` for the dep + check
-    # derivations so they share a clean naming family.
-    pname = "hyperhive-workspace";
-    version = "0.1.0";
-    inherit nativeBuildInputs;
-  };
-}

nix/sources.nix

@@ -1,49 +0,0 @@
-# Named, explicitly-filtered source views of this repo. Each real
-# consumer gets its own filtered derivation used as `src`, rather than
-# an inline filter at the use site. Companion to the rust `cleanSrc`
-# (crane's cargo-source filter — see ./rust.nix).
-{ lib }:
-{
-  # Filtered view of this repo handed to hive-c0re as the `hyperhive`
-  # meta-flake input. Drops files no nix or cargo derivation reads —
-  # shell helper scripts and root-level markdown — so editing them
-  # does NOT change the store path and therefore does NOT force a
-  # rebuild of every agent container.
-  #
-  # Dropped: scripts/, docs/, root-level *.md (README/CLAUDE/TODO/…).
-  # Kept (build needs them): .nix, .rs, Cargo.*, branding/,
-  # frontend/, prompts/, flake.lock. docs/ is deliberately dropped:
-  # it is shipped to agent containers as its OWN narrow meta-flake
-  # input (`hyperhiveDocsSource`, below), threaded through hive-c0re
-  # → the meta flake → `hyperhive.docs.source`. Keeping docs/ out of
-  # THIS source means a doc edit only re-hashes the docs input (a
-  # cheap re-link), not the whole flake source (which would rebuild
-  # every agent container). The `reference-docs` build from `../docs`
-  # stays only for standalone `nix build .#reference-docs` from a
-  # full checkout — the meta path never evaluates it.
-  hyperhiveFlakeSource = lib.cleanSourceWith {
-    name = "hyperhive-flake-source";
-    src = ../.;
-    filter =
-      path: type:
-      let
-        # Repo-relative path (strip the absolute source-dir prefix).
-        rel = lib.removePrefix (toString ../. + "/") (toString path);
-      in
-      !(lib.hasPrefix "scripts/" rel || rel == "scripts")
-      && !(lib.hasPrefix "docs/" rel || rel == "docs")
-      && !(type == "regular" && !lib.hasInfix "/" rel && lib.hasSuffix ".md" rel);
-  };
-
-  # The repo `docs/` tree as a standalone narrow source. Its store
-  # path moves ONLY on doc edits, decoupled from `hyperhiveFlakeSource`.
-  # hive-c0re threads this to the meta flake as the `hyperhive-docs`
-  # input (same pattern as the `hyperhive` input); the harness resolves
-  # `$HIVE_DOCS_DIR` from it via `hyperhive.docs.source`. Evaluated
-  # here on the host where docs/ exists — it cannot be derived from
-  # inside the docs-stripped `hyperhiveFlakeSource`.
-  hyperhiveDocsSource = lib.cleanSourceWith {
-    name = "hyperhive-docs-source";
-    src = ../docs;
-  };
-}

nix/templates/agent-base.nix

@@ -1,6 +1,6 @@
 { ... }:
 {
-  imports = [ ../agent-modules ];
+  imports = [ ./harness-base.nix ];
   # Entry-point for sub-agent containers. Referenced from `flake.nix`
   # (`nixosConfigurations.agent-base`) and the meta-flake's
   # `applied/<name>/flake.nix`.

nix/templates/manager.nix

@@ -3,7 +3,7 @@
   # Entry-point for the privileged root agent (ruth). Referenced from
   # `flake.nix` (`nixosConfigurations.ruth`) and the meta-flake's
   # `applied/ruth/flake.nix`.
-  imports = [ ../agent-modules ];
+  imports = [ ./harness-base.nix ];
 
   # The root/manager bootstraps a fresh hive, so it gets the hyperhive
   # reference docs made available by default (readable at

nix/templates/weston-vnc.nix

@@ -32,7 +32,7 @@ in
 {
   # Optional Weston (Wayland compositor) with the VNC backend,
   # surfaced as a per-agent `hyperhive.gui.enable` option. Imported
-  # from ./default.nix so every sub-agent + the manager sees the
+  # from harness-base.nix so every sub-agent + the manager sees the
   # option; only those that flip it on get the service.
   #
   # Port allocation, weston bind-address quirk, PAM service name, the

nix/treefmt.nix

@@ -1,11 +0,0 @@
-# treefmt-nix module — shared by `nix fmt` (the flake `formatter`
-# output) and the `formatting` flake check.
-{
-  projectRootFile = "flake.nix";
-  programs = {
-    keep-sorted.enable = true;
-    nixfmt.enable = true;
-    rustfmt.enable = true;
-    taplo.enable = true;
-  };
-}