phoebus_os/docs/STATUS.md
Phoebus 7e9fa9c2a3
Some checks are pending
ci / test (push) Waiting to run
feat(installer): graphical welcome and install wizard over a typed bridge
Add a branded live welcome window and a Quickshell/QML installer frontend
over a narrow, fail-closed JSON bridge (phoebus-installer --gui-bridge)
that reuses the same InstallConfig, plan, validation, authorization and
staged executor as the TUI/CLI. Add the Phoebus brand system (emblem,
wordmark, wallpaper, tokens), suppress DMS first-run dialogs on the live
medium, identify the live medium as protected, make the installer
shortcut live-only, and fix the installed boot default so systemd-boot
never selects the recovery entry.

Verified in a disposable graphical VM (welcome/installer journey,
duplicate prevention, keyboard navigation, blocked AI prerequisite) plus
a real non-interactive install and detached boot (INSTALL-RC=0,
NO_SECRET_LEAK, systemd running, 0 failed units, LUKS2, Btrfs, network).
2026-09-21 13:13:40 -07:00

9.4 KiB

Status

Truthful implementation/verification matrix. Vocabulary:

  • Implemented — code exists.
  • Unit tested — covered by automated tests that run on any host.
  • VM verified — exercised in the disposable QEMU/OVMF VM.
  • Hardware verified — exercised on real hardware.
  • Not verified — do not claim it works.

Proven baseline (do not regress)

A complete installation in a disposable UEFI VM, booted with the ISO detached:

QEMU + OVMF (UEFI)
30 GiB qcow2, virtio-blk (/dev/vda); live ISO at /dev/sr0
GPT: 1 GiB FAT32 ESP + LUKS2 remainder
Btrfs: @ @home @var @snapshots @swap
Gentoo systemd stage3 (default/linux/amd64/23.0/systemd)
systemd-boot + BLS entry + dracut initramfs
LUKS2 passphrase unlock at boot
systemd PID 1, login, networking
systemctl is-system-running = running; 0 failed units

Boot timing (Rust installer): 1.378 s kernel + 5.238 s initrd + 4.114 s userspace = 10.730 s.

The committed VM harness (installer/tests/vm/serial-driver.py + install.sh) drives the static Rust binary; the Bash installer is no longer on the install path (Bash migration Phase 2, see docs/VM-BOOT-VERIFICATION.md).

A second harness (installer/tests/vm/appliance-driver.py + appliance-guest.sh) drives the Debian-Live appliance ISO. On 2026-09-21 it produced INSTALL-RC=0, NO_SECRET_LEAK, and a detached boot (systemd, running, 0 failed units) whose Btrfs history contains the installer's coordinated @ + @var initial known-good snapshot and a snapshot-based recovery boot entry (see docs/VM-BOOT-VERIFICATION.md). sys undo itself is still not VM-verified.

Matrix

Area Implemented Unit tested VM verified Hardware verified
Config (TOML + legacy), validation yes yes yes n/a
Hardware/disk discovery, protection yes yes yes no
Install plan + destructive preview yes yes yes n/a
Destructive authorization (ERASE) yes yes yes n/a
GPT partitioning + ESP yes yes yes no
LUKS2 format/open/close yes yes yes no
Btrfs subvolumes + swapfile yes yes yes no
fstab / crypttab generation yes yes yes no
stage3 fetch + SHA-256 verify + extract yes yes yes n/a
Portage config + sync + getuto yes yes yes n/a
Signed Gentoo binary install yes yes yes n/a
Source package compilation yes yes yes n/a
Kernel install + dracut initramfs yes yes yes no
systemd-boot + BLS yes yes yes no
Boot default pins the real kernel (not recovery) yes yes yes no
Recovery BLS entry (rescue.target) yes yes boots (not default) no
Users, passwords, sudo yes yes yes n/a
Locale/timezone/keymap/services yes yes yes n/a
Rust VM boot parity yes yes yes no
Rust TUI yes yes smoke test no
Typed GUI bridge (--gui-bridge) yes yes (dry-run) live VM n/a
Graphical welcome + install wizard (Quickshell) yes guards tested live graphical VM no
Phoebus brand system (SVG + tokens) yes yes live VM n/a
Desktop profile (dwl/waybar/mako/swaybg) yes partial headless only no
Desktop session script (socket wait, polkit, cleanup) yes yes functional test (stubs) no
PipeWire/WirePlumber yes no headless (wpctl) no
Flatpak + flathub yes no installed + remote no
XWayland / polkit agent / kitty / wofi yes no installed, not launched no
Package policy + measured history yes yes yes (326 entries) no
Background update preparation yes yes yes (fetch; buildpkgonly skipped) no
Btrfs snapshots + history yes yes yes no
Coordinated snapshot sets (@ + @var) yes yes no no
Btrfs rollback (sys undo) yes yes no no
Recovery/known-good BLS entry yes yes no no
Snapshot retention + free-space gate yes yes no no
AI typed proposals + evidence review yes yes fixture end-to-end n/a
AI guided install (DeepSeek/OpenAI) yes yes fixture path only (no live call) n/a
AI privacy boundary (facts only) yes yes no n/a
AI OS sandbox (systemd hardened unit) yes yes no no
Installed assistant (sys ask) yes yes fixture path only (no live call) n/a
Resolved package effects + approval binding yes yes no n/a
Transaction log yes yes no no
Flatpak/Nix bounded typed actions yes yes no no
Desktop session helpers (menu/lock/idle) yes yes functional test (stubs) no
Mango + DankMaterialShell profile yes yes live graphical VM yes; installed no no
Mango is the default desktop yes yes live graphical VM yes; installed install pending no
greetd login (Mango default, dwl fallback) yes yes no no
Live desktop ISO (Mango + DMS) yes guards tested graphical VM + GUI journey + detached boot no
Live welcome autostart + duplicate prevention yes guards tested live graphical VM no
GURU packaging (scoped keywords) yes yes no (build/install unverified) no
Release gates + atomic publish yes yes no n/a
sys verbs yes yes yes no
OpenCode pinned bootstrap yes yes no n/a
Release manifest/verify yes yes no n/a
NVIDIA proprietary architecture only no no no
UKI no (deferred) no no no

Known limitations

  • Desktop graphical session was verified with the headless wlroots backend because the serial-only VM has no logind seat. The DRM path and a real VT login are not yet exercised. phoebus-session is written by the installer for that purpose.
  • Flatpak apps were not installed from the remote; only the runtime and the flathub remote were verified.
  • NVIDIA is architecturally allowed but not verified on hardware.
  • UKI is deferred; the dracut UKI generator did not embed the kernel command line, so BLS is used (and verified).
  • Rollback is implemented and unit-tested end to end at the command/text layer (snapshot sets, root/var generation, fstab and BLS rewriting, kernel selection, interruption resume, retention, free-space gate), but the destructive VM acceptance test (deliberately broken update -> sys undo -> detached reboot -> package-state check -> recovery with no network/model) has not been run. sys undo is present; treat VM verification as the gate before relying on it.
  • Mango + DankMaterialShell is the default desktop (desktop.profile = "mango", Flatpak on). It is implemented with Mango 0.17.2, DMS (pinned release), Quickshell 0.3.1 and scenefx 0.5 from the GURU overlay, a dwl fallback session and scoped ~amd64 keywords. The default is set by explicit owner decision; it has not been installed or booted in a graphical VM, so no desktop stability is claimed. docs/STATUS.md distinguishes "default in configuration", "successfully built" and "graphically verified".
  • The live desktop ISO (installer/live/build.sh) builds a Debian testing rootfs with Mango + DMS, live-only autologin, a branded welcome window and a graphical installer frontend over the typed bridge. Its desktop-payload guards are unit-tested, and the built ISO (sha256 2a52178c…, 1.6 GiB) was booted in a graphical, seat-providing VM: the welcome window opened automatically, the installer launched (a second launch created no duplicate), keyboard navigation reached the network and AI steps, and advancing without a connected model was refused. The same ISO was then installed non-interactively (INSTALL-RC=0, NO_SECRET_LEAK) and booted with the ISO detached (systemd running, 0 failed units, LUKS2, all Btrfs subvolumes, network). A live AI provider call was not possible (no key in this environment); the AI step is verified as a blocked prerequisite and with a fixture transport in unit tests. The installed Mango system (GURU + compiled Quickshell/DMS) and the dwl fallback in a VM are not yet verified.
  • AI sandbox is implemented (systemd-run hardening properties, tested at the argv level) and fails closed without systemd-run; it has not been exercised in a VM. Only typed actions and the privacy boundary were previously enforced.
  • Release automation now has gates, a report, atomic publish and signing command helpers, but no gate has been executed by a configured CI runner; the report records unexecuted gates as NotRun.
  • The desktop transaction compiles heavily because desktop USE does not match the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM). The official Gentoo binhost is OpenRC/hardened, so a systemd system can only reuse binaries for packages whose USE matches; the policy still requests signed binaries where it can. Publishing a matching binhost is future work.
  • Live AI provider calls are not verified. DeepSeek/OpenAI requests are built and reviewed by fixtures (phoebus-ai::provider::TestTransport) and the curl transport is covered by a recording runner; no call was made with a real key.
  • The installer rebuilds sys-apps/systemd from source because boot/policykit/cryptsetup USE differ from the binhost.
  • sys undo is implemented with the default-subvolume, fstab, kernel-cmdline and BLS handling described in ADR 0007; its destructive VM acceptance test is the remaining safety gate.