161 lines
9.6 KiB
Markdown
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`).
|