phoebus_os/docs/HANDOFF.md
Phoebus 6e5c7d999f
Some checks are pending
ci / test (push) Waiting to run
feat(installer): overhaul GUI to 6-step flow and resilient UX
- Streamline installer to direct 6-step flow, eliminating Step 0 duplicate welcome
- Parse friendly layout names from evdev.lst and sort top 30 world layouts first
- Enable dynamic live keymap switching via localectl on layout selection
- Auto-detect timezone and close sibling combos on dropdown expansion
- Remove redundant keyboard test modal from welcome application
- Default-enable single-password disk encryption and accept passwords under 8 chars
- Replace ERASE typing confirmation with direct 'Install now' action
- Enforce Mango desktop, Btrfs filesystem, and Flatpak/Nix invariants against AI mutation
- Add loopback OpenCode/Ollama auto-detection and humanized failure screen with Retry
2026-09-23 05:42:03 -07:00

10 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), Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI.
  • 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.
  • 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.
  • 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).