felhom-agent/REPORT.md

# REPORT — Slice 5 Phase A: storage observe + report + watchdog (v0.5.0-rc1) (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.

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

## 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 -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 ./...`.

## Out of scope (deferred)

- **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.

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