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.

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.