Wait out the Home Assistant landing page before reading onboarding

[eschultz]

🔍 Summary

On a fresh Home Assistant OS install, the onboarding hook records "Onboarding state unavailable (HTTP 401)" where it should record the onboarding state. The lab run for #26 and eshtek/hexos-platform#2105 on 2026-10-10 (fresh HAOS, Core 2026.10.1) caught it: the hook ran about 25 s after readiness, while the Supervisor's landing page ("Preparing Home Assistant") was still serving the guest. The landing page answers / with 200, so the reachability check passes, and it answers every /api/ path with a bare 401 (home-assistant/landingpage, main.go, unchanged since 2020). Core came up a few minutes later and served /api/onboarding with 200. The old port 8123 hits the same landing page, so the bug predates #26.

Core never answers the status view with 401. The view takes no authentication, and Core's HTTP server starts only after the frontend is set up, which depends on onboarding. A bare 401 therefore means Core is not up yet.

Changes, all in home-assistant-os/haos_setup.ts:

• After the front page answers, the hook reads /api/onboarding every 10 s for as long as the answer is a bare 401 or there is no answer (the gap between the landing page stopping and Core listening). Any other answer is described as before.
• The wait ends 540 s after the run started, which leaves the outcome recorded inside the declaration's 600 s timeout. If the landing page is still up at that point, the checkpoint is skipped with "Home Assistant is still preparing its first start". If the guest never answered the read, the message says it "did not answer the status read".
• A 401 that carries WWW-Authenticate comes from a proxy asking for credentials, so it is recorded at once, as before.
• While the hook waits, the onboarding checkpoint reads "Waiting for Home Assistant to finish preparing" and each pass moves the progress bar from 50 toward 95. The platform refuses that write once it has ended the attempt (cancel or timeout), which stops the wait at the next pass.
• A status read that gets no answer no longer fails the attempt. The hook waits through it, logs each distinct error once, and skips the checkpoint if the guest stays silent for the whole budget.
• The status read passes the platform's default 10 s timeout explicitly, because the budget counts it. The wait is timed with performance.now(), so a wall-clock step on the box cannot stretch it past the timeout.

⚠️ Known limits

• The 540 s budget matches the 600 s timeout in home-assistant-os.json by hand. The tests read the declared timeout from the JSON and fail if the hook can outlast it, so lowering the timeout without the budget breaks CI.
• If Core takes longer than about nine minutes to start on first boot (a slow download of the Core image), the hook ends with "still preparing" and the user checks onboarding in the browser, as they do today.

✅ Test plan

• Reproduced first: the new landing-page tests failed on the unchanged hook with the message the lab recorded, "Onboarding state unavailable (HTTP 401)".
• bun run test-hooks: 92 pass. The HAOS file has 23 tests, 10 of them new.
• Broke each rule one at a time, and a test failed for each: a 401 not treated as the landing page, WWW-Authenticate ignored, no progress write, the last error winning over the last answer, every error logged, errors not waited through, a budget past the timeout, the budget measured from after the front page, no waiting message, and the read timeout dropped.
• bun run validate: 29 blueprints and 32 apps, 0 errors.
• bun run typecheck: the same 5 errors in the vendored vm-surfaces.ts as on staging, none from this PR.
• Lab box on TrueNAS 26.0.0-BETA.3, dev main synced from this branch, two fresh HAOS installs with the hook opted in. Both times the landing page was still up when the hook started: port 80 redirected to 8123, which answered /api/onboarding with 401. The hook recorded "Home Assistant answered at http://:8123/", waited, and recorded "Fresh install: finish onboarding in the browser (4 of 4 steps remain)" once Core answered on port 80. The setup tasks took 91 s and 85 s. The second install ran the final revision: during the wait the checkpoint read "Waiting for Home Assistant to finish preparing" and progress went from 50 to 54. On 2026-10-10 the same box, running the hook from staging, recorded the 401.
• After merge: sync the catalog to staging and prod. The platform needs no change.