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

9.6 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), 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:
    # 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:
    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).