docs(agent-hierarchy): fix stale topology.rs path, ManagerRequest, dead reminder_scheduler.rs ref, and hardcoded forge URLs

This commit is contained in:
iris 2026-08-15 12:20:04 +02:00 committed by mara
commit 723e33ae6c

View file

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