fix: address argus+mara review on #1243 — stale docs, MANAGER_DEFAULT refs, ruth migration

hive-c0re/src/meta.rs

@@ -755,7 +755,7 @@ where
             .map_or_else(|| "null".to_owned(), |p| format!("\"{p}\""));
         // Emit `toolGroups = "group1,group2"` when the operator has
         // explicitly configured groups for this agent. Absent entry = null
-        // = harness falls back to its role default (no env var emitted,
+        // = harness falls back to AGENT_DEFAULT (no env var emitted,
         // no rebuild cascade for agents whose groups haven't changed).
         let groups = tool_groups_map.get(&spec.name).cloned().unwrap_or_default();
         let tool_groups_attr = if groups.is_empty() {

hive-c0re/src/migrate.rs

@@ -1,5 +1,6 @@
-//! Startup auto-migration. Five idempotent phases: applied repo,
-//! proposed repo, meta repo, container repoint, root→h-root rename.
+//! Startup auto-migration. Six idempotent phases: applied repo,
+//! proposed repo, meta repo, container repoint, root→h-root rename,
+//! and manager tool-groups backfill.
 //! Kill-switch: `HIVE_SKIP_META_MIGRATION=1`. Full migration sequence
 //! and phase details: `docs/approvals.md::Migration from the pre-tag`.
 
@@ -12,6 +13,7 @@ use tokio::process::Command;
 use crate::coordinator::Coordinator;
 use crate::lifecycle::{self, AGENT_PREFIX, MANAGER_CONTAINER, MANAGER_NAME};
 use crate::meta;
+use crate::tool_groups;
 
 const KILL_SWITCH: &str = "HIVE_SKIP_META_MIGRATION";
 
@@ -112,6 +114,11 @@ pub async fn run(coord: &Arc<Coordinator>) -> Result<()> {
     // fresh installs (conf file absent) and after first successful run.
     rename_manager_container(coord).await;
 
+    // Phase 6: ensure ruth has explicit tool groups so removing the
+    // role-based fallback (Role::Manager → MANAGER_DEFAULT) doesn't
+    // silently strip her privileged tools on next rebuild.
+    backfill_manager_tool_groups(&names);
+
     Ok(())
 }
 
@@ -322,6 +329,37 @@ async fn repoint_container(name: &str) -> Result<()> {
     Ok(())
 }
 
+/// Phase 6: if ruth is a deployed agent and has no explicit entry in
+/// `tool-groups.json`, set her groups to `MANAGER_DEFAULT` (all groups).
+/// Idempotent — skips when entry already present. Prevents a silent tool
+/// downgrade when upgrading from a build that relied on the manager-flavor
+/// fallback in `effective_tool_groups()`.
+fn backfill_manager_tool_groups(names: &[String]) {
+    if !names.iter().any(|n| n == MANAGER_NAME) {
+        return; // ruth not deployed — nothing to backfill
+    }
+    let existing = tool_groups::groups_for(MANAGER_NAME);
+    if !existing.is_empty() {
+        tracing::debug!(
+            "migration: ruth already has explicit tool groups — skipping backfill"
+        );
+        return;
+    }
+    let all_groups: Vec<String> = hive_sh4re::ToolGroup::MANAGER_DEFAULT
+        .iter()
+        .map(|g| g.as_str().to_owned())
+        .collect();
+    match tool_groups::set_groups(MANAGER_NAME, &all_groups) {
+        Ok(()) => tracing::info!(
+            "migration: backfilled ruth's tool groups to MANAGER_DEFAULT (all groups)"
+        ),
+        Err(e) => tracing::warn!(
+            error = ?e,
+            "migration: failed to backfill ruth's tool groups — she may lose privileged tools on next rebuild"
+        ),
+    }
+}
+
 async fn raw_git(dir: &Path, args: &[&str]) -> Result<()> {
     let out = lifecycle::git_command()
         .current_dir(dir)

hive-c0re/src/tool_groups.rs

@@ -12,16 +12,14 @@
 //! }
 //! ```
 //!
-//! An absent entry (or an absent file) means "use the harness role
-//! default" — agents get `messaging + meta + inbox`, the manager gets
-//! all groups. `render_flake` in `meta.rs` reads this file and
-//! injects `HIVE_TOOL_GROUPS` into each agent's systemd service env;
-//! agents with no entry get no env var and the harness falls back.
+//! An absent entry (or an absent file) means "use the harness default"
+//! (`AGENT_DEFAULT`: `messaging + meta + inbox + execution`). `render_flake`
+//! in `meta.rs` reads this file and injects `HIVE_TOOL_GROUPS` into each
+//! agent's systemd service env; agents with no entry get no env var and the
+//! harness falls back to `AGENT_DEFAULT`.
 //!
 //! Write path: `set_groups` is called from the dashboard action handler
 //! that the operator uses to grant/revoke tool groups per agent.
-//! The manager may also request group changes via an approval; hive-c0re
-//! applies the change on approval, commits the file, and cascades a rebuild.
 
 use std::collections::BTreeMap;
 use std::path::PathBuf;