phoebus_os/docs/HANDOFF.md
Phoebus 3b1b54ffb9
Some checks are pending
ci / test (push) Waiting to run
docs: reconcile NVIDIA, verification and harness status
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.
2026-09-23 06:28:30 -07:00

7.7 KiB

Handoff

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), NVIDIA reliability and verification pass: live driver decision, verifier hardening, installed lifecycle, rollback harness, GUI harness repair, scoped live privilege.
  • Current focus:
    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 modprobes 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):
    • 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. 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

  • 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/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).
  • 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 (via scripts/agent-commit.sh) and pushed (scripts/publish.sh).