# 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-24), AI-First Administration & Desktop Assistant: Unified AI-first administration across the CLI (`sys`) and desktop GUI (`phoebus-assistant`), backed by package correctness guarantees, quiet proactive monitoring, user preferences, and a 22-case verified VM acceptance suite. - **Current focus:** 1. **Unified AI-first administration contract**: - Natural language is the default interaction: `sys install `, `sys please install `, and `sys ask ""` all enter the identical AI workflow. - Source flags (`--flatpak`, `--portage`, `--nix`, `--snap`, `--appimage`, `--ebuild`) constrain AI candidate evaluation without bypassing the model. - Deterministic administration explicitly selected via `--legacy`: `sys install --legacy --`, `sys history --legacy`, `sys undo --legacy`. `sys install --legacy` without a source refuses execution and displays available sources. - Audited entry points: `--action` and `--action-file` fail closed unless invoked with `--legacy` (for deterministic administration) or `--broker` (for internal UI/bridge calls). - Missing or failed model: halts AI execution cleanly and provides actionable `--legacy` alternatives without silently mutating the system or falling back across sources. 2. **Package correctness and safety guarantees**: - Nix attribute evaluation probe (`nix-instantiate`) verifies attribute existence in nixpkgs. - Portage binary binhost check (`emerge -p --usepkgonly`) verifies binary availability; aborts if an action changes to source compilation (`EffectSource::Source`), invalidating prior approval. - Cross-source installed application ownership tracking detects duplicates and targets the correct installation during update or removal. - User data preserved by default on application removal. 3. **Desktop Assistant GUI (`phoebus-assistant`) & Bridge**: - Quickshell QML application in `installer/live/desktop/phoebus-assistant/` with conversational assistant chat, recommendation cards with concise rationales, expandable comparison options, unified updates, proactive alerts, legacy controls, and preferences. - Stdio JSON-RPC bridge (`sys --assistant-bridge`) ensures zero business logic lives in QML. - Session scripts and desktop launcher integration (`Super+Space` / `phoebus-assistant.desktop`). 4. **Unified Updates & Quiet Proactive Assistance**: - Unified multi-source update overview across Portage, Flatpak, Snap, AppImage, and Nix. - Bounded deterministic checks for reboot required, low storage (< 5 GiB), failed transactions, systemd service failures, and updates ready. - Deduplication, snoozing, dismissals, and persistent state under `/var/lib/phoebus/proactive.toml`. 5. **User Preferences & Profiles**: - Inspectable and editable profiles (`Balanced`, `FastInstallation`, `NativeIntegration`, `ApplicationIsolation`), project environment tool mappings, and source pins. 6. **Repeatable Acceptance Verification**: - `installer/tests/vm/sys-acceptance.sh` expanded to 22 acceptance cases, passing 100% (22/22 PASS). - **Last verified (this session):** - `cargo fmt --all -- --check` clean. - `cargo clippy --workspace --all-targets` clean (0 warnings). - `cargo test --workspace` (all 481 crate unit/integration tests pass: 173 phoebus-core, 205 phoebus-executor, 103 phoebus-installer). - `cargo build --release -p phoebus-installer` compiled cleanly. - `installer/tests/vm/sys-acceptance.sh` passed 22/22 cases (`PASS=22 FAIL=0`). - **Not yet verified this session:** - AI-selected live installation against a remote production provider with live credentials (fixture and mock paths fully verified). - Physical-seat DRM desktop session (headless and virtual seats verified). - **Public repo:** (remote `origin`, SSH port 2222). ## Next actions (in order) 1. **AI-selected install journey (needs an authorised provider)**: boot the installed disposable disk (`/var/tmp/phoebus-vm/disks/test-disk.qcow2`), 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. 2. **Rollback VM acceptance** (`serial-driver.py rollback`) on a cloned disposable image of the installed system. 3. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU. 4. **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`).