phoebus_os/docs/HANDOFF.md
2026-09-23 04:44:39 -07:00

145 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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), Responsive display layout, 1-click resolution switcher & hotkeys, and fullscreen installer.
- **Current focus:**
1. Low-Resolution Responsiveness & Scrollability: wrapped `phoebus-welcome` and
`phoebus-install` form/progress views in bounded `Flickable` containers with
`ScrollBar.vertical`. Added compact view adaptation (< 760px) in `phoebus-welcome`
with flow-wrapped readiness chips, resolving text/control clipping on 800×600
and 640×480 displays.
2. 1-Click Display Resolution Modal & Hotkeys: added a dedicated Display Resolution
dialog to `phoebus-welcome` (and hotkeys `Super+Shift+F12` for 1080p, `F11` for 900p,
`F10` for 768p, `F9` for 1024x768) that applies native modes via `wlr-randr`,
eliminating blurry bilinear scaling.
3. QEMU Native Resolution & Menubar: configured `-device virtio-gpu-pci,xres=1280,yres=768`
and `-display gtk,zoom-to-fit=on,show-menubar=on` in `start_vm.sh`.
4. Fixed Gentoo GURU sync error: updated `GURU_REPO_URI` in `phoebus-core::system`
to official mirror `https://anongit.gentoo.org/git/repo/proj/guru.git`.
5. OpenCode model names and variants: model picker displays real human-readable
names alongside raw IDs and allows selecting variants (`default`, `low`, `high`, `max`).
6. Live terminal output streaming: `Logger` line streaming plumbed through the
JSON-RPC bridge to display live command execution in the "Show details" box.
- **Last verified (this session):**
- `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.
- **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`).
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.
- 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.
- 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`).
## 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`).