docs: record the 2026-09-22 harness, security and polish session
Some checks are pending
ci / test (push) Waiting to run

Update the changelog, status matrix, handoff and VM boot verification with
the 23/23 graphical journey, the hardened harness, the confirmed fixes and
the remaining blocked/unverified gates (full GUI install past AI, rollback,
installed desktop, physical second-computer OpenCode transport).
This commit is contained in:
Phoebus 2026-09-21 20:01:58 -07:00
parent 613e383082
commit fb4dcc5683
4 changed files with 168 additions and 35 deletions

View file

@ -7,6 +7,65 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased
### Added
- **OpenCode connection workflow and capability probe.** New ADR 0011 and
`docs/OPENCODE.md` separate the four components (client, server, model
service, Phoebus broker) and document host-local and tunnelled remote use.
`phoebus-executor::opencode_server` probes `/global/health` and
`/config/providers` and reports a typed state (`disconnected`,
`authentication_required`, `incompatible`, `reachable_no_model`, `ready`)
instead of assuming a TCP connect or HTTP 200 means compatibility. Exposed as
`phoebus-installer --opencode-probe <url>` (read-only, nonzero unless a model
is available). Never returns provider credentials. Verified against the
installed `opencode 1.18.32` (ready) and a deliberate unauthenticated LAN bind
(`authentication_required`).
### Security
- **The target disk is revalidated immediately before partitioning.** An
approval now binds to a verified device, not a name: `storage_prepare` re-probes
and refuses if the disk disappeared, became protected (mounted/read-only/live),
or changed size/model since it was selected. Regression tests cover each case.
- **The GUI bridge refuses replayed and overlapping installs.** An approval is
single-use and consumed before destructive work; a second `start_install`, a
retry or a reconnected frontend cannot start a second installation. Request
lines and secret values are length-bounded; deeply nested JSON is rejected.
- **Provider transport hardened.** Only `http(s)` endpoints are accepted, URLs
with characters that could inject curl config directives are refused, the
transfer is restricted to `http,https`, redirects stay disabled (so an
`Authorization` header cannot follow a redirect to another origin), and the
response is size-bounded (`max-filesize`).
- **`TargetRoot` refuses symlink escapes.** `write`/`ensure_dir` reject a
symlinked path component inside the target instead of following it, so a
planted symlink cannot redirect an installer write to the host.
- **Unauthenticated OpenCode endpoints are not treated as usable.** The probe
reports `authentication_required` for a passwordless LAN bind rather than
`ready`.
### Fixed
- **Disk sizes are no longer reported as `0 B`.** `probe_disks` invoked `lsblk`
without `-b`, so human-readable sizes (`30G`) failed the byte parse and every
disk displayed `0 B`; the size-based disk-identity check was also blind. The
`-b` flag is now used and pinned by a test.
- **The welcome window's primary action is keyboard-reachable.** It now requests
activation and force-focuses "Install Phoebus OS", so Return launches the
installer (previously no focus ring was shown and Return did nothing). A
regression test also rejects the non-existent `FloatingWindow.onActiveChanged`.
- **The installer cannot be abandoned mid-install without explanation.** Escape
during the destructive phase is refused and the UI states that the operation
cannot be cancelled safely; the AI step shows its "connect and validate"
guidance inline, beside the controls.
### Changed
- **The VM harness enforces its own safety rules and reports structured
results.** `installer/tests/vm/vmsafety.py` validates every writable drive
(qcow2, inside `PHOEBUS_VM_DISKS`, no `/dev/*`, block/char devices, raw
images, escaping symlinks or outside backing chains), gives each run its own
OVMF variable file and QMP socket, uses structured QMP and argument arrays
(no `os.system`), and returns nonzero on any failed assertion, timeout, EOF or
missing result. Statuses are `PASS`/`FAIL`/`BLOCKED`/`SKIPPED`/`NOT RUN`.
`make test` now runs the harness unit tests; `installer/tests/vm/report.py`
builds a browsable run report.
### Added
- **Graphical installation experience.** The live ISO now boots into a branded
Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the

View file

@ -3,53 +3,70 @@
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-21), graphical installer ISO.
- **Current focus:** The ISO now boots into a branded **welcome window** and a
full **graphical installer wizard** over a typed JSON bridge
(`phoebus-installer --gui-bridge`), with the TUI/CLI as fallback. The brand
system, boot-menu identity, live-medium detection and the recovery-boot
default bug are fixed. See ADR 0010 and `docs/VM-BOOT-VERIFICATION.md`.
- **Last updated:** this session (2026-09-22), harness + security + polish.
- **Current focus:** Hardened the VM harness (enforced qcow2/`/dev`/backing-chain
safety, structured PASS/FAIL results, per-run OVMF+QMP, no `os.system`),
fixed confirmed security defects (disk revalidation before partitioning,
bridge replay/concurrency + input bounds, provider transport URL/size
hardening, `TargetRoot` symlink escapes, and the `0 B` disk-size probe bug),
added an OpenCode server capability probe + docs/ADR 0011, and fixed the
welcome focus ring and the untruthful mid-install cancellation.
- **Last verified (this session):**
- `gui-driver.py gui`: welcome autostarts; DMS first-run dialogs suppressed;
installer opens; duplicate sessions prevented (`n1=n2=1`); keyboard
navigation reaches network + AI steps; the AI step blocks without a model.
- `gui-driver.py install` + `boot` on the built ISO: `INSTALL-RC=0`,
`NO_SECRET_LEAK`, and a **detached** boot with systemd `running`,
**0 failed units**, LUKS2, all Btrfs subvolumes and network, and the boot
menu defaulting to **Gentoo Linux** (not recovery).
- Rust suite: GUI bridge dry-run protocol, approval binding/invalidation,
secret non-disclosure, brand tokens/contrast, boot default pinning.
- `gui-driver.py gui` on the rebuilt ISO: **23/23 PASS**, exit 0. Welcome
autostarts; Return launches the installer (focus fixed); duplicate sessions
prevented; live medium protected; keyboard navigation reaches network + AI;
advancing without a model is refused and starts nothing.
- `make test` green (Rust + 16 harness unit tests); `cargo fmt --check`,
`cargo clippy --workspace --all-targets` (no errors), release + static
builds.
- OpenCode probe: `ready` against `opencode 1.18.32`; `authentication_required`
(exit 1) against an unauthenticated LAN bind.
- ISO: `installer/live/phoebus-installer-amd64.iso` 1.6 GiB,
`sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee`.
`sha256 428dbd7547db8690596bf5c3a0d7a6fa8aee4c9f9eca1e926c216712dd050b36`;
static binary `sha256 2f9cd4b36a12e469d2b6187166acaf8b11f7f382cc19f7ad08bb2a809c855591`.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Live AI provider call**: exercise the GUI AI step (and `sys ask`) with a
real 0600 key or a downloaded local model; the path is fixture-verified only.
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. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
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`).
5. **Release gates on a CI runner**: `phoebus-release gates --execute` and
6. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed.
## Known blockers / risks
- No live DeepSeek/OpenAI call has been made (no key in this environment); the
AI step is verified as a blocked prerequisite and with a fixture transport.
- 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.
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

View file

@ -93,6 +93,13 @@ still not VM-verified.
| greetd login (Mango default, dwl fallback) | yes | yes | no | no |
| Live desktop ISO (Mango + DMS) | yes | guards tested | graphical VM + GUI journey + detached boot | no |
| Live welcome autostart + duplicate prevention | yes | guards tested | live graphical VM | no |
| Welcome primary action keyboard-focus | yes | guards tested | live graphical VM | no |
| VM harness disk safety + structured results | yes | yes (16 tests) | n/a | n/a |
| Target disk revalidation before partition | yes | yes | no | n/a |
| Bridge replay/concurrency + input bounds | yes | yes | no | n/a |
| Provider transport endpoint/size hardening | yes | yes | no | n/a |
| `TargetRoot` symlink-escape guard | yes | yes | n/a | n/a |
| OpenCode server capability probe | yes | yes | real host probe (`ready`) | n/a |
| GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no |
| Release gates + atomic publish | yes | yes | no | n/a |
| `sys` verbs | yes | yes | yes | no |
@ -130,18 +137,21 @@ still not VM-verified.
- **The live desktop ISO** (`installer/live/build.sh`) builds a Debian testing
rootfs with Mango + DMS, live-only autologin, a branded welcome window and a
graphical installer frontend over the typed bridge. Its desktop-payload
guards are unit-tested, and the built ISO
(`sha256 2a52178c…`, 1.6 GiB) was booted in a graphical, seat-providing VM:
the welcome window opened automatically, the installer launched (a second
launch created no duplicate), keyboard navigation reached the network and AI
steps, and advancing without a connected model was refused. The same ISO was
then installed non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and
booted **with the ISO detached** (systemd running, 0 failed units, LUKS2,
all Btrfs subvolumes, network). A live AI provider call was **not** possible
(no key in this environment); the AI step is verified as a blocked
prerequisite and with a fixture transport in unit tests. The **installed**
Mango system (GURU + compiled Quickshell/DMS) and the dwl fallback in a VM
are not yet verified.
guards are unit-tested. The rebuilt ISO
(`sha256 428dbd75…`, 1.6 GiB, build id in `/etc/phoebus/build`) was booted in
a graphical, seat-providing VM and the automated `gui` journey passed
**23/23** checks: the welcome window opened automatically, "Install Phoebus
OS" launched the installer from the keyboard, a second launch created no
duplicate, the live medium was reported protected, keyboard navigation
reached the network and AI steps, and advancing without a connected model was
refused. An earlier appliance build of the same code path was installed
non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and booted **with the
ISO detached** (systemd running, 0 failed units, LUKS2, all Btrfs subvolumes,
network). A live AI provider call was **not** possible (no key and no local
model in this environment), so the **full graphical install past the AI step**
is not claimed; the AI step is verified as a blocked prerequisite and with a
fixture transport in unit tests. The **installed** Mango system (GURU +
compiled Quickshell/DMS) and the dwl fallback in a VM are not yet verified.
- **AI sandbox** is implemented (`systemd-run` hardening properties, tested at
the argv level) and fails closed without `systemd-run`; it has not been
exercised in a VM. Only typed actions and the privacy boundary were previously

View file

@ -552,6 +552,43 @@ the kernel's `sort-key`, and the specification's final filename tie-break
pinning `loader.conf` to the newest real kernel entry and giving the recovery
entry `sort-key zzzz-phoebus-recovery`; unit tests pin both.
## 2026-09-22 — automated graphical journey (gui-driver) and hardened harness
The graphical live ISO was rebuilt and driven automatically by
`installer/tests/vm/gui-driver.py gui` in a graphical, seat-providing
QEMU/OVMF VM with a disposable qcow2 disk directory and a per-run OVMF variable
file.
- Source revision: `7e9fa9c` plus uncommitted work; build id recorded in
`/etc/phoebus/build` (`7e9fa9c+dirty…`).
- Static installer: `sha256 2f9cd4b3…` (4,716,544 bytes, static-pie).
- ISO: `installer/live/phoebus-installer-amd64.iso`,
`sha256 428dbd75…`, 1.6 GiB, built with
`PHOEBUS_REUSE_ROOTFS=1` (Mango 0.17.2 + DankMaterialShell 1.6.2).
- Result: **23/23 checks PASS**, exit status 0
(`/var/tmp/phoebus-vm/gui-gui-20260922T025537Z-69f754cf/`).
Asserted: welcome autostart; live/branding payload markers from command
output (not the echoed command); the live medium protected; "Install Phoebus
OS" launched the installer from a Return keypress; duplicate sessions
prevented (`n1=n2=1`); the frontend reported no bridge errors; keyboard
navigation reached the network and AI steps; advancing without a connected
model was refused and started no installation.
- Screenshots at every page (welcome focus, language, network, AI model, AI
blocked, final state) plus a `screenshot-manifest.json`; `report.py` builds a
browsable `report.html`. All artifacts stay under `/var/tmp/phoebus-vm/`
(outside git).
Harness safety verified in the same work: the drivers reject `/dev/*`, block
and character devices, raw images, symlinks escaping the disposable directory,
and outside backing chains, with a nonzero exit (`make test-vm`, 16 unit
tests). Screenshots use structured QMP and argument arrays; there is no shell
interpolation.
A host-local OpenCode transport test also ran: `phoebus-installer
--opencode-probe` returned `ready` against `opencode 1.18.32` through a
forwarded second loopback endpoint, and `authentication_required` (exit 1)
against a deliberately unauthenticated LAN bind.
## Known remaining work
- The graphical session was verified with the **headless** wlroots backend
@ -565,3 +602,13 @@ entry `sort-key zzzz-phoebus-recovery`; unit tests pin both.
- Desktop USE still does not match the signed binhost, so the desktop
transaction compiles a large amount from source (~26 minutes for the desktop
package set on 8 vCPUs in the test VM).
- **The full graphical install past the AI step is NOT verified.** No live
provider key and no downloadable local model were available in this
environment, and normal installation requires a connected model by design;
the automated journey stops at (and verifies) the blocked AI prerequisite.
Two fresh-disk graphical installations from the final candidate remain
unrun. The deterministic noninteractive install + detached boot remains the
proven boot path.
- **A separate physical computer for the OpenCode transport test is NOT
available**; that check is BLOCKED. The forwarded-hop and
unauthenticated-LAN-refusal tests are host-local.