phoebus_os/docs/HANDOFF.md
Phoebus 1d37fbc1b8 ci(release): fail closed and bind gates to the candidate artifact
Make a passing CI/release result mean the checks actually ran.

- .forgejo/workflows/ci.yml is fail-closed: it provisions the pinned
  toolchain or fails, then runs one 'make ci' (fmt-check, clippy, workspace
  tests, VM-harness safety tests, release build, static installer build).
- Pin stable Rust 1.93.1 in installer-rs/rust-toolchain.toml; run cargo gates
  with --locked for reproducible dependencies.
- phoebus-release gates now records passed/failed/blocked/skipped/not_run
  (only passed is a pass), executes real host gate commands, and imports the
  existing VM-harness results.json instead of a competing harness. Gates with
  no automation are always blocked.
- Bind gate reports and harness evidence to a candidate name+SHA-256
  (--candidate; PHOEBUS_VM_ARTIFACT[_SHA256]); stale or unbound evidence is
  failed, never passed.
- publish refuses unless the report is candidate-bound and all-passed, the
  manifest verifies the artifact and a detached signature verifies; atomic
  publish preserves and restores the previous release on failure.
- vmsafety.Results records the verified artifact digest; 3 new Python tests.
- 20 new Rust regression tests; ADR 0012 and docs updated.

Verified locally: make ci (364 Rust tests, 19 harness tests, release and
static builds) exit 0; static binary is static-pie linked. CI runner, VM and
model gates remain unexecuted here.
2026-09-22 07:34:27 -07:00

118 lines
7 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-22), CI and release verification
hardening (branch `codex/harden-ci-release-verification`).
- **Current focus:** Made CI and release verification mean what they claim.
(1) `.forgejo/workflows/ci.yml` is fail-closed: it provisions the pinned
toolchain or fails, and runs one `make ci` (fmt-check, clippy, workspace
tests, VM-harness safety tests, release build, static installer build).
`installer-rs/rust-toolchain.toml` pins stable 1.93.1; all cargo gates use
`--locked`. (2) `phoebus-release` gate statuses are now
`passed`/`failed`/`blocked`/`skipped`/`not_run` (only `passed` is a pass);
host gates execute real commands; VM/seat/model gates import the existing VM
harness `results.json` (`--harness-results`). (3) Gate reports and harness
evidence are bound to a candidate name+SHA-256 (`--candidate`;
`PHOEBUS_VM_ARTIFACT[_SHA256]`), so stale evidence cannot authorize another
build. (4) `publish` refuses unless the report is candidate-bound and
all-passed, the manifest verifies the artifact and a detached signature
verifies; `atomic_publish` restores the previous release on failure.
- **Last verified (this session):**
- 364 Rust tests + 19 harness tests green; `cargo fmt --all -- --check` and
`cargo clippy --workspace --all-targets` clean (exit 0); `make ci` exit 0.
- Release build and static installer build succeed; the static binary is
`static-pie linked` (4.99 MB).
- New regression tests (20 Rust + 3 Python) cover: absent prerequisites are
`blocked`; a failed host gate is `failed` with diagnostics; explicit skips
and `--only` are never passes; manual gates are `blocked`; stale or
unbound harness evidence is `failed`; `publish` refuses on not-run gates,
unbound/stale reports, missing manifest, manifest mismatch, missing or
failing signature, and a failed publication leaves the previous release
intact.
- CLI smoke: `gates` (all `not_run`), `gates --execute --only rust-fmt`
(executes and reports `passed`), harness-evidence import (`install`
`passed`), and `publish` refusal on an unbound report.
- **Not yet verified this session:** no Forgejo Actions runner is registered,
so the workflow is unexecuted. The VM, graphical-seat and live-model gates
are `blocked` here (no disposable VM/model in this environment).
`no-model-recovery`, `updates-and-rollback` and `desktop-session` have no
automated harness yet and are always `blocked`, so a full publication is not
possible until they are automated (intentional: no false pass).
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Complete the graphical install with a real model**: download a small local
OpenAI-compatible model (or supply a 0600 provider key), then run
`gui-driver.py gui` through disk/account/review/ERASE/install/rebooot twice
on fresh qcow2 disks and record the passing journeys. The current automated
journey passes to the AI gate only.
2. **Installed Mango desktop**: install the default profile in a graphical VM
and verify the panel/launcher/terminal/audio/network/lock/idle, the dwl
fallback, and the welcome/installer absence on the installed system.
3. **Rollback VM acceptance**: deliberately break an update, run `sys undo`,
reboot detached, verify `/var/db/pkg` matches `/`, then boot the recovery
entry with no network or model (ADR 0007).
4. **Narrow the live broker privilege**: replace the live-only
`NOPASSWD: ALL` rule for the GUI bridge with the smallest practical
command-scoped rule once a safe sudoers form is verified (ADR 0011 context).
5. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
6. **Register a Forgejo Actions runner** and confirm `make ci` runs green
there; no runner is registered, so `.forgejo/workflows/ci.yml` is
unexecuted. `make ci` passes locally, but that is not CI verification.
7. **Automate the three blocked release gates**: `no-model-recovery`,
`updates-and-rollback` and `desktop-session` have no harness scenario yet,
so they are always `blocked` and a full publication is impossible. Add
harness modes (or reviewed manual evidence) and re-run
`make release-gates`.
## Known blockers / risks
- **No Forgejo Actions runner is registered**, so `.forgejo/workflows/ci.yml`
is unexecuted; `make ci` is green locally only. Registering an `act_runner`
with a rustup toolchain is the external prerequisite (ADR 0012).
- **A full release cannot be authorized yet**: `no-model-recovery`,
`updates-and-rollback` and `desktop-session` have no automated harness, so
the gate report is never all-passed. This is deliberate until they are
automated.
- No live DeepSeek/OpenAI key and no local model are available; the **full GUI
install past the AI step** and two fresh-disk graphical installs are NOT
verified (normal installation requires a connected model). The AI step is
verified as a blocked prerequisite and with a fixture transport.
- **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor
is the dwl fallback session.
- Rollback and the AI sandbox are implemented and unit-tested but not
VM-verified. NVIDIA is not verified.
- A **separate physical computer** for the OpenCode transport test is not
available (BLOCKED); a forwarded-hop + unauthenticated-LAN-refusal host-local
test was done instead.
- The GUI bridge reaches Quickshell via `Process` + `/usr/bin/sudo -n`; it
relies on the live user's passwordless sudo. The live sudoers rule is still
`NOPASSWD: ALL` (live-only); narrowing the broker permission is future work.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick present.
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`); the appliance ISO builds without root.
- Local QML iteration: `/tmp/opencode/run-qml.sh <config-dir>` runs a config on
a nested Mango over the host X11 using the built rootfs libraries, and
`grim` captures it. The sanctioned verification is the disposable VM.
- VM harnesses: `installer/tests/vm/gui-driver.py` (graphical live ISO:
`gui`/`install`/`boot`), `appliance-driver.py`, `serial-driver.py`.
`DISK` must be a disposable qcow2; never point it at `/dev/*`.
- Serve the install fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed and pushed
(`scripts/agent-commit.sh` + `scripts/publish.sh`).