From 336ed5a010a1d91bf6fb0182da75ac7160660219 Mon Sep 17 00:00:00 2001 From: atlas Date: Mon, 21 Sep 2026 22:20:21 +0200 Subject: [PATCH] docs+comments: say what changed instead of tagging the tracker item MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prose added by this branch named the tracker item in seventeen places, which check-issue-refs.sh rejects: a `#N` tag is dead weight for anyone reading the public mirror, where no issue data exists. Each one now states the fact it was pointing at — the parent field is gone — so the sentence stands on its own. Two of those lines also carried a rustdoc break: `[`write`]` in topology.rs is ambiguous between the module's own `write` fn and the `write!` macro, which `-D rustdoc::broken-intra-doc-links` fails. Spelled `[`write()`]`, per rustdoc's own suggestion. The host_config.rs rewrite is two lines rather than three so the doc block stays under check-comment-blocks.sh's 30-line ceiling. --- docs/agent-lifecycle/agent-hierarchy.md | 6 +++--- docs/agent-lifecycle/persistence.md | 8 ++++---- docs/process/conventions.md | 4 ++-- docs/web-ui/dashboard.md | 10 +++++----- hive-agent-mcp/src/send_allow.rs | 2 +- hive-agent/src/main.rs | 2 +- hive-c0re/src/agent_config/topology.rs | 8 ++++---- hive-c0re/src/job_queue/exec.rs | 4 ++-- hive-c0re/src/lifecycle/host_config.rs | 8 ++++---- hive-c0re/src/workers/auto_update.rs | 4 ++-- 10 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/agent-lifecycle/agent-hierarchy.md b/docs/agent-lifecycle/agent-hierarchy.md index 69b0dcec..aeddb0fd 100644 --- a/docs/agent-lifecycle/agent-hierarchy.md +++ b/docs/agent-lifecycle/agent-hierarchy.md @@ -2,8 +2,8 @@ -Agents are a **flat set**, with no parent/child tree: #4472 removed the -`parent` field `topology.json` used to carry, and every mechanism that +Agents are a **flat set**, with no parent/child tree: the `parent` field +`topology.json` used to carry is gone, along with every mechanism that read it. The capability store scopes which agents can manage which others; a tree position no longer scopes anything. @@ -33,7 +33,7 @@ agent's `state` read-write and `config` read-only; never `harness`). An agent holding no capability sees its own dirs and nothing else. See [`persistence.md`](persistence.md)'s _Cross-agent access to state._ -### Reading the pre-#4472 format +### Reading the legacy format `topology.json` used to be a map of `name → parent | null`. The reader still accepts that shape and keeps its keys, so a hive upgrading across diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index 5a558d74..da4e4db5 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -344,8 +344,8 @@ The RW on `state` is deliberate, not an oversight: the holder recovers other agents, which includes writing into their state (for example seeding notes, clearing a stuck sentinel) as well as reading it. -This is the **only** cross-agent mount. #4472 removed the topology -parent field, and with it the unconditional grant every agent used to +This is the **only** cross-agent mount. Dropping the topology parent +field took with it the unconditional grant every agent used to get over its own direct children — an agent holding no capability now sees its own dirs and nothing else. @@ -395,8 +395,8 @@ Contents: - `topology.json` — the agent roster (`["alice", "bob", "ruth"]`). Written by `topology::reconcile` on every meta sync; read by `topology::all_agents`, which is the set the `ManageRootAgent` - capability grants mounts over. Carried a `parent` per agent until - #4472; the reader still accepts that shape and keeps its keys. + capability grants mounts over. Carried a `parent` per agent in the + legacy format; the reader still accepts that shape and keeps its keys. - `tool-groups.json` — per-agent MCP tool group grants (`{ "alice": ["messaging", "inbox", "execution"] }`). Written by `tool_groups::set_groups`; injected as `HIVE_TOOL_GROUPS` env diff --git a/docs/process/conventions.md b/docs/process/conventions.md index ebc221b3..cdc6d558 100644 --- a/docs/process/conventions.md +++ b/docs/process/conventions.md @@ -89,8 +89,8 @@ angle-bracket and asterisk shapes below are structurally safe. inbox view; no agent ever `recv`'s them. `` and `` were two more, resolved against a -`topology.json` parent field. #4472 removed that field and both -sentinels with it: address `operator` where you would have said +`topology.json` parent field. That field and both sentinels no longer +exist: address `operator` where you would have said ``, and name the recipients (or broadcast to `*`) where you would have said ``. Nothing rewrites a recipient at send time any more — what an agent passes is what the broker stores. diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index 9621ce58..2072387e 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -59,8 +59,8 @@ surfaces, not tab panes. **C0NTAINERS** — live containers rendered as a flat, alphabetically-sorted list. The renderer still walks `ContainerView.parent` for a depth-first tree with ASCII glyphs -(`├─`, `└─`, `│ ` continuation columns), but #4472 removed that field, -so every row sits at depth 0 and the renderer paints no glyph. The tree +(`├─`, `└─`, `│ ` continuation columns), but that field no longer +exists, so every row sits at depth 0 and the renderer paints no glyph. The tree sorts alphabetically; roots likewise. The tree tolerates cycles in the parent graph — it appends orphaned containers (not reachable from any root) @@ -981,7 +981,7 @@ identically.) ### Topology tree -⚠️ **Dormant since #4472,** which removed `ContainerView.parent`: +⚠️ **Dormant now that `ContainerView.parent` no longer exists:** `buildAgentTree` now puts every container at depth 0 and the rules below are all no-ops — the list renders flat. The walk and the prefix painting are still in `swarm.js`; retiring them falls to the frontend owner rather @@ -1032,8 +1032,8 @@ frosted-mauve bar slides up from the bottom of the viewport - `DESTR0Y` / `PURG3` — always available - #4472 removed the `M0V3` picker that used to sit here — an agent has - no parent to move it to any more. + The `M0V3` picker that used to sit here no longer exists — an agent + has no parent to move it to any more. - **`✕ clear`** button + `Esc` key clear the entire selection. Every render prunes stale selections (agents destroyed while diff --git a/hive-agent-mcp/src/send_allow.rs b/hive-agent-mcp/src/send_allow.rs index 3033eca8..8bfc0e1f 100644 --- a/hive-agent-mcp/src/send_allow.rs +++ b/hive-agent-mcp/src/send_allow.rs @@ -25,7 +25,7 @@ pub fn check_send_allowed(to: &str) -> Result<(), String> { // // This bypass used to be spelled ``, which the broker // resolved per `topology.json` and which fell back to `operator` - // for a root agent. #4472 removed the parent field, so every + // for a root agent. The parent field is gone now, so every // agent is what that fallback called a root — the exemption is // now written as the name it always resolved to. Same reachable // set, one fewer indirection. diff --git a/hive-agent/src/main.rs b/hive-agent/src/main.rs index a5a3a054..064f79cd 100644 --- a/hive-agent/src/main.rs +++ b/hive-agent/src/main.rs @@ -282,7 +282,7 @@ trait Surface { /// of a container: this is where a turn failure or a plugin-install /// failure surfaces when nothing inside the harness can act on it. /// - /// Was `` before #4472, a sentinel the broker resolved per + /// Was `` while the hierarchy existed, a sentinel the broker resolved per /// `topology.json` and which already fell through to `operator` for a /// root agent. With the parent field gone every agent takes that /// branch, so the recipient is written out rather than resolved. diff --git a/hive-c0re/src/agent_config/topology.rs b/hive-c0re/src/agent_config/topology.rs index 60ba5a93..d4dfbff2 100644 --- a/hive-c0re/src/agent_config/topology.rs +++ b/hive-c0re/src/agent_config/topology.rs @@ -6,7 +6,7 @@ //! **There is no hierarchy here any more.** The file used to be a map of //! `name → parent | null` and this module owned the parent/child tree that //! fed `` / `` routing, the reparenting API and the -//! dashboard's tree view. All of that is gone (#4472); what the file is +//! dashboard's tree view. All of that is gone; what the file is //! *for* now is the one thing that survived the removal — naming every //! agent, which is the set a //! [`hive_sh4re::permissions::Capability::ManageRootAgent`] holder gets @@ -28,8 +28,8 @@ pub fn topology_path() -> PathBuf { crate::paths::meta_root().join(TOPOLOGY_FILE) } -/// On-disk shapes [`read`] accepts. The array is what [`write`] emits; the -/// map is the pre-#4472 `name → parent | null` format, kept readable so a +/// On-disk shapes [`read`] accepts. The array is what [`write()`] emits; the +/// map is the legacy `name → parent | null` format, kept readable so a /// hive that upgrades across this change keeps its roster instead of /// blanking it until the next `reconcile` pass — and a blank roster is not /// a cosmetic gap, it is every `ManageRootAgent` holder losing its mounts @@ -204,7 +204,7 @@ mod tests { } /// The upgrade path. A hive whose `topology.json` still carries the - /// pre-#4472 `name → parent` map must read as the same roster, parent + /// legacy `name → parent` map must read as the same roster, parent /// values discarded — otherwise the first read after the upgrade hands /// `ManageRootAgent` holders an empty mount set. #[test] diff --git a/hive-c0re/src/job_queue/exec.rs b/hive-c0re/src/job_queue/exec.rs index 6ac5cda7..d7f82ce0 100644 --- a/hive-c0re/src/job_queue/exec.rs +++ b/hive-c0re/src/job_queue/exec.rs @@ -862,8 +862,8 @@ async fn run_deploy_tail( /// flake affects — the fan-out set for `MetaUpdate` DAGs. Empty /// `inputs` or any input under `hyperhive` → every container; /// otherwise just the agents named by `agent-` inputs. -/// Sorted by name — #4472 removed the parent field the old depth sort -/// keyed on, and with every agent a root that sort already reduced to +/// Sorted by name — the parent field the old depth sort keyed on is +/// gone, and with every agent a root that sort already reduced to /// this. /// /// `inputs` is the caller-supplied flake-input-name list (the dashboard's diff --git a/hive-c0re/src/lifecycle/host_config.rs b/hive-c0re/src/lifecycle/host_config.rs index 904dc23d..4bf1da77 100644 --- a/hive-c0re/src/lifecycle/host_config.rs +++ b/hive-c0re/src/lifecycle/host_config.rs @@ -92,8 +92,8 @@ fn config_bind_source(name: &str) -> PathBuf { /// directories so nspawn doesn't refuse to start; missing dirs are /// non-fatal. /// -/// The only caller left is the `ManageRootAgent` grant — #4472 removed the -/// parent/child tree that used to hand every agent its own children here. +/// The only caller left is the `ManageRootAgent` grant; the parent/child +/// tree that handed every agent its own children here is gone. /// /// **Three dirs, three different answers** — the uniformity of the /// original loop is what hid that: @@ -335,8 +335,8 @@ async fn set_nspawn_flags( // now says so out loud instead of deriving it from a field that no // longer discriminates. // - // This is the *only* cross-agent mount left. #4472 dropped the - // topology parent field, and with it the unconditional grant every + // This is the *only* cross-agent mount left. Dropping the topology + // parent field took with it the unconditional grant every // agent used to get over its own direct children — so an agent with // no capability now sees its own dirs and nothing else. if crate::capabilities::has_cap(agent_name, Capability::ManageRootAgent) { diff --git a/hive-c0re/src/workers/auto_update.rs b/hive-c0re/src/workers/auto_update.rs index 09a799e0..bb510d7c 100644 --- a/hive-c0re/src/workers/auto_update.rs +++ b/hive-c0re/src/workers/auto_update.rs @@ -267,8 +267,8 @@ pub async fn run(coord: Arc) -> Result<()> { let current_rev = current_flake_rev(&coord.hyperhive_flake); - // Resolve container names to logical agent names, then sort. #4472 - // removed the parent field this used to depth-sort by; with no + // Resolve container names to logical agent names, then sort. The + // parent field this used to depth-sort by is gone; with no // hierarchy left to respect, alphabetical is the whole order — and it // is exactly what the depth sort already produced once every agent // was a root.