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

128 lines
7.4 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.
- **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`).