felhom-agent/REPORT.md

REPORT — Impl-2a: raw-device discovery + registry-sourced drive tracking (agent v0.55.0)

Date: 2026-07-01 · Repo: felhom-agent (backend only) · Class: Risky/supervised (re-sources the drive health/detach path — a regression re-creates the 3b-fix false-detach class). No mkfs here.

Impl-2a of the drive-enrollment series (SPIKE-drive-enrollment §SQ1/SQ4/SQ5). Makes raw (non-PVE-storage) drives discoverable for enrollment AND health-tracked without being a PVE storage. The controller wizard (Impl-2b) + the shared-box operator gate (Impl-3) are separate.

1. Baseline → target

felhom-agent 5209830 (v0.54.0) → v0.55.0.

2. Files changed + commit

• internal/storage/candidates.go (new) — ListCandidateDisks (enumerate /sys/block whole-disks → Impl-1 deviceUnclaimed → probe: size/model/FS/data-bearing/durable-id; mountable ext4/xfs split).
• internal/storage/registry_known.go (new) — RegistryKnownTargets (watchdog Known() from intent registry + Felhom .mount units) + ReconcileExistingDrives (idempotent migration).
• internal/localapi/disks.go — GET /disks/candidates handler + DiskOps.ListCandidateDisks; handleDisks additive+deduped registry-drive union. internal/localapi/server.go — route + DriveTargets option.
• cmd/felhom-agent/main.go — swap watchdog KnownTargets source → RegistryKnownTargets; run the migration at start; thread driveKnown into the local-API.
• Tests: internal/storage/registry_known_test.go, internal/localapi/disks_candidates_test.go, disks_test.go (fake). CHANGELOG.md, README.md, version.
• Commit 91f6a26 on main (parent 066e3bf). Watchdog/HostLiveness/Remounter unchanged.

3. Green gate

go build ./..., go vet ./..., go test ./... — clean (local + build server 180).

4. Tests + red-proof

• TestRegistryKnownTargets: enrolled drive tracked; new-intent excluded; ejected still tracked; non-Felhom unit ignored; KnownTarget fields correct (DurableID uuid:<UUID>, MountBacked, MountPath).
• TestRegistryVsObserve_RedProof: with NO PVE storage, the OLD Observer.Known() returns empty (drive invisible — the 3b-fix class) while RegistryKnownTargets.Known() tracks it. Proves the decoupling adds the coverage.
• TestReconcileExistingDrives_Idempotent: a mounted Felhom-unit drive → enrolled; re-run no-op; an UNMOUNTED unit is NOT auto-migrated.
• TestDiskCandidates_Split: initialize = all unclaimed; attach = mountable-FS subset. (Candidate fail-safe carries through Impl-1's classifyClaim, unit-tested there.)

5. Deploy + live validation (felhom-pve, agent v0.55.0)

Published Gitea felhom-agent/0.55.0 (sha b8122511460413489ae0f5323ad34ebeaa00cfd091e91cba06f00398128bb577); deployed (backup .bak-0.54.0, restart). All four scenarios proven:

Scenario	Result
C — no false detach	✅ post-deploy: 5 storages (Observe intact), both drives mounted, both intents enrolled, no detach/error in the journal, 9201 running. Migration a no-op (drives already enrolled).
B — registry-sourced tracking (definitive)	✅ controlled systemctl stop mnt-felhom\x2dflash.mount (app-less drive) → watchdog detected felhom-flash attached→disconnected (durable_id=uuid:81a26531… = the registry key) → self-healed (re-mounting enrolled drive → gate benign → ensured mount → remounted in 5s). Proves the Known set is registry+units-sourced, NOT silently empty.
A — discovery	✅ GET /disks/candidates (real local-API endpoint) returns only /dev/sdd (size 63.8G, model, fstype ext4, mountable, durable_id uuid:950d8ad0…) under both initialize and attach; sda/sdb/sdc excluded.
D — fail-safe	✅ carried through the reused Impl-1 filter (classifyClaim exclude-on-error; unit-tested).

6. NOT yet done

• Impl-2b: the controller wizard rewiring (consume GET /disks/candidates) + the enroll orchestration UI + a live end-to-end raw enrollment (format via the Impl-1 guarded path → mount → bind → intent). Impl-3: the shared-box operator gate for self-serve format.
• The controller settings storage-section screenshot for Scenario C (agent-side evidence above is definitive; the UI still shows the drives via Observe dir-storages + the registry union).

7. Observations

• The existing drives are still PVE dir-storages (not removed — later cleanup, per the spike). They now ALSO track via the registry; /disks dedups by mount path (no doubles). Retiring the dir-storages is optional and out of scope here.
• /dev/sdd (the Impl-1 throwaway, now ext4) is a live discovery candidate; unmounted, not enrolled.