felhom-controller/REPORT.md

REPORT — v0.285.0: a box keeps two controller versions (decision 56); the update clean-up's crash (R-751) — 2026-10-01

Full session report: felhom.eu/REPORT-rulings-2026-10-01.md. Evidence: felhom.eu/documentation/audits/rulings-2026-10-01/B/. Architecture read: 09 §3 decisions 30, 45, 52, 53, 56; 03-host-agent.md (the controller swap); agent internal/localapi/controllerswap.go.

What changed

• internal/stacks/controller_image_retention.go — RetainControllerImages(ControllerImageRecord): keeps every image a container uses, the running version's tag, the previous one (the swap record, selfupdate.UpdateState.RecordedPrevious; version order only when the record names none present), every version above the running one and every non-version tag; deletes older and untagged controller images by exact name/ID; nothing while the controller swaps itself. Called 3 minutes after every start (cmd/controller/main.go).
• internal/stacks/image_retention.go — R-751: RetainImagesAfterUpdate returns when the app is gone after its rescan (it dereferenced a nil stack in a goroutine; a panic there ends the process).
• internal/stacks/r650_main_test.go — both retention seams are no-ops in the package's tests.

Measured before building

The agent's swap rolls back to what /etc/felhom-controller-image named when the swap began — the running image. The controller never hands it a previous image (SwapController(ctx, target)). So the self-update's own roll-back needs only the running image; "the previous" is kept for a roll-back by hand, as ruled.

Tests and red-proofs

TestControllerRetention_* (6), TestRecordedPrevious, TestRetainImagesAfterUpdate_AppGoneDoesNotPanic. Each guard was broken on purpose and its test failed with the wrong value visible: the previous dropped from the keep switch (0.284.2 deleted), the record ignored (0.283.1 deleted), the swap check removed (deleted while swapping), the in-use check removed (an image a container uses deleted), the success check removed (a failed swap's image named as previous), the nil-stack check removed (panic). Full suite go build/vet/test ./... green; controller_gates.py --fast OK.

Live

box	controller images before → after	Docker images (system df)	how
9202	5 → 2	3.17 → 3.10 GB	bootstrap deploy (self-update is off there); previous by version order
demo-hp 9201	84 → 2	15.2 → 11.65 GB	floor 0.285.0; previous from the swap record
N100 9201	76 → 2	6.07 → 1.11 GB	floor 0.285.0; previous from the swap record

Each kept 0.285.0 (running) and 0.284.2 (previous). Every app container stayed up. Golden 0.285.0 baked and vouched.