felhom-controller/REPORT.md

# REPORT — v0.86.0: Phase 2 managed updates — floor-driven auto-update

**Repo:** `felhom-controller` · **Version:** `v0.85.1` → **`v0.86.0`** · **Date:** 2026-06-27

## Why
Phase 1 shipped an opt-in "update to latest" button. Phase 2 adds the **managed default**: the operator
sets a per-customer **minimum controller version** (FLOOR; defaults to a global floor), and any box below
it **auto-updates to the floor** on its next report — no customer click. Latest stays the customer's
manual opt-in; the floor is the auto-target (never latest).

## Files changed
- `internal/report/pusher.go` — `PushResponse` += `min_controller_version`, `latest_version`. The pusher
  already parsed the ACK (for `customer_blocked`) and exposed `OnPushResponse`; extended, not a new path.
  *(The task spec pointed at `notify/notifier.go`'s `io.Discard` response-drops, but the real periodic
  report sender is `pusher.go` — it already had the seam, so the floor is read there.)*
- `cmd/controller/main.go` — the existing `OnPushResponse` now also `updater.SetFloor(...)` +
  `updater.MaybeAutoUpdate()`. Rides the existing report cycle; no new timer/endpoint.
- `internal/selfupdate/updater.go` — `floor`/`lastAutoFloorAttempt` state; `SetFloor`/`GetFloor`;
  `MaybeAutoUpdate()` reusing **Phase 1 `performUpdate`** (pull → agent `SwapController` → rollback) with
  the floor as target (`initiatedBy="auto-floor"`).
- `internal/web/handlers.go` + `templates/settings.html` — Hungarian floor display + auto restart-poll.

## Gating (MaybeAutoUpdate) — auto-target is the FLOOR, never latest
No-op unless ALL: floor set; current parses (not dev); **current < floor** (at/above = nothing — does
NOT chase latest, Scenario B); agent wired; no backup running; no swap in flight; not already attempted
this floor (in-process flag **and** persisted UpdateState — no flapping across the report cycle or a
restart); floor is **pullable** (floor ≤ latest available in the registry; floor > latest → warn + do
nothing, no chasing a non-existent image). Rollback on failure is Phase 1's (the agent) — not duplicated.

## Tests — `go build ./... && go vet ./... && go test ./...` green
`internal/selfupdate/floor_test.go`:
- below-floor → updates to the **floor** ref (fake agent asserts `…:0.87.0`, not latest) — Scenario A
- at/above floor → no pull, no swap (latest far ahead is irrelevant) — Scenario B
- no floor → inert — Scenario D
- floor > latest available → no pull/swap + warning — Rule 2
- no-flap → exactly one swap across repeated reconciles — Rule 4
- raised floor (override/global bump) honored on next reconcile — Scenario C/E
- dev current / no agent → no-op
- **Companion red-proof (verified):** forcing `MaybeAutoUpdate` to always no-op →
  `TestMaybeAutoUpdate_BelowFloor_UpdatesToFloor` FAILS (pulled "", 0 swaps) → restored → green.

## Live test — floor auto-update 0.86.0 → 0.87.0 on demo 9201 — PASS

**Sequence (all live on `felhom-pve` guest 9201 + hub on k3s):**
1. Built/pushed hub `0.15.0` + controller `0.86.0`; deployed hub via ArgoCD.
2. **Dogfood deploy (Phase 1 still works):** triggered the controller's self-update via the exact
   endpoint the Settings button invokes (`POST /api/selfupdate/update`, hub-key bearer, in-guest) → the
   demo went **0.85.1 → 0.86.0** (in-guest pull → agent swap → healthy). This put the floor-reading code
   on the box.
3. Built/pushed a trivial **0.87.0** (version-only) as the auto-update target.
4. **Set the floor:** global floor → **0.87.0** via `DEFAULT_MIN_CONTROLLER_VERSION` on the hub (the
   implemented global-floor mechanism; the operator-UI form is password-gated, which I'm not permitted to
   submit — the form handlers are covered by hub unit/render tests). Hub logged
   `Default controller-version floor: 0.87.0`.
5. **Auto-update fired (Scenario A):** on the demo's next report (forced immediately by restarting the
   controller, which performs a startup hub report) the ACK carried `min_controller_version=0.87.0`; the
   controller saw current `0.86.0 < 0.87.0` and **auto-updated to 0.87.0 with no click**.
   - Proof (`/api/selfupdate/status` `last_state`): `previous_version=0.86.0`, `target_version=0.87.0`,
     `status=success`, **`initiated_by="auto-floor"`**, completed 10:15:42Z.
   - Host-side: container `…:0.87.0 Up (healthy)`; `/etc/felhom-controller-image = 0.87.0`.
   - Hub-side: `reports.controller_version` for demo-felhom = **0.87.0** (verified via sqlite on the
     copied DB; temp copy deleted afterwards).
6. **No flap / at-or-above floor (Scenario B):** forced another report with the box now at 0.87.0
   (== floor) → **no second update**: image stayed `…:0.87.0` healthy, and `last_state.initiated_at`
   was **unchanged** (still 10:15:37Z). The floor does not re-trigger when at/above.

**End state (left consistent, per spec):** demo 9201 at **0.87.0**; global floor **0.87.0** persisted in
`manifests/hub.yaml` (`DEFAULT_MIN_CONTROLLER_VERSION`), hub Synced/Healthy. Only demo-felhom reports
(peti-felhom is config-only) so the global floor has no other effect.

## What was NOT done
- No agent binary change (reuses Phase 1 swap). The customer latest-only button is untouched. No new
  floor-polling endpoint/timer. No auto-update loop / while a swap is in flight.