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

147 lines
8.5 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), 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:
```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
```
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:
```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`).