phoebus_os/docs/HANDOFF.md
Phoebus b120c1e5e4 docs: record AI guidance, desktop reliability and snapshot verification
Update the status matrix, roadmap, changelog and handoff; add the WS4/WS3 VM
evidence and a concise real-VT desktop test procedure.
2026-09-20 05:03:37 -07:00

53 lines
2.5 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:** commit `TBD_HEAD` (2026-09-20)
- **Current focus:** four workstreams — AI-assisted install guidance, desktop
session reliability, signed-binary reuse, and snapshots/safe updates.
- **Last verified:** static Rust binary install + detached boot
(`docs/VM-BOOT-VERIFICATION.md`); in this session additionally: `sys`
snapshot/history and update preparation on an installed Btrfs VM, and the
generated `phoebus-session` script against stub binaries.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Physical-seat desktop**: run `/usr/local/bin/phoebus-session` on a real VT
and check kitty, XWayland, the polkit agent, logout/reap and reboot
(`docs/DEVELOPMENT.md` -> "Physical VT / real-seat check").
2. **Matching signed binhost**: the official Gentoo binhost is OpenRC/hardened,
so systemd/desktop packages compile from source. Publish (or point at) a
systemd/desktop binhost to raise binary reuse; verify with `emerge -pv`.
3. **Rollback gate**: implement Btrfs default-subvolume + ESP handling and pass
a detached-boot test before exposing `sys undo`.
4. **Live AI provider call**: exercise DeepSeek/OpenAI with a real 0600 key
file; the path is currently fixture-verified only.
5. **Desktop graphical login**: exercise a real logind seat.
## Known blockers / risks
- No live DeepSeek/OpenAI call has been made (no key in this environment).
- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml`
only runs once one is registered.
- Desktop graphical login / physical seat has not been exercised; the serial
VM has no logind seat.
- NVIDIA is not verified on hardware.
- Rollback is not implemented (by design, gated).
## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy installed.
- Reference ISO is `livegui-amd64-20260913T163055Z.iso` (gitignored).
- Forgejo token for API tasks: `~/.config/phoebus/forgejo.token` (0600).
- The VM harness disks are disposable qcow2 files on `/` (not `/tmp`, which is
a small tmpfs on the dev host); never point `DISK` at `/dev/*`.
- The VM harness honours `CHECKS_TIMEOUT` for long guest checks.
## 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`).