phoebus_os/docs/HANDOFF.md
Phoebus 297f3201ff
Some checks are pending
ci / test (push) Waiting to run
feat(sys): hardware-aware lane selection and new lanes
Replace the fixed category routing (ADR 0006) with a shared, inspectable,
hardware- and preference-aware selection policy over resolved candidates from
Portage (source/binary/vendor), Nix, Flatpak, Snap, AppImage and the Phoebus
overlay. The policy keeps base components under Portage, separates hard
constraints from preferences, honours and persists explicit choices, errors
instead of silently switching lanes, and reuses an already-installed lane.

- phoebus-core::selection: the pure policy (16 tests: base-system, low-memory
  vs high-core, sandbox requirement, GPU/arch/storage rejection, explicit
  preference, unavailable backend, reproducibility, render).
- phoebus-executor::chooser: resolves real metadata and hardware facts.
- phoebus-executor::{snap,appimage,ebuild}: new lanes. Snap detects daemon and
  confinement and installs app-containers/snapd through Portage; AppImage
  adopts images with a pinned SHA-256, checks the ELF architecture without
  executing, integrates a desktop entry and preserves user data on removal; the
  custom ebuild overlay binds approval to the ebuild content digest and builds
  through Portage's sandbox.
- Typed actions choose_package / set_package_preference / snap_* / appimage_* /
  custom_ebuild_* with strict validators; the assistant prompt and schema are
  reconciled (no category routing; custom ebuilds are untrusted).
- Installed sys: the installer locates the trusted static binary, copies it to
  /usr/local/bin/sys and proves it runs in the target chroot before the
  recovery snapshot, failing closed if absent; the VM harness fetches sys.
- docs/SYS.md: command/action reference and acceptance matrix; ADR 0006 revised.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test,
release and static sys builds. VM lane journeys remain pending (see HANDOFF).
2026-09-23 18:35:26 -07:00

114 lines
6.4 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-24), hardware-aware software
selection across all lanes, Snap/AppImage/custom-ebuild backends, and the
installed-`sys` lifecycle.
- **Current focus:**
1. **Shared selection policy** (`phoebus-core::selection`, ADR 0006 revised):
fixed category routing is gone. A deterministic, inspectable policy
resolves real candidates from Portage (source/binary/vendor), Nix, Flatpak,
Snap, AppImage and the Phoebus overlay; separates hard constraints from
preferences; keeps base components under Portage; honours and persists
explicit choices; errors instead of silently switching lanes; reuses an
already-installed lane.
2. **New backends** (`phoebus-executor`): `snap` (daemon/confinement
detection, install/list/remove/refresh/connections, `app-containers/snapd`
through Portage), `appimage` (pinned-hash acquire/import, ELF arch check
without execution, desktop integration, data-preserving removal), `ebuild`
(Phoebus overlay, rationale + content digest, approval-gated build with
Portage's sandbox).
3. **`sys` surface**: `choose_package`, `set_package_preference`, `snap_*`,
`appimage_*`, `custom_ebuild_*` typed actions with strict validators and
deterministic phrases; `docs/SYS.md` is the command reference and
acceptance matrix.
4. **`sys` in the installed target**: located beside the installer, copied to
`/usr/local/bin/sys`, proven to run in the target chroot before the
recovery snapshot; install fails closed if absent.
5. **VM harness**: `install.sh` fetches `sys`; `rollback-guest.sh` uses the
installed binary; new `installer/tests/vm/sys-acceptance.sh`.
- **Last verified (this session):**
- `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets`
(no new warnings) and `cargo test --workspace` pass. New coverage: the
selection policy (16 tests across hardware/preference/failure cases), Snap
and AppImage parsing/behaviour, the ebuild digest/approval path, chooser
resolution, and `sys_cli` host tests.
- `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the new guest
script.
- **Not yet verified this session:** the new lanes and the installed-`sys`
lifecycle are unit/integration tested but **not exercised in a booted VM**: a
full `gui-install` (started by a prior session) was still running on the only
disposable disk. The NVIDIA boot gates and the rollback destructive gate remain
unrun.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Boot the installed disk and run the `sys` acceptance matrix** once the
current `gui-install` VM releases the disk:
```sh
cp installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer \
installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
cp installer/tests/vm/{install.sh,sys-acceptance.sh,rollback-guest.sh,rollback-verify.sh} /home/dominic/vmlab/serve/
# in the serve dir: python3 -m http.server 8000 --bind 127.0.0.1
DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 OVMF_CODE=... OVMF_VARS=... \
BOOT_CHECKS='test -x /usr/local/bin/sys && /usr/local/bin/sys --version; sudo /usr/local/bin/sys history; \
curl -fsSL http://10.0.2.2:8000/sys-acceptance.sh -o /tmp/sa.sh && SYS_ACCEPTANCE_MUTATE=1 bash /tmp/sa.sh; \
echo ===CHECKS-$(printf END)===' \
python3 installer/tests/vm/serial-driver.py boot
```
Confirm `/usr/local/bin/sys` exists (installed lifecycle), the matrix reports
`FAIL=0`, and a Portage install/remove appears in `sys history`.
2. **Snap / AppImage / custom-ebuild VM journeys**: on a disposable installed
VM, `sys snap install <tiny-snap>`, `sys appimage import` a small test image,
and one `custom_ebuild_prepare` + `custom_ebuild_install`. Needs network for
Snap/AppImage; the custom-ebuild path can use a local file.
3. **Rollback VM acceptance**: clone the installed disk and run
`serial-driver.py rollback`. The destructive gate is written and unit-checked
but unrun.
4. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU; unchanged.
5. **Live AI provider call**: exercise `sys ask` with a real 0600 key file; the
path is fixture-verified only.
6. **Installed Mango desktop** and the **live ISO `gui` journey** remain to be
re-run on this checkout.
## Known blockers / risks
- **One disposable disk, shared with a long `gui-install`.** Do not start a
second VM against the same qcow2; clone it first. `make doctor` reports
~29 GiB free now (the earlier ~12 GiB disk blocker has eased).
- **No NVIDIA GPU** (and no authorised passthrough): acceleration cannot be
verified here.
- **Snap needs network and AppArmor** for meaningful confinement. The lane
detects confinement honestly; a host without AppArmor reports `none`.
- **AppImage provides no sandbox.** Do not describe it as one; runtime
requirements (FUSE) are not auto-installed.
- **The custom-ebuild build is Portage sandboxed, not VM-isolated.** Treat a
generated ebuild as untrusted and keep the digest-bound approval.
- **`gui-install` completion is host-time bound** (base stage ~116 min, kernel
compile beyond the 4 h timeout). The deterministic install + detached boot is
the proven path.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git).
## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
present. `flatpak` and `snap` clients are installed on the host (not usable as
proof of the VM lanes).
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`.
- VM harnesses: `installer/tests/vm/gui-driver.py`, `serial-driver.py`,
`appliance-driver.py`, `live-driver.py`, and `sys-acceptance.sh`.
`DISK` must be a disposable qcow2; never point it at `/dev/*`.
- Serve fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
- The static binaries for the VM: `make static` builds `phoebus-installer` and
`sys` under `installer-rs/target/x86_64-unknown-linux-gnu/release/`.
## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
pushed (`scripts/publish.sh`).