v0.5.0: slice 5 Phase B — the host-root surface (mounts + SMART + grow + destructive gate)

The privileged write surface, isolated behind a narrow, arg-validated, adversarially-
tested seam (HostOps), the same discipline as the slice-4 gate. Completes slice 5.

- internal/storage: HostOps seam + SudoHostOps (systemd .mount units by fs-UUID, detach,
  SMART, lvs) via sudoers allowlist + fixed arg vectors, no shell; NoopHostOps fallback.
- validate.go: strict UUID/mount-path/device/LVM validators + in-process systemd-escape.
  Headline test: adversarial matrix (metacharacters/traversal/malformed) refused with
  zero exec.
- smart.go: smartctl SATA + NVMe parse, UNKNOWN-degrade; lvs thin-pool metadata fill.
- observer enrichment (Observe only): fills smart + thin-pool metadata.
- watchdog: benign re-mount response off the poll path (DevicePresent probe, rate-limited).
- reconcile: ActionResize (benign, grow-only) + proxmox.ResizeLXC; destructive storage ops
  (ClassStorageWipe/Decommission) through the slice-4 gate, target-scoped; built+tested,
  inert live.
- --selftest=storage [-watch] live harness; configs/felhom-agent.sudoers; privileged.* knobs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

REPORT.md

@@ -1,81 +1,79 @@
-# REPORT — Slice 5 Phase A: storage observe + report + watchdog (v0.5.0-rc1) (2026-06-09)
+# REPORT — Slice 5 Phase B: the host-root surface (v0.5.0) (2026-06-09)
 
 > Overwrite-latest report (most recent significant work only). Cumulative history lives in [CHANGELOG.md](CHANGELOG.md).
 
 ## Outcome
 
-**Slice 5 Phase A is complete and pushed as `v0.5.0-rc1`** — the read-only, live half of the
-storage slice (doc 03 §7). The agent now observes every host storage target, reports it into
-the host-report (the slice-3 `storage_targets` stub is filled), and runs a fast-poll storage
-watchdog that pushes a disconnect to the hub out-of-band in seconds. **No host-root writes**
-this phase — mounts/SMART/disk-grow/destructive-gate are Phase B, which earns isolated review
-of the new privileged surface. This is the hard checkpoint: Phase A awaits validation before
-Phase B begins.
+**Slice 5 is complete and pushed as `v0.5.0`.** Phase B adds the privileged **write surface** —
+the agent's first step outside its Proxmox API token into OS-root — isolated behind a narrow,
+argument-validated, adversarially-tested seam, the same discipline as the slice-4 reversibility
+gate. Phase A (read-only observe/report/watchdog, `v0.5.0-rc1`) is reused unchanged.
 
 ## What landed
 
-New package **`internal/storage`**:
-
-- **`StorageTarget` wire contract** (`internal/hub/report.go`) — the slice-3 `struct{}` stub
-  is now the full reported shape: identity (`name`/`type`/`durable_id`), `state`
-  (`attached`/`disconnected`/`decommissioned`) + `reachable`, usage (`total`/`used`/`avail`/
-  `used_fraction`), `content`, `mount_path`/`backing_device`, a `class_hint` (a rotational
-  HINT — **never** authoritative; class is hub-owned), `role` (empty until slice 10), a
-  `thin_pool` sub-object (lvmthin DATA fill), and a `smart` sub-object (`UNKNOWN` until Phase B).
-- **`durable_id` derivation** — deterministic per type, the DR-load-bearing re-attach key:
-  fs-UUID (usb/local-dir), `server:export` (nfs/cifs), `repo+fingerprint` (pbs), `vg/pool`
-  (lvmthin). Never empty — falls back to a stable store id so the hub's re-attach lookup
-  always has something.
-- **`Observer`** — joins `ListStorage` (config) + `NodeStorage` (usage/active) with
-  non-privileged host reads (`/proc/mounts`, `/dev/disk/by-uuid`, `/sys/.../rotational` +
-  `removable`) behind a `HostReader` seam. Surfaces the lvmthin **thin-pool data fill**
-  prominently (a full pool corrupts every guest on it) and warns at ≥85%.
-- **Storage watchdog** — the third daemon goroutine (alongside the hub loop + reconcile
-  engine). Fast-polls (default 8s) the *known* target set for `attached↔disconnected`
-  transitions and fires a **debounced** (default 30s) out-of-band host-report. Flags only a
-  *known* target's change (never a never-attached device), coalesces flaps (leading +
-  trailing edge). `CachingKnownTargets` rate-limits the Proxmox-derived known set;
-  `HostLiveness` does device/mount-presence (local) + a reachability dial (network).
-
-Wiring + supporting changes:
-
-- `proxmox.Storage` gained additive parse-only config fields (server/export/share/datastore/
-  fingerprint/vgname/thinpool) — the durable_id sources. The API/root fence is untouched.
-- The collector gained a `StorageObserver` seam (hub does **not** import storage); `Loop`
-  gained `SetTrigger` for the out-of-band report; the daemon runs the watchdog as a third
-  goroutine; `StorageConfig` exposes the watchdog knobs.
-- **Hub** (`felhom.eu/hub`): `hostReportPayload` parses `storage_targets`, persists them via
-  `report_json`, counts/warns on disconnected targets, and carries its half of the
-  bidirectional golden key-set test. Both repos' goldens are byte-identical.
+- **`HostOps` seam + `SudoHostOps`** — the one privileged surface: persistent mounts via
+  **systemd `.mount` units keyed by fs-UUID** (enabled, survive reboot), detach (stop+disable),
+  SMART, thin-pool metadata. Shells out via the fenced Runner (`sudo -n`, fixed arg vectors,
+  **no shell**). Tests use a fake — **no real root in the suite**. `NoopHostOps` is the
+  degrade-cleanly fallback.
+- **The argument validator (the security boundary)** — `ValidateUUID` / `ValidateMountPath`
+  (absolute, no traversal, no metacharacters) / `ValidateSMARTDevice` (raw-disk whitelist) /
+  `ValidateLVMName`, plus an in-process `systemd-escape`. **Every argument is validated before a
+  command is constructed.** The headline test is an adversarial matrix (shell metacharacters,
+  `../`, malformed) that must be refused with **zero exec** — proven both at the validators and
+  at `SudoHostOps` (a recording runner asserts no command was built).
+- **SMART** — `smartctl -a -j` parsed into `StorageTarget.smart` for **SATA and NVMe** attribute
+  sets, degrading to `UNKNOWN` on devices with no SMART. **`lvs`** fills the lvmthin thin-pool
+  **metadata** fill. Enrichment runs in `Observe` only (not the watchdog's fast `Known` path).
+- **Watchdog re-mount response** — a new `DevicePresent` probe lets the watchdog detect a known
+  mount-backed target whose **device returned but is unmounted**, and **dispatch a benign
+  by-UUID re-mount off the poll path** (goroutine, never under the lock), rate-limited to the
+  debounce window. Routed through the gate as benign (`gateRemounter` in `main.go`, keeping
+  `storage` decoupled from `reconcile`).
+- **Disk-grow executor** — `proxmox.ResizeLXC` (API, async) + a benign `ActionResize` planned
+  **grow-only**; a shrink is refused (never silently grown) at the planner and re-guarded at the
+  executor. Built + fixture-tested; unfed live.
+- **Destructive storage ops through the slice-4 gate** — `IntentForStorageMount` (benign) /
+  `IntentForStorageDestructive` (`ClassStorageWipe`/`ClassDecommission`), host/target-scoped
+  (binds on the storage **target identity** in `target.guest_id`). Reuses the existing
+  verifier/role-scoping/binding/audit. Adversarial cases: unsigned → `pending_signature`,
+  wrong-target → `binding_mismatch`, valid → accepted. Inert live.
+- **`--selftest=storage` [`-watch <dur>`]** — the live USB-runbook harness (observe pass + a
+  bounded watchdog window with re-mount live), standalone on the Proxmox host (no hub).
+- **`configs/felhom-agent.sudoers`** — the documented narrow allowlist + the agent-side fine
+  validation. New `privileged.*` config knobs for the binary paths / dirs.
 
 ## Tests
 
-`go test ./...` is green across both repos. New tests: observer build (incl. lvmthin
-thin-pool fill, USB-unplugged→disconnected, Proxmox-error fatal, mount-read-failure
-degrade), `durable_id` per-type table, watchdog transitions + debounce coalescing +
-never-attached suppression + caching TTL + stale-on-error + HostLiveness mount/network,
-collector seam (populate + error-degrade), loop out-of-band trigger, and the cross-repo
-golden contract on both sides.
+`go test ./...` green; **`go test -race ./...` green on the build server** (the watchdog
+re-mount dispatch runs off the poll path concurrently). New tests: the **validator adversarial
+matrix** (headline) + `SudoHostOps` "no-exec-on-hostile-arg"; HostOps mount/re-mount lifecycle
+against a fake; SMART parsing SATA + NVMe + unsupported; thin-pool metadata parse; the grow
+executor (grow applies, non-grow refused at the executor) + plan grow-only/shrink-refused;
+the destructive-storage gate cases (unsigned / wrong-target / valid) reusing the slice-4
+real-verifier harness; and the watchdog → re-mount path (device-return triggers, rate-limited,
+re-armed after a successful mount).
 
-**`go test -race`** must be run on the build server (192.168.0.180, has cgo/gcc); the local
-Windows toolchain lacks gcc. To run after pull: `CGO_ENABLED=1 go test -race ./...`.
+## Design decisions (flagged for the reviewer)
 
-## Out of scope (deferred)
+1. **Unit-file write mechanism.** The agent stages the `.mount` unit to an agent-owned dir
+   (`privileged.stage_dir`, default `/var/lib/felhom-agent/units`) then `sudo install -o root
+   -g root -m 0644 -- <stage> /etc/systemd/system/<unit>`. This avoids a stdin-to-root channel
+   and keeps fixed arg vectors. The sudoers entry uses path-prefix wildcards; the agent's strict
+   validation (unit name derived from a validated mountpoint; no traversal) is the fine gate, so
+   the wildcard can't be abused. Swappable behind the seam if you prefer another mechanism.
+2. **Storage-op gate scoping.** Host/target-scoped destructive ops carry the storage **target
+   name** (the operator handle / hub manifest key) in `target.guest_id`, with VMID 0. So "wipe A"
+   cannot authorize "wipe B" (binding_mismatch), exactly like the wrong-guest case.
+3. **Shrink handling.** A desired disk < actual is refused by omission at the planner (no
+   action) and re-guarded at the executor (size must start with `+`); a deliberate shrink would
+   be a signed destructive op (slice 10), never a benign reconcile grow.
 
-- **Phase B** (next, after this checkpoint validates): the host-root surface — systemd
-  `.mount` units + sudoers allowlist behind a `HostOps` seam, benign re-mount-by-UUID,
-  SMART (SATA + NVMe), the disk-grow executor (`pct resize`, grow-only), and routing
-  destructive storage ops (detach/wipe/resize-shrink) through the slice-4 gate. Built +
-  tested but inert live until slice 10 serves destructive deltas.
-- Reconcile against the hub manifest (attach new targets, enforce class/role/policy,
-  `decommissioned`) → slice 10. Backup/restore orchestration → slice 6.
+## Live validation (for project Claude / the runbook)
 
-## Validation notes for the reviewer
-
-- The reachability heuristic for dir storages: a Felhom usb/local-dir target is realized as
-  its **own** mountpoint, so reachability = it is currently an exact mount + its device node
-  exists (we deliberately do not fall through to PVE's `active` flag, which reads stale-
-  attached because the mountpoint directory survives on the root fs after an unplug). Builtin
-  `local` and network/block targets use the `active` flag. Worth confirming against the demo
-  host's actual storage set during live validation.
-- A live `--selftest=hub` against the demo host will print the populated `storage_targets`.
+Not run from here (the observer reads the *local* host's `/proc/mounts` + privileged tools, so a
+meaningful run must be **on the demo Proxmox host**, not the build server). The
+`--selftest=storage -watch` harness is the intended live USB-cycle test:
+`felhom-agent --selftest=storage -watch 3m` on `felhom-pve`, then physically unplug/replug a USB
+target and watch detect → out-of-band report → by-UUID re-mount in the logs. SMART/lvs need the
+sudoers drop-in installed (`configs/felhom-agent.sudoers`).