hive-c0re: back agent state dirs with btrfs subvolumes

Progressive enhancement: a brand-new agent's state root under
/var/lib/hyperhive/agents is created as a btrfs subvolume when the host
filesystem is btrfs, otherwise it falls back to a plain directory. No
existing agent is auto-migrated — the new path only fires when the root
does not yet exist, so plain-dir agents are left untouched until an
explicit opt-in upgrade.

Two new privileged ops (subvolume create/delete are root-only):
EnsureAgentSubvolume statfs-gates on btrfs, creates the subvolume, and
chowns it to the hive-core user so the normal state/claude/harness
mkdirs succeed inside it; DeleteAgentSubvolume btrfs-subvolume-deletes
the root iff it is actually a subvolume. hive-c0re calls Ensure before
the per-agent dirs are created (spawn/rebuild/InitConfig) and Delete on
the purge path only — destroy keeps the subvolume for revival, matching
plain-dir semantics. btrfs-progs added to the hive-priv unit PATH.

Per-subvolume usage accounting + optional quota is a separate
follow-up.

hive-priv/Cargo.toml

@@ -9,6 +9,7 @@ workspace = true
 [dependencies]
 anyhow.workspace = true
 hive-sh4re.workspace = true
+libc.workspace = true
 serde_json.workspace = true
 tokio.workspace = true
 tracing.workspace = true

hive-priv/src/main.rs

@@ -269,6 +269,16 @@ async fn exec(req: PrivRequest, writer: &mut OwnedWriteHalf) -> Result<(String,
             ref container,
             action,
         } => control_infra_container(container, action).await,
+
+        PrivRequest::EnsureAgentSubvolume { ref agent_name } => {
+            validate_agent_name(agent_name)?;
+            ensure_agent_subvolume(agent_name).await
+        }
+
+        PrivRequest::DeleteAgentSubvolume { ref agent_name } => {
+            validate_agent_name(agent_name)?;
+            delete_agent_subvolume(agent_name).await
+        }
     }
 }
 
@@ -484,6 +494,118 @@ fn write_agent_state_file(
     Ok((String::new(), String::new()))
 }
 
+/// btrfs superblock magic, as reported by `statfs(2)`'s `f_type`.
+const BTRFS_SUPER_MAGIC: i64 = 0x9123_683E;
+
+/// Inode number of a btrfs subvolume root (`BTRFS_FIRST_FREE_OBJECTID`).
+/// Every subvolume's top directory has this inode; plain directories do
+/// not, so `statfs == btrfs && st_ino == 256` reliably identifies a
+/// subvolume root.
+const BTRFS_SUBVOL_ROOT_INO: u64 = 256;
+
+/// Whether `path` lives on a btrfs filesystem (via `statfs(2)`).
+fn is_on_btrfs(path: &Path) -> Result<bool> {
+    use std::os::unix::ffi::OsStrExt as _;
+    let c_path = std::ffi::CString::new(path.as_os_str().as_bytes())
+        .with_context(|| format!("path {} has an interior null byte", path.display()))?;
+    // SAFETY: `c_path` is a valid NUL-terminated C string that outlives the
+    // call; `statfs` only writes into the zero-initialised `buf`.
+    let mut buf: libc::statfs = unsafe { std::mem::zeroed() };
+    let rc = unsafe { libc::statfs(c_path.as_ptr(), &raw mut buf) };
+    if rc != 0 {
+        return Err(std::io::Error::last_os_error())
+            .with_context(|| format!("statfs {}", path.display()));
+    }
+    Ok(buf.f_type == BTRFS_SUPER_MAGIC)
+}
+
+/// Whether `path` is the root of a btrfs subvolume (on btrfs and inode 256).
+fn is_btrfs_subvolume(path: &Path) -> bool {
+    use std::os::unix::fs::MetadataExt as _;
+    let on_btrfs = is_on_btrfs(path).unwrap_or(false);
+    let ino_match = std::fs::metadata(path).is_ok_and(|m| m.ino() == BTRFS_SUBVOL_ROOT_INO);
+    on_btrfs && ino_match
+}
+
+/// `EnsureAgentSubvolume` — make the agent's state root a btrfs subvolume
+/// when the FS supports it. Idempotent + progressive: no-op when the root
+/// already exists or the FS isn't btrfs. See the wire doc on the variant.
+async fn ensure_agent_subvolume(agent_name: &str) -> Result<(String, String)> {
+    use std::os::unix::fs::MetadataExt as _;
+
+    let root = PathBuf::from(AGENT_STATE_ROOT);
+    let agent_root = root.join(agent_name);
+
+    // Progressive: existing agents (plain dir OR already a subvol) are left
+    // untouched — never auto-migrated.
+    if agent_root.exists() {
+        return Ok((String::new(), String::new()));
+    }
+
+    // Only btrfs supports subvolumes; on anything else hive-c0re's normal
+    // `create_dir_all` makes a plain dir (the pre-subvolume behaviour). The
+    // parent must exist for both statfs and `btrfs subvolume create`.
+    std::fs::create_dir_all(&root)
+        .with_context(|| format!("create agents root {}", root.display()))?;
+    if !is_on_btrfs(&root)? {
+        return Ok((String::new(), String::new()));
+    }
+
+    let out = Command::new("btrfs")
+        .args(["subvolume", "create"])
+        .arg(&agent_root)
+        .output()
+        .await
+        .with_context(|| format!("spawn btrfs subvolume create {}", agent_root.display()))?;
+    if !out.status.success() {
+        bail!(
+            "btrfs subvolume create {} failed: {}",
+            agent_root.display(),
+            String::from_utf8_lossy(&out.stderr).trim()
+        );
+    }
+
+    // The subvol root is created root-owned; hive-c0re (the `hive-core` user)
+    // must be able to mkdir state/ claude/ harness/ inside it, exactly as it
+    // would in a plain dir. Match the owner of AGENT_STATE_ROOT (hive-core).
+    if let Ok(meta) = std::fs::metadata(&root)
+        && let Err(e) = std::os::unix::fs::chown(&agent_root, Some(meta.uid()), Some(meta.gid()))
+    {
+        tracing::warn!(
+            agent = %agent_name,
+            error = %e,
+            "ensure_agent_subvolume: chown subvol to agents-root owner failed"
+        );
+    }
+    tracing::info!(agent = %agent_name, path = %agent_root.display(), "created agent state subvolume");
+    Ok((String::new(), String::new()))
+}
+
+/// `DeleteAgentSubvolume` — delete the agent's state root iff it's a btrfs
+/// subvolume (purge path only). No-op for plain dirs / missing paths;
+/// hive-c0re's own `remove_dir_all` covers those. See the wire doc.
+async fn delete_agent_subvolume(agent_name: &str) -> Result<(String, String)> {
+    let agent_root = PathBuf::from(AGENT_STATE_ROOT).join(agent_name);
+    if !is_btrfs_subvolume(&agent_root) {
+        return Ok((String::new(), String::new()));
+    }
+    let out = Command::new("btrfs")
+        .args(["subvolume", "delete"])
+        .arg(&agent_root)
+        .output()
+        .await
+        .with_context(|| format!("spawn btrfs subvolume delete {}", agent_root.display()))?;
+    if !out.status.success() {
+        bail!(
+            "btrfs subvolume delete {} failed: {}",
+            agent_root.display(),
+            String::from_utf8_lossy(&out.stderr).trim()
+        );
+    }
+    tracing::info!(agent = %agent_name, path = %agent_root.display(), "deleted agent state subvolume");
+    Ok((String::new(), String::new()))
+}
+
 /// Validate a single argument destined for `forgejo admin`. Rejects
 /// null bytes and newlines (which could corrupt the subprocess args list
 /// or log output). Shell metacharacters are harmless since the command