felhom-agent/REPORT.md

REPORT — live-drive disk fixes F9 + F20-BUG2 + F20-BUG3 → agent v0.31.0 (2026-06-14)

The last live-drive findings, all agent disk/localapi-side. Implemented trunk-based on main, each its own commit + regression tests; built v0.31.0, deployed to felhom-pve, and validated live on guest 9201 + the 916 GB felhom-usb. Supervised, phased; every phase verified. Controller side reflected in v0.63.0 (two passthrough fields).

Phase 0 (gate) — approach

• 9201 ran controller v0.62.0 (not v0.61.0 — stale premise); no golden template exists; build-golden.sh bakes controller 0.43.0 by default ⇒ a re-provision would REGRESS the controller + lose apps.
• F9's bind is agent runtime pct set -mpN (guestbind.go AttachBind), NOT golden-baked ⇒ no golden rebake needed. Operator-confirmed approach: attach-to-existing 9201 (no re-provision), with the bind auto-re-assert validated via a real trigger (agent restart), not unit-tests + a manual call.

Fixes (each a commit + tests)

Finding	Commit	What	Live proof
F9	4cd1d02 (+a2a76e7 reporting)	GuestBindStore + ReassertGuestBinds (startup, durable-id-matched) restore a bind a re-provision dropped; GuestAttached reporting	dropped bind → agent restart auto-re-attached (no manual call) → reboot activated → HDD app deployed, data on /dev/sdb1; guest_attached=True end-to-end
F20-BUG2	a2a76e7	shared deviceDurableID seam → /disks WipeDurableID is the gate's scheme; one id for the wipe-confirm	confirmed wipe with /api/disks's wipe_durable_id accepted (no binding_mismatch)
F20-BUG3	4777f8a	mkfs detached off baseCtx + persisted formatJob + GET /disks/format/status + RecoverFormatJob startup recovery (anti-retarget)	2 s client timeout left a ~30 s mkfs running to a clean ext4; agent restart mid-format recovered + completed clean — the live-drive corruption is gone

Verification (per phase)

• P1: go build/vet/test ./... green on the build server incl. new tests (BUG2 scheme + gate-binding; F9 re-assert restores/skips-absent/skips-bound + store persist; BUG3 detached-persist + status + recover re-runs/skips-blank/skips-unresolvable).
• P2: agent v0.31.0 active; local API reachable; 9201 controller online; AGENT-001 refusals still hold (no-confirmation → 409; wrong durable_id → 409).
• P3 / P4: as above — all live-proven on 9201 + felhom-usb.

Backward-compat + safety notes

• BUG3 keeps the synchronous format response (the live v0.62.0 controller's agentapi.FormatDisk is sync) — the detached mkfs just can't be killed by a dropped request; /disks/format/status is additive.
• The controller has no automated SSD↔HDD data-migration feature (removed in de-privileging) — F9 unblocks HDD-app deployment + data-on-HDD, which is proven; an app-data mover would be a separate feature.
• The GuestBindStore/intent durable-id is the storage-view uuid: (fs UUID), which CHANGES on a reformat — so after a wipe a drive must be re-enrolled (auto-re-assert won't match a new fs identity). Correct for the F9 re-provision case (drive unchanged); noted for the reformat edge.

Rollback

Baseline preserved at /usr/local/bin/felhom-agent.bak-0.30.0. Not needed — all verifications passed.

Follow-up queued (separate task — NOT folded into this)

Bump the golden's default controller tag (build-golden.sh:43, currently :0.43.0, 20 versions stale) to current + validate the full destroy→provision→first-boot path. That path does warrant a supervised destroy+re-provision (it's the real customer-onboarding flow).

Final demo state

Agent v0.31.0; controller v0.63.0; 9201 healthy. felhom-usb wiped clean by the BUG3 test, then re-enrolled

• re-attached (guest_attached=True); romm redeployed onto the HDD (/dev/sdb1); all apps healthy.