phoebus_os/docs/HANDOFF.md

6 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-25), 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.

What this session changed (code)

  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.

Not completed / blocked

  • Snap install/refresh/remove: no snapd in the image. Prerequisite: app-containers/snapd + AppArmor + network, installed through the supported integration. The Snap transaction code is unit-tested only.
  • 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. Snap lane acceptance with app-containers/snapd (install/refresh/remove, confinement recorded).
  2. Recovery boot by selecting the recovery BLS entry with the network down.
  3. Live AI with a faster local model/GPU or an authorized provider credential (natural-language discovery, source constraints, reviewed install).
  4. Nix profile GC stability if the dangling re-run is reproducible.

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