docs: reconcile NVIDIA, verification and harness status
Some checks are pending
ci / test (push) Waiting to run

Record the reliability pass across STATUS, HANDOFF, CHANGELOG, ADR 0012,
the live README and the boot-verification log: the deterministic live GPU
decision with a real nouveau fallback, the 580 legacy cap and mixed
open/proprietary incompatibility, the compatibility verifier, the
installed lifecycle fix, the repaired GUI harness, the automated but
unrun rollback gate, and the scoped live sudoers. Withdraw the stale
handoff claim that the gui_bridge tests hang (the workspace suite
passes) and record the installed-target missing-sys gap.
This commit is contained in:
Phoebus 2026-09-23 06:28:30 -07:00
parent 4265aefacd
commit 3b1b54ffb9
6 changed files with 282 additions and 183 deletions

View file

@ -3,6 +3,57 @@
All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary.
## 2026-09-23 — NVIDIA reliability, verification and harness repair
- **Deterministic live GPU decision (`phoebus-core`, `phoebus-installer`):**
`--live-gpu-plan` classifies the PCI display controllers (class `0x03`,
vendor `0x10de`) against the generated device table and the bundled branch's
capabilities, returning `load-nvidia`, `nouveau-fallback`, `no-device` or
`disabled`. The live `phoebus-nvidia-load` script consumes it: a supported GPU
loads the accelerated stack, an unsupported GPU (or a failed load) explicitly
`modprobe`s `nouveau`, and a machine without an NVIDIA display device is left
alone. `build.sh` now creates `etc/modprobe.d/phoebus-nvidia.conf` (the file
the old build required but never produced) and replaces Debian's
unconditional nouveau configuration. The fail-safe entry sets
`nomodeset phoebus.nvidia=off`, which the script and the unit both honour.
- **Legacy branch boundary corrected (`phoebus-core`):** Maxwell/Pascal/Volta
are capped at NVIDIA's last supporting series (580) with
`>=x11-drivers/nvidia-drivers-581` masked; a Blackwell plus proprietary-only
GPU set is now reported as an explicit incompatibility instead of installing a
single driver that cannot serve both.
- **Payload verifier hardened (`phoebus-executor`):** `--verify-live-nvidia`
now rejects placeholder modules/libraries, requires every module to be
registered in the live kernel's `modules.dep`, normalises the dpkg revision
and matches userspace/firmware versions to the bundled driver, infers and
checks the module flavor, and requires the exact `phoebus-nvidia.conf`. All
reads stay rooted inside the build root.
- **Installed lifecycle fixed (`phoebus-executor`, `phoebus-installer`):** the
NVIDIA dracut `force_drivers` fragment is written only in the NVIDIA stage,
after the driver exists, and the final initramfs is regenerated then. The
installer proves the modules were built for a kernel (or fails) and records
the real resolved version, kernel and module names. The update path verifies
the rebuilt modules before reporting success.
- **GUI acceptance harness repaired (`installer/tests/vm/gui-driver.py`):**
state-based step navigation replaces the step-0 keystroke count; the real
account fields and the default single-password encryption are driven; the
direct "Install now" action replaces ERASE typing and the (never-assigned)
confirmation toggle; duplicate submission is exercised; install timeouts
report stage, elapsed time and last state; the detached boot unlocks with the
single-password passphrase and falls back to the separate one.
- **Rollback acceptance automated (`installer/tests/vm/`):** a new
`serial-driver.py rollback` mode with `rollback-guest.sh` /
`rollback-verify.sh` records the package-database fingerprint and a `/home`
marker, creates a recovery point with `sys snapshot`, performs a controlled
reversible package install, runs `sys undo`, reboots detached and compares
package state and `/home`. The destructive VM gate is written but unrun.
- **Live privilege scoped (`phoebus-core`, `installer/live`):** the live
`NOPASSWD: ALL` rule is replaced by an emitted, `visudo`-validated policy that
grants unattended escalation only to the typed brokers
(`phoebus-installer`, `sys`) and `systemctl` power actions. The recovery
console is preserved via the password-authenticated live credential.
- Docs: ADR 0012 updated; the stale "`gui_bridge` tests hang" handoff claim
withdrawn (the workspace suite passes).
## 2026-09-23 — Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI
- **Streamlined 6-Step Flow (`phoebus-install`, QML):**

View file

@ -3,144 +3,127 @@
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-23), Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI.
- **Last updated:** this session (2026-09-23), NVIDIA reliability and
verification pass: live driver decision, verifier hardening, installed
lifecycle, rollback harness, GUI harness repair, scoped live privilege.
- **Current focus:**
1. Streamlined 6-Step Flow: eliminated Step 0 duplicate welcome screen in installer, starting directly at "Step 1 of 6 · Language and keyboard", hiding "Back" on Step 1, and rendering 6 accurate progress dots.
2. Friendly Keyboard & Locale Pickers: parsed full names from `evdev.lst`, sorted top 30 world layouts first, dynamic keymap switching on select via `localectl set-x11-keymap`, auto-detected timezone, and auto-closing sibling combos on dropdown open.
3. Cleaned Welcome Screen: removed redundant "Keyboard test" button and modal from live welcome app.
4. Simplified Credentials: single password toggle ("Use same password to encrypt disk") default enabled, single username field (no fullname prompt), and removed 8-char minimum limit.
5. Direct Review & Confirmation: replaced typing "ERASE" in all caps and checkboxes with a direct "Install now" button on the review screen.
6. Subsystem & Desktop Invariants: enforced Mango + DMS desktop, Btrfs filesystem, and Flatpak/Nix in both AI prompt and validator.
7. Local AI Auto-Detection & Guidance: auto-probes ports 4096 (OpenCode) and 11434 (Ollama), replaces technical jargon with friendly instructions.
8. Humanized Error Handling: calm, user-friendly failure explanations with [Retry] and [View technical details] buttons; working live details box with auto-scroll.
1. **Deterministic live NVIDIA decision.** `phoebus-installer
--live-gpu-plan` classifies the actual PCI display controllers against the
bundled branch and returns `load-nvidia` / `nouveau-fallback` /
`no-device` / `disabled`; the old `0x10de`-vendor grep is gone. An
unsupported GPU (or a failed load) explicitly `modprobe`s `nouveau`, and
the fail-safe entry sets `nomodeset phoebus.nvidia=off` which the script
and unit both honour.
2. **Live payload gate is a compatibility gate.** It rejects placeholder
modules/libraries, requires registration in the live kernel's
`modules.dep`, matches userspace/firmware versions to the bundled driver,
infers and checks the module flavor, and requires the exact
`etc/modprobe.d/phoebus-nvidia.conf` (now produced by `build.sh`).
3. **Branch boundary corrected.** Maxwell/Pascal/Volta are capped at the last
supporting series (580) instead of `<595`; a Blackwell plus
proprietary-only GPU is reported as an explicit incompatibility.
4. **Installed lifecycle.** The NVIDIA `force_drivers` fragment is written
only after the driver exists; the installer proves the modules built for a
kernel and records the real version/kernel/module names.
5. **GUI harness repaired** for the six-step installer (no step 0, no ERASE,
no confirmation toggle, single-password account); state-based step
navigation; boot uses the single-password disk passphrase.
6. **Rollback acceptance automated** as `serial-driver.py rollback`.
7. **Live privilege scoped:** `NOPASSWD` only for the two typed brokers and
`systemctl` power actions; the recovery console uses the live password.
- **Last verified (this session):**
- All workspace tests pass: `cargo fmt`, `cargo clippy`, and `cargo test --workspace` pass 100% (47 phoebus-installer tests, 36 phoebus-ai tests, etc.).
- Static release binary built and deployed to live VM.
- Interactive live VM tested and verified with screenshots:
- Welcome app shows clean action buttons with "Keyboard test" completely removed.
- Installer launches in full screen without 50/50 window tiling splits.
- Installer starts directly at Step 1 of 6 with human-readable language, keyboard, and timezone pickers.
- Sibling combos auto-close when another is expanded; search filtering is active.
- OpenCode local loopback auto-detected on port 4096.
- Disk selection, account credentials, single-password toggle, and "Install now" button all verified.
- Failure screen displays humanized explanation and expands technical details on request.
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
finished with 0 errors (pre-existing warnings only).
- All tests pass for `phoebus-core` (142), `phoebus-ai` (35),
`phoebus-executor` (129), `phoebus-tui`, and every `phoebus-installer`
integration test (`plan_golden`, `cli_coverage` incl. the new
`--verify-live-nvidia` gate, `live_iso`, `ai_guidance`, `sys_cli`); the
non-`gui_bridge` installer library tests pass. The `gui_bridge` dry-run
tests block in this environment (pre-existing; unrelated to this change).
- New tests: PCI classification (representative IDs), branch/flavor policy,
Kepler/unknown fallback, hybrid, package/`modprobe`/dracut config, plan
exposure and stage ordering, live-payload verification (complete, missing
module, missing userspace/firmware, missing kernel, Debian `nvidia-current*`
naming), the AI refusal, and the `@module-rebuild`/`kernel-install` update
coordination.
- **Live NVIDIA payload build proven**: a minimal `mmdebstrap` rootfs
(Debian testing userspace + the pinned stable kernel) built the DKMS modules
and passed `--verify-live-nvidia` end to end: driver `550.163.01`, kernel
`6.12.107+deb13-amd64`, modules `nvidia-current/-modeset/-uvm/-drm`,
userspace + EGL/GBM + firmware present. The live kernel is now pinned to
Debian stable because testing's 7.2 kernel removed `strncpy` and breaks the
550 driver.
- **Not yet verified this session:** the **full desktop live ISO** was not
assembled (host disk ~10 GiB free; the build wants more), and the live/
installed NVIDIA boot gates are unrun: this host has no NVIDIA GPU (see
blockers). Actual NVIDIA acceleration is **not** verified. Rollback
(`sys undo`), the AI sandbox, the physical-seat desktop and a separate
physical computer remain open as before.
- `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets`
(0 errors) and `cargo test --workspace` all pass. The `gui_bridge` dry-run
tests **do not hang** on this checkout: the earlier "block" note was stale
and is withdrawn.
- `installer/tests/vm/test_vmsafety.py` (18 tests) passes, including `bash -n`
over every guest script.
- Py-compile clean for `gui-driver.py`, `serial-driver.py`, `live-driver.py`.
- The emitted live sudoers policy is validated with host `visudo` in a unit
test and at build time.
- New coverage: `live_nvidia_plan` decisions, sysfs device scan + CLI
fixtures, mixed-hardware incompatibility, verifier negatives (placeholders,
stale `modules.dep`, version/flavor mismatch, missing final config),
installed module proof + version record, and the ordering fix.
- **Not yet verified this session (unchanged blockers):** the **full desktop
live ISO** is still not assembled (host has ~12 GiB free; `make doctor` wants
>=20 GiB), so the `gui`/`opencode`/`gui-install` journeys were **not re-run**
against the repaired harness, and the NVIDIA live/installed boot gates are
unrun (no NVIDIA GPU). The rollback harness is written and unit-checked but
its destructive VM gate is **unrun**. `sys` is not installed into the target
(see below).
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
(or an explicitly authorized passthrough VM) boot the built live ISO and the
installed system and confirm: `phoebus-nvidia.service` loaded the driver,
`nvidia-smi` works, `cat /sys/module/nvidia_drm/parameters/modeset` is `Y`,
Mango/DMS logs in accelerated, XWayland/Flatpak render, monitors and
suspend/resume work, and a kernel update rebuilds the modules and initramfs.
Needs an NVIDIA GPU; none is available here and passthrough must not be
reconfigured unilaterally.
2. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
now bundles and verifies the NVIDIA payload. It needs more free space than
the ~12 GiB this host has; free space (do not delete unrelated files) and run
the `gui` harness to confirm ordinary virtual-GPU boot is unchanged.
3. **Installed Mango desktop**: install the default profile (Mango + DMS) in a
graphical VM and verify the panel/launcher/terminal/audio/network/lock/idle,
the dwl fallback, and the welcome/installer absence on the installed system.
4. **Rollback VM acceptance (BLOCKED)**: deliberately break an update, run
`sys undo`, reboot detached, verify `/var/db/pkg` matches `/`, then boot the
recovery entry with no network or model (ADR 0007). Needed: (a) free the
>=20 GiB `make doctor` wants for the harness; (b) an automated driver for the
break-update/undo/recovery sequence — the harness has no such mode.
5. **Narrow the live broker privilege**: replace the live-only `NOPASSWD: ALL`
rule for the GUI bridge with the smallest practical command-scoped rule once
a safe sudoers form is verified (ADR 0011 context).
6. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
1. **Run the repaired GUI harness** once disk allows: `gui`, `opencode`, then
`gui-install` + detached `boot`. It now expects the six-step flow and the
direct "Install now" action. Serve `live.pw` (0600) alongside `test.conf`,
`luks.pw` and `user.pw` for the `gui-install` preseed.
2. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
boot the live ISO and the installed system and confirm the accelerated stack,
`nvidia_drm` modeset, Mango/DMS acceleration, XWayland/Flatpak, and a kernel
update that rebuilds the modules and initramfs. Needs an NVIDIA GPU.
3. **Rollback VM acceptance (BLOCKED on disk + a clone)**: create an installed
disposable clone, then `serial-driver.py rollback`. The gate and the exact
evidence markers are implemented; it has not executed.
4. **Install `sys` into the target**: the installed system still lacks the
deterministic CLI, so the no-model fallback contract is only partially
shipped. This blocks a pure product-path rollback test.
5. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
now also emits and `visudo`-validates the scoped sudo policy and produces the
live NVIDIA config. Free space and run the `gui` harness.
6. **Installed Mango desktop**: install the default profile in a graphical VM
and verify panel/launcher/terminal/audio/network/lock/idle and the dwl
fallback; a no-desktop run is a separate baseline.
7. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed.
## Known blockers / risks
- **NVIDIA hardware verification is BLOCKED**: this host has no NVIDIA GPU and
QEMU's virtual GPU cannot establish NVIDIA acceleration; no passthrough setup
is available or authorized. Unit/integration tests and the live-payload
verifier pass, and a minimal live rootfs with the driver was built and
verified, but no NVIDIA-accelerated boot has been observed. The **full desktop
ISO** also cannot be assembled here: `df` shows ~10 GiB free. Unblock by
providing an NVIDIA GPU (or an authorized passthrough VM) and freeing disk
space, then running `installer/live/build.sh` and the `gui`/`install`/`boot`
harness modes. Note: the live kernel is pinned to Debian stable because
testing's 7.2 kernel breaks Debian's 550 driver; revisit when Debian ships a
matching driver.
- **The complete graphical install and detached boot are BLOCKED on host build
time.** The `gui-install` journey passes every assertion and starts a real
install, but on this host the base packages take ~116 min and the
(AI-selected) optimized kernel was still compiling after 100 min, so the 4h
harness timeout fired. Two completed fresh-disk GUI installs + detached boot
therefore remain unrun here. The deterministic noninteractive install +
detached boot is the proven path.
- **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor
is the dwl fallback session. The `gui-install` journey intentionally preseeded
a no-desktop, safe-kernel configuration to bound the harness run, so it proves
the wizard and the install pipeline, not the desktop build.
- **Rollback (`sys undo`) is implemented and unit-tested but NOT VM-verified
(BLOCKED).** Exact blockers: `make doctor` reports ~13 GiB free versus the
>=20 GiB the harness wants, and the harness has no automated
break-update/undo/recovery-boot mode. The AI sandbox is likewise
implemented/unit-tested but not VM-verified. NVIDIA is not verified.
- A **separate physical computer** for the OpenCode transport test is not
available (BLOCKED); a forwarded-hop + unauthenticated-LAN-refusal host-local
test was done instead.
- The GUI bridge reaches Quickshell via `Process` + `/usr/bin/sudo -n`; it
relies on the live user's passwordless sudo. The live sudoers rule is still
`NOPASSWD: ALL` (live-only); narrowing the broker permission is future work.
- **Disk is the harness constraint.** `make doctor` reports ~12 GiB free versus
the >=20 GiB the VM harness wants. This blocks assembling the full desktop
ISO and the rollback acceptance run. Do not delete unrelated files.
- **No NVIDIA GPU** (and no authorised passthrough): actual acceleration cannot
be verified here. The live decision and verifier are device-based and
unit/fixture-tested only.
- **`sys` is absent from the installed target.** The live medium and the
`phoebus-assistant` launcher use `sys`, and the rollback harness fetches it
from the host, but the installed system has no `/usr/local/bin/sys`. Fixing it
(embedding the static `sys` binary in the install) is future work.
- **The `gui-install` completion is still host-time bound**: the base package
stage took ~116 min and the AI-selected kernel was still compiling at the 4 h
timeout. The deterministic noninteractive install + detached boot remains the
proven path.
- **Installed** Mango (GURU + compiled Quickshell/DMS) and the dwl fallback are
still not VM-verified.
- **Recovery-entry offline boot** is not automated: the rollback harness records
the snapshot recovery entry but does not select it in the bootloader.
- The live appliance guest scripts (`appliance-guest.sh`,
`appliance-guest-gui.sh`) still use `sudo -n`/`poweroff` and a
`/run/live/medium/phoebus/bin/phoebus` launcher path; they predate the scoped
policy and would need the live password if re-run against the narrowed image.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick present.
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
present. ~12 GiB free on the root filesystem.
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`); the appliance ISO builds without root.
- Local QML iteration: `/tmp/opencode/run-qml.sh <config-dir>` runs a config on
a nested Mango over the host X11 using the built rootfs libraries, and
`grim` captures it. The sanctioned verification is the disposable VM.
- VM harnesses: `installer/tests/vm/gui-driver.py` (graphical live ISO:
`gui`/`opencode`/`gui-install`/`install`/`boot`), `appliance-driver.py`,
`serial-driver.py`. `DISK` must be a disposable qcow2; never point it at
`/dev/*`. A `gui-install` run leaves its installed disk for a following
`boot` run.
- Serve the install fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
(matches `installer/live/base.sha256`).
- VM harnesses: `installer/tests/vm/gui-driver.py` (`gui`/`opencode`/
`gui-install`/`install`/`boot`), `serial-driver.py`
(`install`/`boot`/`rollback`), `appliance-driver.py`, `live-driver.py`.
`DISK` must be a disposable qcow2; never point it at `/dev/*`.
- Serve fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`),
including `live.pw` for the `gui-install` preseed and `rollback-guest.sh`,
`rollback-verify.sh` and `sys` for the rollback mode.
## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed and pushed
(`scripts/agent-commit.sh` + `scripts/publish.sh`).
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
pushed (`scripts/publish.sh`).

View file

@ -118,6 +118,10 @@ still not VM-verified.
| 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 |
| NVIDIA installed lifecycle (driver before final initramfs, module proof) | yes | yes | 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 |
| UKI | no (deferred) | no | no | no |
## Known limitations
@ -131,33 +135,49 @@ still not VM-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. A minimal live rootfs with the stable kernel and NVIDIA
driver was **built and verified** this session (driver 550.163.01, kernel
6.12.107+deb13-amd64, modules `nvidia-current*`). It is **not verified on
hardware**: 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 ~10 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 Ada/Hopper, and Blackwell 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.
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 target does not install the `sys` binary.** The deterministic
CLI is present on the live medium and on the installed desktop's
`phoebus-assistant` launcher (which calls `sudo sys ask`), but the installed
system has no `/usr/local/bin/sys`: the harness fetches it from the host to
exercise rollback. This is a real gap against the "operate and repair by hand"
contract and is recorded as future work; it also blocks the rollback harness
from being a pure product-path test.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **Rollback 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), but the destructive acceptance test (deliberately broken update ->
`sys undo` -> detached reboot -> package-state check -> recovery with no
network/model) was **not run in this session**. Blockers: (1) `make doctor`
reports only ~13 GiB free versus the >=20 GiB the VM harness wants, and the
root filesystem has ~12 GiB free; (2) the committed appliance/serial harness
only implements `install` and `boot` modes — there is no automated driver for
the break-update / `sys undo` / recovery-boot sequence, which is documented as
an interactive procedure. `sys undo` is present; treat VM verification as the
gate before relying on it.
- **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**:
`make doctor` reports ~12 GiB free versus the >=20 GiB the harness wants, and
there is no already-installed disposable clone available. 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 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

View file

@ -399,13 +399,23 @@ 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.
**2026-09-23 update — rollback acceptance automated, still NOT run.** The
missing driver now exists: `serial-driver.py rollback` (with
`rollback-guest.sh` and `rollback-verify.sh`) performs the full sequence,
including a `/var/db/pkg` fingerprint comparison and a `/home` survival check,
and `bash -n` guards run in `test_vmsafety.py`. The **destructive VM gate
itself is unrun**: `make doctor` reports ~12 GiB free versus the >=20 GiB the VM
harness requires, and no already-installed disposable clone is available.
Booting the recovery entry offline is still a manual step. `sys undo` therefore
remains **unverified**, not passing.
**2026-09-23 update — NVIDIA gates still NOT run.** The live driver decision,
the hardened payload verifier and the installed lifecycle are implemented and
covered by Rust/fixture tests, but no NVIDIA-accelerated boot has been observed:
no NVIDIA GPU is present and QEMU's virtual GPU cannot establish acceleration.
The full desktop ISO was not assembled (disk), so the ordinary virtual-GPU
`gui`/`install`/`boot` journeys were not re-run against the repaired harness
either.
## Mango + DankMaterialShell verification (IN PROGRESS)

View file

@ -14,11 +14,14 @@ Phoebus must run NVIDIA's official accelerated driver stack on both targets:
NVIDIA's Linux driver has three relevant regimes (verified 2026-09 against
NVIDIA/Gentoo and the PCI ID database):
- **Turing (GTX 16xx / RTX 20xx) and newer** can use NVIDIA's **open kernel
modules** (`kernel-open`). The open modules are *recommended* from 560 and
*mandatory* from 595; Blackwell (RTX 50xx) requires them.
- **Turing (GTX 16xx / RTX 20xx) through Hopper** can use NVIDIA's **open
kernel modules** (`kernel-open`). The open modules are *recommended* from 560
and *mandatory* from 595.
- **Blackwell (RTX 50xx)** *requires* the open kernel modules; the proprietary
kernel modules cannot drive it.
- **Maxwell, Pascal and Volta** cannot use the open modules and need the
proprietary modules from a branch that still supports them.
proprietary modules. NVIDIA's **580 series is the last** to support them; the
next series drops those architectures.
- **Fermi, Kepler and older** have no security-supported proprietary branch;
the in-tree `nouveau` driver is the honest choice.
@ -40,15 +43,24 @@ never claimed as supported.
### 2. Deterministic branch/flavor selection
One driver install covers every adapter, so the branch must serve the **oldest**
supported GPU present:
One driver install covers every adapter, so the branch is computed **across the
whole device set** rather than assuming the oldest card's branch serves the
newer ones:
| Generation | Branch | Module flavor | Portage |
| --- | --- | --- | --- |
| Turing / Ampere / Ada / Hopper / Blackwell | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Maxwell / Pascal / Volta | proprietary | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-595` |
| Turing / Ampere / Ada / Hopper | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Blackwell | current | open required (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Maxwell / Pascal / Volta | proprietary (580 is the last series) | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-581` |
| Fermi / Kepler and older | none (nouveau) | — | no NVIDIA package |
A Blackwell GPU (open-only) together with a Maxwell/Pascal/Volta GPU
(proprietary-only) has **no single compatible branch**. The plan reports that
incompatibility explicitly and leaves the adapters on `nouveau` instead of
installing one driver that cannot accelerate one of the cards. Pascal plus a
Turing-class GPU stays proprietary and supported, because the newer generation
accepts either flavor.
Hybrid Intel/AMD GPUs keep their `VIDEO_CARDS` entries; the NVIDIA decision
only adds `nvidia`, or `nouveau` when the card is unserved.
@ -80,8 +92,21 @@ override it.
- The signed Debian `contrib`/`non-free`/`non-free-firmware` components supply
the driver. Debian 13/testing ships branch **550.163.01**, whose proprietary
modules cover Maxwell through Ada/Hopper. **Blackwell is unsupported by that
modules cover Maxwell through Hopper. **Blackwell is unsupported by that
branch**; on live it falls back to nouveau, reported, never silently claimed.
- The live driver choice is **deterministic and device-based**:
`phoebus-installer --live-gpu-plan` enumerates the PCI display controllers
(class `0x03`, vendor `0x10de`), classifies them against the generated
device table, and decides `load-nvidia`, `nouveau-fallback`, `no-device` or
`disabled`. It never matches on a vendor name alone.
- `nouveau` is blacklisted so it cannot *auto-bind* a supported GPU, but an
unsupported GPU (or a failed accelerated load) explicitly `modprobe`s
`nouveau`, so the documented fallback is real. The fail-safe GRUB entry sets
`nomodeset phoebus.nvidia=off`; the load script and the unit both stand down
on that command line, so recovery intent is authoritative.
- The live policy file `etc/modprobe.d/phoebus-nvidia.conf` is created by
`build.sh` (not only on the installed Gentoo target) and replaces Debian's
unconditional nouveau configuration.
- The **live kernel is pinned to Debian stable (trixie, 6.12 LTS)**. Testing's
current kernel (7.2) removed the `strncpy` declaration the 550 driver still
uses, so `nvidia-kernel-dkms` cannot build against it; the rolling kernel
@ -91,11 +116,15 @@ override it.
any module is missing. Debian renames them `nvidia-current*`; the hook and the
verifier accept either that or the upstream names.
- `build.sh` runs `--verify-live-nvidia` on **every** build (including
`PHOEBUS_REUSE_ROOTFS=1`): it checks modules, userspace libraries,
`nvidia-smi`, EGL external-platform manifests, firmware, the gated load script
and the nouveau blacklist, and records the bundled driver version, module
flavor and kernel in `/etc/phoebus/nvidia`. A missing or mismatched component
fails the build.
`PHOEBUS_REUSE_ROOTFS=1`). It is a compatibility gate, not a presence list:
it rejects placeholder modules/libraries, requires every module to be
registered in the live kernel's `modules.dep`, normalises the dpkg revision
and requires the userspace `libnvidia-glcore` and firmware-directory versions
to match the bundled driver, infers and checks the module flavor, requires a
non-empty GSP firmware and the exact `etc/modprobe.d/phoebus-nvidia.conf`,
and keeps every read rooted inside the build root. It records the bundled
driver version, module flavor and kernel in `/etc/phoebus/nvidia`. Any
missing or mismatched component fails the build.
- Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of a gated service that loads the driver before greetd/Mango **only

View file

@ -116,24 +116,30 @@ anything at boot.
`nvidia-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`,
`nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook
accept either that naming or the upstream names.
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`, which checks
the kernel modules, the GLVND/EGL/GBM userspace libraries, `nvidia-smi`, the
EGL external-platform manifests, the GSP firmware, the gated load script and
the nouveau blacklist. It runs on **every** build, including
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship without
the payload. The bundled driver version, module flavor and kernel are recorded
in `/etc/phoebus/nvidia` on the medium.
- Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of the live-only `phoebus-nvidia.service`, which runs the gated
`phoebus-nvidia-load` before greetd/Mango **only when an NVIDIA display device
is present**, so systems without one keep nouveau/virtio and record no failed
unit.
- The GRUB **fail-safe graphics** entry disables modesetting
(`nomodeset`) and blacklists the NVIDIA modules for that boot; it is the
documented recovery path when driver initialisation misbehaves. Use
`phoebus-gpu-report` for read-only diagnostics (PCI devices, loaded modules,
`nvidia_drm` modeset, `nvidia-smi`, recent kernel messages).
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`. It is a
compatibility gate, not a presence list: it rejects placeholder
modules/libraries, requires every module to be registered in the live kernel's
`modules.dep`, checks the userspace `libnvidia-glcore` and firmware-directory
versions against the bundled driver, infers and checks the module flavor,
requires non-empty GSP firmware and the exact
`etc/modprobe.d/phoebus-nvidia.conf`. It runs on **every** build, including
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship a
mismatched payload. The bundled driver version, module flavor and kernel are
recorded in `/etc/phoebus/nvidia` on the medium.
- The live load script makes a **deterministic, device-based decision** via
`phoebus-installer --live-gpu-plan`, not a `0x10de` vendor grep. A supported
GPU loads the bundled accelerated stack; an unsupported GPU (or a failed
accelerated load) explicitly `modprobe`s `nouveau`; a machine with no NVIDIA
display device leaves auto-detection alone. `build.sh` writes
`etc/modprobe.d/phoebus-nvidia.conf` (replacing Debian's unconditional
nouveau configuration), so the fallback is real. Debian's unconditional
modules-load entry is removed in favour of `phoebus-nvidia.service`, which
runs the script before greetd/Mango.
- The GRUB **fail-safe graphics** entry sets `nomodeset phoebus.nvidia=off` and
blacklists the NVIDIA modules for that boot; the load script and the unit both
stand down, so recovery intent is authoritative. Use `phoebus-gpu-report` for
read-only diagnostics (PCI devices, loaded modules, `nvidia_drm` modeset,
`nvidia-smi`, recent kernel messages).
- The installed Gentoo target is unaffected: it uses Portage
(`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI
device IDs — open kernel modules for Turing and newer, the proprietary branch