docs: host-reboot drill + regression analysis for v0.71.0

Re-drilled the HOST reboot (felhom-pve) x2 after the follow-up challenge: both
recover all 8 drive-backed apps automatically; host-btime prefix advances so the
host path triggers processGuestBootChange; the boot-race manifests on host reboots
too (not just guest). Corrected the REPORT's 'host path unaffected' claim.

Regression analysis: the v0.68 sweep genuinely exercised the recovery (it surfaced
a real state-filter bug on the host reboot), so the agent path worked then and
regressed after (controller.yaml reset to golden no-local_api baseline on each
recreate; old MaybeIngest never re-merged). v0.70.0 config round-trip exonerated
(GET /api/config is verbatim). ensureLocalAPI closes the regression on both paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-16 16:46:20 +02:00
parent edc09bbdcb
commit 6b9603ed26
2 changed files with 43 additions and 8 deletions
+6 -1
View File
@@ -40,7 +40,12 @@ Tests (non-hollow, with pre-fix companions, red-proofed): `pollLiveBinds` waits
reports live (recreate fires) / never-live stays absent / a single early sample misses the not-yet-live reports live (recreate fires) / never-live stays absent / a single early sample misses the not-yet-live
bind; `ensureLocalAPI` merges `local_api` into an already-configured controller.yaml that lacks it bind; `ensureLocalAPI` merges `local_api` into an already-configured controller.yaml that lacks it
(companion: pre-fix MaybeIngest left it empty) and no-ops when already present. Live-accepted with (companion: pre-fix MaybeIngest left it empty) and no-ops when already present. Live-accepted with
repeated `pct reboot 9201`. **guest reboots ×2 AND host (`felhom-pve`) reboots ×2** — all 8 drive-backed apps recover automatically,
zero manual starts; the persisted boot-id now advances per boot (it had been frozen at the first-boot
value). Note: the agent path worked at the v0.68 acceptance (it surfaced a real bug there) and regressed
afterward — `controller.yaml` is reset to the golden's no-`local_api` baseline on each container recreate
and the old `MaybeIngest` never re-merged it; `ensureLocalAPI` closes that. The boot-race manifests on
host reboots too (not just guest), so both paths needed this fix.
### v0.70.0 — config-apply self-restart + geo-restriction UX fixes (2026-06-16) ### v0.70.0 — config-apply self-restart + geo-restriction UX fixes (2026-06-16)
+37 -7
View File
@@ -48,8 +48,8 @@ present + not-disconnected → no transition; settings showed `felhom-flash disc
idempotent (boot-id gated) — so a momentarily-unreachable agent right after a reboot no longer idempotent (boot-id gated) — so a momentarily-unreachable agent right after a reboot no longer
permanently strands recovery. permanently strands recovery.
The host-reboot path the earlier sweep validated is unaffected (same code path, strictly more robust); the Both reboot paths share this code, the same agent dependency, and the same boot-race — so both were
**guest-only reboot path** (never exercised by host-reboot sweeps) is now covered. broken by the regression and both are fixed here (see the regression analysis + host-reboot drill below).
## Phase C — tests (non-hollow, pre-fix companions, red-proofed) ## Phase C — tests (non-hollow, pre-fix companions, red-proofed)
@@ -71,12 +71,42 @@ the container recreate reset controller.yaml, the code re-merged `local_api`, `/
| #1 | `…7348791` | "waiting (≤2m0s) for live drive bind(s) … → live bind confirmed — recreating" ×8 | all 8 `Up` | | #1 | `…7348791` | "waiting (≤2m0s) for live drive bind(s) … → live bind confirmed — recreating" ×8 | all 8 `Up` |
| #2 | `…7367438` | same full sequence ×8 | all 8 `Up` | | #2 | `…7367438` | same full sequence ×8 | all 8 `Up` |
Both recovered audiobookshelf, calibre-web, immich-server, jellyfin, komga, radarr, romm, Both recovered all 8 drive-backed apps automatically. (komga reports its container healthcheck
paperless-webserver automatically. (komga reports its container healthcheck "unhealthy" but is up and "unhealthy" but is up and serving — a pre-existing, unrelated issue.)
serving — a pre-existing, unrelated issue.) The boot-id now advances correctly on each reboot.
**HOST reboot (re-drilled after the follow-up challenge — the guest reboots only prove the guest path):**
two `systemctl reboot` of felhom-pve itself.
| host reboot | host btime | boot-id | result |
|---|---|---|---|
| #1 | `1781545822``1781620637` | `1781620637-1443` — recreate ×8 (apps were `state=stopped`) | all 8 `Up` |
| #2 | `1781620637``1781620928` | `1781620928-1516` — recreate ×8 | all 8 `Up` |
Both recovered automatically, zero manual starts. Two findings: (a) the **host-btime prefix advances**, so
the host-reboot path triggers `processGuestBootChange` (the persisted `LastGuestBootID` now tracks each
boot — it was frozen at the first-boot value before the fix); (b) the **boot-race manifests on host
reboots too** (the gate recreated `state=stopped` apps), so the host path is **not** immune — it has the
same race and the same agent-path dependency as the guest path.
## Regression analysis — "how did the earlier (v0.68) host-reboot sweep pass?"
It genuinely passed and genuinely exercised `processGuestBootChange`:
`documentation/audits/storage-lifecycle-acceptance-2026-06-15.md` records the host reboot **surfacing a
real bug** (5 apps stayed exited because the recreate filtered on container state, fixed in v0.68.1). If
`agentClient()` had been failing then, `processGuestBootChange` would have bailed and that bug could never
have appeared. **So the agent path worked at v0.68 and regressed afterward** — "boot-id determinism was
never exercising" is false; it was.
The regression: `controller.yaml` is reset to the golden's "configured-but-no-`local_api`" baseline on
every container recreate (each deploy), and the old `MaybeIngest` returned immediately on "already
configured" → `local_api` was never re-merged → `agentClient()` → "agent not configured" → the whole
drive gate + boot recovery silently died, on **both** reboot paths. (My v0.70.0 config-apply round-trip is
**exonerated**: `GET /api/config` returns the file verbatim — `router.go:1150`, no redaction — so it
preserved `local_api`.) `ensureLocalAPI` re-merges `local_api` on every startup, closing the regression
permanently.
## Notes ## Notes
- The Komga healthcheck quirk is pre-existing and out of scope. - The Komga healthcheck quirk is pre-existing and out of scope.
- The `local_api`-merge gap likely affected the whole drive gate on this golden, not just boot recovery — - The `local_api`-merge gap affected the **whole drive gate** on this golden, not just boot recovery —
the `ensureLocalAPI` fix restores the agent path generally. `ensureLocalAPI` restores the agent path generally.