phoebus_os/docs/HANDOFF.md
Phoebus f30b99d272
Some checks are pending
ci / test (push) Waiting to run
feat(admin): implement AI-first administration across CLI and desktop GUI
- Default natural-language and conversational routing for sys install, sys please install, and sys ask through shared AI workflow
- Constrain AI candidate evaluation when source flags are supplied without bypassing the model
- Enforce explicit --legacy flag for deterministic administration; legacy install without a source flag refuses execution and offers choices
- Audit --action and --action-file entry points to require --legacy or --broker
- Provide truthful guidance on absent or failing AI models without silent mutation or unverified fallback
- Implement package correctness safeguards: Nix attribute evaluation probe, Portage binary check with source compile abort guard, cross-source installed application tracking, and data preservation on removal
- Provide Quickshell desktop assistant (phoebus-assistant) backed by stdio JSON-RPC bridge (sys --assistant-bridge) and desktop integration
- Implement unified multi-source update checking across all package lanes
- Implement quiet proactive assistance monitor with alert deduplication and snoozing
- Expand acceptance suite in installer/tests/vm/sys-acceptance.sh to 22 cases (22/22 PASS)
2026-09-24 16:38:38 -07:00

6.7 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: 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 <pkg>, sys please install <pkg>, and sys ask "<request>" 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 <pkg> --legacy --<source>, sys history --legacy, sys undo --legacy. sys install <pkg> --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: 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).