refactor: per-agent state paths (/agents/{label}/state), centralize in paths.rs

hive-ag3nt/prompts/agent.md

@@ -11,10 +11,10 @@ Need new packages, env vars, or other NixOS config for yourself? You can't edit
 
 Durable knowledge: write to `/agents/{label}/state/notes.md` (free-form) or any other path under `/agents/{label}/state/`. That directory is bind-mounted from the host and persists across container destroy/recreate — claude's `--continue` session only carries short-term context, but `/agents/{label}/state/` is forever. Read it back at the start of relevant turns to remember things across resets.
 
-Claude session (OAuth credentials) lives at `/agents/{label}/claude/` and persists across restarts.
+Claude session (OAuth credentials) lives at `/root/.claude/` and persists across restarts.
 
 **Shared space**: `/shared` is accessible to all agents (read/write). Only put things here you're willing to lose — other agents may delete them. Use for explicit cross-agent communication or shared artifacts when appropriate.
 
-Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/state/<descriptive-name>` and `send` a short pointer ("dropped the cluster audit in /state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The manager + operator can read your `/state/` from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's `/state/` directly — go through the manager if a payload needs to reach another sub-agent.
+Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/agents/{label}/state/<descriptive-name>` and `send` a short pointer ("dropped the cluster audit in /state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The manager + operator can read your state from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's `/state/` directly — go through the manager if a payload needs to reach another sub-agent.
 
 When your inbox has a message, handle it and stop. Don't narrate intent — act.

hive-ag3nt/prompts/manager.md

@@ -32,7 +32,7 @@ in {
   environment.systemPackages = [ matrixPkg ];
   hyperhive.extraMcpServers.matrix = {
     command = "${matrixPkg}/bin/mcp-matrix";
-    args = [ "--config" "/state/matrix.toml" ];
+    args = [ "--config" "/agents/<name>/state/matrix.toml" ];  # replace <name> with the agent's label
     allowedTools = [ "send_message" "join_room" ];
   };
 }

hive-ag3nt/src/bin/hive-ag3nt.rs

@@ -65,7 +65,7 @@ async fn main() -> Result<()> {
                 .and_then(|s| s.parse::<u16>().ok())
                 .unwrap_or(DEFAULT_WEB_PORT);
             let label = std::env::var("HIVE_LABEL").unwrap_or_else(|_| "hive-ag3nt".into());
-            let claude_dir = PathBuf::from(login::DEFAULT_CLAUDE_DIR);
+            let claude_dir = login::default_dir();
             let initial = LoginState::from_dir(&claude_dir);
             tracing::info!(state = ?initial, claude_dir = %claude_dir.display(), "harness boot");
             let login_state = Arc::new(Mutex::new(initial));

hive-ag3nt/src/bin/hive-m1nd.rs

@@ -55,7 +55,7 @@ async fn main() -> Result<()> {
                 .and_then(|s| s.parse::<u16>().ok())
                 .unwrap_or(DEFAULT_WEB_PORT);
             let label = std::env::var("HIVE_LABEL").unwrap_or_else(|_| "hm1nd".into());
-            let claude_dir = PathBuf::from(login::DEFAULT_CLAUDE_DIR);
+            let claude_dir = login::default_dir();
             let initial = LoginState::from_dir(&claude_dir);
             tracing::info!(state = ?initial, claude_dir = %claude_dir.display(), "hm1nd boot");
             let login_state = Arc::new(Mutex::new(initial));

hive-ag3nt/src/events.rs

@@ -20,21 +20,18 @@ const CHANNEL_CAPACITY: usize = 256;
 /// Max `LiveEvent`s the `Bus` returns from `history()` and keeps in
 /// sqlite. Older rows are vacuumed on a periodic sweep.
 const HISTORY_CAPACITY: usize = 2000;
-/// Default sqlite db path. Lives under `/state/` so it survives
+/// Path to the persisted event db. Overridable via `HYPERHIVE_EVENTS_DB`
-/// destroy/recreate but goes away on purge. Overridable via the
+/// for dev / tests; otherwise derived from the agent's state dir.
-/// `HYPERHIVE_EVENTS_DB` env var (used in tests and one-shot tools).
+fn events_db_path() -> PathBuf {
-const DEFAULT_EVENTS_DB: &str = "/state/hyperhive-events.sqlite";
+    std::env::var_os("HYPERHIVE_EVENTS_DB")
+        .map_or_else(|| crate::paths::state_dir().join("hyperhive-events.sqlite"), PathBuf::from)
+}
 
-/// Persisted model name file. Same lifecycle as the events db —
+/// Path to the persisted model file. Overridable via `HYPERHIVE_MODEL_FILE`
-/// survives destroy/recreate, gone on purge. Empty / missing file
+/// for dev / tests; otherwise derived from the agent's state dir.
-/// falls back to `DEFAULT_MODEL`.
-const DEFAULT_MODEL_FILE: &str = "/state/hyperhive-model";
-
-/// Path to the persisted model file. Overridable via
-/// `HYPERHIVE_MODEL_FILE` for dev / tests.
 fn model_file_path() -> PathBuf {
     std::env::var_os("HYPERHIVE_MODEL_FILE")
-        .map_or_else(|| PathBuf::from(DEFAULT_MODEL_FILE), PathBuf::from)
+        .map_or_else(|| crate::paths::state_dir().join("hyperhive-model"), PathBuf::from)
 }
 
 fn load_model() -> Option<String> {
@@ -183,7 +180,7 @@ pub struct Bus {
     tx: Arc<broadcast::Sender<LiveEvent>>,
     /// Persistent event log. `None` only if opening the sqlite db failed
     /// at construction — we keep going so the harness doesn't die on a
-    /// missing `/state/` mount in dev / test scenarios.
+    /// missing state dir mount in dev / test scenarios.
     store: Option<Arc<EventStore>>,
     /// Current turn-loop state + since-when (unix seconds).
     state: Arc<Mutex<(TurnState, i64)>>,
@@ -200,13 +197,11 @@ pub struct Bus {
 }
 
 impl Bus {
-    /// Open the default events db (`/state/hyperhive-events.sqlite`, or
+    /// Open the events db (path from `events_db_path()`). On failure, fall back
-    /// `HYPERHIVE_EVENTS_DB`). On failure, fall back to a no-store bus —
+    /// to a no-store bus — the harness still works, just without persistent history.
-    /// the harness still works, just without persistent history.
     #[must_use]
     pub fn new() -> Self {
-        let path = std::env::var_os("HYPERHIVE_EVENTS_DB")
+        let path = events_db_path();
-            .map_or_else(|| PathBuf::from(DEFAULT_EVENTS_DB), PathBuf::from);
         let store = match EventStore::open(&path) {
             Ok(s) => Some(Arc::new(s)),
             Err(e) => {
@@ -247,8 +242,8 @@ impl Bus {
     }
 
     /// Switch the model for future turns. The current turn (if any)
-    /// keeps the model it was already running. Persisted to
+    /// keeps the model it was already running. Persisted to the agent's
-    /// `/state/hyperhive-model` so the override survives harness
+    /// state dir (`hyperhive-model`) so the override survives harness
     /// restart and container rebuild (gone on `--purge`, matching
     /// every other piece of agent state).
     pub fn set_model(&self, name: impl Into<String>) {

hive-ag3nt/src/lib.rs

@@ -6,6 +6,7 @@ pub mod events;
 pub mod login;
 pub mod login_session;
 pub mod mcp;
+pub mod paths;
 pub mod plugins;
 pub mod turn;
 pub mod web_ui;

hive-ag3nt/src/login.rs

@@ -1,6 +1,6 @@
 //! Login-state probe for the bind-mounted `~/.claude/` dir. The dir is
-//! provided by hive-c0re (Phase 8 step 1) and persists across container
+//! provided by hive-c0re and persists across container destroy/recreate so
-//! destroy/recreate so OAuth tokens survive.
+//! OAuth tokens survive.
 //!
 //! "Has session" today means "the dir contains at least one regular file."
 //! That's a heuristic: a fresh bind-mount starts empty, and `claude auth login`
@@ -8,11 +8,15 @@
 //! specific credentials filename, or run a no-op `claude` call) once the
 //! exact layout is locked in.
 
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
-/// Mount point of the per-agent Claude credentials dir inside the container.
+/// Returns the Claude credentials directory for this agent, derived from
-/// Matches `hive_c0re::lifecycle::CONTAINER_CLAUDE_MOUNT`.
+/// `HIVE_LABEL`. Manager ("hm1nd") uses `/root/.claude`; sub-agents use
-pub const DEFAULT_CLAUDE_DIR: &str = "/root/.claude";
+/// `/agents/{label}/claude`. Overridable via `HYPERHIVE_CLAUDE_DIR`.
+#[must_use]
+pub fn default_dir() -> PathBuf {
+    crate::paths::claude_dir()
+}
 
 /// Returns `true` if `dir` exists and contains any regular file. Used at
 /// startup to decide whether to enter the turn loop (logged in) or stay in

hive-ag3nt/src/paths.rs

@@ -0,0 +1,39 @@
+//! Per-agent path resolution for state and credential directories.
+//!
+//! Manager ("hm1nd") keeps `/state`; sub-agents use `/agents/{label}/state`.
+//! Claude credentials are always at `/root/.claude` for all agents.
+//!
+//! Both paths can be overridden via env vars (`HYPERHIVE_STATE_DIR`,
+//! `HYPERHIVE_CLAUDE_DIR`) for dev / test scenarios.
+
+use std::path::PathBuf;
+
+/// Container label of the manager. Sub-agents get `/agents/{label}/state`;
+/// the manager keeps `/state`. Must match `hive-c0re::lifecycle::MANAGER_NAME`.
+pub const MANAGER_NAME: &str = "hm1nd";
+
+/// Durable state directory for the current agent. Reads `HYPERHIVE_STATE_DIR`
+/// first; falls back to `/agents/{label}/state` for sub-agents or `/state` for
+/// the manager / any unrecognised label.
+#[must_use]
+pub fn state_dir() -> PathBuf {
+    if let Some(p) = std::env::var_os("HYPERHIVE_STATE_DIR") {
+        return PathBuf::from(p);
+    }
+    let label = std::env::var("HIVE_LABEL").unwrap_or_default();
+    if label == MANAGER_NAME || label.is_empty() {
+        PathBuf::from("/state")
+    } else {
+        PathBuf::from(format!("/agents/{label}/state"))
+    }
+}
+
+/// Claude credentials directory for the current agent. Always `/root/.claude`
+/// because the `claude` CLI reads `$HOME/.claude` (uid 0 → `/root`), and
+/// hive-c0re binds the per-agent credentials dir there for every container.
+/// Overridable via `HYPERHIVE_CLAUDE_DIR` for dev / test scenarios.
+#[must_use]
+pub fn claude_dir() -> PathBuf {
+    std::env::var_os("HYPERHIVE_CLAUDE_DIR")
+        .map_or_else(|| PathBuf::from("/root/.claude"), PathBuf::from)
+}

hive-ag3nt/src/turn.rs

@@ -230,15 +230,13 @@ async fn run_claude(prompt: &str, files: &TurnFiles, bus: &Bus) -> Result<bool>
         ));
     }
     let mut cmd = Command::new("claude");
-    // Spawn inside /state so any path claude resolves relatively (Read
+    // Spawn inside the agent's state dir so relative paths in tool calls
-    // foo.md, Bash ls, Write notes.md) lands in the agent's durable
+    // (Read foo.md, Bash ls, Write notes.md) land in the durable dir
-    // dir instead of wherever the harness systemd unit started. /state
+    // instead of wherever the harness systemd unit started. Falls back
-    // is bind-mounted RW from the host so survives destroy/recreate.
+    // silently if the dir is missing (dev / test without the bind mount).
-    // Fall back silently if the dir is missing (dev / test setups
+    let state_dir = crate::paths::state_dir();
-    // running without the bind mount) — Command picks up the parent's
+    if state_dir.is_dir() {
-    // cwd in that case.
+        cmd.current_dir(&state_dir);
-    if std::path::Path::new("/state").is_dir() {
-        cmd.current_dir("/state");
     }
     cmd.arg("--print")
         .arg("--verbose")

hive-c0re/src/lifecycle.rs

@@ -743,25 +743,18 @@ fn set_nspawn_flags(
     let path = format!("/etc/nixos-containers/{container}.conf");
     let original = std::fs::read_to_string(&path).with_context(|| format!("read {path}"))?;
 
-    // Compute mount points: for sub-agents, bind /agents/<name>/ with state+claude inside.
+    // Compute the in-container state mount point. Sub-agents get
-    // For manager, use the old structure with /root/.claude and /state.
+    // /agents/<name>/state; the manager keeps the legacy /state path.
-    let agent_mount_base = if container == MANAGER_NAME {
+    // Claude credentials always land at /root/.claude for all agents so
-        None // Manager has no agent-specific mount
+    // the `claude` CLI (which reads $HOME/.claude) finds them without any
+    // HOME override.
+    let notes_mount = if container == MANAGER_NAME {
+        CONTAINER_NOTES_MOUNT.to_owned()
     } else {
-        // Strip the "h-" prefix from container name to get agent name
         let agent_name = container.strip_prefix(AGENT_PREFIX).unwrap_or(container);
-        Some(format!("/agents/{agent_name}"))
+        format!("/agents/{agent_name}/state")
-    };
-
-    // For sub-agents: bind /agents/<name>/ containing state and claude
-    // For manager: use old /state and /root/.claude mounts
-    let (notes_mount, claude_mount) = if let Some(ref mount_base) = agent_mount_base {
-        // Sub-agent: state at /agents/<name>/state, claude at /agents/<name>/claude
-        (format!("{mount_base}/state"), format!("{mount_base}/claude"))
-    } else {
-        // Manager: keep current structure
-        (CONTAINER_NOTES_MOUNT.to_owned(), CONTAINER_CLAUDE_MOUNT.to_owned())
     };
+    let claude_mount = CONTAINER_CLAUDE_MOUNT;
 
     let mut binds = format!(
         "--bind={runtime}:{CONTAINER_RUNTIME_MOUNT} --bind={claude}:{claude_mount} --bind={notes}:{notes_mount} --bind={shared}:{CONTAINER_SHARED_MOUNT}",