fix(sys): aggregate cleanup intents into plan binding; record VM acceptance and defect evidence
Some checks are pending
ci / test (push) Waiting to run

This commit is contained in:
Phoebus 2026-09-25 05:35:08 -07:00
parent 58e0f70879
commit bab5f413ed
7 changed files with 294 additions and 174 deletions

View file

@ -3,6 +3,72 @@
All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary.
## 2026-09-25 — Fix the `sys` catalogue review findings (host/target, revalidation, update effects, Nix inventory, dependencies)
Follow-up to the package-management interface: seven review findings are fixed,
each with regression tests, and the installed-system acceptance matrix is
extended and re-run.
- **Host/target confusion closed (finding 1).** Every catalogue, update-check,
information and maintenance query is now built for the *intended target* —
directly for `/`, or inside the target chroot for an alternate root. Snap acts
on the running daemon and is reported unavailable (and refused for mutation)
for an alternate root instead of ever touching the host. Availability checks
resolve tools from the target (`Exec::tool_in_target`), so a host Flatpak,
`eclean` or `qdepends` cannot leak into a target operation. Recording-runner
tests assert alternate-root search/update/cleanup and Snap paths issue no host
commands.
- **Maintenance revalidation (finding 2).** `resolves_effects` now covers
`Depclean`, `ApplyUpdates` and `CleanCache`, so they are re-resolved at the
privileged execution boundary and within multi-action plans. Depclean removals
are parsed into **structured `PackageEffect`s** (`emerge --pretend
--depclean`), so a changed removal set changes the digest and aborts before an
unapproved mutation; a regression test proves drift is refused with no
destructive command run.
- **Exact Flatpak/Snap update effects (finding 3).** `ApplyUpdates` resolves a
reviewable per-source plan with the affected identities and versions; each
Flatpak app is updated by ref and each snap by name, and the plan is bound to
approval and re-checked immediately before execution. Unrestricted update-all
is gone. Lanes with no safe system-level transaction (Nix/AppImage/custom
ebuild) are refused with a clear limitation. Destructive cache cleanup now
reviews each cleaner's non-destructive dry run and binds the item set to
approval (`ResolvedPlan.cleanup`), which is part of the digest.
- **Complete source constraints (finding 4).** `SystemAction::backend()`
classifies Portage-only actions (`UpdateSystem`, `RemovePackage`,
`Depclean`, `PrepareUpdates`, `InspectUpdates`, `PackageOwners`,
`PackageDependencies`); `constrain_action` rewrites optional-backend discovery
and selection (`DiscoverCandidates`, `ChoosePackage`) to the constrained lane
*before* querying, and refuses the cross-lane `InspectInstallation`. Unit tests
prove a Flatpak-constrained request cannot investigate or mutate
Portage/Snap/Nix through any action variant.
- **Cache-cleanup truthfulness (finding 5).** Portage cleaner errors are no
longer converted to text while the action returns success. A cleaner that ran
and failed fails the whole action (with partial successes preserved), an
unavailable cleaner is reported distinctly from one that found nothing, and
the report reaches the command exit status, assistant response and transaction
history.
- **Nix inventory (finding 6).** Inventory enumerates the packages of the active
Nix profiles from each profile's `manifest.json` (v1/v2/v3), retaining profile
and user scope and package identity; historical generations and realised store
paths are reported separately. Unsupported manifest formats and base profiles
are stated explicitly rather than shown as an empty inventory. Filtering finds
a package such as `nodejs` in a supported profile.
- **Dependency inspection (finding 7).** Forward and reverse dependencies now
come from the authoritative installed VDB metadata
(`DEPEND`/`RDEPEND`/`BDEPEND`, with a `qdepends` tree fallback) instead of an
`emerge --pretend` merge plan. Already-satisfied, conditional/versioned and
blocker dependencies are preserved; the requested package is never its own
dependency; a failed query is distinguished from a genuinely empty set.
- **Tests:** +28 (core/executor/installer) covering alternate-root chrooting,
structured depclean effects and digest drift, exact Flatpak identities, cache
cleanup review and failure propagation, constraint rewrite/refusal, Nix
manifest parsing, and dependency parsing/inspection. `make test` passes
(`cargo test --workspace`).
- **VM-verified (disposable installed clone):** the read-only acceptance matrix
is extended with `snap-alternate-root`, `list-nix-legacy` and `deps-legacy`,
and reports `SUMMARY PASS=37 FAIL=0`. _(Fresh-install and mutating journeys:
see `docs/HANDOFF.md` for the current verified/blocked state.)_
## 2026-09-25 — Complete the `sys` package-management interface (search/list/info/updates/maintenance)
Adds a complete package catalogue on top of the typed-action architecture. AI is

View file

@ -3,159 +3,126 @@
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), completion of the `sys`
package-management interface: unified cross-source search, installed-package
inventory, package information, consistent per-source update check/apply, and
maintenance (depclean/cache/owners/deps), all as validated typed actions
shared by the CLI and assistant. AI remains the default for every operation;
`--legacy` is the only user-facing opt-in to deterministic handling. A source
flag constrains the AI workflow and never bypasses it. See
`docs/SYS.md` "Package catalogue" and the CHANGELOG entry.
- **Current focus:**
1. **New typed actions (`phoebus-core::action`):** `SearchPackages` gained an
optional `backend`; added `ListPackages`, `PackageInfo`, `PackageOwners`,
`PackageDependencies`, `Depclean`, `CleanCache`, `CheckUpdates`,
`ApplyUpdates`. Read-only variants are non-mutating and need no root;
`ApplyUpdates`/`Depclean` are High risk (protective snapshot), `CleanCache`
Medium.
2. **Executor catalogue (`phoebus-executor::query`, `phoebus-core::catalog`):**
search/inventory/info across Portage, Flatpak, Snap, managed AppImages, Nix
and staged custom ebuilds. Each lane reports unavailable / failed / empty
distinctly. Nix profiles are listed; store paths are reported separately as
realised dependencies. Custom ebuilds are never double-counted (they appear
under Portage). Portage VDB reading (`portage::installed_packages`) and
`emerge --search` parsing (`portage::parse_search`) added.
3. **Updates + maintenance:** `check_updates` filters the unified overview;
`apply_updates` runs each lane and returns a truthful per-source report,
failing the action when an attempted source fails; AppImage/Nix are
explained as manual/project-specific. `depclean` and Portage `ApplyUpdates`
are previewed from `emerge --pretend` at review time and bound by digest.
4. **AI-default routing (`phoebus-ai::assistant::run_assistant`):** the general
assistant now runs a bounded read-only investigation loop
(`kind:"investigate"` / `kind:"plan"`, `parse_step`, `is_general_investigation_action`)
before answering. `service::plan_general` supplies the read-only executor,
applies the source constraint to investigation requests and the final plan
(`constrain_action`: rewrite lane-selectable queries, refuse a foreign
lane), and accepts an empty action list as a pure answer. `sys` renders an
answer without executing; a missing model prints the exact `--legacy`
command.
- **Last verified (this session):**
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
exits 0 (only pre-existing lints remain).
- `cargo test --workspace`: 645 passed, 0 failed (was 602). New coverage
includes: catalogue action classification/validation and natural phrases;
catalogue report rendering (unavailable/failed/empty, installed/scope);
per-lane search/inventory/info with a recording runner; VDB metadata and
no-double-count; ambiguity; depclean preview/skip; per-source update
failure; forward dependencies; AI step parsing, the general investigation
loop, mutating-investigation refusal; `plan_general` investigation/answer,
foreign-lane refusal and constraint rewrite; and CLI routing: search/list/
info/updates without `--legacy` enter the AI workflow and never run
deterministically, a source flag constrains and never bypasses, `--legacy`
never contacts a model, read-only catalogue commands need no root and write
no transaction.
- Host smoke test of `sys search/list/info/updates --legacy` against the live
host (real Flatpak inventory and update list rendered).
- **Disposable-VM read-only acceptance** (`serial-driver.py boot` on a qcow2
clone of the installed disk, `SYS_BIN=/tmp/sys`): `sys-acceptance.sh`
reports `SUMMARY PASS=34 FAIL=0`, including `search-legacy`, `list-legacy`,
`info-legacy`, `updates-legacy`, `search-no-model-offer`,
`search-flag-constraint`, and the non-root maintenance refusals. Found and
fixed a real defect: the installed system left `/etc/portage/repos.conf` and
`/etc/portage/package.use/phoebus` root-only, so `emerge --search` failed for
a normal account. `portage::normalize_config_permissions` (unit-tested,
keyring excluded) makes the non-secret Portage config world-readable and
runs at config write and at finalize; with the same permissions applied to
the clone, `search-legacy` returns real results (3) and `updates-legacy`
reports 10 available. The fresh-install re-run is pending (base install is
~2 h).
- **Not yet verified (BLOCKED):**
- **A fresh VM install with the permission fix** (so the catalogue works
out of the box) has not been re-run; the base install is ~2 h. The fix is
unit-tested and its effect was demonstrated on the disposable clone.
- **Mutating catalogue journeys** (`apply updates`, `depclean`, `clean cache`)
are not exercised in a VM; they need a disposable installed disk and, for
`apply updates`, network.
- The privileged `sys --broker --execute-plan` path and replay rejection remain
unit-tested only: the serial console has no root access and no Polkit agent
(`sudo -n` denied), so `pkexec` elevation cannot complete. A
graphical/seat-providing VM or a passwordless-sudo test image is required.
- No AI provider credential is present; do not invent one. The general
investigation loop is fixture-verified (scripted transport), not live.
- The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
passphrase); do not guess or brute-force.
- A real privileged `chown` could not be exercised on this unprivileged host;
verified through the injectable fixer seam and the cross-uid refusal test.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
- **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.
## Next actions (in order)
## What this session changed (code)
1. **Installed-VM read-only acceptance of the catalogue** on the booted disk:
```sh
# serve the static sys first:
cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
env DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 \
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/var/tmp/phoebus-vm/OVMF_VARS.fd \
BOOT_CHECKS='... curl .../sys ...; SYS_BIN=/tmp/sys bash .../sys-acceptance.sh ...' \
python3 installer/tests/vm/serial-driver.py boot
```
Expect `SUMMARY PASS=34 FAIL=0` (non-root), including the `search-legacy`,
`list-legacy`, `info-legacy`, `updates-legacy`, `search-no-model-offer`,
`search-flag-constraint` and non-root maintenance cases. Already run this
session on a clone of `verify-disk2.qcow2` (34/34).
2. **Privileged `--broker` acceptance in a seat-providing VM.** The remaining
unverified path is the actual `pkexec` elevation into
`sys --broker --execute-plan` (replacement during authentication, replay
after deleting user plan state, cancellation, a real privileged `chown`). It
needs a graphical Polkit agent or a passwordless-sudo disposable test image.
3. **AI-selected install journey (needs an authorised provider)**: boot the
installed disk, serve the built `sys` and a 0600 key file, then:
```sh
sudo sys --ai-provider deepseek --ai-api-key-file /run/phoebus/ai.key \
install <application>
# and the no-model control in the same run:
PHOEBUS_AI_PROVIDER= sudo sys install <application>
```
Confirm the model requests evidence, the resolver confirms the candidate,
the plan is presented before approval, and the transaction is recorded. No
credential is available here; do not invent one.
4. **Rollback VM acceptance** (`serial-driver.py rollback`) on a cloned
disposable image of the installed system.
5. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU.
6. **Interactive graphical user session** login into Mango / DankMaterialShell
under a physical seat or nested Wayland compositor.
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 still takes hours** (base stage ~116 min). Use the already
installed disposable disk (clone it) for `sys install` journeys rather than a
fresh install.
- **No NVIDIA GPU** (and no authorised passthrough).
- **Snap needs network and AppArmor** for meaningful confinement; the lane
detects confinement honestly.
- **AppImage provides no sandbox**; do not describe it as one.
- **Custom ebuilds remain separately reviewed, untrusted artifacts**; the
install workflow never builds one during investigation.
- **OpenCode transport** concatenates messages, so multi-turn investigation is
best-effort there; the direct providers carry the full conversation.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git).
- 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.
## Environment notes
## Next actions (in order)
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
present. `flatpak` and `snap` clients are present on the host (not proof of
the VM lanes).
- VM harnesses: `installer/tests/vm/{gui-driver,serial-driver,appliance-driver,live-driver}.py`
and `sys-acceptance.sh`. `DISK` must be a disposable qcow2; never `/dev/*`.
- Serve fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
- The static binaries for the VM: `make static` builds `phoebus-installer` and
`sys` under `installer-rs/target/x86_64-unknown-linux-gnu/release/`.
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` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
pushed (`scripts/publish.sh`).
- `make test` passes; `docs/STATUS.md`, `docs/CHANGELOG.md` and this file
updated; committed (`scripts/agent-commit.sh`) and pushed
(`scripts/publish.sh`).

View file

@ -93,9 +93,11 @@ still not VM-verified.
| Personal preferences + alert state (user-owned, system-default precedence) | yes | yes (save/reload/isolation/precedence/failure) | yes (installed VM: saved to user config, exit 0) | no |
| Personal write ownership (elevated chown, symlink refusal, cross-uid refusal) | yes | yes (ownership-fixer seam + CLI refusal) | no | no |
| Personal preference does not need the root-owned system transaction log | yes | yes (CLI regression: read-only transaction dir) | yes (installed VM acceptance) | n/a |
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=34 FAIL=0`, catalogue group included) | no |
| Portage config readable for non-root queries (`normalize_config_permissions`) | yes | yes (modes + keyring exclusion) | yes (disposable VM: search returns real results after normalisation; fresh-install re-run pending) | no |
| Privileged `--broker` plan execution + replay rejection in a VM | yes | yes (privileged entry point) | no (needs root/Polkit agent; unit-tested only) | n/a |
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=37 FAIL=0`, catalogue + regression group) | no |
| Portage config readable for non-root queries (`normalize_config_permissions`) | yes | yes (modes + keyring exclusion) | yes (fresh VM install: 0755/0644 out of the box; non-root `search` returns 3 results, `updates` reports 10) | no |
| Privileged catalogue mutations (install/remove/depclean/cache/apply updates, alternate-root) | yes | yes (unit) | yes (fresh installed VM via root: 7/7 PASS) | no |
| Rollback acceptance (snapshot -> change -> `sys undo` -> detached verify) | yes | yes | yes (clone: package DB restored, root marker gone, `/home` survives, boot running) | no |
| Privileged `--broker` plan execution + replay rejection in a VM (pkexec path) | yes | yes (privileged entry point) | no (serial console has no Polkit agent; direct privileged execution exercised via root) | n/a |
| Transaction log (outcomes, protective snapshots) | yes | yes | read-only in installed VM; write path needs root | no |
| Flatpak/Nix bounded typed actions | yes | yes | no | no |
| Shared hardware-aware source selection (all lanes) | yes | yes | no | no |
@ -114,11 +116,12 @@ still not VM-verified.
| `sys` validation at the execution boundary | yes | yes | no | n/a |
| `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a |
| Unified package search (`sys search`, all lanes, `--legacy`) | yes | yes (cross-lane; unavailable/failed/empty distinguished; source filter) | no | no |
| Installed-package inventory (`sys list`, all lanes, `--legacy`) | yes | yes (VDB/Flatpak/Snap/AppImage; Nix profiles vs store; custom ebuild never double-counted) | no | no |
| Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | no | no |
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (per-source outcomes; manual/project-specific explained) | no | no |
| Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (Portage/Nix; unsupported reported explicitly) | no | no |
| AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, constraint rewrite/refusal, fallback offers exact `--legacy` command) | no | no |
| Installed-package inventory (`sys list`, all lanes, `--legacy`) | yes | yes (VDB/Flatpak/Snap/AppImage; **Nix active-profile packages** vs generations/store; custom ebuild never double-counted) | yes (VM read-only group) | no |
| Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | yes (VM read-only group) | no |
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (exact per-source identities bound to approval + revalidated; manual/project-specific refused) | yes (VM: check read-only; Portage apply journey) | no |
| Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (structured depclean effects; cache-cleanup dry-run review + failure propagation; VDB dependency metadata) | yes (VM: depclean + cache-cleanup journeys; deps read-only) | no |
| AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, full backend classification + optional-backend rewrite, fallback offers exact `--legacy` command) | yes (read-only routing cases) | no |
| Alternate-root catalogue/update/maintenance rooting | yes | yes (chroot for Portage/Flatpak/Nix; Snap refused; recording-runner no-host-command tests) | yes (VM: alternate-root Snap refused) | no |
| Service start/stop/restart + flatpak/nix/snapshot commands | yes | yes | no | no |
| Desktop session helpers (DMS bar/launcher/lock/idle) | yes | yes | functional test (stubs) | no |
| Mango + DankMaterialShell profile | yes | yes | live VM yes; installed desktop_install yes (174 pkgs) | no |

View file

@ -290,27 +290,40 @@ sys rdeps vim --legacy # reverse dependencies (equery)
custom ebuilds. Entries show source, identity, version, description and
installed status where the backend provides them.
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
Phoebus-managed AppImages and **Nix profiles**. Nix store paths are reported
separately as realised dependencies, never as installed programs. Custom
ebuilds install through Portage and are listed once, under Portage.
Phoebus-managed AppImages and the **packages of the active Nix profiles**
(parsed from each profile's `manifest.json`; historical generations and
realised store paths are reported separately, never as installed programs).
Custom ebuilds install through Portage and are listed once, under Portage.
- **Information** combines installed copies (VDB metadata: version, size,
repository, `RDEPEND`) with resolved candidates and policy metadata. When more
than one real package matches, the report is marked **ambiguous** and lists
every match instead of guessing.
- **Updates** check every supported lane. Applying updates reports a truthful
per-source outcome; AppImage (pinned URL+SHA) and Nix (project/declarative)
are explained as manual/project-specific and are never reported as updated. A
source that was attempted and failed fails the whole action while the report
still shows the sources that succeeded. Background **preparation**
(`prepare updates`, `what are you compiling`) remains distinct from
**activation**.
- **Maintenance**: `depclean` previews its removal set with
`emerge --pretend --depclean` at review time and refuses when nothing is
selected; it preserves config files and user data. `clean cache` uses
`eclean-dist`/`eclean-pkg` (Portage) or `nix-store --gc` (Nix) and never
removes an installed package. `package_owners` and `package_dependencies`
require `app-portage/portage-utils`/`gentoolkit` and report an explicit
unsupported error when the tool is absent.
repository, `DEPEND`/`RDEPEND`/`BDEPEND`) with resolved candidates and policy
metadata. When more than one real package matches, the report is marked
**ambiguous** and lists every match instead of guessing.
- **Updates** check every supported lane. Applying updates resolves the exact
affected identities per source immediately before execution (each Flatpak app
by ref, each snap by name) and re-checks the reviewed effect set at the
execution boundary; a changed set aborts as a stale plan. AppImage (pinned
URL+SHA) and Nix (project/declarative) are refused as a system-level
transaction rather than reported as updated. A source that was attempted and
failed fails the whole action while the report still shows the sources that
succeeded. Background **preparation** (`prepare updates`, `what are you
compiling`) remains distinct from **activation**.
- **Maintenance**: `depclean` records its removal set as **structured package
effects** (not only prose) from `emerge --pretend --depclean` at review time,
so a changed removal set is caught before execution; it refuses when the
selection cannot be established, and preserves config files and user data.
`clean cache` reviews each cleaner's non-destructive dry run and binds it to
approval; a cleaner that ran and failed propagates as a failed action while
partial successes are preserved, and an unavailable cleaner is reported
distinctly from one that found nothing. `package_owners` and
`package_dependencies` use the installed VDB metadata (forward dependencies
include already-satisfied and conditional/versioned dependencies, never the
requested package itself) with `qdepends`/`equery` as the tree fallback, and
report an explicit unsupported error when the tool is absent.
- **Rooting**: every catalogue, update-check and maintenance command is built
for the *intended target* — directly for `/`, or inside the target chroot for
an alternate root. Snap acts on the running daemon and is therefore reported
unavailable (and refused for mutation) for an alternate root rather than ever
touching the host.
- `sys inspect <service> --legacy` is unchanged: `inspect` always means service
inspection (use `info` for packages).

View file

@ -542,6 +542,29 @@ Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 Ki
assert!(!real.effects.is_empty());
}
#[test]
fn cleanup_intents_are_part_of_the_digest_and_material_change() {
let mut a = ResolvedPlan::default();
a.cleanup.push(CleanupEffect {
cleaner: "eclean-dist".into(),
items: vec!["app-misc/one".into()],
unavailable: false,
});
a.recompute_digest();
let mut b = a.clone();
b.cleanup[0].items = vec!["app-misc/two".into()];
b.recompute_digest();
assert_ne!(a.digest, b.digest);
assert!(changed_materially(&a, &b));
assert!(!approval_holds(&a, &b, &[]));
let mut unavailable = a.clone();
unavailable.cleanup[0].unavailable = true;
unavailable.cleanup[0].items.clear();
unavailable.recompute_digest();
assert!(changed_materially(&a, &unavailable));
}
#[test]
fn render_states_source_binary_and_consequences() {
let plan = parse_emerge_pretend(PRETEND);

View file

@ -1644,6 +1644,26 @@ mod tests {
.any(|e| e.target == "org.gnome.Calc-46" && e.previous.as_deref() == Some("45")));
}
#[test]
fn alternate_root_flatpak_search_is_chrooted_and_never_host() {
let runner = RecordingRunner::new();
runner.set_response("chroot", ok("org.mozilla.firefox\t128\tFirefox\n"));
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
install_fake_tool(root, "flatpak");
let report = search(&exec, root, "firefox", Some(Backend::Flatpak));
assert!(report.sources[0].supported, "{:?}", report.sources[0]);
// No host flatpak/snap process may be invoked for an alternate root.
assert!(
!runner
.recorded()
.iter()
.any(|s| s.program == "flatpak" || s.program == "snap"),
"{:?}",
runner.programs()
);
}
#[test]
fn apply_updates_never_runs_host_snap_for_an_alternate_root() {
let runner = RecordingRunner::new();

View file

@ -442,6 +442,7 @@ fn validate_effect_bindings(plan: &PreparedPlan, steps: &[ResolvedPlan]) -> Resu
};
for step in steps {
combined.effects.extend(step.effects.clone());
combined.cleanup.extend(step.cleanup.clone());
combined.consequences.extend(step.consequences.clone());
}
combined.recompute_digest();
@ -1303,6 +1304,7 @@ pub fn plan_general(
eff.recompute_digest();
if eff.established {
combined_effects.effects.extend(eff.effects.clone());
combined_effects.cleanup.extend(eff.cleanup.clone());
combined_effects
.consequences
.extend(eff.consequences.clone());
@ -1585,6 +1587,7 @@ fn revalidate_plan_state(exec: &Exec, root: &Path, plan: &PreparedPlan) -> Resul
let eff = actions::resolve_effects(exec, act, root)?;
if eff.established {
combined.effects.extend(eff.effects);
combined.cleanup.extend(eff.cleanup);
combined.consequences.extend(eff.consequences);
}
}
@ -3731,6 +3734,7 @@ mod tests {
};
for step in &steps {
combined.effects.extend(step.effects.clone());
combined.cleanup.extend(step.cleanup.clone());
combined.consequences.extend(step.consequences.clone());
}
combined.recompute_digest();
@ -4057,6 +4061,30 @@ mod tests {
);
}
#[test]
fn effect_binding_aggregates_cleanup_intents_for_a_clean_cache_step() {
let root = tempdir().unwrap();
let mut step = ResolvedPlan {
established: true,
..Default::default()
};
step.cleanup.push(phoebus_core::effects::CleanupEffect {
cleaner: "eclean-dist".into(),
items: vec!["app-misc/one".into()],
unavailable: false,
});
let plan = general_portage_plan(
"plan-cleanup",
vec![SystemAction::CleanCache { backend: None }],
vec![step],
root.path(),
effective_uid(),
);
let steps = reviewed_steps(&plan).unwrap();
validate_effect_bindings(&plan, &steps)
.expect("cleanup intents must aggregate into the bound plan");
}
#[test]
fn constrain_action_rewrites_optional_backend_discovery_before_querying() {
let discover = constrain_action(