phoebus_os/docs/HANDOFF.md
Phoebus 7c5d4c5ca6
Some checks are pending
ci / test (push) Waiting to run
fix(sys): make Snap first-use setup reviewable and VM-tested
2026-09-25 18:07:13 -07:00

8.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.

  • Snap first-use follow-up (2026-09-25): the previous "no snapd" note was a real integration gap. The normal sys install … --legacy --snap resolver needs snapd to confirm a Store candidate before approval, while a raw typed snap_install silently added it during execution. First-use setup is now a separately reviewed Portage install plus socket enable/start, with exact guidance when absent. Fresh installs set scoped sys-fs/squashfs-tools lzma lzo, which Gentoo's snapd ebuild requires. A disposable VM exposed a second bug: Portage candidate resolution picked the first dependency (dev-lang/go-bootstrap) instead of the requested app-containers/snapd; it now matches the requested atom. Snap confinement is reported from the daemon rather than assumed strict. The disposable VM completed setup, Store install, refresh and remove (PASS=10 FAIL=0), with partial confinement. A fresh overlay and a clean reboot repeat with the final static binary each passed PASS=11 FAIL=0, including clean poweroff. Refresh found no newer revision.

  • Previous session: second-round sys review fixes. Follow-up to d3f676a. Three further confirmed defects are fixed with regression tests: unsafe cleanup previews, non-exact Flatpak/Snap update execution, and reverse-dependency self-reference. make test is green (661 → 683 tests). This corrects the earlier blanket claim that every review finding was already fixed.

  • Interface contract (unchanged): ordinary requests use AI; only explicit --legacy selects deterministic handling; source flags constrain the AI and never bypass it; a missing model stops the workflow and offers the exact --legacy command without executing it.

Snap first-use changes

  • phoebus-core::system generates scoped SquashFS USE flags for new installs.
  • Portage candidate resolution selects the requested atom from the pretend plan, even when dependencies precede it. A multi-package regression covers the bug found by the VM.
  • The Snap install path gives exact setup commands when snapd is absent; the typed action no longer adds an unreviewed Portage dependency. Candidate sandbox levels and missing snap info fields are treated conservatively.
  • installer/tests/vm/snap-guest.sh drives the installed-system journey. The serial driver can authenticate for boot checks and logs only guest output, keeping sent test passwords out of its transcript.

Previous sys review work

  1. Cleanup previews are non-destructive (finding 1). eclean-dist/ eclean-pkg delete by default, so portage_cleaners now previews with --pretend --deep (same selection policy as execution) and executes with --deep; the Nix preview uses the documented nix-store --gc --print-dead. Items are read from stdout+stderr, sorted and bound. Tests prove a cleaner never runs destructively during planning, revalidation or cancelled approval.
  2. Exact Flatpak/Snap update transactions (finding 2). ResolvedPlan.updates carries UpdateTransactions: full Flatpak ref + full installed/remote commits (via flatpak info, since the commit column is abbreviated), or snap name + old/new revisions + channel. Execution consumes the reviewed transaction (add_executable… flatpak update --commit=<c>), revalidates each source immediately before its mutation, verifies the resulting commit/revision, and refuses non-exact transactions. A source whose resolution failed is never re-discovered. PlanStore aggregation includes updates.
  3. Reverse dependencies (finding 3). The reverse branch no longer drops valid matches; it excludes only a genuine self-reference (the dependent is the queried package).
  4. Determinism. All selected packages: removals are sorted (depclean previews are now order-independent); emerge --depclean --ask=n.

Verified in disposable VMs

  • Cache cleanup + depclean (real tools): eclean upstream preview is non-destructive; sys clean cache preview/cancelled/approved/drift/failed all behave correctly; depclean cancel/approve with transaction history and preserved /home.
  • Reverse dependencies: sys-libs/glibc and sys-libs/zlib report real dependents (conditional/versioned included).
  • Flatpak: installed via Portage (sys-apps/flatpak, enabling media-libs/freetype[harfbuzz]), flathub added, an app installed and downgraded, then sys apply updates --flatpak resolved full ref+commits, deployed the pinned commit, and verified it.
  • Custom ebuild: stage → build/install (VDB entry + installed file) → remove.
  • Managed AppImage: acquire with pinned SHA-256, list, run the managed ELF, remove; a placeholder SHA is refused.
  • Nix: a NIX_ENABLED=yes install bootstraps Nix; nix profile install nixpkgs#nodejs-slim into /nix/var/nix/profiles/profile is enumerated by sys list --nix and found by sys list nodejs --nix, with store paths and generations reported separately.
  • Non-root pkexec sys --broker: with the shipped polkit action and the standard wheel-admin rule installed on the disposable image, a wheel user authenticated through a terminal agent; cancellations changed nothing, the approved removal returned the broker JSON outcome, and the replay was rejected. The shipped privilege policy is unchanged.
  • Read-only acceptance: installer/tests/vm/sys-acceptance.sh PASS=38 FAIL=0 re-run against the final static sys (dd61c610…), including the new rdeps-legacy reverse-dependency regression.
  • Snap first use: the disposable VM installed app-containers/snapd through the reviewed Portage plan (six effects), enabled and started snapd.socket, installed Snap Store hello-world 6.4 revision 29, ran refresh, then removed it. The daemon reported partial confinement and the install review agreed. The harness reported PASS=10 FAIL=0 (serial-boot-20260926T001830Z-107996de). Final-binary runs on a fresh overlay passed PASS=11 FAIL=0 on first boot (serial-boot-20260926T005327Z-c024cc43) and after a clean reboot (serial-boot-20260926T010605Z-e6193c3a); both shut down cleanly.

Not completed / blocked

  • Snap update to a different revision / strict confinement: refresh with no newer revision and partial confinement were VM-verified. A revision-changing refresh and AppArmor-backed strict confinement were not.
  • Live AI: a local OpenAI-compatible model (llama-server + a GGUF model) was served on the host; the AI workflow reached the model, but the sandboxed call exceeded the 120 s transport timeout on CPU (curl exit 28). Needs a faster model/GPU or a remote provider credential. Fixture-backed routing and failure tests pass (ask-offline, missing-model offer, source constraint).
  • Recovery boot (distinct from rollback): the recovery BLS entry is present and asserted in the rollback acceptance, but booting it interactively was not automated. Method: select "Phoebus Recovery (known-good snapshot)" in the systemd-boot menu with no network.
  • Nix re-run flakiness: a later sys list --nix re-run reported the profile link dangling (the profile store path was gone) and correctly listed no packages; the first run with a real profile is the positive evidence.

Known blockers / risks

  • VM serial login is occasionally flaky; retry the boot when detached-boot-login fails.
  • make doctor passes (KVM accessible via an ACL). Disk is shared by build and VM; watch free space.
  • The pre-existing test-disk.qcow2 cannot be unlocked (unknown passphrase); do not guess or brute-force it.

Next actions (in order)

  1. Recovery boot by selecting the recovery BLS entry with the network down.
  2. Live AI with a faster local model/GPU or an authorized provider credential (natural-language discovery, source constraints, reviewed install).
  3. Nix profile GC stability if the dangling re-run is reproducible.
  4. Snap strict confinement and changed-revision update in a disposable VM when an AppArmor-ready kernel and a revision-changing Store test are available.

Definition of a good stopping point

  • make test passes; docs/STATUS.md, docs/CHANGELOG.md and this file updated; committed (scripts/agent-commit.sh) and pushed (scripts/publish.sh).