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