phoebus_os/docs/HANDOFF.md
2026-09-25 03:11:18 -07:00

161 lines
9.6 KiB
Markdown

# 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), completion of the `sys`
package-management interface: unified cross-source search, installed-package
inventory, package information, consistent per-source update check/apply, and
maintenance (depclean/cache/owners/deps), all as validated typed actions
shared by the CLI and assistant. AI remains the default for every operation;
`--legacy` is the only user-facing opt-in to deterministic handling. A source
flag constrains the AI workflow and never bypasses it. See
`docs/SYS.md` "Package catalogue" and the CHANGELOG entry.
- **Current focus:**
1. **New typed actions (`phoebus-core::action`):** `SearchPackages` gained an
optional `backend`; added `ListPackages`, `PackageInfo`, `PackageOwners`,
`PackageDependencies`, `Depclean`, `CleanCache`, `CheckUpdates`,
`ApplyUpdates`. Read-only variants are non-mutating and need no root;
`ApplyUpdates`/`Depclean` are High risk (protective snapshot), `CleanCache`
Medium.
2. **Executor catalogue (`phoebus-executor::query`, `phoebus-core::catalog`):**
search/inventory/info across Portage, Flatpak, Snap, managed AppImages, Nix
and staged custom ebuilds. Each lane reports unavailable / failed / empty
distinctly. Nix profiles are listed; store paths are reported separately as
realised dependencies. Custom ebuilds are never double-counted (they appear
under Portage). Portage VDB reading (`portage::installed_packages`) and
`emerge --search` parsing (`portage::parse_search`) added.
3. **Updates + maintenance:** `check_updates` filters the unified overview;
`apply_updates` runs each lane and returns a truthful per-source report,
failing the action when an attempted source fails; AppImage/Nix are
explained as manual/project-specific. `depclean` and Portage `ApplyUpdates`
are previewed from `emerge --pretend` at review time and bound by digest.
4. **AI-default routing (`phoebus-ai::assistant::run_assistant`):** the general
assistant now runs a bounded read-only investigation loop
(`kind:"investigate"` / `kind:"plan"`, `parse_step`, `is_general_investigation_action`)
before answering. `service::plan_general` supplies the read-only executor,
applies the source constraint to investigation requests and the final plan
(`constrain_action`: rewrite lane-selectable queries, refuse a foreign
lane), and accepts an empty action list as a pure answer. `sys` renders an
answer without executing; a missing model prints the exact `--legacy`
command.
- **Last verified (this session):**
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
exits 0 (only pre-existing lints remain).
- `cargo test --workspace`: 645 passed, 0 failed (was 602). New coverage
includes: catalogue action classification/validation and natural phrases;
catalogue report rendering (unavailable/failed/empty, installed/scope);
per-lane search/inventory/info with a recording runner; VDB metadata and
no-double-count; ambiguity; depclean preview/skip; per-source update
failure; forward dependencies; AI step parsing, the general investigation
loop, mutating-investigation refusal; `plan_general` investigation/answer,
foreign-lane refusal and constraint rewrite; and CLI routing: search/list/
info/updates without `--legacy` enter the AI workflow and never run
deterministically, a source flag constrains and never bypasses, `--legacy`
never contacts a model, read-only catalogue commands need no root and write
no transaction.
- Host smoke test of `sys search/list/info/updates --legacy` against the live
host (real Flatpak inventory and update list rendered).
- **Disposable-VM read-only acceptance** (`serial-driver.py boot` on a qcow2
clone of the installed disk, `SYS_BIN=/tmp/sys`): `sys-acceptance.sh`
reports `SUMMARY PASS=34 FAIL=0`, including `search-legacy`, `list-legacy`,
`info-legacy`, `updates-legacy`, `search-no-model-offer`,
`search-flag-constraint`, and the non-root maintenance refusals. Found and
fixed a real defect: the installed system left `/etc/portage/repos.conf` and
`/etc/portage/package.use/phoebus` root-only, so `emerge --search` failed for
a normal account. `portage::normalize_config_permissions` (unit-tested,
keyring excluded) makes the non-secret Portage config world-readable and
runs at config write and at finalize; with the same permissions applied to
the clone, `search-legacy` returns real results (3) and `updates-legacy`
reports 10 available. The fresh-install re-run is pending (base install is
~2 h).
- **Not yet verified (BLOCKED):**
- **A fresh VM install with the permission fix** (so the catalogue works
out of the box) has not been re-run; the base install is ~2 h. The fix is
unit-tested and its effect was demonstrated on the disposable clone.
- **Mutating catalogue journeys** (`apply updates`, `depclean`, `clean cache`)
are not exercised in a VM; they need a disposable installed disk and, for
`apply updates`, network.
- The privileged `sys --broker --execute-plan` path and replay rejection remain
unit-tested only: the serial console has no root access and no Polkit agent
(`sudo -n` denied), so `pkexec` elevation cannot complete. A
graphical/seat-providing VM or a passwordless-sudo test image is required.
- No AI provider credential is present; do not invent one. The general
investigation loop is fixture-verified (scripted transport), not live.
- The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
passphrase); do not guess or brute-force.
- A real privileged `chown` could not be exercised on this unprivileged host;
verified through the injectable fixer seam and the cross-uid refusal test.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Installed-VM read-only acceptance of the catalogue** on the booted disk:
```sh
# serve the static sys first:
cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
env DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 \
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/var/tmp/phoebus-vm/OVMF_VARS.fd \
BOOT_CHECKS='... curl .../sys ...; SYS_BIN=/tmp/sys bash .../sys-acceptance.sh ...' \
python3 installer/tests/vm/serial-driver.py boot
```
Expect `SUMMARY PASS=34 FAIL=0` (non-root), including the `search-legacy`,
`list-legacy`, `info-legacy`, `updates-legacy`, `search-no-model-offer`,
`search-flag-constraint` and non-root maintenance cases. Already run this
session on a clone of `verify-disk2.qcow2` (34/34).
2. **Privileged `--broker` acceptance in a seat-providing VM.** The remaining
unverified path is the actual `pkexec` elevation into
`sys --broker --execute-plan` (replacement during authentication, replay
after deleting user plan state, cancellation, a real privileged `chown`). It
needs a graphical Polkit agent or a passwordless-sudo disposable test image.
3. **AI-selected install journey (needs an authorised provider)**: boot the
installed disk, serve the built `sys` and a 0600 key file, then:
```sh
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.
4. **Rollback VM acceptance** (`serial-driver.py rollback`) on a cloned
disposable image of the installed system.
5. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU.
6. **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`).