docs: v0.31.0 CHANGELOG + REPORT + CLAUDE banner (F9/F20-BUG2/BUG3 live-validated)

REPORT.md

@@ -1,45 +1,40 @@
-# REPORT — AGENT-001 anti-retarget wipe fix: merge + deploy (v0.30.0)
+# REPORT — live-drive disk fixes F9 + F20-BUG2 + F20-BUG3 → agent v0.31.0 (2026-06-14)
 
-**Date:** 2026-06-13 (supervised deploy session)
-**Outcome:** SUCCESS — merged to `main`, built v0.30.0, deployed to the demo Proxmox host, verified non-destructively. No rollback.
+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).
 
-## What shipped
+## 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.
 
-`v0.30.0` — AGENT-001 fix (from the 2026-06-13 deep-sweep audit). The inline customer-confirmed wipe in
-`internal/localapi/disks.go` `handleDiskFormat` previously ran `mkfs` on the caller-supplied mutable
-`/dev` path (`req.Device`); a USB re-enumeration between inspection and `mkfs` could wipe the wrong
-disk (classify→mkfs TOCTOU). Now it re-resolves the confirmed durable id → current device, requires a
-re-derived exact match, re-inspects data-bearing, and formats the **re-resolved** device — at parity
-with `signedjobs.WipeExecutor`. New `internal/localapi/wipe_reresolve.go` (`antiRetargetResolve`,
-injectable `reresolveWipe` seam); refusals → `409`, no `mkfs`. Merged from
-`fix/agent-001-wipe-durable-reresolve`.
+## 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** |
 
-## Deploy
+## 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.
 
-- Build server (192.168.0.180, go1.26.0): green gate on the branch (`build`/`vet`/`test` clean; `TestAntiRetargetResolve` incl. `retarget-mismatch-refused` PASS). Built `v0.30.0` (ldflags `-X main.version=0.30.0`).
-- Demo Proxmox host (`felhom-pve`): binary verified by sha256 at each hop; backed up the running binary to `/usr/local/bin/felhom-agent.bak-0.29.1`; installed the new binary; `systemctl restart felhom-agent.service`.
-- **Rollback target was v0.29.1** (not needed).
-- Pin check before the live run: served PVE leaf-cert SHA-256 prefix matches the pinned value (`BA:7C:99:7D:45:D0…`).
-- Scope: **agent-only**. No golden rebake, no re-provision, no controller change. Guest 9201 controller stayed online through a brief local-API blip.
+## 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.
 
-## Verification (non-destructive)
+## Rollback
+Baseline preserved at `/usr/local/bin/felhom-agent.bak-0.30.0`. Not needed — all verifications passed.
 
-| Check | Result |
-|---|---|
-| Service active + version | `felhom-agent.service` active/running; `--version` = **0.30.0**; clean startup logs (local-api on :8443, hub desired gen=2, PBS verify ok) |
-| Local API reachable (full chain) | controller→agent `/disks` proxy returns the disk list (vmid 9201); guest 9201 controller healthy on the hub |
-| Regression A — data-bearing device, NO confirmation | **REFUSED** (HTTP 409, `needs_confirmation:true`, `formatted:false`); no `mkfs` |
-| Regression B — confirmed + WRONG durable_id | **REFUSED** (HTTP 409, `formatted:false`); a non-matching confirmation did not authorize a wipe; no `mkfs` |
-| Data safety | `felhom-usb` (`/dev/sdb1`, RomM data) still mounted, `used_bytes` unchanged — untouched |
-| Blank-device benign-format | SKIPPED — no disposable blank device available on the host |
-| Happy-path destructive wipe | SKIPPED — HUMAN-only (never wipe real data to verify); covered by the unit test |
+## 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).
 
-Note: `reresolveWipe`'s post-gate refusal runs only when the gate ALLOWS (a correctly-matching
-confirmation), which on a real device leads to the destructive success path — so it is not safely
-live-triggerable and is verified by the unit test `retarget-mismatch-refused`. Live, both the
-no-confirmation (A) and wrong-confirmation (B) gate refusals confirm no un-gated destructive path.
-
-## Branch / commits
-
-- `main` merge + version bump pushed. Branch `fix/agent-001-wipe-durable-reresolve` left in place (per the runbook) until the operator confirms.
-- felhom.eu audit record (`documentation/audits/deep-sweep-2026-06-13.md`) updated: AGENT-001 → MERGED + DEPLOYED (agent v0.30.0).
+## 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.