felhom-agent/REPORT.md

# 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 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

- **`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 ./...` 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).

## Design decisions (flagged for the reviewer)

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.

## Live validation (for project Claude / the runbook)

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`).