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

114 lines
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-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`).