phoebus_os/docs/HANDOFF.md
2026-09-24 19:14:16 -07:00

8.5 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), the three remaining administration defects from the latest review: (1) bind privileged execution to the actual approved plan via a broker-controlled approval ledger, (2) make personal settings work from a normal desktop account in user-owned storage, and (3) carry reviewed effects through execution and finish every started transaction truthfully. See ADR 0014.
  • Current focus:
    1. Approval ledger (phoebus_installer::approval, ADR 0014):
      • The plan's integrity seal (actions, per-step effects, candidate, target root, initiating uid, expiry) is the binding fingerprint and the O_EXCL consumption key in a root-owned ledger (/var/lib/phoebus/approvals, 0700 / 0600).
      • execute_plan_privileged now takes the reviewed digest and passes it to validate_prepared_plan(..., Some(expected_digest), ...). The digest travels across authentication independently of the plan file (sys --broker --execute-plan <id> --plan-uid <uid> --approval-digest <sha256> --root <root>).
      • Replacement under the same identifier is refused even when resealed with a valid checksum; replay is refused even after the user deletes every file in their own plan directory; concurrent submissions allow one execution; a crash leaves a reconciled interrupted record. reconcile_interrupted runs at broker startup.
      • The initiator is derived from PKEXEC_UID (approval::broker_initiator_uid); --plan-uid is untrusted input. Authentication precedes the ledger claim, so refusal consumes nothing.
    2. User-owned personal settings (phoebus_executor::personal):
      • UserStorage resolves the initiating user (PHOEBUS_UID → SUDO_UID → PKEXEC_UID → effective uid; home from /etc/passwd) and writes 0600 in 0700 atomically.
      • Personal preferences → ~/.config/phoebus/package-preferences.toml; proactive snooze/dismiss → ~/.local/state/phoebus/proactive-state.toml (bounded). System defaults remain /etc/phoebus/..., changed only via set_package_preference { system_wide: true } through the broker.
      • chooser::load_preferences merges system < personal (personal wins, per-app union); proactive reads the legacy root-owned file only as a migration fallback. Bridge failures are surfaced; the QML notifies on failure and the profile combo now uses the exact serde values.
    3. Reviewed effects + terminal transactions (service::execute_prepared):
      • Reviewed per-step effects are carried forward; resolve_effects is now only evidence compared with phoebus_core::effects::approval_holds (earlier-step-introduced targets are the only allowance). A material change aborts with stale plan; only Portage actions are compared (other lanes are validated by validate_prepared_plan).
      • Every path after transaction::begin reaches a terminal result; effect resolution failure, stale plan, action failure and verification failure are recorded with per-action outcomes and the snapshot retained.
  • Last verified (this session):
    • cargo fmt --all -- --check clean.
    • cargo test --workspace: 582 passed, 0 failed, including new privileged entry-point regressions: replacement during authentication, recomputed checksum, deleted user plan+claim replay, concurrent execution, wrong caller/root, expiry, interruption reconciliation, effect drift, effect resolution failure after begin, and later-step failure after an earlier success.
    • cargo clippy --workspace --all-targets runs (exit 0; only the pre-existing result_large_err, one arg-count and one DiskPhase lints remain).
    • Static sys (crt-static) builds (static-pie, 6.4 MiB).
    • Host-level sys CLI tests: system-wide preference refused without root; personal preference saved to user storage without touching /etc.
  • Not yet verified this session (BLOCKED):
    • Installed-VM journey and the 12-step acceptance list. The existing disposable installed disk (/var/tmp/phoebus-vm/disks/test-disk.qcow2) reaches the LUKS prompt but no passphrase in this environment opens it: the harness default (phoebus-luks-test, which is also the content of /home/dominic/vmlab/serve/luks.pw) is rejected, and no other credential is available. Do not guess or brute-force.
    • No AI provider credential is present; do not invent one.
    • A fresh disposable VM install would verify the installed journey but takes ~2 h (disk space is tight, 24 GiB free), so it was not attempted in this pass.
  • Public repo: https://git.phoebus.club/phoebus/phoebus_os (remote origin, SSH port 2222).

Next actions (in order)

  1. Unlock or rebuild the installed VM (blocker). The installed disk reaches the LUKS prompt but its passphrase is unknown; the committed harness default is rejected. Either supply the real passphrase or perform a fresh disposable install (~2 h) to obtain an installed system, then run the full 12-step acceptance list below.
  2. Installed sys acceptance 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
    
    The new broker behaviour (replacement during authentication, replay after deleting user plan state, cancellation) is already covered by phoebus-installer unit tests; the installed run confirms the sealed elevation path and the personal-preference acceptance case.
  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).