phoebus_os/docs/HANDOFF.md
Phoebus f9e39925b4 feat(install): AI-first sys install workflow
Implement the shared installation workflow (ADR 0013). sys install, sys ask
install and the explicit backend flags all use one path: identify -> evidence
-> AI investigation -> deterministic validation/effects -> review -> approval
-> execute -> verify -> history.

- phoebus-ai::install: bounded, multi-turn investigation. The model may request
  typed read-only evidence (discover_candidates, inspect_candidate,
  check_backend, inspect_installation), ask one bounded question about intent,
  and must return a structured InstallProposal. Turn/request/size limits and
  repeated-request detection bound it; a rejected proposal is revised.
- phoebus-core: add the four read-only investigation actions and strict
  validators; add a transaction id; backend/kind wire names now match as_str.
- phoebus-executor::install: resolve_explicit (no model, no fallback),
  resolve_deterministic and resolve_with_ai; validate_proposal re-resolves the
  candidate against real metadata, rejects fabrication/ambiguity/staleness/
  duplicates, maps it to the existing broker action, and binds approval to a
  digest; revalidate + verify_installed. chooser gains per-lane friendly-name
  resolution and structured evidence.
- transaction::begin/finish record an in-progress transaction before mutation.
- sys: --portage/--flatpak/--nix/--snap/--appimage/--ebuild (mutually
  exclusive) bypass the model; an unqualified install consults the model and,
  with none, prints the deterministic selection and installs nothing.
- The installer persists /etc/phoebus/install.toml; sys loads it and adds free
  space, Wayland, usable lanes, saved preferences and recovery capability to
  the bounded facts.
- Docs: ADR 0013, docs/SYS.md install sections and cases 23-31, CHANGELOG,
  STATUS, HANDOFF, ROADMAP. New live-VM workflow check script.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test.
VM: verified the workflow CLI and read-only investigation on the reference
LiveGUI ISO; a full target install journey is running (see HANDOFF).
2026-09-23 20:30:13 -07:00

5.8 KiB
Raw Blame History

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 package installation: the shared sys install workflow, bounded AI investigation, deterministic proposal validation, explicit backend flags and truthful install transactions.
  • Current focus:
    1. Shared install workflow (phoebus-executor::install, ADR 0013): identify → evidence → AI investigation → deterministic validation/effects → review → approval → execute → verify → history. Used by sys install, sys ask install ... and the explicit backend flags.
    2. Bounded investigation (phoebus-ai::install): the model may request typed read-only evidence (discover_candidates, inspect_candidate, check_backend, inspect_installation) and ask one bounded question before proposing; turn/request/size limits and repeated-request detection bound it. A rejected proposal is revised with the resolver's finding.
    3. Deterministic authority: validate_proposal re-resolves the candidate against real metadata (fabrication, staleness, ambiguity and duplicates are refused), maps it to the existing broker action, and binds approval to a digest that is revalidated before execution.
    4. Explicit flags: --portage/--flatpak/--nix/--snap/--appimage/--ebuild bypass the model, are mutually exclusive and never fall back.
    5. No-model path: an unqualified install with no provider prints the deterministic selection and explicit commands and installs nothing.
    6. Transactions: transaction::begin/finish record an in-progress transaction before the mutation; installs verify identity/version after.
    7. Real install facts: /etc/phoebus/install.toml is now written by the installer and read by sys; facts add free space, Wayland, usable lanes, saved preferences and recovery capability.
  • Last verified (this session):
    • cargo fmt --all -- --check, cargo clippy --workspace --all-targets (no new warnings) and cargo test --workspace pass.
    • New tests: AI loop steps/bounds/repetition/revision/provider-failure; resolver fabrication/ambiguity/duplicate/changed-version; action mapping; transaction begin/finish (ok and failed); sys_cli flag conflicts, no-fallback, no-model offer, help; target-vs-host facts.
    • installer/tests/vm/test_vmsafety.py (18 tests) passes with the extended sys-acceptance.sh.
  • Not yet verified this session: a real VM installation journey through sys install (AI-selected and explicit-backend). The sys acceptance matrix now includes the read-only install-workflow cases (23–31). No live model call was made.
  • Public repo: https://git.phoebus.club/phoebus/phoebus_os (remote origin, SSH port 2222).

Next actions (in order)

  1. VM install journey: clone the installed disposable disk, boot it detached, and run:
    # serve the freshly built static binaries (make static) plus the guest scripts
    DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 OVMF_CODE=... OVMF_VARS=... \
      BOOT_CHECKS='test -x /usr/local/bin/sys && /usr/local/bin/sys --version; \
        sudo /usr/local/bin/sys install app-misc/hello --portage; \
        sudo /usr/local/bin/sys history; \
        curl -fsSL http://10.0.2.2:8000/sys-acceptance.sh -o /tmp/sa.sh && bash /tmp/sa.sh; \
        echo ===CHECKS-$(printf END)===' \
      python3 installer/tests/vm/serial-driver.py boot
    
    Confirm an explicit-backend install succeeds, appears in sys history, and the matrix reports FAIL=0.
  2. AI-selected install journey: with a configured provider (existing authorization, 0600 key file), run sudo sys install <app> in the VM and confirm the model investigates, the resolver confirms the candidate, and the plan is presented before approval. Use PHOEBUS_AI_PROVIDER= (empty) to exercise the no-model offer in the same run.
  3. Rollback VM acceptance (serial-driver.py rollback) remains unrun.
  4. NVIDIA hardware acceptance (BLOCKED): needs an NVIDIA GPU.
  5. Installed Mango desktop and the live ISO gui journey remain to be re-run.

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