phoebus_os/docs/HANDOFF.md
Phoebus 7ebb616c99
Some checks are pending
ci / test (push) Waiting to run
feat(ai,desktop): unify administration layer, provision QML, and add conversation continuity
Unifies AI-first administration across the CLI (sys) and desktop GUI
(phoebus-assistant) through a shared service layer, fixes installed
desktop QML asset provisioning, adds Polkit elevation, and introduces
contextual conversation continuity.

- Extract phoebus_installer::service shared by CLI and desktop assistant bridge:
  - Reviewable plan staging (PreparedPlan) with SHA-256 cryptographic digests,
    15-minute TTL expiration, and replay prevention (PlanStore).
  - Pre-mutation system state revalidation binding execution strictly to the reviewed plan.
  - Honest recommendations displaying genuine provenance and unmeasured compile times.
  - Two-phase transaction logging (begin before mutation, finish with verification).
- Provision installed desktop assets and Polkit policy in phoebus-executor::desktop:
  - Added gui-apps/quickshell to canonical Mango desktop packages.
  - Embed 13 QML and policy files into target root under /usr/share/phoebus/assistant/.
  - Installed Polkit policy (club.phoebus.sys.policy) allowing unprivileged users to
    authenticate mutating plans via pkexec without blanket passwordless sudo.
- Eliminate startup freeze and polling in phoebus-assistant:
  - Multi-source update queries moved to on-demand tab switching.
  - Handshake timer reduced to one-shot 100ms with fast deterministic check.
- Add phoebus_installer::conversation:
  - Bounded 10-turn history with credential redaction.
  - Contextual follow-up resolution for comparisons, backend switching, and confirmation.
- Implement unified cross-source removal (plan_removal) preserving user data by default.
- Verified: all 486 workspace tests pass, release and crt-static builds succeed,
  and 23/23 VM acceptance cases pass (PASS=23 FAIL=0).
2026-09-24 17:21:16 -07:00

97 lines
5.9 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-24), AI-First Administration & Desktop Assistant Remediation:
Shared planning service layer (`phoebus_installer::service`), reviewable plan staging with
cryptographic digests (`PreparedPlan`, `PlanStore`), target desktop QML and Polkit policy
provisioning, unprivileged GUI execution with Polkit elevation (`pkexec`), contextual conversation
continuity (`conversation::*`), and cross-source application removal with user data preservation.
- **Current focus:**
1. **Shared planning and execution layer (`phoebus_installer::service`)**:
- Both CLI (`sys`) and desktop GUI (`phoebus-assistant` via `assistant_bridge.rs`) share one unified
administration pipeline for investigation, recommendation, effect resolution, authorization, execution, and verification.
- Reviewable plans staged as `PreparedPlan` with cryptographic digests (`Sha256`), 15-minute TTL, and replay rejection.
- System state revalidation before mutation; material alterations invalidate previous approvals and abort.
- Honest recommendation formatting with verified provenance (no false "avoids a lengthy build" claims).
- In-progress transaction recording (`begin`) before mutation; completed verification (`finish`) after mutation.
2. **Target desktop & QML asset provisioning**:
- `gui-apps/quickshell` added to canonical Mango desktop package list.
- Embedded all 13 QML and policy assets into `/usr/share/phoebus/assistant/` via `TargetRoot` in `write_session_script`.
- Polkit policy (`club.phoebus.sys.policy`) enables desktop users to elevate mutating plans via `pkexec` without passwordless sudo.
3. **Desktop assistant responsiveness**:
- Eliminated startup polling freeze; update checks are on-demand when switching to the Updates tab.
- Fast deterministic status checking on startup (reboot-required marker).
4. **Contextual conversation continuity (`phoebus_installer::conversation`)**:
- Bounded 10-turn history with secret redaction.
- Follow-up resolution for comparative questions, backend switching, and plan confirmations.
5. **Cross-source removal**:
- Unified removal planning (`plan_removal`) across Flatpak, Snap, AppImage, and Portage.
- Requires explicit lane flag if ambiguous duplicate copies exist; preserves user home data by default.
- **Last verified (this session):**
- `cargo fmt --all -- --check` clean.
- `cargo clippy --workspace --all-targets` clean (0 errors, 0 custom warnings).
- `cargo test --workspace` (all 486 crate unit/integration tests pass: 173 phoebus-core, 205 phoebus-executor, 108 phoebus-installer).
- `cargo build --release -p phoebus-installer` compiled cleanly.
- Static binary build with `crt-static` compiled cleanly.
- `installer/tests/vm/sys-acceptance.sh` passed 23/23 cases (`PASS=23 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:** <https://git.phoebus.club/phoebus/phoebus_os>
(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 <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.
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`).