# 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 `PackageEffect`s 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`).