phoebus_os/docs/HANDOFF.md
Phoebus 1106bcaa0a
Some checks are pending
ci / test (push) Waiting to run
docs(verification): record the graphical journey results and host-time blocker
Update the changelog, status, handoff, verification register and VM boot
record with the 2026-09-22 graphical journey work: the fixed step sequence,
the interaction-defect fixes (readiness refresh, catalog sync/staleness, AI
revalidation, keyboard suggestion navigation, truthful keyboard-step label,
link vs service readiness, busy/failure handling), the new gui-install
harness mode, and the final-ISO results.

The gui (28/28) and opencode (18/18) journeys pass; gui-install passes every
journey assertion and starts a real install, but the four-hour harness timeout
fired during the kernel build (base packages ~116 min), so two completed
fresh-disk graphical installs + detached boot remain BLOCKED on host build
time, not on a code defect.
2026-09-22 12:30:55 -07:00

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-22), graphical installer journey polish and reliability.
  • Current focus: Reworked the graphical installer into a fixed, first-time-user journey — Welcome, Language and keyboard, Internet and readiness, AI connection, Destination disk, Account and encryption, Review and confirmation, Installation, Completion — while keeping configuration, validation, plans, approval and execution authoritative in Rust. Fixed the interaction defects called out in the audit: the readiness refresh no longer resets the wizard; model catalogs are fetched after syncing the edited settings/credentials and stale replies are ignored; editing a connection field invalidates the validated state; suggestion lists have full keyboard navigation; the keyboard step is labelled truthfully (the live session keeps its layout); readiness separates a local link from reachable install services; and every busy state now clears on failure with an actionable retry (the bridge fails outstanding requests when the backend exits). AI changes require an explicit Accept or Discard; the review screen is built from backend facts with edit links; progress reports real stages, elapsed time and activity.
  • Last verified (this session):
    • cargo fmt --all -- --check and cargo clippy --workspace --all-targets clean (only the pre-existing result_large_err advisory); the Rust workspace tests pass and make test (Rust + 16 harness tests) is green.
    • Disposable graphical VM, rebuilt ISO (sha256 125d002b…, 1.6 GiB): gui 28/28 PASS and opencode 18/18 PASS, including the keyboard-suggestion regression, the blocked AI gate, a real model response and validated proposal, and the new "editing the model invalidates the connection" regression.
    • gui-install (new mode) passed every journey assertion on a fresh 30 GiB qcow2 — AI connect/accept, disk, account, ERASE, confirmation toggle — and the backend then reported real stages with elapsed time and no fabricated percentage. The install itself was still compiling the kernel after four hours (the base-package stage alone took ~116 min on this host), so the harness timed out; the completed install + detached boot gate is BLOCKED on host build time (see docs/VM-BOOT-VERIFICATION.md).
  • Not yet verified this session: the complete graphical install and detached boot (BLOCKED on host build time — the 4h harness run was still compiling the kernel; see blockers), the installed Mango desktop rollback and NVIDIA checks are unchanged; rollback (sys undo) and the AI sandbox remain unit-tested but not VM-verified, and the physical-seat desktop and a separate physical computer remain open (see blockers).
  • Public repo: https://git.phoebus.club/phoebus/phoebus_os (remote origin, SSH port 2222).

Next actions (in order)

  1. 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.
  2. 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.

  3. 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).
  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

  • 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).