# REPORT — v0.42.0: agentic controller update — in-guest image swap + rollback (Phase 1)

**Repo:** `felhom-agent` · **Version:** `v0.41.0` → **`v0.42.0`** · **Date:** 2026-06-26

## What & why
The controller's old self-update (`docker compose up -d` on an in-container compose path) is dead in the
LXC architecture. Phase 1 moves the **container swap** to the host agent: the in-guest controller pulls
the target image, then the agent — external to the controller container, so it survives the controller
being killed mid-swap — rewrites `/etc/felhom-controller-image`, restarts the golden's
`felhom-controller-bootstrap.service`, verifies health, and **rolls back** if the new controller doesn't
come up. The guest is never left without a controller.

## Baseline
felhom-agent `4725396` v0.41.0 → v0.42.0. Cross-repo: felhom-controller v0.85.0 (the pull + delegate half).

## Changes
- **`internal/localapi/controllerswap.go` (new)** — `ControllerSwapper` (testable, over a `GuestExecutor`
  seam) + handlers:
  - `POST /controller/swap {image}` (`withGuest`) → **202** `{status, previous_image, target_image}`, then
    async: record previous to `/var/lib/felhom-agent/controller-swap-<vmid>.json` (crash-safety) → confirm
    the target image is present in the guest (else abort, **no swap**) → write the image file → restart the
    bootstrap unit → poll the new controller to healthy (`docker inspect`, ≤90s) → **roll back** + restart
    if not. Strict image-ref gate (`gitea.dooplex.hu/admin/felhom-controller:<semver>`); single-flight per
    guest (409).
  - `GET /controller/swap/status` → `{state, current, previous, target, error}`.
- **`internal/localapi/guestbind.go`** — `GuestBinder.GuestExec` (the single `pct exec` seam).
- **`internal/localapi/server.go`** — `ControllerSwap` option + route wiring + single-flight map.
- **`cmd/felhom-agent/main.go`** — `ControllerSwap: guestBinder`; `--selftest=controller-swap -vmid -image`
  (+ the allowlist fix — see below); version → 0.42.0.

## Tests (`internal/localapi/controllerswap_test.go`) — all green
happy swap; **rollback-on-unhealthy** (image reverted to previous + restart called ≥2×); image-absent →
no swap (no file write); running-with-no-healthcheck → healthy; bad image → 400; single-flight → 409.
- **Companion red-proof:** disabling the verify→rollback left the guest on the bad image and **failed**
  `TestControllerSwap_RollbackOnUnhealthy` (`image file = …:0.84.0 after rollback, want previous …:0.77.0`)
  → reverted → green. The rollback assertion is load-bearing.
- localapi package: 70 → **71** tests. `go build ./... && go vet ./... && go test ./...` — all `ok`.

## Live test on demo 9201 (operator-authorized; agent v0.42.0 deployed to felhom-pve)
- **Bug found live + fixed:** `--selftest=controller-swap` printed flag-usage — `controller-swap` was
  missing from `selftestFlag.Set`'s allowlist. Fixed (commit `b17d07b`), rebuilt, redeployed.
- **Swap 0.77→0.84** (`--selftest=controller-swap`, after pre-pulling 0.84): state=**done**, new controller
  `Up (healthy)`, `/etc/felhom-controller-image` = 0.84.0. (~9s to healthy.)
- **Rollback** (swap to a present-but-broken `:99.99.99` built from a controller base with `ENTRYPOINT
  /bin/false`): 90s verify timeout → **rolled back to 0.84.0 healthy**, state=failed, current=0.84.0 — the
  guest was never left without a controller.
- **E2E (real UI button)** via claude-in-chrome on `felhom.demo-felhom.eu/settings`: with the demo on 0.85.0
  (new code) and 0.85.1 pushed as latest, clicked **"Frissítés telepítése"** → the controller pulled 0.85.1
  in-guest and called the agent → agent log: swap → "new controller healthy" `0.85.1` → UI reloaded showing
  **"Sikeres (0.85.0 → 0.85.1)"**. No "docker-compose.yml nem elérhető".
- Hub reflects the version via the controller's report path: `0.84.0 → 0.85.0 → 0.85.1`.

## Observations (out of scope — not acted on)
1. **Agent host-report `controller_version` is hardcoded `""`** (`internal/hub/collect.go:180`, "slice 8
   fills" — never done). So the hub's `guests.controller_version` stays empty; the controller's own report
   path carries the real version (verified `0.85.1`). Pre-existing, untouched here.
2. **Agent-restart-mid-swap auto-resume:** the swap records previous to a state file (so a manual/operator
   rollback is possible), but the agent does not yet auto-reconcile a `swapping` state file on its own
   restart. The common failure (controller killed mid-swap) is fully handled; agent-crash-mid-swap leaves a
   recoverable record. A startup reconcile is a candidate follow-up.
3. **Golden freshness:** the golden bakes controller 0.77.0; a golden rebuild at current is wanted so new
   provisions start current (independent of this feature).

## Commits
- `6f14b66` — v0.42.0 swap + rollback + tests.
- `b17d07b` — fix: register `controller-swap` in the `--selftest` allowlist (found live).

No secrets in any committed file; the registry token used for the live pre-pull stayed on the host
(stdin login, logged out).