omarchy-mac-boot: deterministic m1n1 device-tree order, first boot via #528

[maralcbr]

Ticket 09 of the Apple Silicon convergence plan: the omarchy-mac-boot source changes its notes ask for. The recipe is omacom/omarchy-pkgs#637, which pins this branch's head until a quattro-upstream merge commit exists.

Base is now quattro-upstream, which has #527 and #528. quattro-upstream is merged into this branch.

• Deterministic boot.bin. update-m1n1 concatenates device trees through an unquoted glob, so boot.bin followed the locale of whatever ran the pacman transaction. On the M2 Max it was in en_US order, and checks that rebuilt it in C order reported a mismatch. The package now ships /etc/default/update-m1n1 exporting LC_ALL=C.
• The boot check compares the device-tree set. When the C-order rebuild differs, the check splits the ESP image on its flattened device tree headers, requires exactly the expected device trees, each as often, rebuilds in that order and compares again. This replaces the session-locale rebuild, so an image written before the pin no longer fails from a session in another locale.
• Deferred hardware setup. First boot runs omarchy-provision-hardware once the keyring exists, instead of sourcing the Limine leaf itself, and omarchy-provision-hardware.service waits for first boot. mac-first-boot/deferred-steps stays the initrd's conversion token. A fresh image (token present) now also needs Defer image hardware setup to the Mac's first boot #528's build manifest, /var/lib/omarchy/image/target (or target.booted on a retry); without it first boot stops rather than finishing with no hardware setup and GRUB still in charge. The image builder has to write it (tickets 21/23/24). A reset root has no token and is unaffected.

Testing

• packages/omarchy-mac/boot/test/all in an Arch Linux ARM container as a non-root user: all 97 checks pass. New cases: update-m1n1's own steps under a real en_US.UTF-8 locale (without the file the caller's collation wins; with it C wins under LANG or LC_ALL; the file sets no update-m1n1 input), the boot check accepting the expected device trees in any order and refusing a duplicate, a missing or foreign device tree or a different tail, the first-boot hand-off and drop-in, and a fresh image without a manifest. Each new check fails against the previous code (mutation runs).
• Runtime suite (test/all) as a non-root user in the same container: 2 of 314 files fail (hermes-remove-test.sh, and system-sleep-ownership-migration-test.sh, which is flaky), both in Run the shell suites in CI for quattro-upstream #518's list. Land #503 with the review fixes and the gap-audit merge blockers #527's head fails the same two plus desktop-entry-launch-test.sh.
• Recipe build, ownership and pacman upgrade checks: Add omarchy-mac-boot for aarch64 edge omarchy-pkgs#637.
• Not done: hardware. Cold boots on the M2 Max and M1 Pro are tickets 25 and 26.

Follow-up for #528: first boot runs omarchy-provision-hardware while this drop-in holds the service's own start job queued, and its disarm deletes the unit file and reloads systemd, so the journal logs a failed start job for a unit that no longer exists. Nothing is degraded. Removing only the wants link (keeping the unit, whose ConditionPathExists= then skips it) would avoid it; that is #528's code, so it is not changed here.

Second review: an independent review found that first boot would finish a fresh image with no hardware setup when the builder wrote no manifest (fixed, with a test), and the #528 follow-up above. The device-tree walk (truncated, garbage and oversized images, duplicate-content trees, a symlinked m1n1), the locale pin under sh and the unit ordering held up. The second-model review could not run today (usage limit) and still has to run before merge.

Update (2026-09-25, Brisbane): merged #527's current head (a279bffdc) into this branch. The only conflict was docs/file-layout.md; both paragraphs are kept, in quattro-upstream's order. Boot package suite: 97 checks pass. Runtime test/all as a non-root user in an Arch Linux ARM container: only hermes-remove-test.sh fails (known). The base fails that plus the flaky system-sleep-ownership-migration-test.sh. The recipe, omacom/omarchy-pkgs#637, now pins 3a58abb5. Second review of the merge, from a fresh-context reviewer on a different model, because the usual second-model reviewer was rate-limited: the conflict resolution is correct and no auto-merged file was silently combined. The usual reviewer's re-check is still owed.

Update 2 (2026-09-25, Brisbane):

• Merged quattro-upstream (418159a3) into the branch. It now has Land #503 with the review fixes and the gap-audit merge blockers #527, Defer image hardware setup to the Mac's first boot #528, Compose mkinitcpio HOOKS from an early per-platform baseline #536 and Runtime settings profile and platform package lists #542. The only conflict was docs/file-layout.md. It keeps quattro-upstream's manifest and detector text plus this branch's "disables the service" and Mac hand-off sentences.
• Second review (full diff vs quattro-upstream) found two first-boot defects, both fixed in d46c1bf0:
  1. First boot handed off whenever omarchy-provision-hardware failed, including when it refused to run at all (an untrusted manifest or queue). A failed step now exits 75. First boot tolerates only that; any other failure keeps it on the retry screen.
  2. After an offline first boot, apple/pacman.sh's repository sync stays queued ahead of the Limine activation, and the retry service ran before the network was up. The Mac drop-in now orders it after network-online.target.
  • Refuted: device-tree walk edge cases, the locale pin under sh, factory-reset scrubbing and unit ordering.
• Tests: boot package suite passes, with new cases for a refused hardware setup and the drop-in. image-deferred-hardware-test.sh checks exit 75 for a failed step and 1 for a refused queue entry. Runtime test/all (non-root, Arch Linux ARM): only hermes-remove-test.sh fails, and quattro-upstream fails it too, along with the flaky sleep-migration test.
• Recipe: Add omarchy-mac-boot for aarch64 edge omarchy-pkgs#637 merged, pinned to integ/boot-set-1 (a09ee0ca), which has this branch at 3a58abb5, before these fixes. The next pin goes through omarchy-mac-boot 20260925-3: re-pin to quattro-upstream f7ea7ecc omarchy-pkgs#641.

[maralcbr]

Ticket 64 is folded in here rather than opened as a separate PR. I pushed seven commits on top of 602266c8; the head is now 7237f6d8d, so omacom/omarchy-pkgs#637's pin needs to move to it.

• Kept unit file (the Defer image hardware setup to the Mac's first boot #528 follow-up above). Once the queue is empty, omarchy-provision-hardware removes only the enable link and keeps the unit file. I checked this in a systemd 261 container. Deleting the file while first boot holds the service's start job made the next daemon-reload fail that job. With the file kept, the job is skipped on its condition.
• Drop-in gate. The drop-in also has ConditionPathExists=!/var/lib/omarchy/mac-first-boot/pending, so the queue never runs before this Mac's keyring exists.
• Offline first boot. A failed deferred step no longer stops first boot. The queue holds every hardware leaf, and apple/pacman.sh needs the network, so an offline first boot left the owner at the failure screen with no way to get online. The step now stays queued for the service, and the journal names both logs. A missing omarchy-provision-hardware and a fresh image without a manifest still stop first boot.
• Encryption gate. The initramfs gate never reads /var/lib/omarchy/image, which @factory keeps and a reset restores. There is a static check and a new disposable loop-device case: a reset-style root with a restored queue stays plaintext, and a gate mutated to accept the queue fails that case. A factory reset now also removes the mac-first-boot/deferred-steps token from @factory and from the next root.
• Comments and docs are updated (disabled, not disarmed; who retires the manifest; docs/file-layout.md, source-port note). The tests now check that the hand-off runs after the keyring, before owner setup is staged, and leaves no error behind.

Tested at 7237f6d8d in an Arch Linux ARM container as a non-root user. packages/omarchy-mac/boot/test/all passes, 97 checks. The disposable encrypt lane passes, 34 checks. The runtime suite has 315 passing files. The same two fail on the base (hermes-remove, and update-lock in this container). test/cli and packages/omarchy-mac/test/all pass. Mutations of each new behaviour fail the tests.

Second review: two independent rounds. They found the offline dead end, the pipefail false pass in the new static check, a loose grep, a missing check that no error is left behind, and stale wording. All are fixed.

Left open, since they are #528's design: the service has no network ordering, so an Apple step that needs the network may keep failing at early boot. Its non-zero exit also doesn't separate a broken image from a transient failure, so first boot can't tell them apart.