phoebus_os/docs/HANDOFF.md
Phoebus 7e9fa9c2a3
Some checks are pending
ci / test (push) Waiting to run
feat(installer): graphical welcome and install wizard over a typed bridge
Add a branded live welcome window and a Quickshell/QML installer frontend
over a narrow, fail-closed JSON bridge (phoebus-installer --gui-bridge)
that reuses the same InstallConfig, plan, validation, authorization and
staged executor as the TUI/CLI. Add the Phoebus brand system (emblem,
wordmark, wallpaper, tokens), suppress DMS first-run dialogs on the live
medium, identify the live medium as protected, make the installer
shortcut live-only, and fix the installed boot default so systemd-boot
never selects the recovery entry.

Verified in a disposable graphical VM (welcome/installer journey,
duplicate prevention, keyboard navigation, blocked AI prerequisite) plus
a real non-interactive install and detached boot (INSTALL-RC=0,
NO_SECRET_LEAK, systemd running, 0 failed units, LUKS2, Btrfs, network).
2026-09-21 13:13:40 -07:00

4 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-21), graphical installer ISO.
  • Current focus: The ISO now boots into a branded welcome window and a full graphical installer wizard over a typed JSON bridge (phoebus-installer --gui-bridge), with the TUI/CLI as fallback. The brand system, boot-menu identity, live-medium detection and the recovery-boot default bug are fixed. See ADR 0010 and docs/VM-BOOT-VERIFICATION.md.
  • Last verified (this session):
    • gui-driver.py gui: welcome autostarts; DMS first-run dialogs suppressed; installer opens; duplicate sessions prevented (n1=n2=1); keyboard navigation reaches network + AI steps; the AI step blocks without a model.
    • gui-driver.py install + boot on the built ISO: INSTALL-RC=0, NO_SECRET_LEAK, and a detached boot with systemd running, 0 failed units, LUKS2, all Btrfs subvolumes and network, and the boot menu defaulting to Gentoo Linux (not recovery).
    • Rust suite: GUI bridge dry-run protocol, approval binding/invalidation, secret non-disclosure, brand tokens/contrast, boot default pinning.
    • ISO: installer/live/phoebus-installer-amd64.iso 1.6 GiB, sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee.
  • Public repo: https://git.phoebus.club/phoebus/phoebus_os (remote origin, SSH port 2222).

Next actions (in order)

  1. Live AI provider call: exercise the GUI AI step (and sys ask) with a real 0600 key or a downloaded local model; the path is fixture-verified only.
  2. Installed Mango desktop: install the default profile 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.
  3. Rollback VM acceptance: 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).
  4. 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).
  5. Release gates on a CI runner: phoebus-release gates --execute and publish once a runner exists; no gate has executed.

Known blockers / risks

  • No live DeepSeek/OpenAI call has been made (no key in this environment); the AI step is verified as a blocked prerequisite and with a fixture transport.
  • Installed Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor is the dwl fallback session.
  • Rollback and the AI sandbox are implemented and unit-tested but not VM-verified. NVIDIA is not verified.
  • The GUI bridge reaches Quickshell via Process + /usr/bin/sudo -n; it relies on the live user's passwordless sudo.

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/install/boot), appliance-driver.py, serial-driver.py. DISK must be a disposable qcow2; never point it at /dev/*.
  • 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).