phoebus_os/docs/STATUS.md
2026-09-24 18:01:13 -07:00

18 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 + full journey n/a
Graphical welcome + install wizard (Quickshell) yes yes live graphical VM + full GUI journey no
Phoebus brand system (SVG + tokens) yes yes live VM n/a
Desktop profile (Mango + DarkMaterial) yes yes live VM + installed 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 (empty vs unestablished) no n/a
Transaction log (outcomes, protective snapshots) yes yes no no
Flatpak/Nix bounded typed actions yes yes no no
Shared hardware-aware source selection (all lanes) yes yes no no
Snap lane (detect/install/list/remove/refresh/connections) yes yes no no
AppImage lane (import/acquire/integrity/desktop/remove) yes yes no no
Custom ebuild overlay (stage/approve/build/remove) yes yes no no
sys installed into the target + verified in chroot yes yes (unit) yes (detached boot verified) no
AI-first install workflow (sys install, sys ask) yes yes explicit-backend journey; AI-selected not run no
Bounded AI investigation (typed read-only evidence) yes yes read-only actions on a booted VM no
Deterministic proposal validation (fabrication/stale/ambiguous/duplicate) yes yes no no
Explicit backend install flags (no fallback) yes yes yes (Portage install + remove, history) no
No-model unqualified install refuses and offers commands yes yes yes (matrix case) no
Install transaction begin/finish + verification yes yes yes (install verified; durable across reboot) no
Installed config loaded (/etc/phoebus/install.toml) yes no install writes it; sys reads it on the installed system no
sys consistent target-root execution yes yes no no
sys validation at the execution boundary yes yes no n/a
sys ask truthful failure (nonzero, stop, record) yes yes no n/a
Service start/stop/restart + flatpak/nix/snapshot commands yes yes no no
Desktop session helpers (DMS bar/launcher/lock/idle) yes yes functional test (stubs) no
Mango + DankMaterialShell profile yes yes live VM yes; installed desktop_install yes (174 pkgs) no
Mango is the canonical desktop yes yes live VM yes; installed default session configured no
greetd login (Mango + DarkMaterial) yes yes yes (tuigreet verified on detached boot) 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
Welcome primary action keyboard-focus yes guards tested live graphical VM no
VM harness disk safety + structured results yes yes (16 tests) n/a n/a
Target disk revalidation before partition yes yes no n/a
Bridge replay/concurrency + input bounds yes yes no n/a
Provider transport endpoint/size hardening yes yes no n/a
TargetRoot symlink-escape guard yes yes n/a n/a
OpenCode server capability probe yes yes real host probe + auth + policy n/a
OpenCode proposal adapter (real inference) yes yes real model (deepseek-v4-flash) n/a
OpenCode in GUI / CLI / sys ask yes yes GUI AI step + sys ask live n/a
OpenCode full graphical install yes yes yes (12 stages, 174 packages, detached boot) n/a
GUI readiness refresh / AI revalidation / keyboard nav yes yes (Rust) VM harness regressions n/a
Mandatory AI requires a validated interaction yes yes bridge + CLI n/a
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 PCI device classification + branch/flavor policy yes yes no no
NVIDIA installed Gentoo integration (Portage/modprobe/dracut/initramfs) yes yes no no
NVIDIA live ISO payload (bundled modules/firmware/userspace) yes yes (verifier + guards) no no
NVIDIA kernel/module/initramfs update coordination (@module-rebuild) yes yes no no
NVIDIA live GPU decision + real nouveau fallback yes yes (fixtures + CLI) no no
Live GUI broker scoped sudoers (no NOPASSWD: ALL) yes yes (visudo) no n/a
Rollback acceptance harness mode yes yes (bash -n/unit) destructive gate unrun no
Desktop assistant GUI (phoebus-assistant) yes yes yes (live VM layout) no
Desktop assistant JSON-RPC bridge (sys --assistant-bridge) yes yes yes (acceptance matrix) n/a
AI-first administration contract (sys install, please, ask) yes yes yes (acceptance matrix) no
Deterministic --legacy administration (fail-closed source choice) yes yes yes (acceptance matrix) n/a
Audited action execution (--legacy/--broker enforcement) yes yes yes (acceptance matrix) n/a
Nix attribute verification probe yes yes no n/a
Portage binary binhost verification + compile abort guard yes yes no n/a
Cross-source application ownership & user data preservation yes yes yes (acceptance matrix) no
Unified multi-source update management yes yes no no
Quiet proactive assistance monitor & deduplicated alerting yes yes no no
User preference profiles & project environment mappings yes yes no n/a
Shared administration service layer (service::*) & PreparedPlan staging yes yes yes (acceptance matrix) n/a
Authoritative privileged validation boundary (integrity/root/uid/state/claim) yes yes no (needs an authenticated VM boot) n/a
Protected per-user plan storage, atomic claim, tamper/traversal rejection yes yes no (needs an authenticated VM boot) n/a
Plan digests, target-root/uid binding, TTL, replay & concurrent-claim protection yes yes no n/a
Truthful transaction outcomes (failure/verify-fail/refusal/interruption) yes yes no n/a
AI-first removal (deterministic discovery underneath; --legacy bypasses) yes yes no n/a
GUI plan review card for every plan type; prepared ≠ completed yes no (QML) no (needs graphical VM) no
Shared provider/credential handling (ai_setup::*) for CLI and GUI yes yes no (no live credential) n/a
Contextual conversation continuity (conversation::*) yes yes yes (acceptance matrix) n/a
Conversation-history privacy (minimized, redacted, 0600, bounded, clearable) yes yes no n/a
Target desktop QML assets & Polkit policy provisioning yes yes yes (live VM layout) no
Desktop assistant unprivileged execution & Polkit elevation yes yes yes (live VM layout) 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 implemented (hardware-driven branch/flavor policy, scoped Portage configuration, a live payload that is build-time verified, and kernel/module/initramfs update coordination) and covered by Rust tests and the live-payload verifier. The policy now caps Maxwell/Pascal/Volta at the last supporting series (580) and reports a Blackwell plus proprietary-only GPU combination as an explicit incompatibility rather than installing one driver that cannot serve both. The live driver choice is a deterministic, device-class-based decision (--live-gpu-plan) with a real nouveau fallback, and the verifier rejects placeholders, cross-kernel module trees and version/flavor mismatches. The installed sequence now installs the driver and proves its modules exist before forcing them into the final initramfs. A minimal live rootfs with the stable kernel and NVIDIA driver was built and verified previously (driver 550.163.01, kernel 6.12.107+deb13-amd64, modules nvidia-current*). It is not verified on hardware or in the VM: this host has no NVIDIA GPU and QEMU's virtual GPU cannot establish NVIDIA acceleration; no passthrough setup is available or authorized. The full desktop ISO was not assembled here (the host has ~12 GiB free; the build wants more) and the live/installed NVIDIA boot gates are unrun. See docs/VM-BOOT-VERIFICATION.md for the exact unblock commands. The live kernel is pinned to Debian stable (trixie 6.12 LTS) because testing's kernel (7.2) breaks Debian's 550 driver; the bundled branch covers Maxwell through Hopper, and Blackwell (or a failed accelerated load) falls back to nouveau on the live medium. The installed Gentoo system uses the current branch with NVIDIA's open kernel modules on Turing and newer.
  • The installed sys binary and desktop assistant (phoebus-assistant): The installer provisions sys into /usr/local/bin/sys and configures the desktop assistant Quickshell application (phoebus-assistant) launched via desktop entries and keybindings. On the installed system, all 22 acceptance test cases in installer/tests/vm/sys-acceptance.sh pass cleanly (PASS=22 FAIL=0), verifying the unified AI-first CLI/GUI interface, deterministic --legacy mode, fail-closed source requirements, audited --broker/--legacy gates, proactive system monitors, and offline fallback guidance.
  • UKI is deferred; the dracut UKI generator did not embed the kernel command line, so BLS is used (and verified).
  • Rollback (sys undo) is NOT VM-verified. It 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). The harness now automates the acceptance sequence (serial-driver.py rollback + rollback-guest.sh / rollback-verify.sh): a known-good package-database fingerprint and /home marker, sys snapshot, a controlled reversible package install, sys undo, detached reboot, then package-state/home comparison, kernel-module check and recovery-entry/status evidence. The destructive gate itself is unrun in this session: a full GUI install was occupying the only disposable disk. make doctor now reports ~29 GiB free (the disk blocker recorded in the last handoff has eased), but the acceptance run needs a dedicated already-installed disposable clone; the exact commands are in docs/HANDOFF.md. Booting the recovery entry offline is still a manual step. sys undo is present; treat the VM gate as unpassed before relying on it.
  • Mango + DankMaterialShell is the canonical Phoebus 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 and scoped ~amd64 keywords. Standalone dwl has been retired completely; Phoebus has one desktop experience only. The desktop is verified in live graphical VM and detached booted VM installations.
  • 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. The rebuilt ISO (sha256 0c386a1b…, 1.6 GiB, build id in /etc/phoebus/build) was booted in a graphical, seat-providing VM. The gui journey passed 28/28 checks (welcome autostart, launcher from the keyboard, duplicate prevention, the live medium protected, keyboard suggestion selection, the network and AI steps, the AI gate refused without a model and reported inline, no bridge errors) and the opencode journey passed 18/18 (real model response, validated proposal, and editing the model invalidating the validated state). The gui-install journey passed every assertion on a fresh 30 GiB qcow2 — OpenCode connect/review/accept, disk, account, ERASE and confirmation — and the backend then reported real stages with elapsed time and no fabricated percentage. The completed install succeeded through all 12 stages, compiled all 174 packages of the Mango desktop profile, and confirmed completion (gui-install-completes passed). The installed system then booted with the ISO detached (LUKS2 decrypt, systemd running, 0 failed units, all Btrfs subvolumes mounted, sys CLI operational, and tuigreet greeter active). The installed Mango session (graphical user login into DMS) remains to be verified under a physical seat / DRM compositor backend.
  • 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.