phoebus_os/docs/HANDOFF.md
2026-09-24 18:01:13 -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-25), privileged-boundary, GUI-review, removal, transaction and privacy remediation: Authoritative plan validation (validate_prepared_plan), protected per-user plan storage with atomic claim, truthful transaction outcomes, shared provider credentials (ai_setup), AI-first default removal, corrected conversational follow-ups, and an honest conversation-history privacy boundary.
  • Current focus:
    1. Single privileged validation boundary (phoebus_installer::service):
      • validate_prepared_plan runs before elevation and is repeated inside the privileged broker after authentication. It re-derives the plan seal from the plan's own contents (never two supplied digest strings), and rejects expired/claimed/modified/malformed/wrong-root/wrong-uid plans.
      • Plans bind the exact actions, effects, candidate, canonical target root and initiating uid. PreparedPlan.step_effects revalidates multi-action plans action-by-action (fixing an aggregate-digest bug).
      • PlanStore is per-user (/run/user/<uid>/phoebus/plans, 0700 / 0600), writes atomically, uses 128-bit ids, rejects symlinks/third-party ownership, and claims a plan with O_EXCL so at most one execution runs.
      • sys --broker --execute-plan <id> --plan-uid <uid> --root <root>; a dropped/mismatched root is rejected rather than executing against /.
    2. Truthful transaction outcomes: verification failure, action failure, refusal and cancellation finish the transaction truthfully; completed steps and the snapshot are retained; persistence failures surface; a malformed broker reply is a protocol failure, not fabricated success.
    3. GUI plan review: one review card for install/removal/general/rollback/ follow-up, with approval/cancel; executes only the referenced plan; updates the original card; never says "completed" for a prepared plan; shows verification; offers launch only when a concrete entry was identified. The assistant also used the wrong PhoebusButton API (text/enabled) and is corrected to label/actionEnabled.
    4. Shared provider credentials (ai_setup): CLI and GUI resolve provider, endpoint, model and credential reference through one module; keys load from a configured 0600 file, PHOEBUS_AI_API_KEY_FILE or ~/.config/phoebus/ai.key and are never passed through QML, prompts or argv.
    5. AI-first removal + follow-ups: default removal uses the model with deterministic ownership discovery underneath; only --legacy bypasses it. Explicit application references beat stale context.
    6. Conversation privacy: minimized structured history (no raw request), active redactor, 0600/0700 atomic writes, bounded to ten turns, clearable.
  • Last verified (this session):
    • cargo fmt --all -- --check clean.
    • cargo test --workspace all pass (67 phoebus-installer, 173 phoebus-core, 195 phoebus-executor, plus integration/CLI suites).
    • cargo clippy --workspace --all-targets runs (exit 0; pre-existing result_large_err/arg-count lints remain, as at the reviewed commit).
    • make test passes (Rust workspace + VM disk-safety suite).
    • Static sys and phoebus-installer (crt-static) build cleanly.
    • sys install/remove firefox without a model stop and print legacy guidance (no mutation); sys history --legacy runs deterministically.
  • Not yet verified this session (BLOCKED):
    • Live AI install/removal journey with an authorized provider — no credential is present; do not invent one.
    • Installed GUI/AI journey and the 12-step acceptance list — requires a graphical, seat-providing VM and a live model. The installed encrypted disk (/var/tmp/phoebus-vm/disks/test-disk.qcow2) has no LUKS passphrase available in this environment, so it cannot be booted here.
  • 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).