docs: reconcile NVIDIA, verification and harness status
Some checks are pending
ci / test (push) Waiting to run
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:
parent
4265aefacd
commit
3b1b54ffb9
6 changed files with 282 additions and 183 deletions
|
|
@ -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):**
|
||||
|
|
|
|||
221
docs/HANDOFF.md
221
docs/HANDOFF.md
|
|
@ -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`).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue