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

5.9 KiB

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:
    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).