felhom-controller/REPORT.md

REPORT — controller v0.261.0: the box stops updating itself out from under an app update

R-608 (P2) + R-609 (P3). Base d0d431b42b51 (v0.260.0) → v0.261.0 (811f75736ec8). MinAgent 0.131.0 unchanged. Architecture read first and named: felhom.eu/documentation/architecture/09-update-architecture.md §3 (the ten decisions), §3b (the seven open questions), §6.1 (the guarded update's phases), §6.2.

Not done / changed from the brief — first, because it is the point

item	state
Part 2 (the lock, the reason on the wire, the red-proofs)	done in full
Part 0 (floor to 0.260.0)	done — see felhom.eu/REPORT.md
Parts 1, 3, 4	not in this repo — they are measurements and documents; see felhom.eu
the caller script's ≤150-line budget	167 lines. Over by 17. Not trimmed: the excess is the same_major rule and its comment, and shortening it would have meant a terser rule, which is the one thing in that file that must be readable. Named rather than hidden.

What was wrong

The controller updates itself — daily at self_update.auto_update_time, default 04:30 (config/config.go L422, scheduled cmd/controller/main.go ~L1365), and again from MaybeAutoUpdate after any hub report once a floor sits above the box, so at any hour. That swap restarts the controller container, which is the supervisor of a running app update. 09 §3b Q1 proposes 02:30–05:00 for automatic app updates. It contains 04:30.

What the brief got wrong, measured rather than assumed

The gap was narrower than "the whole update", and that matters for where the fix goes. The brief said the self-updater's only busy gate is backupRunning and left open whether that covers the update's backing-up phase. It does: RunAppBackupNow calls acquireRunning (internal/backup/update_guard.go:333), so backupMgr.IsRunning() was already true for that one phase. It was false for checking, safety-dump, pinning, pulling, starting and verifying — and the last two are exactly where the new version may already have touched the customer's data. Everything else the brief asserted about the three call sites and the wiring held at source.

What shipped

• stacks.Manager.AnyUpdating() — is a guarded update in flight for ANY app.
• Updater.SetAppUpdatingCheck — a deliberate sibling of SetBackupRunningCheck, consulted in the same three places (the dry run, TriggerUpdate, maybeAutoUpdate). One busy-gate pattern in that file, not two.
• Manager.SetSelfUpdatingCheck — the reverse. UpdatePreflight refuses self_updating.
• Both halves wired in main.go, the only place holding both objects. stacks never imports selfupdate — the dependency is inverted with a plain callback rather than by widening UpdateGuards, which is the backup side's interface and has nothing to do with this.
• Two sentences, born as bundle keys, in both bundles, registered in i18n_go_keys.json.
• data.reason on every update refusal (R-609) — additive; the sentence is unchanged, so no page moves. busy/updating/deploying/migrating/self_updating are transient; held/downgrade terminal; memory/disk/no_backup need a person.

The two things the tests found that reading did not

1. The router refuses a HELD app on its own line, BEFORE UpdatePreflight (api/router.go ~L601). Without a second edit, held — the single reason an unattended caller most needs — would have been the one missing from the wire, and such a caller would press a terminally-refused button on every pass for ever. Found while writing the table, not while reading the code.
2. The lock must not latch. Stack.Updating is cleared on done, failed and held, so a held app does not block the controller's own updates — including the release that might fix whatever held it. A latching gate would be a worse failure than the one prevented, and silent for weeks. TestR608_LockReleasesAfterHold is a consequence test and exists for that alone.

Red-proofs — five, each SEEN to fail

#	the mutation	what failed
1	AnyUpdating always false	TestR608_AnyUpdatingSeesAnUpdateInFlight — the gate reads false with an update in flight
2	AnyUpdating true for a held app too	TestR608_LockReleasesAfterHold — "a HELD app must not hold the self-update lock for ever"
3	delete the preflight's self_updating block	TestR608_PreflightRefuses… — "while the controller swaps itself the app update must be REFUSED"
4	delete TriggerUpdate's app-update block	TestR608_TriggerUpdateRefused… — the swap proceeds over a live app update
5	drop Data from the refusal	TestR609_EveryRefusalCarriesItsReason — reason = "" on no_backup and self_updating

Green gate

go build ./... && go vet ./... && go test ./... — all green, full suite. controller_gates.py --fast — 17 gates OK; go-parity convicted the two new keys first and was satisfied properly by registering both as BORN-AS-KEYS with the test that pins each. No --no-verify; the pre-push hook ran and passed.

Image gitea.dooplex.hu/admin/felhom-controller:0.261.0 built and pushed. Deployed to guest 9202 (the scratch guest) ONLY — the demo boxes and the fleet stay on 0.260.0. The floor is NOT raised to 0.261.0; that is a separate ask for the operator, recorded in felhom.eu/STATUS.md.

The measurements this release was built for — the three power cuts and the unattended night — are in felhom.eu/documentation/audits/update-arc-gaps-2026-09-21/.