hive-c0re: hivectl subvol upgrade — migrate an agent state dir to a btrfs subvolume

New agents get a btrfs subvolume state root automatically when the host
FS is btrfs, but agents that predate that migration are left on plain
dirs and miss the subvolume feature set (snapshots, per-subvol
usage/quota, send/receive migration). Add an opt-in operator verb to
convert an existing plain-dir agent in place.

btrfs cannot promote a directory to a subvolume in place, so the new
privileged op stages a sibling subvolume mirroring the dir (create +
`cp -a --reflink=auto` preserving ownership/permissions/xattrs + match
the root's owner and mode), then atomically renames the original aside
and the subvolume into place, then removes the original. Any failure
before the swap leaves the original untouched; idempotent (no-op if
already a subvolume) and btrfs-gated.

The `hivectl subvol upgrade <agent> --yes` verb composes it client-side
like `restart`: stop the agent so its state bind-mount is released, run
the migration via hive-priv, then restart it — the restart is attempted
regardless of the migration outcome so a failed migration never leaves
the agent down.

- hive-sh4re: UpgradeAgentSubvolume priv request variant.
- hive-priv: the migration handler plus stage/cleanup helpers.
- hive-c0re: priv_client wrapper and the hivectl verb; regen CLI docs.

docs/tools/hivectl-cli.md

@@ -32,6 +32,8 @@ This document contains the help content for the `hivectl` command-line program.
 * [`hivectl quota enable`↴](#hivectl-quota-enable)
 * [`hivectl quota show`↴](#hivectl-quota-show)
 * [`hivectl quota limit`↴](#hivectl-quota-limit)
+* [`hivectl subvol`↴](#hivectl-subvol)
+* [`hivectl subvol upgrade`↴](#hivectl-subvol-upgrade)
 * [`hivectl completions`↴](#hivectl-completions)
 
 ## `hivectl`
@@ -52,6 +54,7 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
 * `start` — Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). Requires the hive-c0re daemon
 * `restart` — Restart containers hive-wide — `stop` then `start` over the same scope. Bare `hivectl restart` restarts **everything** (all sub-agents plus the ci/forge/gateway/matrix infra containers); the same scope flags as `stop`/`start` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). If the stop phase reports a failure the start phase is skipped so the operator can investigate. Requires the hive-c0re daemon
 * `quota` — Per-agent disk accounting + optional quotas via btrfs qgroups
+* `subvol` — btrfs subvolume management for agent state dirs
 * `completions` — Generate a shell completion script for `hivectl` and print it to stdout
 
 ###### **Options:**
@@ -465,6 +468,36 @@ Set or clear an agent's disk quota (a referenced-usage cap). `size` accepts a by
 
 
 
+## `hivectl subvol`
+
+btrfs subvolume management for agent state dirs.
+
+New agents get a btrfs subvolume state root automatically (when the host FS is btrfs); agents that predate that are left on plain dirs. `subvol upgrade <agent>` opts an existing plain-dir agent into the subvolume feature set (snapshots, per-subvol usage/quota, migration) by migrating its state dir in place. Requires the hive-c0re daemon (for the stop/start) and root (for the privileged migration).
+
+**Usage:** `hivectl subvol <COMMAND>`
+
+###### **Subcommands:**
+
+* `upgrade` — Convert an existing plain-dir agent state root into a btrfs subvolume in place. Stops the agent (so its state bind-mount is released), migrates `…/agents/<name>/` to a subvolume preserving ownership/permissions/xattrs, then restarts it. Idempotent (no-op if already a subvolume) and safe (the original dir is left untouched on any failure before the final swap). Requires `--yes` since it bounces the agent and moves its state
+
+
+
+## `hivectl subvol upgrade`
+
+Convert an existing plain-dir agent state root into a btrfs subvolume in place. Stops the agent (so its state bind-mount is released), migrates `…/agents/<name>/` to a subvolume preserving ownership/permissions/xattrs, then restarts it. Idempotent (no-op if already a subvolume) and safe (the original dir is left untouched on any failure before the final swap). Requires `--yes` since it bounces the agent and moves its state
+
+**Usage:** `hivectl subvol upgrade [OPTIONS] <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Agent name (e.g. `damocles`, `iris`)
+
+###### **Options:**
+
+* `--yes` — Confirm: this stops the agent, migrates its state dir, and restarts it. Required — the command refuses without it
+
+
+
 ## `hivectl completions`
 
 Generate a shell completion script for `hivectl` and print it to stdout.