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

6.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-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:
    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).