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`; All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary. 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 ## 2026-09-23 — Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI
- **Streamlined 6-Step Flow (`phoebus-install`, QML):** - **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 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. 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:** - **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. 1. **Deterministic live NVIDIA decision.** `phoebus-installer
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. --live-gpu-plan` classifies the actual PCI display controllers against the
3. Cleaned Welcome Screen: removed redundant "Keyboard test" button and modal from live welcome app. bundled branch and returns `load-nvidia` / `nouveau-fallback` /
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. `no-device` / `disabled`; the old `0x10de`-vendor grep is gone. An
5. Direct Review & Confirmation: replaced typing "ERASE" in all caps and checkboxes with a direct "Install now" button on the review screen. unsupported GPU (or a failed load) explicitly `modprobe`s `nouveau`, and
6. Subsystem & Desktop Invariants: enforced Mango + DMS desktop, Btrfs filesystem, and Flatpak/Nix in both AI prompt and validator. the fail-safe entry sets `nomodeset phoebus.nvidia=off` which the script
7. Local AI Auto-Detection & Guidance: auto-probes ports 4096 (OpenCode) and 11434 (Ollama), replaces technical jargon with friendly instructions. and unit both honour.
8. Humanized Error Handling: calm, user-friendly failure explanations with [Retry] and [View technical details] buttons; working live details box with auto-scroll. 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):** - **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.). - `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets`
- Static release binary built and deployed to live VM. (0 errors) and `cargo test --workspace` all pass. The `gui_bridge` dry-run
- Interactive live VM tested and verified with screenshots: tests **do not hang** on this checkout: the earlier "block" note was stale
- Welcome app shows clean action buttons with "Keyboard test" completely removed. and is withdrawn.
- Installer launches in full screen without 50/50 window tiling splits. - `installer/tests/vm/test_vmsafety.py` (18 tests) passes, including `bash -n`
- Installer starts directly at Step 1 of 6 with human-readable language, keyboard, and timezone pickers. over every guest script.
- Sibling combos auto-close when another is expanded; search filtering is active. - Py-compile clean for `gui-driver.py`, `serial-driver.py`, `live-driver.py`.
- OpenCode local loopback auto-detected on port 4096. - The emitted live sudoers policy is validated with host `visudo` in a unit
- Disk selection, account credentials, single-password toggle, and "Install now" button all verified. test and at build time.
- Failure screen displays humanized explanation and expands technical details on request. - New coverage: `live_nvidia_plan` decisions, sysfs device scan + CLI
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets` fixtures, mixed-hardware incompatibility, verifier negatives (placeholders,
finished with 0 errors (pre-existing warnings only). stale `modules.dep`, version/flavor mismatch, missing final config),
- All tests pass for `phoebus-core` (142), `phoebus-ai` (35), installed module proof + version record, and the ordering fix.
`phoebus-executor` (129), `phoebus-tui`, and every `phoebus-installer` - **Not yet verified this session (unchanged blockers):** the **full desktop
integration test (`plan_golden`, `cli_coverage` incl. the new live ISO** is still not assembled (host has ~12 GiB free; `make doctor` wants
`--verify-live-nvidia` gate, `live_iso`, `ai_guidance`, `sys_cli`); the >=20 GiB), so the `gui`/`opencode`/`gui-install` journeys were **not re-run**
non-`gui_bridge` installer library tests pass. The `gui_bridge` dry-run against the repaired harness, and the NVIDIA live/installed boot gates are
tests block in this environment (pre-existing; unrelated to this change). unrun (no NVIDIA GPU). The rollback harness is written and unit-checked but
- New tests: PCI classification (representative IDs), branch/flavor policy, its destructive VM gate is **unrun**. `sys` is not installed into the target
Kepler/unknown fallback, hybrid, package/`modprobe`/dracut config, plan (see below).
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.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os> - **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222). (remote `origin`, SSH port 2222).
## Next actions (in order) ## Next actions (in order)
1. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU 1. **Run the repaired GUI harness** once disk allows: `gui`, `opencode`, then
(or an explicitly authorized passthrough VM) boot the built live ISO and the `gui-install` + detached `boot`. It now expects the six-step flow and the
installed system and confirm: `phoebus-nvidia.service` loaded the driver, direct "Install now" action. Serve `live.pw` (0600) alongside `test.conf`,
`nvidia-smi` works, `cat /sys/module/nvidia_drm/parameters/modeset` is `Y`, `luks.pw` and `user.pw` for the `gui-install` preseed.
Mango/DMS logs in accelerated, XWayland/Flatpak render, monitors and 2. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
suspend/resume work, and a kernel update rebuilds the modules and initramfs. boot the live ISO and the installed system and confirm the accelerated stack,
Needs an NVIDIA GPU; none is available here and passthrough must not be `nvidia_drm` modeset, Mango/DMS acceleration, XWayland/Flatpak, and a kernel
reconfigured unilaterally. update that rebuilds the modules and initramfs. Needs an NVIDIA GPU.
2. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh` 3. **Rollback VM acceptance (BLOCKED on disk + a clone)**: create an installed
now bundles and verifies the NVIDIA payload. It needs more free space than disposable clone, then `serial-driver.py rollback`. The gate and the exact
the ~12 GiB this host has; free space (do not delete unrelated files) and run evidence markers are implemented; it has not executed.
the `gui` harness to confirm ordinary virtual-GPU boot is unchanged. 4. **Install `sys` into the target**: the installed system still lacks the
3. **Installed Mango desktop**: install the default profile (Mango + DMS) in a deterministic CLI, so the no-model fallback contract is only partially
graphical VM and verify the panel/launcher/terminal/audio/network/lock/idle, shipped. This blocks a pure product-path rollback test.
the dwl fallback, and the welcome/installer absence on the installed system. 5. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
4. **Rollback VM acceptance (BLOCKED)**: deliberately break an update, run now also emits and `visudo`-validates the scoped sudo policy and produces the
`sys undo`, reboot detached, verify `/var/db/pkg` matches `/`, then boot the live NVIDIA config. Free space and run the `gui` harness.
recovery entry with no network or model (ADR 0007). Needed: (a) free the 6. **Installed Mango desktop**: install the default profile in a graphical VM
>=20 GiB `make doctor` wants for the harness; (b) an automated driver for the and verify panel/launcher/terminal/audio/network/lock/idle and the dwl
break-update/undo/recovery sequence — the harness has no such mode. fallback; a no-desktop run is a separate baseline.
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`).
7. **Release gates on a CI runner**: `phoebus-release gates --execute` and 7. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed. `publish` once a runner exists; no gate has executed.
## Known blockers / risks ## Known blockers / risks
- **NVIDIA hardware verification is BLOCKED**: this host has no NVIDIA GPU and - **Disk is the harness constraint.** `make doctor` reports ~12 GiB free versus
QEMU's virtual GPU cannot establish NVIDIA acceleration; no passthrough setup the >=20 GiB the VM harness wants. This blocks assembling the full desktop
is available or authorized. Unit/integration tests and the live-payload ISO and the rollback acceptance run. Do not delete unrelated files.
verifier pass, and a minimal live rootfs with the driver was built and - **No NVIDIA GPU** (and no authorised passthrough): actual acceleration cannot
verified, but no NVIDIA-accelerated boot has been observed. The **full desktop be verified here. The live decision and verifier are device-based and
ISO** also cannot be assembled here: `df` shows ~10 GiB free. Unblock by unit/fixture-tested only.
providing an NVIDIA GPU (or an authorized passthrough VM) and freeing disk - **`sys` is absent from the installed target.** The live medium and the
space, then running `installer/live/build.sh` and the `gui`/`install`/`boot` `phoebus-assistant` launcher use `sys`, and the rollback harness fetches it
harness modes. Note: the live kernel is pinned to Debian stable because from the host, but the installed system has no `/usr/local/bin/sys`. Fixing it
testing's 7.2 kernel breaks Debian's 550 driver; revisit when Debian ships a (embedding the static `sys` binary in the install) is future work.
matching driver. - **The `gui-install` completion is still host-time bound**: the base package
- **The complete graphical install and detached boot are BLOCKED on host build stage took ~116 min and the AI-selected kernel was still compiling at the 4 h
time.** The `gui-install` journey passes every assertion and starts a real timeout. The deterministic noninteractive install + detached boot remains the
install, but on this host the base packages take ~116 min and the proven path.
(AI-selected) optimized kernel was still compiling after 100 min, so the 4h - **Installed** Mango (GURU + compiled Quickshell/DMS) and the dwl fallback are
harness timeout fired. Two completed fresh-disk GUI installs + detached boot still not VM-verified.
therefore remain unrun here. The deterministic noninteractive install + - **Recovery-entry offline boot** is not automated: the rollback harness records
detached boot is the proven path. the snapshot recovery entry but does not select it in the bootloader.
- **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor - The live appliance guest scripts (`appliance-guest.sh`,
is the dwl fallback session. The `gui-install` journey intentionally preseeded `appliance-guest-gui.sh`) still use `sudo -n`/`poweroff` and a
a no-desktop, safe-kernel configuration to bound the harness run, so it proves `/run/live/medium/phoebus/bin/phoebus` launcher path; they predate the scoped
the wizard and the install pipeline, not the desktop build. policy and would need the live password if re-run against the narrowed image.
- **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.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git): - Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots. `results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes ## 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` - Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`); the appliance ISO builds without root. (matches `installer/live/base.sha256`).
- Local QML iteration: `/tmp/opencode/run-qml.sh <config-dir>` runs a config on - VM harnesses: `installer/tests/vm/gui-driver.py` (`gui`/`opencode`/
a nested Mango over the host X11 using the built rootfs libraries, and `gui-install`/`install`/`boot`), `serial-driver.py`
`grim` captures it. The sanctioned verification is the disposable VM. (`install`/`boot`/`rollback`), `appliance-driver.py`, `live-driver.py`.
- VM harnesses: `installer/tests/vm/gui-driver.py` (graphical live ISO: `DISK` must be a disposable qcow2; never point it at `/dev/*`.
`gui`/`opencode`/`gui-install`/`install`/`boot`), `appliance-driver.py`, - Serve fixtures from `/home/dominic/vmlab/serve` with
`serial-driver.py`. `DISK` must be a disposable qcow2; never point it at `python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`),
`/dev/*`. A `gui-install` run leaves its installed disk for a following including `live.pw` for the `gui-install` preseed and `rollback-guest.sh`,
`boot` run. `rollback-verify.sh` and `sys` for the rollback mode.
- 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`).
## Definition of a good stopping point ## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated; - `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed and pushed `docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
(`scripts/agent-commit.sh` + `scripts/publish.sh`). 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 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 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 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 | | UKI | no (deferred) | no | no | no |
## Known limitations ## Known limitations
@ -131,33 +135,49 @@ still not VM-verified.
- **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped - **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped
Portage configuration, a live payload that is build-time verified, and Portage configuration, a live payload that is build-time verified, and
kernel/module/initramfs update coordination) and covered by Rust tests and the 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 live-payload verifier. The policy now caps Maxwell/Pascal/Volta at the last
driver was **built and verified** this session (driver 550.163.01, kernel supporting series (580) and reports a Blackwell plus proprietary-only GPU
6.12.107+deb13-amd64, modules `nvidia-current*`). It is **not verified on combination as an explicit incompatibility rather than installing one driver
hardware**: this host has no NVIDIA GPU and QEMU's virtual GPU cannot that cannot serve both. The live driver choice is a deterministic,
establish NVIDIA acceleration; no passthrough setup is available or device-class-based decision (`--live-gpu-plan`) with a real `nouveau`
authorized. The full desktop ISO was not assembled here (the host has ~10 GiB fallback, and the verifier rejects placeholders, cross-kernel module trees and
free; the build wants more) and the live/installed NVIDIA boot gates are version/flavor mismatches. The installed sequence now installs the driver and
unrun. See `docs/VM-BOOT-VERIFICATION.md` for the exact unblock commands. The proves its modules exist **before** forcing them into the final initramfs.
live kernel is pinned to Debian stable (trixie 6.12 LTS) because testing's A minimal live rootfs with the stable kernel and NVIDIA driver was **built and
kernel (7.2) breaks Debian's 550 driver; the bundled branch covers Maxwell verified** previously (driver 550.163.01, kernel 6.12.107+deb13-amd64, modules
through Ada/Hopper, and Blackwell falls back to nouveau on the live medium. `nvidia-current*`). It is **not verified on hardware or in the VM**: this host
The installed Gentoo system uses the current branch with NVIDIA's open kernel has no NVIDIA GPU and QEMU's virtual GPU cannot establish NVIDIA
modules on Turing and newer. 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 - **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified). command line, so BLS is used (and verified).
- **Rollback is NOT VM-verified.** It is implemented and unit-tested end to end - **Rollback (`sys undo`) is NOT VM-verified.** It is implemented and
at the command/text layer (snapshot sets, root/var generation, fstab and BLS unit-tested end to end at the command/text layer (snapshot sets, root/var
rewriting, kernel selection, interruption resume, retention, free-space generation, fstab and BLS rewriting, kernel selection, interruption resume,
gate), but the destructive acceptance test (deliberately broken update -> retention, free-space gate). The harness now **automates the acceptance
`sys undo` -> detached reboot -> package-state check -> recovery with no sequence** (`serial-driver.py rollback` + `rollback-guest.sh` /
network/model) was **not run in this session**. Blockers: (1) `make doctor` `rollback-verify.sh`): a known-good package-database fingerprint and `/home`
reports only ~13 GiB free versus the >=20 GiB the VM harness wants, and the marker, `sys snapshot`, a controlled reversible package install, `sys undo`,
root filesystem has ~12 GiB free; (2) the committed appliance/serial harness detached reboot, then package-state/home comparison, kernel-module check and
only implements `install` and `boot` modes — there is no automated driver for recovery-entry/status evidence. The destructive gate itself is **unrun**:
the break-update / `sys undo` / recovery-boot sequence, which is documented as `make doctor` reports ~12 GiB free versus the >=20 GiB the harness wants, and
an interactive procedure. `sys undo` is present; treat VM verification as the there is no already-installed disposable clone available. Booting the recovery
gate before relying on it. 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 - **Mango + DankMaterialShell** is the default desktop
(`desktop.profile = "mango"`, Flatpak on). It is implemented with Mango (`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 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 detached rollback reboot, and recovery with no network/model (the rollback
acceptance gate). acceptance gate).
**2026-09-22 update — rollback acceptance still NOT run.** A session of `sys` **2026-09-23 update — rollback acceptance automated, still NOT run.** The
administration hardening did not run the destructive acceptance test. The missing driver now exists: `serial-driver.py rollback` (with
blockers are unchanged and exact: `make doctor` reports ~13 GiB free versus the `rollback-guest.sh` and `rollback-verify.sh`) performs the full sequence,
>=20 GiB the VM harness requires (the root filesystem has ~12 GiB free), and the including a `/var/db/pkg` fingerprint comparison and a `/home` survival check,
committed harness (`appliance-driver.py`, `serial-driver.py`) implements only and `bash -n` guards run in `test_vmsafety.py`. The **destructive VM gate
`install` and `boot`, with no automated break-update / `sys undo` / itself is unrun**: `make doctor` reports ~12 GiB free versus the >=20 GiB the VM
recovery-boot mode. `sys undo` therefore remains **unverified**, not passing. 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) ## 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's Linux driver has three relevant regimes (verified 2026-09 against
NVIDIA/Gentoo and the PCI ID database): NVIDIA/Gentoo and the PCI ID database):
- **Turing (GTX 16xx / RTX 20xx) and newer** can use NVIDIA's **open kernel - **Turing (GTX 16xx / RTX 20xx) through Hopper** can use NVIDIA's **open
modules** (`kernel-open`). The open modules are *recommended* from 560 and kernel modules** (`kernel-open`). The open modules are *recommended* from 560
*mandatory* from 595; Blackwell (RTX 50xx) requires them. 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 - **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; - **Fermi, Kepler and older** have no security-supported proprietary branch;
the in-tree `nouveau` driver is the honest choice. the in-tree `nouveau` driver is the honest choice.
@ -40,15 +43,24 @@ never claimed as supported.
### 2. Deterministic branch/flavor selection ### 2. Deterministic branch/flavor selection
One driver install covers every adapter, so the branch must serve the **oldest** One driver install covers every adapter, so the branch is computed **across the
supported GPU present: whole device set** rather than assuming the oldest card's branch serves the
newer ones:
| Generation | Branch | Module flavor | Portage | | Generation | Branch | Module flavor | Portage |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Turing / Ampere / Ada / Hopper / Blackwell | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` | | Turing / Ampere / Ada / Hopper | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Maxwell / Pascal / Volta | proprietary | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-595` | | 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 | | 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 Hybrid Intel/AMD GPUs keep their `VIDEO_CARDS` entries; the NVIDIA decision
only adds `nvidia`, or `nouveau` when the card is unserved. 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 signed Debian `contrib`/`non-free`/`non-free-firmware` components supply
the driver. Debian 13/testing ships branch **550.163.01**, whose proprietary 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. 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 - 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 current kernel (7.2) removed the `strncpy` declaration the 550 driver still
uses, so `nvidia-kernel-dkms` cannot build against it; the rolling kernel 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 any module is missing. Debian renames them `nvidia-current*`; the hook and the
verifier accept either that or the upstream names. verifier accept either that or the upstream names.
- `build.sh` runs `--verify-live-nvidia` on **every** build (including - `build.sh` runs `--verify-live-nvidia` on **every** build (including
`PHOEBUS_REUSE_ROOTFS=1`): it checks modules, userspace libraries, `PHOEBUS_REUSE_ROOTFS=1`). It is a compatibility gate, not a presence list:
`nvidia-smi`, EGL external-platform manifests, firmware, the gated load script it rejects placeholder modules/libraries, requires every module to be
and the nouveau blacklist, and records the bundled driver version, module registered in the live kernel's `modules.dep`, normalises the dpkg revision
flavor and kernel in `/etc/phoebus/nvidia`. A missing or mismatched component and requires the userspace `libnvidia-glcore` and firmware-directory versions
fails the build. 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 - Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in `nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of a gated service that loads the driver before greetd/Mango **only 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-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`,
`nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook `nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook
accept either that naming or the upstream names. accept either that naming or the upstream names.
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`, which checks - `build.sh` then runs `phoebus-installer --verify-live-nvidia`. It is a
the kernel modules, the GLVND/EGL/GBM userspace libraries, `nvidia-smi`, the compatibility gate, not a presence list: it rejects placeholder
EGL external-platform manifests, the GSP firmware, the gated load script and modules/libraries, requires every module to be registered in the live kernel's
the nouveau blacklist. It runs on **every** build, including `modules.dep`, checks the userspace `libnvidia-glcore` and firmware-directory
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship without versions against the bundled driver, infers and checks the module flavor,
the payload. The bundled driver version, module flavor and kernel are recorded requires non-empty GSP firmware and the exact
in `/etc/phoebus/nvidia` on the medium. `etc/modprobe.d/phoebus-nvidia.conf`. It runs on **every** build, including
- Nouveau blacklisting and module options come from Debian's own `PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship a
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in mismatched payload. The bundled driver version, module flavor and kernel are
favour of the live-only `phoebus-nvidia.service`, which runs the gated recorded in `/etc/phoebus/nvidia` on the medium.
`phoebus-nvidia-load` before greetd/Mango **only when an NVIDIA display device - The live load script makes a **deterministic, device-based decision** via
is present**, so systems without one keep nouveau/virtio and record no failed `phoebus-installer --live-gpu-plan`, not a `0x10de` vendor grep. A supported
unit. GPU loads the bundled accelerated stack; an unsupported GPU (or a failed
- The GRUB **fail-safe graphics** entry disables modesetting accelerated load) explicitly `modprobe`s `nouveau`; a machine with no NVIDIA
(`nomodeset`) and blacklists the NVIDIA modules for that boot; it is the display device leaves auto-detection alone. `build.sh` writes
documented recovery path when driver initialisation misbehaves. Use `etc/modprobe.d/phoebus-nvidia.conf` (replacing Debian's unconditional
`phoebus-gpu-report` for read-only diagnostics (PCI devices, loaded modules, nouveau configuration), so the fallback is real. Debian's unconditional
`nvidia_drm` modeset, `nvidia-smi`, recent kernel messages). 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 - The installed Gentoo target is unaffected: it uses Portage
(`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI (`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI
device IDs — open kernel modules for Turing and newer, the proprietary branch device IDs — open kernel modules for Turing and newer, the proprietary branch