phoebus_os/docs/VM-BOOT-VERIFICATION.md
Phoebus b4a6b5df80
Some checks are pending
ci / test (push) Waiting to run
feat(nvidia): hardware-driven driver policy, installed integration and live payload
- resolve the NVIDIA branch and kernel-module flavor from PCI device IDs
  (Turing+ open modules; Maxwell/Pascal/Volta proprietary, masked below 595;
  Fermi/Kepler fall back to nouveau, reported; unknown IDs reported)
- capture pci_id/pci_address in the probe; drive VIDEO_CARDS, package.use,
  package.accept_keywords, package.mask, modprobe.d and dracut from the plan,
  preserving hybrid Intel/AMD
- add the nvidia_drivers install stage (after the kernel, before boot) that
  emerges the driver, regenerates the initramfs, records /etc/phoebus/nvidia and
  fails the install on failure; sys update rebuilds modules and the initramfs
- refuse AI changes to x11-drivers/nvidia-drivers
- live ISO: signed non-free components, stable-kernel pin (testing 7.2 breaks
  the 550 driver), DKMS build for the exact kernel, gated pre-greetd load,
  fail-safe entry, gpu-report, and a --verify-live-nvidia build gate that runs
  on cached rootfs builds and fails on any missing component
- docs: ADR 0012, STATUS/CHANGELOG/HANDOFF, live README
- also carries the pending OpenCode model-variant/streaming changes and fixes
  the GUI bridge install thread join that could hang
2026-09-22 21:53:28 -07:00

35 KiB
Raw Blame History

Disposable UEFI VM boot verification

This records the first successful end-to-end install and boot of Phoebus OS against a disposable qcow2 disk. No physical disk was ever touched.

Exact tested path

Host (Ubuntu, no root required):

  • QEMU qemu-system-x86_64 (extracted locally under /tmp/opencode/qemudeb), OVMF (OVMF_CODE_4M.fd + OVMF_VARS_4M.fd).
  • Target disk: /tmp/opencode/vm/work/target.qcow2, 30 GiB, virtio-blk (/dev/vda in the guest).
  • Live boot: the reference ISO's own boot/gentoo + boot/gentoo.igz, with -append "root=live:CDLABEL=gentoo-amd64-livegui rd.live.dir=/ rd.live.squashimg=image.squashfs cdroot console=ttyS0,115200".
  • A host python3 -m http.server serves the installer tarball, the pinned stage3 and the test config to the guest over QEMU user networking.

Phase 1 (install):

  1. Boot the live ISO headless; get a root shell on the serial console.
  2. Download the installer and test config from the host.
  3. Write secrets to 0600 files and run the installer binary (the original run used the Bash prototype; the harness now serves phoebus-installer): phoebus-installer --config test.conf --install --yes --luks-passphrase-file FILE --user-password-file FILE
  4. Stages executed in order: preflight, storage, stage3, fstab, portage, base packages, kernel, bootloader, users, services, desktop, finalize.

Phase 2 (boot the disk alone, ISO detached):

  1. Power off, then start a new QEMU with no ISO and no -kernel, boot order=c, same OVMF NVRAM.
  2. Firmware runs \EFI\systemd\systemd-bootx64.efi; systemd-boot boots the "Gentoo Linux" BLS entry from the ESP.
  3. systemd-cryptsetup prompts for the LUKS2 passphrase, unlocks /dev/vda2, mounts the Btrfs @ subvolume as /.
  4. systemd (PID 1) starts, serial getty appears, user login succeeds.

Verified results

  • Firmware booted the disk's own systemd-boot (Boot000C "Linux Boot Manager").
  • LUKS2 passphrase prompt and successful unlock.
  • Btrfs subvolumes mounted: /, /home, /var, /.snapshots, /swap (later fix), ESP at /efi.
  • cat /proc/1/comm -> systemd.
  • systemd-analyze: 1.442s kernel + 5.755s initrd + 2.942s userspace.
  • Login as phoebus with the configured password; groups: wheel audio video render input plugdev power network libinput.
  • Networking up (enp0s2 10.0.2.15/24).
  • systemctl --failed: exactly one unit, swap-swapfile.swap (fixed after this run; see below).

Bugs found and fixed during this work

  1. Subvolumes created after mounting @ - storage_prepare mounted subvol=@ before @ existed (mount exit 32). Added btrfs_create_layout (mount top-level, create subvols, unmount, then mount layout) and a regression test (tests/test_btrfs_order.sh).
  2. Generated fstab overwritten by stage3 - fstab/crypttab were generated during storage, then the stage3 tarball replaced /etc/fstab. Moved generation to a new fstab_generate stage after extraction.
  3. /var/tmp absent in the target - systemd's kernel-install needs a temporary directory; /var/tmp was missing. The fstab stage now creates /var/tmp, /tmp, /root, /home, and chroot commands set TMPDIR=/tmp.
  4. installkernel needs uki_generator even for BLS - with an explicit /etc/kernel/install.conf, 05-check-config.install always requires a uki_generator. BLS now writes uki_generator=none.
  5. dracut could not build the crypt module - the target lacked sys-fs/cryptsetup. Added sys-fs/cryptsetup and sys-fs/btrfs-progs to the base package set.
  6. No systemd-cryptsetup - sys-apps/systemd was built without the cryptsetup USE flag, so the encrypted root could not be unlocked. Added cryptsetup (and policykit) to the systemd package.use entry.
  7. Kernel command line used unnamed LUKS - rd.luks.uuid yields luks-<uuid>, not the configured name. Switched to rd.luks.name=<uuid>=<name>.
  8. Dracut UKI did not embed the command line - the dracut uki_generator produced a UKI with no .cmdline, so it booted with no root=. Deferred UKI in favour of a reliable BLS entry carrying options. UKI remains future work.
  9. fstab did not mount @swap - the swapfile unit failed because /swap was never the @swap subvolume. Added the subvol=@swap fstab entry.
  10. local root="$1" dir="$root/..." class bug - reintroduced in boot_write_dracut_conf; split into two local statements. This class of bug is now covered by the regression suite.
  11. Wrong package atoms - gui-apps/fuzzel (not in Gentoo) -> gui-apps/wofi, app-misc/brightnessctl (not packaged) removed, app-crypt/gnome-keyring -> gnome-base/gnome-keyring, gui-apps/polkit-gnome -> gnome-extra/polkit-gnome.
  12. Package policy compiled too much - unknown packages defaulted to source. balanced now compiles cheap builds and uses signed Gentoo binaries for everything else, which cut installer time substantially.

Rust installer parity (same VM path)

The Rust installer (installer-rs) reproduced the entire path on a fresh disposable qcow2 disk using the static binary phoebus-installer (x86_64-unknown-linux-gnu, crt-static):

  • Same config (legacy flat format), same pinned stage3 URL + SHA-256.
  • INSTALL_RC=0; stages: storage, stage3, fstab, portage, base packages, kernel, bootloader, users, services, desktop (none), finalize.
  • Policy decisions matched Bash: sudo/networkmanager/polkit binary, cryptsetup/btrfs-progs source.
  • The installer recorded 81 then 97 measured compile times from Portage's emerge.log (real data, not estimates).
  • NO_SECRET_LEAK from the log secret scan.

Booted with the ISO detached:

  • UEFI firmware ran systemd-boot; BLS entry booted.
  • LUKS2 unlock, Btrfs @ root, /home, /var, /swap, ESP at /efi.
  • cat /proc/1/comm -> systemd.
  • systemctl is-system-running -> running (not degraded).
  • systemctl --failed -> 0 loaded units listed.
  • systemd-analyze: 1.378s kernel + 5.238s initrd + 4.114s userspace = 10.730s.
  • Login as phoebus succeeded; networking up (10.0.2.15/24).

This is the point at which the Rust installer satisfies the parity criteria and may become the primary installer. The Bash implementation remains the reference/fallback until the desktop milestone is also verified.

Desktop and Flatpak (Rust installer, verified)

The Rust installer, running the desktop profile, installed the full Wayland desktop and Flatpak successfully (INSTALL_RC=0; 326 measured compile times recorded). Key change: a desktop install now selects the supported stable Gentoo profile default/linux/amd64/23.0/desktop/systemd instead of reconstructing X/Wayland/dbus USE by hand from the minimal systemd profile. This resolved the earlier cairo[X]/libglvnd[X]/libxkbcommon[X] conflicts, and sys-fs/{btrfs-progs,cryptsetup} -man avoided a Sphinx/Pillow circular dependency.

Booted with the ISO detached and logged in:

  • systemctl is-system-running -> running; systemctl --failed -> 0 units.
  • flatpak --version -> Flatpak 1.18.1; flatpak remotes -> flathub configured.
  • Binaries present and runnable: dwl 0.7, Waybar v0.15.0, wofi 1.4.1, mako, swaybg, pipewire, wireplumber, grim, wl-clipboard.

Session verification. The VM's serial session has no logind seat, so wlroots' DRM backend correctly refuses (Failed to start a DRM session). This is a headless-harness limitation, not an installer defect. Using WLR_BACKENDS=headless WLR_RENDERER=pixman:

  • dwl started (pid observed), created the wayland-0 socket.
  • mako, waybar, and swaybg started and connected (swaybg found output HEADLESS-1).
  • wl-copy/wl-paste round-tripped phoebus-clip.
  • grim /tmp/shot.png produced a 14401-byte PNG, proving the compositor renders and captures.
  • wpctl status reported the PipeWire graph; systemctl --user --failed -> 0.
  • waybar logged a non-fatal warning about a missing power-menu file and power-profiles-daemon.

The installer writes /usr/local/bin/phoebus-session, which starts waybar, mako and swaybg and then execs dwl, with a software-render fallback when no render node is present.

Official harness on the static binary (Bash migration, Phase 2)

The committed harness (installer/tests/vm/serial-driver.py + installer/tests/vm/install.sh) now drives the static Rust binary and no longer runs the Bash installer. Re-verified end to end on a fresh disposable qcow2 (24 GiB, virtio-blk /dev/vda):

# Build:
cd installer-rs && RUSTFLAGS="-C target-feature=+crt-static" \
  cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu

# Install in the disposable VM, then boot the disk detached:
python3 installer/tests/vm/serial-driver.py install
python3 installer/tests/vm/serial-driver.py boot

Install (INSTALL-RC=0):

  • The guest fetched /tmp/phoebus-installer and printed phoebus-installer 0.1.0 (the Rust binary, not Bash).
  • Stages completed in proven order: storage_prepare, stage_install, fstab_generate, portage_configure, packages_base, kernel_install, boot_install, users_configure, services_configure, desktop_install (none), finalize.
  • Policy matched Bash: crypto/btrfs-progs source build, sudo/ networkmanager/polkit binary.
  • NO_SECRET_LEAK; the run powered off cleanly.

Boot with the ISO detached (serial-driver.py boot):

  • UEFI firmware ran \EFI\systemd\systemd-bootx64.efi (Boot0002 "Linux Boot Manager"); the BLS "Gentoo Linux" entry booted.
  • systemd-cryptsetup prompted for the LUKS2 passphrase and unlocked phoebus-root (cryptroot).
  • Login as phoebus succeeded.
  • cat /proc/1/comm -> systemd.
  • systemctl is-system-running -> running.
  • systemctl --failed -> 0 loaded units listed.
  • Networking: enp0s2 UP 10.0.2.15/24.
  • Mounts: / (btrfs @), /home, /var, /.snapshots, /swap, ESP /efi; vda2 is crypto_LUKS.

This satisfies the Phase 2 exit gate of docs/BASH-MIGRATION.md: the only proven boot path no longer depends on the retired Bash installer.

Snapshots and safe updates (four-workstream session)

Verified on the installed Btrfs system from the static-binary harness, driving the new sys binary fetched into the guest:

  • sys history before -> no transaction history.
  • sys -y --action '{"action":"create_snapshot","operation":"vm test"}' -> protective snapshot: @-20260920T114917-vm-test.
  • sys history after -> @-20260920T114917-vm-test Committed vm test.
  • btrfs subvolume list / shows @snapshots/@-20260920T114917-vm-test as a real subvolume (read-only snapshot).
  • sys -y prepare-updates fetched distfiles successfully; --buildpkgonly was refused by Portage with --buildpkgonly requires all dependencies to be merged, which the installer now records as status: Ready with the reason (distfiles fetched; binary prebuild skipped: ...) instead of a hard failure.
  • sys inspect-updates reports the state and timestamp.

Unit regression tests cover the failure paths that a VM cannot easily force: corrupt snapshot history is an error, and a high-risk action aborts when the protective snapshot fails.

Desktop session on an installed VM

A full dwl desktop install was built with the static Rust binary (DESKTOP_PROFILE=dwl, FLATPAK=no) and booted with the ISO detached: INSTALL_RC=0, all stages, NO_SECRET_LEAK, systemctl is-system-running -> running, 0 failed units.

Running the installed /usr/local/bin/phoebus-session under the headless wlroots backend (the serial VM has no logind seat):

  • the wayland-0 socket is created before any helper starts;
  • after startup the process tree is dwl, waybar, mako, swaybg -c #1e1e2e and /usr/libexec/polkit-gnome-authentication-agent-1 (the polkit agent, which the previous script never started);
  • dwl reports the HEADLESS-1 output;
  • after dwl exits, all session processes are reaped.

Installed and on PATH: dwl, waybar, mako, swaybg, kitty, wofi, Xwayland. The polkit agent lives at /usr/libexec/polkit-gnome-authentication-agent-1; the session script's fallback finds it because it is not on PATH.

This is headless verification. A physical VT / real logind seat remains to be exercised interactively (docs/DEVELOPMENT.md -> "Physical VT / real-seat check").

Signed binary reuse analysis

The desktop transaction's installer log (emerge grouping) shows the policy already requests signed binaries for the expensive set:

  • source group: sys-fs/cryptsetup sys-fs/btrfs-progs;
  • binary groups: base tools, gentoo-kernel-bin/firmware, and the dwl/waybar/ wofi/mako/sway*/gtk-layer-shell/xwayland set.

The desktop install in this session took ~1h49m wall time (12:01–13:50 UTC) on 8 vCPUs. Most of that is Portage falling back to source because the OpenRC/ hardened binhost cannot satisfy the systemd/desktop USE set, even though the policy requested binaries. Two comparable data points are now recorded: the base-only install took ~44 min and the desktop install ~1h49m. The code changes here remove forced flags but cannot raise reuse without a matching binhost, so no new time saving is claimed.

The remaining source builds are caused by the official Gentoo binhost being built for the OpenRC/hardened profile (PROFILE: default/linux/amd64/17.0/ hardened), which cannot satisfy a systemd/desktop USE set. The safe changes made here are: stop forcing the unused installkernel uki flag, remove the duplicate PipeWire and empty WirePlumber package.use lines, and derive the binhost URI from the selected profile when it is not set. Signature verification remains enabled. Publishing a matching systemd/desktop binhost is the remaining step; no time estimate is claimed beyond the recorded ~26 min.

Debian-Live installer appliance (actual ISO)

An appliance ISO was built without root by installer/live/build.sh (Debian-Live 13.7 standard base + /phoebus overlay). The full-install evidence below was recorded with build c0105bc9a282fddcbefab42baa577ea99843060f00fa45a75bcbc8358186bfd5.

A desktop install was re-run and verified with build c1846f0d18ed9813e5ef3e699b9110f4fb04ab09a4c5ed800970b1d54971d114:

  • mandatory-AI gate refused the install until --no-ai was passed (GATE_REFUSED_OK);
  • Nix: /nix/store/2nhrwv91g6ycpyxvhmvc0xs8p92wp4bk-nix-2.24.9 present, nix (Nix) 2.24.9, nix-daemon.service enabled and active, and nix shell nixpkgs#hello downloaded from cache.nixos.org and printed Hello, world!;
  • desktop portals: xdg-desktop-portal 1.20.4, -gtk 1.15.3, -wlr 0.7.1;
  • desktop binaries present: dwl, waybar, kitty, wofi, Xwayland;
  • hostname phoebus, networking enp0s2 UP 10.0.2.15/24, systemd PID 1, running, 0 loaded units listed.

The current build is 3ba913ba660fb7436e26e587e9777f1f65ed10dcc9b50d17458ebb3d3a739b5c: Nix is now on by default, and finalize flushes the target (sync) before unmounting. That build was not re-run end to end because the host root filesystem reached ~98% and the base emerge became pathologically slow. Treat c1846f0d as the verified artifact and 3ba913ba as the current one.

Firmware boot (UEFI/OVMF, no -kernel; the ISO's own grub chain):

  • auto-boots the live system on the serial console;
  • login user / live (passwordless sudo);
  • the overlaid tools run: cryptsetup 2.7.5, sgdisk 1.0.10, partprobe 3.6, mkfs.btrfs 6.14, mkfs.fat.

Full install to a fresh 24 GiB qcow2 driven from the appliance:

  • INSTALL_RC=0, all stages, NO_SECRET_LEAK.

Detached boot of the installed disk (ISO removed):

  • systemd-boot -> LUKS2 unlock -> phoebus login;
  • systemctl is-system-running -> running; 0 loaded units listed;
  • Gentoo-only: Gentoo Base System release 2.18, Portage 3.0.82.2, no-apt; systemd PID 1;
  • cryptroot Btrfs mounted at /, /home, /var, /.snapshots, /swap, ESP /efi.

This is Bash-free and Gentoo-target-only: the appliance contributes tooling, never configuration.

Open items found in this run

  • Resolved: the earlier gentoo hostname anomaly did not recur; the target boots as phoebus with /etc/hostname set, and DHCP comes up (enp0s2 UP 10.0.2.15/24) once awaited.
  • Implemented, not re-verified: /usr/local/bin/phoebus-session (and the exported installer log) were absent after boot in the earlier runs. The installer wrote and existence-checked them, and the root unmounted cleanly, but comparison with a boot-time-created file showed the finalize writes were not on disk: Btrfs commits lazily and the harness used poweroff -f. The fix is a sync in finalize before unmounting (build 3ba913ba). It has not been re-run end to end (host disk pressure). Until it is, treat the session script as unverified in the shipped ISO.

2026-09-21 appliance baseline (rollback/recovery foundations)

A fresh install of the committed code was run in a disposable qcow2 (24 GiB) with the rebuilt Debian-Live appliance ISO, then booted with the ISO detached. This validates the coordinated-snapshot and recovery-entry code on a real Btrfs system; it does not validate a rollback (that gate is still pending).

  • Build: static phoebus-installer from the tree, appliance ISO 206551ec21e13753fb97f6d65bfc01e3642b0167908807f64d6ca5a80141adab.
  • Config: DESKTOP_PROFILE=none, KERNEL_PROFILE=safe, LUKS2 + Btrfs, NIX_ENABLED=no; the host served the stage3 (sha256 6a3d85ee...f77d44d5), config and 0600 secret files over HTTP.
  • Harness: installer/tests/vm/appliance-driver.py install then boot (new in this session).

Install:

  • ===NO_SECRET_LEAK===, ===INSTALL-RC=0===, clean poweroff (reboot: Power down). Target grew to 6.3 GiB.

Detached boot (no ISO, no -kernel):

  • UEFI ran systemd-boot; its menu listed Gentoo Linux, Phoebus Recovery (known-good snapshot) and Reboot Into Firmware Interface; the default booted.

  • systemd-cryptsetup prompted for the LUKS2 passphrase and unlocked phoebus-root (cryptroot).

  • cat /proc/1/comm -> systemd; systemctl is-system-running -> running; systemctl --failed -> 0 loaded units listed.

  • Networking: enp0s2 UP 10.0.2.15/24.

  • The target's transaction history contains the initial coordinated snapshot:

    [[records]]
    id = "@-20260921T110110-initial-known-good"
    operation = "initial known-good"
    source_subvol = "/mnt/phoebus"
    snapshot_subvol = "@-20260921T110110-initial-known-good"
    var_snapshot = "@var-20260921T110110-initial-known-good"
    status = "committed"
    

    This confirms @ and the separately mounted @var are captured together and that the installer writes a snapshot-based recovery entry (not one that depends on the live root). Reading the recovery entry and btrfs subvolume list as the unprivileged user was refused; the menu entry above is the evidence that it exists.

Not yet verified for this baseline: sys undo, a deliberately broken update, a detached rollback reboot, and recovery with no network/model (the rollback acceptance gate).

2026-09-22 update — rollback acceptance still NOT run. A session of sys administration hardening did not run the destructive acceptance test. The blockers are unchanged and exact: make doctor reports ~13 GiB free versus the

=20 GiB the VM harness requires (the root filesystem has ~12 GiB free), and the committed harness (appliance-driver.py, serial-driver.py) implements only install and boot, with no automated break-update / sys undo / recovery-boot mode. sys undo therefore remains unverified, not passing.

Mango + DankMaterialShell verification (IN PROGRESS)

Live ISO — graphical VM (verified 2026-09-21)

Artifact: installer/live/build.sh output phoebus-mango-amd64.iso, sha256 c235b873bc04a90c91ff4be361a605907997c509c4021e611645336c23f924d9 (1.6 GiB). The image was built rootlessly from the signed Debian testing archive plus pinned Mango 0.17.2 and DankMaterialShell 1.6.2 releases (installer/live/releases.sha256).

Booted in a disposable QEMU/OVMF VM with a graphical device (-device virtio-gpu-pci, no -vga, serial console still attached) — a real DRM node and logind seat, not a headless compositor:

  • uname -r -> 7.1.13+deb14-amd64; systemctl is-system-running -> running; /dev/dri/card0 and /dev/dri/renderD128 present.
  • Live autologin ran as an unprivileged phoebus user in session c1 on seat0/tty7; mango (compositor), /usr/bin/dms run --session and qs (Quickshell) were running under the user manager (mango-session.target and dms.service both active).
  • No dwl helpers (waybar/mako/swayidle/swaylock) were started.
  • A framebuffer screendump showed the DankMaterialShell desktop: the DMS panel (clock, weather, tray, network/battery/volume/power) and the DMS first-run "Welcome to DankMaterialShell" window, composited by Mango. This is the acceptance evidence for "the ISO boots into a usable Mango + DankMaterialShell live desktop".
  • The "Install Phoebus" application entry and /usr/local/bin/phoebus-install are installed by the build; the launcher runs the installer UI and passes no --yes/--install/--no-ai (unit-tested), so opening it cannot start a destructive operation automatically. The serial console and a spare VT remain available as a recovery path.

Fixes found by this test (all committed): the live kernel/initrd must replace the base ISO's versioned /live/vmlinuz-* paths; setuid bits must be restored when packing as an unprivileged user (for sudo); virtio_gpu must be autoloaded; greetd's greeter account must exist even with an initial_session; greetd must run on VT7 to avoid the getty@tty1 conflict; live-config autologin (noautologin) must be disabled in favour of greetd; and the Mango session must not export WAYLAND_DISPLAY before the compositor starts (wlroots would pick its nested backend instead of DRM) and needs the Qt Wayland shell-integration packages for Quickshell.

Installed system — not yet run

A default install (desktop.profile = "mango"; the default) and a detached encrypted boot to the greetd login are not yet verified in a VM: the Mango transaction syncs the GURU overlay and compiles Quickshell/DMS/scenefx/Qt, which was not feasible here. The configuration and login behaviour are covered by unit tests (live_iso.rs, system::installed_login_*, desktop.rs), and the plan renders the session. Verify with the harness once a full Mango build is affordable:

python3 installer/tests/vm/appliance-driver.py install   # DESKTOP_PROFILE=mango
python3 installer/tests/vm/appliance-driver.py boot

Remaining graphical checks (installed system and live): panel interactions and launcher, notifications, polkit prompt, lock/unlock, idle/suspend and resume, display changes, clipboard/screenshots/terminal/file manager, a Flatpak app launch + file chooser + screen sharing, logout/reboot, the dwl fallback, shell restart, and idle memory/CPU versus dwl.

Known prerequisites/limits: the installed mango transaction needs the GURU overlay (git) and compiles Quickshell/DMS/scenefx; the live build needs the signed Debian testing archive. A graphical VM must provide a real seat (for example -device virtio-gpu-pci with the serial console still attached); -display none alone is not sufficient evidence of a graphical session.

  1. Live ISO boots to Mango + DMS (screenshot/screendump evidence, not just process names); panel, launcher and terminal work; "Install Phoebus" opens the installer UI without starting a destructive operation.
  2. Live text-console recovery (serial and a spare VT) remains accessible.
  3. Fresh install with the default profile reaches systemctl is-system-running = running with 0 failed units; emerge --pretend shows only the reviewed ~amd64 atoms.
  4. Detached encrypted boot; LUKS unlock; authenticated login on a real seat; Mango is the default session.
  5. phoebus-mango.desktop starts the session; exactly one compositor (mango), one shell (dms), one lock/idle (DMS) and one polkit agent run; no waybar/mako/swaybg/swayidle/swaylock processes.
  6. Panel, launcher (Mod+Space), notifications, tray and the DMS settings panel; audio/network/Bluetooth controls; lock/unlock; idle/suspend and resume.
  7. Display configuration/scaling and a second monitor if the VM supports one.
  8. Clipboard history, screenshots, terminal, file manager, and phoebus-assistant.
  9. An actual Flatpak app: launch, file chooser, and portal screen sharing.
  10. Logout reaps session processes; reboot; select the phoebus-dwl.desktop fallback and confirm it still works.
  11. Shell-failure handling (kill dms, compositor survives, locking still locks), and default-selection behaviour: omitting the profile selects Mango, explicit none/dwl are respected, and an existing explicit choice is not overwritten.
  12. Idle memory/CPU and startup measured against the dwl session.

Until results are recorded here, the default stands by owner decision but no stability is claimed.

Graphical installer ISO and typed bridge (2026-09-21)

A dedicated driver, installer/tests/vm/gui-driver.py, boots the built live ISO with a graphical device and a serial console, drives the graphical frontend through the compositor, and captures QEMU framebuffer screenshots.

Artifact: installer/live/phoebus-installer-amd64.iso, 1.6 GiB, sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee (Mango 0.17.2 + DankMaterialShell 1.6.2).

What was observed (gui mode):

  1. The live session autologins into Mango + DMS; the branded phoebus-welcome window opens automatically. The DMS first-run greeter and changelog dialogs do not appear (markers pre-seeded).
  2. The welcome shows the wordmark, emblem, wallpaper, ISO version (0.1.0) and readiness (network connected, UEFI, memory, cores), with "Install Phoebus OS" dominant and the secondary tools plus Advanced present.
  3. Launching phoebus-install opens the wizard; running it again leaves the session count at 1 (DUP n1=1 n2=1), so duplicate installer sessions are prevented.
  4. Keyboard navigation (Ctrl+Right / Enter / Tab) reaches step 2 (network and prerequisites, with real UEFI/memory/CPU/network values) and step 3 (AI model). Provider selection, the secret API-key field and the model field render; advancing without a connected model is refused with "Connect and validate an AI model before continuing."
  5. A backend probe on the real guest lists /dev/vda as unprotected and selectable, and /dev/sr0 as the live_medium installation medium, protected (the model tests cover the classification logic).
  6. Screenshots: docs/screenshots/01-welcome.png … 05-ai-blocked.png. The destination-disk, review and confirmation screens (06–08) were rendered from the same QML against a dry-run backend because a real provider call was not available in this environment.

What was not possible: a live AI provider call (no key/model in this environment). The AI step is verified as a blocked prerequisite and in unit tests with a fixture transport; it is not a passed live call.

Real install + detached boot on the same ISO (install then boot modes):

  • Guest install used the same deterministic backend as the GUI (phoebus-installer --install --yes --no-ai): INSTALL-RC=0, installation complete, NO_SECRET_LEAK.
  • Detached boot (no ISO, -boot order=c): systemd PID 1, running, 0 failed units, systemd-boot menu shows Gentoo Linux first, LUKS2 unlocked, /dev/vda1 -> /efi, cryptroot Btrfs with / /home /var /.snapshots /swap, network up.

Bug found and fixed during this work: the snapshot recovery BLS entry shared the kernel's sort-key, and the specification's final filename tie-break (decreasing) made it first when the random machine-id sorted low; with default * the installed system booted systemd.unit=rescue.target. Fixed by pinning loader.conf to the newest real kernel entry and giving the recovery entry sort-key zzzz-phoebus-recovery; unit tests pin both.

2026-09-22 — automated graphical journey (gui-driver) and hardened harness

The graphical live ISO was rebuilt and driven automatically by installer/tests/vm/gui-driver.py gui in a graphical, seat-providing QEMU/OVMF VM with a disposable qcow2 disk directory and a per-run OVMF variable file.

  • Source revision: 7e9fa9c plus uncommitted work; build id recorded in /etc/phoebus/build (7e9fa9c+dirty…).
  • Static installer: sha256 2f9cd4b3… (4,716,544 bytes, static-pie).
  • ISO: installer/live/phoebus-installer-amd64.iso, sha256 428dbd75…, 1.6 GiB, built with PHOEBUS_REUSE_ROOTFS=1 (Mango 0.17.2 + DankMaterialShell 1.6.2).
  • Result: 23/23 checks PASS, exit status 0 (/var/tmp/phoebus-vm/gui-gui-20260922T025537Z-69f754cf/). Asserted: welcome autostart; live/branding payload markers from command output (not the echoed command); the live medium protected; "Install Phoebus OS" launched the installer from a Return keypress; duplicate sessions prevented (n1=n2=1); the frontend reported no bridge errors; keyboard navigation reached the network and AI steps; advancing without a connected model was refused and started no installation.
  • Screenshots at every page (welcome focus, language, network, AI model, AI blocked, final state) plus a screenshot-manifest.json; report.py builds a browsable report.html. All artifacts stay under /var/tmp/phoebus-vm/ (outside git).

Harness safety verified in the same work: the drivers reject /dev/*, block and character devices, raw images, symlinks escaping the disposable directory, and outside backing chains, with a nonzero exit (make test-vm, 16 unit tests). Screenshots use structured QMP and argument arrays; there is no shell interpolation.

A host-local OpenCode transport test also ran: phoebus-installer --opencode-probe returned ready against opencode 1.18.32 through a forwarded second loopback endpoint, and authentication_required (exit 1) against a deliberately unauthenticated LAN bind.

2026-09-22 — graphical journey polish and the gui-install mode

The graphical installer was reworked into a fixed first-time-user journey and re-verified on the final ISO.

  • Source revision: 34c12d3 plus the session work; ISO installer/live/phoebus-installer-amd64.iso, sha256 0c386a1b…, 1.6 GiB, built with PHOEBUS_REUSE_ROOTFS=1 (Mango 0.17.2 + DankMaterialShell 1.6.2).
  • gui 28/28 PASS (/var/tmp/phoebus-vm/gui-gui-20260922T191954Z-876d5e91/): welcome autostart, launcher from the keyboard, duplicate prevention, the live medium protected, keyboard suggestion selection (Down then Enter stores the identifier), the network and AI steps, the AI gate refused without a model with an inline error, and no bridge errors.
  • opencode 18/18 PASS (/var/tmp/phoebus-vm/gui-opencode-20260922T192457Z-01714c92/): OpenCode selected and driven through the UI, a real model response (Test connection), a validated proposal (4 changes applied), and a regression asserting that editing the model flips the validated state off.
  • gui-install 24 PASS / 1 FAIL (/var/tmp/phoebus-vm/gui-gui-install-20260922T151232Z-0ef19969/): every journey assertion passed — OpenCode connect/review/accept, back-nav-preserves-ai, readiness-refresh-preserves-wizard, disk-survives-backtrack, disk selection, account and encryption, ERASE and gui-install-erase-confirmed — and the backend then reported the real stage sequence (storage_prepare, stage_install, fstab_generate, portage_configure, packages_base, kernel_install) with elapsed time and no fabricated percentage. The single FAIL is gui-install-completes: after four hours the install was still in kernel_install, because the base-package stage took ~116 min and the AI-selected optimized kernel compiled for more than 100 min on this host, so the harness timeout fired. The completed install + detached boot gate is BLOCKED on host build time; the deterministic noninteractive install + detached boot (above) remains the proven boot path. No code defect is implicated.
  • The new PHOEBUS_GUI_CONFIG / /etc/phoebus/install.conf hook lets a medium preseed the wizard defaults. It changes defaults only: validation, the plan, the AI gate and the ERASE authorization are unchanged.

Known remaining work

  • The graphical session was verified with the headless wlroots backend (no logind seat in the serial harness). A physical VT / seat path is architected (phoebus-session) but was not exercised on real hardware.

  • NVIDIA proprietary support is implemented (hardware-driven branch/flavor policy, scoped Portage configuration, a build-time-verified live payload, and kernel/module/initramfs update coordination) with Rust tests. A minimal live rootfs was built and its NVIDIA payload verified this session (driver 550.163.01, kernel 6.12.107+deb13-amd64, modules nvidia-current*). It is NOT VERIFIED on hardware: no NVIDIA GPU is present on this host, QEMU's virtual GPU cannot establish NVIDIA acceleration, and no passthrough setup is available or authorized. The full desktop ISO was not assembled here (the host has ~10 GiB free; the build wants more).

    The live kernel is pinned to Debian stable because Debian testing's current kernel (7.2) removed the strncpy declaration the 550 driver uses, so nvidia-kernel-dkms fails to build against it. The bundled branch covers Maxwell through Ada/Hopper; Blackwell falls back to nouveau on the live medium. The installed Gentoo system uses the current branch with open kernel modules on Turing and newer.

    Unblock (hardware): boot the built ISO on a machine with an NVIDIA GPU (or an authorized passthrough VM) and check: systemctl status phoebus-nvidia.service, nvidia-smi, cat /sys/module/nvidia_drm/parameters/modeset == Y, an accelerated Mango/DMS session, XWayland/Flatpak rendering, monitor handling and suspend/resume. Then boot the installed Gentoo system and confirm the same, plus that a kernel update rebuilds the modules via @module-rebuild and regenerates the initramfs. Unblock (build): free sufficient disk space and run installer/live/build.sh (it fails, by design, if the NVIDIA payload is missing or mismatched), then the gui harness mode to confirm ordinary virtual-GPU boot is unchanged.

  • UKI is deferred (BLS is used).

  • The installer rebuilds sys-apps/systemd from source because boot/policykit/cryptsetup USE differ from the binhost. Shipping a matching systemd binpkg is a future optimization.

  • Desktop USE still does not match the signed binhost, so the desktop transaction compiles a large amount from source (~26 minutes for the desktop package set on 8 vCPUs in the test VM).

  • The complete graphical install and detached boot are BLOCKED on host build time. The gui-install harness now drives the real controls and passes every journey assertion on a fresh qcow2 (AI connect/review/accept, disk, account, ERASE, confirmation) and starts a real install, but on this host the base-package stage takes ~116 min and the AI-selected optimized kernel was still compiling after 100 min, so a four-hour harness timeout fired during kernel_install. Two completed fresh-disk graphical installs + detached boot therefore remain unrun here; the deterministic noninteractive install + detached boot is the proven boot path.

  • A separate physical computer for the OpenCode transport test is NOT available; that check is BLOCKED. The forwarded-hop and unauthenticated-LAN-refusal tests are host-local.