From f6d681c2e29cb0ecca1b5f089d964e4f0250d4ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?m=C3=BCde?= <git@darkest.space>
Date: Thu, 14 May 2026 23:12:43 +0200
Subject: [PATCH] CLAUDE.md: Phases 4 + 5 status, approval-flow runbook

---
 CLAUDE.md | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1f2f80a..0190186 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -140,11 +140,48 @@ in.
   hot-reload works under the patch stack (validated empirically on muede-lpt2)
 - ✅ Phase 2 — per-agent sockets, in-memory broker, agent harness round-trips messages
 - ✅ Phase 3 — sqlite broker (durable across restart) + claude-or-echo turn loop
-- 🔜 Phase 4 — `hm1nd` manager binary with privileged tool surface
-- 🔜 Phase 5 — git-commit approval flow (`state-repo` + per-agent config flakes)
+- ✅ Phase 4 — `hm1nd` manager binary + manager socket + declarative `containers.hm1nd`
+- ✅ Phase 5 — git-commit approval flow:
+  - 5a — sqlite approval queue (`request_apply_commit` / `pending` / `approve` / `deny`)
+  - 5b — per-agent config flakes at `/var/lib/hyperhive/agents/<name>/config/`;
+    `approve <id>` validates the commit + advances `main` + rebuilds
 - 🔜 Phase 6 — per-agent web UI + dashboard MVP
 - 🔜 Phase 7 — dashboard commit-view + polish
 
+## Approval flow (Phase 5)
+
+End-to-end: manager edits per-agent config repo → commits → submits commit sha
+for approval → user approves on host CLI → `hive-c0re` advances `main` + rebuilds.
+
+```
+# Inside the hm1nd container (manager has /agents bind-mounted RW):
+cd /agents/alice/config
+$EDITOR agent.nix              # add `environment.systemPackages = [ pkgs.htop ];`
+git commit -am "add htop"
+SHA=$(git rev-parse HEAD)
+hive-m1nd request-apply-commit alice $SHA
+exit
+
+# On the host:
+sudo hive-c0re pending          # shows the queued approval with id N
+sudo hive-c0re approve N        # validates, advances main, rebuilds h-alice
+sudo nixos-container run h-alice -- which htop   # /run/current-system/sw/bin/htop
+```
+
+Per-agent flake layout (generated by `setup_config` on every spawn / rebuild):
+
+```
+/var/lib/hyperhive/agents/<name>/config/
+├── .git/
+├── flake.nix     # managed by hive-c0re — rewritten when hyperhive flake URL changes
+└── agent.nix     # manager-editable; per-agent NixOS overrides
+```
+
+The flake's `inputs.hyperhive.url` is the same URL `hive-c0re` was launched with
+(`services.hive-c0re.hyperhiveFlake`), inlined as a string. The flake's
+`nixosConfigurations.default` extends `hyperhive.nixosConfigurations.agent-base`
+with `./agent.nix`. So adding packages is a one-line edit in `agent.nix`.
+
 See PLAN.md for the full design and the deferred-out-of-scope list.
 
 ## Inspirations