phoebus_os/docs/HANDOFF.md
Phoebus 15b69f524d
Some checks are pending
ci / test (push) Waiting to run
docs: record quality-pass evidence (boxed ExecError, splits, VM acceptance)
Changelog entry for the 2026-09-26 refactor; STATUS corrected to the
current 38-case sys matrix with the new static-binary evidence; VM boot
verification gains the sys-acceptance-refactor run; handoff updated.
Verified with cargo test --workspace (692/692) and the disposable-VM
matrix (guest PASS=38 FAIL=0, driver PASS=41 FAIL=0).
2026-09-25 18:50:19 -07:00

167 lines
9.7 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.
- **Quality pass (2026-09-26):** boxed `ExecError::Command` details
(`CommandFailure`, 128 → 96 bytes, measured with a path-dependent probe crate;
constructor + all match sites updated, error text/redaction/stderr-tail
preserved, 4 regression tests), cleared `cargo clippy --workspace --all-targets
-- -D warnings` with no blanket allows (type alias, `CommandRecord` params
struct, `DiskPhase` renames), and split `service.rs` (4218 lines →
`service/mod,plan,validation,execution,tests`) and `gui_bridge.rs`
(2763 lines → `gui_bridge/mod,protocol,bridge,tests`) as structural refactors
with explicit re-exports and `pub(super)` seams — no `service.rs` left
alongside `service/mod.rs`. `make test` green (692/692, unchanged across the
splits). Release + static-pie builds pass. The disposable VM re-ran the
current 38-case `sys` acceptance matrix against the new static `sys`
(`70f0a72b…`): guest `PASS=38 FAIL=0`, driver `PASS=41 FAIL=0`
(`serial-boot-20260926T014746Z-3089a820`, overlay
`sys-acceptance-refactor.qcow2`). Commits `e69bfb9`, `1bf31c5`, `2dd48d1`.
- **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 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 `UpdateTransaction`s: 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`).