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

105 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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:
```sh
# 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`).