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

129 lines
7.7 KiB
Markdown

# 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 `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):**
- `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`).