phoebus_os/docs/HANDOFF.md
2026-09-25 05:35:08 -07:00

7.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-25). Follow-up to commit 05d7075: the seven review findings on the sys package-management interface are fixed (host/target rooting, maintenance effect revalidation, exact Flatpak/Snap update effects, complete source constraints, truthful cache-cleanup outcomes, Nix active-profile inventory, VDB-based dependency inspection), with regression tests. The disposable-VM acceptance matrix is extended and the fresh-install / mutating / rollback journeys below were completed.
  • Interface contract (unchanged): every ordinary request uses the AI workflow; only an 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; both modes share the same validated typed actions, approval controls and execution layer.

What this session changed (code)

  1. Host/target rooting (finding 1). Exec::tool_in_target resolves tools from the target; actions::target_spec is shared by catalogue, chooser and update paths. Snap is host-only and is reported unavailable (and refused for mutation) for an alternate root. Recording-runner tests assert no host flatpak/snap process is invoked for an alternate root.
  2. Maintenance revalidation (finding 2). resolves_effects covers Depclean/ApplyUpdates/CleanCache; depclean removals are structured PackageEffects parsed from emerge --pretend --depclean, so a changed removal set changes the digest and aborts at the execution boundary (and within multi-action plans). Plan aggregation now carries cleanup intents.
  3. Exact update effects (finding 3). ApplyUpdates resolves per-source effects (each Flatpak app by ref, each snap by name) bound to approval and revalidated; unrestricted update-all is gone. Lanes with no safe transaction are refused. Cache cleanup reviews each cleaner's dry run via ResolvedPlan.cleanup.
  4. Source constraints (finding 4). backend() classifies Portage-only actions; constrain_action rewrites DiscoverCandidates/ChoosePackage and refuses the cross-lane InspectInstallation before querying.
  5. Cache-cleanup truthfulness (finding 5). A cleaner that ran and failed fails the action (partial successes preserved); unavailable is distinct; the report reaches exit status, assistant response and transaction history.
  6. Nix inventory (finding 6). Active-profile manifest.json (v1/v2/v3) packages are enumerated with profile/user scope and identity; historical generations and realised store paths are separate; unsupported formats and base profiles are stated explicitly.
  7. Dependencies (finding 7). Forward/reverse dependencies use installed VDB DEPEND/RDEPEND/BDEPEND (qdepends tree fallback), include already-satisfied/conditional/versioned deps, never self, and distinguish a failed query from an empty set.

Unit tests: cargo test --workspace (all green; see CHANGELOG). Build/static binaries: make build and make static; the static sys built from the final tree has SHA-256 22232a25… (see the VM log SYS_SHA).

Verified in disposable VMs (this session)

  • Fresh install (fresh-install-1.qcow2, test.conf DESKTOP_PROFILE=none, NIX_ENABLED=no): ===INSTALL-RC=0===, NO_SECRET_LEAK, then a detached boot: boot-systemd-running PASS.
  • Out-of-box Portage permissions: /etc/portage 755, repos.conf 755, repos.conf/gentoo.conf 644, package.use/phoebus 644 → non-root sys search firefox --legacy returns 3 real results and sys updates --legacy reports 10 available. This is the fresh-install proof that normalize_config_permissions works without manual repair.
  • Acceptance matrix: installer/tests/vm/sys-acceptance.sh SUMMARY PASS=37 FAIL=0 on both an existing installed clone and the fresh install, including the new regressions snap-alternate-root, list-nix-legacy, deps-legacy.
  • Privileged mutating journeys on the fresh install (via root; see blocked note): install + VDB, remove, history, depclean, cache cleanup (honest nonzero failure with no cleaner), alternate-root Snap refusal, and a Portage apply updates journey — 7/7 PASS.
  • Rollback acceptance on a disposable clone: snapshot → controlled change (root marker + app-misc/hello) → sys undo → detached boot. The package database fingerprint returned to the pre-change value, the root marker is absent, the /home marker survives, and systemd is running.
  • Revision: the installed sys on the fresh disk matches the static build (SYS_SHA:22232a25…).

Blocked / not yet verified

  • pkexec/Polkit sys --broker --execute-plan path: the serial console has no Polkit agent, so pkexec elevation cannot complete. Privileged execution was exercised by running the same reviewed plan as root (initiator uid 0); the ledger/replacement/replay logic remains unit-tested and was previously reviewed. To unblock: a seat-providing/graphical VM with a working Polkit agent, or a disposable test image with a passwordless-sudo polkit agent.
  • Nix profile journey: the disposable install sets NIX_ENABLED=no, so no Nix profile exists in the VM. The manifest parser (v1/v2/v3, unsupported formats, inactive elements, historical generations) is unit-tested with realistic fixtures. To unblock: install with Nix enabled and a known profile.
  • Snap install/refresh/remove: no snapd/AppArmor in the minimal image; the lane journey would need app-containers/snapd, AppArmor and network.
  • Managed AppImage acquire/launch/remove and custom-ebuild stage/build/install/remove: not run in the VM (no AppImage fixture/FUSE and no build budget); the code paths are unit-tested.
  • Live AI: no provider credential is present. sys ask/guided install and source-constrained live AI remain unverified; do not invent a credential.
  • NVIDIA: no GPU.

Known blockers / risks

  • A full VM install takes ~2 h; the fresh fresh-install-1.qcow2 is now available for future work. make doctor reports low host disk space; delete build/VMs deliberately, never a physical disk.
  • The pre-existing test-disk.qcow2 still cannot be unlocked (unknown passphrase); do not guess or brute-force.
  • OpenCode transport concatenates messages; multi-turn AI investigation is best-effort there.

Next actions (in order)

  1. pkexec/Polkit broker acceptance in a seat-providing or passwordless-agent disposable VM: successful approval, cancelled authentication, plan replacement during authentication, replay after deleting user-owned plan state, and real ownership of personal settings.
  2. Nix profile journey with NIX_ENABLED=yes and a profile containing a known package (nodejs), verifying inventory, filtering and generations.
  3. Snap/AppImage/custom-ebuild lane journeys with benign fixtures and recorded confinement limitations.
  4. Live AI (sys ask, source-constrained discovery, reviewed install, missing-model/provider-failure) once a credential or local model exists.

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