phoebus_os/docs/VM-BOOT-VERIFICATION.md
2026-09-22 07:30:38 -07:00

622 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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):
5. Power off, then start a new QEMU with **no ISO and no `-kernel`**, boot
`order=c`, same OVMF NVRAM.
6. Firmware runs `\EFI\systemd\systemd-bootx64.efi`; systemd-boot boots the
"Gentoo Linux" BLS entry from the ESP.
7. `systemd-cryptsetup` prompts for the LUKS2 passphrase, unlocks
`/dev/vda2`, mounts the Btrfs `@` subvolume as `/`.
8. 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`):
```sh
# 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**:
```toml
[[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:
```sh
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.
## 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 architecturally allowed but **NOT VERIFIED**.
- 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 full graphical install past the AI step is NOT verified.** No live
provider key and no downloadable local model were available in this
environment, and normal installation requires a connected model by design;
the automated journey stops at (and verifies) the blocked AI prerequisite.
Two fresh-disk graphical installations from the final candidate remain
unrun. The deterministic noninteractive install + detached boot remains 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.