# 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), 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:** (remote `origin`, SSH port 2222). ## Next actions (in order) 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/.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 # and the no-model control in the same run: PHOEBUS_AI_PROVIDER= sudo sys install ``` 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. ## 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). ## Environment notes - 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/`. ## 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`).