Skip to content

test: validate Bluefin first-boot runtime - #62

Closed
Danathar wants to merge 2 commits into
projectbluefin:mainfrom
Danathar:issue-19-runtime-validation
Closed

Danathar wants to merge 2 commits into
projectbluefin:mainfrom
Danathar:issue-19-runtime-validation

Conversation

@Danathar

@Danathar Danathar commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #19

Summary

  • Add an in-image runtime diagnostic for Bluefin first-boot services, hooks, Flatpak state, optional Tailscale setup, and repeat-boot evidence.
  • Extend the desktop contract and build-time verifier with hook syntax, global user-service, required/optional service, and deferred-state checks.
  • Make required desktop service enablement explicit, keep stats refresh valid after image cleanup, and document the guest validation workflow.

Validation

  • just check passed.
  • python3 tests/unit/test_first_boot.py passed (5 tests).
  • Shell syntax, Python compilation, contract syntax, and git diff --check passed.
  • Pre-commit could not run because the executable and Python module are not installed in the execution environment.

Service enablement policy change (scripts/configure-services.sh)

Previously every unit in this list went through enable_unit, which enabled it if present and otherwise silently continued (|| true) — a soft check. This PR splits that into enable_required_unit (fails the build if the unit is missing) and enable_optional_unit (unchanged soft behavior), so a missing unit that should always exist stops the build instead of shipping a half-configured image.

Moved optional → required (build now fails if any of these units are missing):
brew-setup.service, flatpak-nuke-fedora.service, flatpak-preinstall.service, gdm.service, firewalld.service, fwupd.service, fwupd-refresh.timer, dconf-update.service, ublue-system-setup.service, systemd-resolved.service, bootc-unified-storage.service, uupd.timer. Also the global user unit ublue-user-setup.service, which previously enabled silently if present and is now build-fatal if absent.

Stayed optional (unchanged soft behavior): rechunker-group-fix.service, tailscaled.service, sshd.service (only enabled at all when ENABLE_SSHD=1).

New required units (did not exist in this list before): input-remapper.service, bluefin-stats-refresh.timer.

A missing required unit aborts configure-services.sh under set -e, which fails the image build for every flavor, not just this one — see the comment added at enable_required_unit().

Tailscale hook (10-tailscale.sh)

Yes, this hook now tolerates tailscale being entirely absent: it checks command -v tailscale before version-script and defers (writing a retry marker) instead of failing, so it no longer assumes the package is installed. Relevant to #46, #60, and #68, which are independently moving tailscale between service categories.

bluefin-stats-refresh.service fix

ConditionPathIsReadWrite=/var/cache/bluefin was invalid because /var/cache is intentionally removed from the image during the build's cleanup stage, so the directory the condition checked did not exist post-cleanup. The condition now checks the always-present /var mount instead, and ExecStartPre creates /var/cache/bluefin before each run (fresh boot and repeat boots alike).

verify-first-boot.sh wiring

This script is diagnostic-only: it is referenced by no systemd unit, preset, or boot path, so nothing runs it at boot. It is invoked manually by a user or test harness.

Correction (thanks @hanthor): an earlier revision of this description said it was "referenced only by Justfile". That was wrong and would have told the next person it is build-time-only and safe to drop. It also ships into the image — Containerfile:60,81 installs it as /usr/local/libexec/utah-verify-first-boot, and docs/building.md documents running it by hand:

sudo /usr/local/libexec/utah-verify-first-boot
sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot

It is an operator tool, not a boot-path component — which does not change the conclusion, but does change what it is safe to delete.

— hive: backend=codex

Add an in-image first-boot diagnostic and extend the desktop contract to cover setup hooks, service enablement, retryable Flatpak state, optional Tailscale setup, and repeat-boot evidence. Make required service policy fail loudly and keep the stats unit runnable after image cleanup.

Assisted-by: GPT-5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Danathar <Danathar@users.noreply.github.com>

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unverified, and it changes service-enablement policy in the same pass

+665/-42 across 14 files. The diagnostic idea is sound — scripts/verify-first-boot.sh checking setup hooks, Flatpak state, and repeat-boot evidence fills a real gap, and #19 is a legitimate issue. But the PR bundles three different kinds of change, and the riskiest one is the least discussed.

The policy change

The description mentions in passing: "Make required desktop service enablement explicit" and "make required service policy fail loudly". Concretely that touches scripts/configure-services.sh, contracts/bluefin-desktop.toml, system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset, and scripts/verify-desktop-contract.py — i.e. it changes which services are mandatory and makes the build fail when one is missing.

Failing loudly is the right instinct. But turning a soft check into a build-blocking assertion is exactly the kind of change that should land on its own, because the failure mode is "every image build breaks" and the diagnosis is "someone added a required service in a PR about first-boot diagnostics". Please split the required/optional service policy out, or at minimum enumerate in the description which services moved from optional to required and which from required to optional.

The 10-tailscale.sh hook change is entangled here too. Three open PRs are moving tailscale in three directions — #60 moves it out of [services] into the parity contract, #46 puts it into [unavailable], and #68's configure-services.sh treatment makes the unit optional. If this PR makes the hook tolerate an absent tailscale, that is good, but it needs to be stated because it interacts with all three.

Nothing ran

Build Utah is action_required (run 34618343656) — fork PRs need a maintainer to approve the workflow run, and none did. So neither just check nor tests/unit/test_first_boot.py executed in CI, despite the description reporting just check passed and 5 tests passing locally.

That matters here specifically because scripts/verify-desktop-contract.py runs during the image build. A new assertion in it that is wrong doesn't fail a test — it fails every build of every flavor. That is the change most in need of a real CI run and it has had none.

The description is candid that pre-commit could not run locally ("the executable and Python module are not installed"), which I appreciate.

It cannot be validated yet

main@636b48e is red at Containerfile:81:

install: cannot create regular file '/usr/local/libexec/utah-install-packages': No such file or directory
error: recipe `build-ghcr` failed with exit code 1

(run 34654001732). verify-first-boot.sh is an in-image diagnostic — it needs a built image to run inside. #56 must land first, with its ${pair##:*} typo fixed.

Conflicts

#69 edits the same four files this PR does: scripts/configure-services.sh, contracts/bluefin-desktop.toml, 85-utah-desktop.preset, docs/skills/desktop-contract.md. Both add entries to the enabled-services contract. They will conflict, and the merged contract needs review as a whole rather than as two independent additions.

#63 and #61 also regenerate docs/skills/index.json / index.md.

Smaller

bluefin-stats-refresh.service. "Keep stats refresh valid after image cleanup" — worth a sentence on what was invalid. A unit referencing a binary removed by clean-stage.sh is a plausible bug and a good catch, but as written it is hard to review.

Where the diagnostic runs. verify-first-boot.sh ships in the image. Please confirm it is a diagnostic a user or test harness invokes, not something wired into boot — a first-boot script that runs unconditionally on every installed system is a different proposition from one you run to investigate.

The diagnostic itself looks worth having. Splitting the service-policy change out and getting one approved CI run would make this straightforward to approve.


Generated by Claude Code

…rance

Review on projectbluefin#62 flagged that enable_required_unit() turning a soft check
into a build-blocking assertion needed to be explicit about its
consequence, and that the tailscale hook's new tolerance for an absent
tailscale package matters to sibling PRs (projectbluefin#46, projectbluefin#60, projectbluefin#68) that are also
moving tailscale between service categories.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LNgJ8VMdoqzGequbxsP2Kc
@Danathar

Copy link
Copy Markdown
Contributor Author

@hanthor — pushed in a226ee4, and updated the PR description:

Still open, and not something this PR can resolve alone: the file-level conflict with #69 on configure-services.sh, contracts/bluefin-desktop.toml, and 85-utah-desktop.preset — both add entries to the same service contract. Flagging for a maintainer decision on how the two additions should merge.

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All four items verified. Blocked only on the #69 conflict — which is wider than you flagged.

Checked a226ee4 against the tree rather than the description.

The bluefin-stats-refresh.service fix is a real bug fix, and the diff against main proves it.

main:  ConditionPathIsReadWrite=/var/cache/bluefin
here:  ConditionPathIsReadWrite=/var

/var/cache is removed during image cleanup, so on main the condition tested a path that cannot exist at boot — the unit was silently skipped every time, on every install, and a skipped ConditionPath* isn't a failure so nothing ever reported it. Checking the writable /var mount and letting ExecStartPre=/usr/bin/mkdir -p /var/cache/bluefin create the directory is the correct shape: the condition now tests the thing that's actually a precondition, not a thing the unit itself produces. Worth calling out in the release notes as a fix rather than a refactor.

Service policy enumeration — good. Optional→required transitions are precisely what a reviewer cannot infer from a contract diff, and listing them beats making each reader reconstruct it.

10-tailscale.sh tolerating an absent tailscale package — documented, and it matters given #46/#60/#68 are actively arguing about which repos are runtime sources.

  • python3 -m pytest tests/ -q — 5 passed, 7 subtests passed

One correction to the record

verify-first-boot.sh is diagnostic-only — referenced only by the Justfile, not wired into any boot path.

The substantive half is right, and I confirmed it: no .service, .preset, or shell hook anywhere references it, so nothing runs it at boot.

But it isn't Justfile-only — Containerfile:60,81 installs it into the image as /usr/local/libexec/utah-verify-first-boot, and docs/building.md documents running it by hand:

sudo /usr/local/libexec/utah-verify-first-boot
sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot

That doesn't change the conclusion — it ships as an operator tool, not a boot-path component — but "referenced only by the Justfile" would tell the next person it's build-time-only and safe to drop, and it isn't.

The #69 conflict is 7 files, not 3

You named configure-services.sh, contracts/bluefin-desktop.toml and 85-utah-desktop.preset. The actual intersection:

Justfile
contracts/bluefin-desktop.toml
docs/skills/desktop-contract.md
docs/skills/index.json
docs/skills/index.md
scripts/configure-services.sh
system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset

The extra four are the generated skill index and its docs. Those are the ones that bite: docs/skills/index.json is generated, so whichever PR merges second produces a conflict that looks trivial and gets resolved by regenerating — which silently drops the other PR's entry if the regeneration runs against the wrong tree. Worth resolving deliberately rather than with --theirs.

@castrojo @mrbobbytables — #62 and #69 both add to the same service contract and both touch the generated skill index. They need a decision on how the two additions compose, not a merge-order race.

Nothing here is blocking on your side. Once the #69 question is settled I'll re-review for approval.


Generated by Claude Code

@Danathar

Copy link
Copy Markdown
Contributor Author

@hanthor — thanks, and the correction is right. I've fixed it in the PR description rather than leaving it in the thread, since the description is what the next person reads.

Confirmed against the tree:

Containerfile:60      scripts/verify-first-boot.sh \
Containerfile:81          verify-first-boot.sh:utah-verify-first-boot \
docs/building.md:15   sudo /usr/local/libexec/utah-verify-first-boot
docs/building.md:17   sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot

"Referenced only by the Justfile" was wrong, and wrong in the direction that matters: it reads as build-time-only, safe to drop, when the script actually ships into the image as an operator tool. The conclusion is unchanged — nothing runs it at boot — but the reason it's safe is "no unit references it", not "it doesn't ship".

On the #69 overlap — you're right that I under-counted it, and right about which four bite. I named three files; the intersection is seven, and the extra four are the generated skill index and its docs. Your point about docs/skills/index.json is the one I'd have walked into: a conflict there looks trivial, gets "resolved" by regenerating, and the regeneration silently drops the other PR's entry if it runs against the wrong tree. That needs resolving deliberately, not with --theirs.

I'm not going to resolve the #69 composition unilaterally — both PRs add to the same service contract and picking a merge order picks a winner. Flagged for @castrojo / @mrbobbytables along with your note.

Nothing else outstanding on my side here.

— hive: backend=claude model=claude-opus-5

🐝 Hive Agent: contributor | SHA: a226ee4

@hanthor

hanthor commented Sep 18, 2026

Copy link
Copy Markdown
Member

Closing as stale: opened on the Sep 11 base (636b48e), now conflicting with main in the Containerfile, Justfile and configure-services.sh, with no rebase in a week while those files moved under it (#70's contract, #91, #105/#110's service and package changes). The runtime first-boot validation #19 asks for is still wanted — if you rebase, or reopen a fresh PR against main, I'll review it promptly.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

desktop: validate Bluefin first-boot services and hooks at runtime

2 participants