phoebus_os/docs/CHANGELOG.md
Phoebus 359f083bc2
Some checks are pending
ci / test (push) Waiting to run
test(gui): drive the OpenCode AI step through the real UI
Add an 'opencode' harness mode with a guest-loopback relay (the tunnel
shape), keyboard selection of the OpenCode chip, UI entry of the server/
provider/model (and a 0600 server password), and assertions on the
frontend's secret-free state (tested, validated, applied). Record the VM
evidence and the remaining not-run full-install gate.
2026-09-22 03:32:07 -07:00

427 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Changelog
All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary.
Format: Keep a Changelog. Dates are UTC.
## Unreleased
### Added
- **Real OpenCode agent-server adapter.** `phoebus-executor::opencode_client`
implements the OpenCode session/message protocol over the project's curl
transport and the `ModelTransport` trait, so the strict proposal parser,
evidence review, bounded facts and executor are reused unchanged. The GUI
("OpenCode agent"), the installer CLI (`--ai-backend opencode`,
`--opencode-server/-provider/-model/-password-file`) and `sys ask` all use it.
It creates a transient session per request, accepts only the completed
assistant text parts, disables tools per message, and deletes the session.
A JSON schema output mode is available in the protocol but is not used: the
shipped DeepSeek models reject it, and the prompt carries an explicit change
shape instead. The `opencode 1.18.32` contract was verified directly: session
creation rejects a `model` field, `/provider` metadata can contain a
credential and is reduced to ids/model names, and auth is HTTP Basic
(`opencode` / `OPENCODE_SERVER_PASSWORD`).
- **`--opencode-test`** obtains and validates a real model response (exit
nonzero on failure), distinct from the read-only `--opencode-probe`. A live
acceptance test (`make opencode-acceptance`) fails as BLOCKED when no server
is configured, so it cannot pass by not running.
- **Truthful OpenCode connection states** (`insecure_transport`, `unreachable`,
`authentication_required`, `authentication_rejected`, `incompatible`,
`reachable`, `model_catalog`, `selected_model_unavailable`); `ready` is
reserved for a validated response and is never returned by the probe.
- **GUI "Test connection"** and OpenCode connection controls, plus a backend
selection (`ai.backend`) in canonical configuration.
### Security
- **The mandatory-AI gate now requires a validated interaction.** Both the GUI
bridge and the installer CLI refuse to install when only a provider name is
configured; a successful, validated model interaction bound to the current
configuration (and credential) is required. Changing the model, endpoint,
server or a secret invalidates it. A direct provider or `--no-ai` remains the
fallback.
- **OpenCode transport policy is enforced.** Plain `http://` is accepted only
when the resolved destination is loopback and the connection is pinned to the
checked address; remote access is `https://` with certificate verification or
an authenticated tunnel to loopback. Redirects, unsafe schemes and oversized
or trickled bodies are bounded, and credentials travel only on curl's stdin.
- **Credentials never surface.** The catalog is reduced to ids/model names;
server responses that echo credentials are not retained, and tests feed
credential-bearing bodies and assert they do not appear in errors or state.
### Verified
- **The graphical installer uses the OpenCode adapter.** In a disposable
graphical VM the wizard selected "OpenCode agent", entered the server,
provider and model through the UI, obtained a real model response (Test
connection) and a validated proposal (Connect and validate, green
"Validated"). The `opencode` harness run passed 17/17 and the GUI regression
25/25. A password-protected server was reached through authentication as
well. The full graphical installation beyond the AI gate is still not run.
### Fixed
- **A malformed model proposal now gets one bounded corrective retry** before
the strict parser rejects the interaction (the shipped DeepSeek models
occasionally keyed the change or rationale wrongly). The parser remains the
final authority; a retry that still fails is still rejected.
- **OpenCode client/probe defects found by testing:** the handwritten HTTP
reader (no total deadline, UTF-8-unsafe chunk fallback) was removed in favour
of the curl transport; the catalog is no longer parsed on a non-2xx status; a
provider-shaped 500 can no longer look like a catalog; the duplicate-session
harness check requires exactly one session; and GUI navigation is asserted
from secret-free frontend state lines rather than inferred from a screenshot.
### 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
dominant action, shows ISO version and readiness (network, firmware, memory,
cores) and keeps network/display/accessibility/help/keyboard-test/power tools
available, with troubleshooting tools under Advanced. A full graphical setup
wizard (`phoebus-install`) guides language and keyboard, network and
prerequisites, AI model connection, destination disk (with protected disks
and the installer medium identified), account and encryption, review,
`ERASE` authorization, progress and completion. Duplicate installer sessions
are prevented. The TUI/CLI remains the fallback. See ADR 0010 and
`docs/VM-BOOT-VERIFICATION.md`.
- **Typed JSON GUI bridge.** `phoebus-installer --gui-bridge` exposes a narrow,
fail-closed protocol over stdin/stdout that reuses the same `InstallConfig`,
validation, plan, `DestructiveAuthorization` and staged executor as the TUI.
Approval is bound to a plan digest, secrets travel only over the stdin pipe,
and real backend stages are reported with categories (no invented
percentages). `Installer::install_observed` and an `InstallObserver` trait
were added; `Installer::install` is unchanged.
- **Phoebus brand system.** `phoebus-core::brand` provides charcoal/warm
white/amber tokens plus a sun emblem, wordmark and wallpaper as deterministic
SVG (emitted via `--emit-asset`, shared with the QML frontend), applied to the
GRUB menu, live wallpaper, welcome window, installer, application icon and
completion screen. Readable contrast and the QML/Rust palette are pinned by
tests.
### Fixed
- **Installed systems no longer default into recovery.** `loader.conf` now pins
the newest real kernel entry, and the snapshot recovery entry carries a
`sort-key` that keeps it after every kernel, so a low machine-id can never
make systemd-boot select the recovery entry by filename tie-break. Previously
an installed system could boot `systemd.unit=rescue.target` after reboot.
- **DMS first-run dialogs are suppressed on the live medium** by pre-seeding
DMS's own onboarding and changelog markers, so the installer is the first
thing the user sees.
- **The live-medium device is now identified.** `probe_disks` also inspects
`/run/live/medium` and `/run/live/rootfs`, so the ISO is labelled as the
installation medium (and remains protected).
- **The installer shortcut is live-only.** `phoebus-install` and its desktop
entry are no longer written to an installed system.
### Changed
- **Mango + DankMaterialShell is now the default desktop** for both the
installation ISO and the installed system (explicit owner decision). Omitted
`desktop.profile` selects `mango`; Flatpak and PipeWire are on by default.
Explicit `none`, `minimal`, `dwl` and `full` continue to work unchanged
(ADR 0009).
- **Installed login uses greetd + tuigreet.** Authentication is always
required; the default session is Mango and the dwl entry remains selectable
(`--sessions /usr/share/wayland-sessions`). Live autologin is a separate,
live-only configuration and is never written to an installed system.
### Added
- **Live desktop ISO**: `installer/live/build.sh` now builds a rootless Debian
testing rootfs containing Mango (built from a pinned source release),
DankMaterialShell (pinned, SHA-256-verified release tarball), Quickshell,
scenefx, wlroots 0.20, greetd/tuigreet and the desktop integration, then
splices it into the base Debian-Live boot equipment. The live user autologins
into Mango, an "Install Phoebus" launcher opens the unchanged installer UI,
and a serial/VT recovery console is retained. The build fails clearly if a
required desktop component is missing. Debian packages never enter the Gentoo
target. The built ISO was booted in a graphical, seat-providing VM: Mango +
DankMaterialShell + Quickshell ran and a `screendump` captured the DMS panel
and welcome window (`docs/VM-BOOT-VERIFICATION.md`).
- Shared desktop assets are emitted from one source of truth by
`phoebus-installer --emit-asset` and used by both the installer and the live
build. Regression tests cover the default/overrides, login configuration,
live/installed separation, session entries, pinned checksums and the live ISO
desktop-payload guards.
### Added
- **Mango + DankMaterialShell desktop option** (`desktop.profile = "mango"`):
`gui-wm/mangowm` 0.17.2 (wlroots 0.20) plus `gui-apps/dankmaterialshell`
1.5.3 / Quickshell 0.3.1 / scenefx 0.5, installed through the GURU community
overlay with scoped `~amd64` keywords (never global). The installer writes
GURU's `repos.conf`, bootstraps `dev-vcs/git`, and syncs the overlay. A
`phoebus-session-mango` entry point, a packaged Mango config seeded once into
the user's config, DMS keybindings, a `mango-session.target` binding for DMS,
and `phoebus-mango.desktop`/`phoebus-dwl.desktop` session entries are
generated. dwl remains the fallback session and is installed alongside. The
profile is selectable but **not promoted to default** pending graphical-VM
verification (ADR 0009).
## 2026-09-21 — Coherent rollback, installed assistant, Nix isolation
### Added
- **Coherent rollback and recovery** (`phoebus-core::rollback`,
`phoebus-executor::rollback`): a recovery point now captures `@` **and** the
separately mounted `@var` (Portage state) under one name; rollback creates a
writable root generation, rewrites the restored root's fstab **and** the BLS
`rootflags=subvol=`, selects a boot entry whose kernel modules match the
restored `/lib/modules`, and writes "previous" and snapshot-based "recovery"
entries. A persisted `rollback-state.toml` makes interruption safe and
resumable; retention prunes old snapshots and protects in-flight targets; a
1 GiB free-space check gates the operation. See ADR 0007.
- `sys undo` / `sys undo <id>` / `sys undo status` and the high-risk `undo`
typed action. The installer now records a snapshot-based "Phoebus Recovery"
entry at install time, so recovery does not depend on the live root.
- **Installed conversational assistant** (`phoebus-ai::assistant`,
`sys ask <request>`): bounded facts -> typed plan -> concrete resolved effects
-> approval/authentication -> deterministic execution -> transaction record.
No model is required: `sys ask` falls back to the deterministic parser.
- **OS-level model sandbox** (`phoebus-executor::sandbox`): the network call
runs in a hardened, unprivileged transient systemd unit (`DynamicUser`,
`ProtectHome`, `ProtectSystem=strict`, `NoNewPrivileges`, syscall and
address-family filters). It fails closed when `systemd-run` is unavailable.
- **Resolved package effects and approval binding** (`phoebus-core::effects`):
`emerge --pretend` is parsed into additions/upgrades/downgrades/removals with
source-vs-binary provenance and download size; a plan digest binds approval,
and a material change between review and execution aborts. New bounded typed
actions `flatpak_install`/`flatpak_remove`/`flatpak_list` and `nix_prepare`.
- **Transaction log** (`phoebus-core::transaction`): assistant and `sys`
actions record their actions, result and recovery point; `sys history` shows
snapshots and transactions.
- **Desktop completeness**: `phoebus-menu` (wofi drun launcher + power menu),
`phoebus-lock` (swaylock), `phoebus-idle` (swayidle: lock, suspend,
before-sleep lock) and a system-wide Waybar config with network, audio,
battery, clock and power controls.
- **Release gates** (`phoebus-installer::release`): a registry of the real
candidate checks (install, detached boot, desktop, updates/rollback,
no-model), a gate report that never records an unexecuted check as passed,
atomic publication that preserves the last known-good `latest.iso.prev`, and
signing/verification command helpers.
- New VM harness for the Debian-Live appliance:
`installer/tests/vm/appliance-driver.py`, `appliance-guest.sh` and
`appliance-test.conf.example`.
### Changed
- **Nix build isolation is enforced**: `sandbox = true`,
`sandbox-fallback = false`, with store bounds (`min-free`/`max-free`) and
`auto-optimise-store`. Lifecycle operations (remove/purge, gc) and a
bounded `nix_prepare` action were added; the Portage-owned ebuild approach is
documented in ADR 0008. See ADR 0006.
- Desktops install `swayidle`/`swaylock` session helpers and a Waybar
configuration; `phoebus-session` starts the idle daemon.
### Added
- **Nix bootstrap (on by default, VM-verified).** `phoebus-executor::nix`
fetches the pinned, SHA-256-verified official Nix release and bootstraps it
into the target with discrete commands (store copy, `nix-store --load-db`,
`nixbld` users, state dirs, profile and daemon units). A desktop VM confirmed
`nix-daemon.service` active and `nix shell nixpkgs#hello` printing
`Hello, world!`. A binary ebuild was ruled out: the upstream installer has no
`DESTDIR` and runs `nix-store --load-db` against the real root.
- `finalize` now flushes the target (`sync`) before unmounting, so late writes
such as `/usr/local/bin/phoebus-session` and the exported installer log are on
disk even after a forced poweroff.
### Changed
- **Installing Phoebus now requires an AI.** The installer refuses an install
with no provider unless the explicit break-glass `--no-ai` (alias `--legacy`,
or `PHOEBUS_NO_AI=1`) is used. A new `local` provider (Ollama/llama.cpp/
LM Studio) and `--ai-endpoint` support a model the user downloaded; no model
is shipped.
- Desktop installs now include `sys-apps/xdg-desktop-portal`,
`xdg-desktop-portal-gtk` and `xdg-desktop-portal-wlr`, so Flatpak and
Wayland apps get file choosers and screencast support.
### Added
- `sys` offline package commands: `sys install <name>`, `sys remove <name>`,
`sys search <query>` (plus the `remove_package`/`search_packages` typed
actions). They are deterministic Portage operations with no model involved —
`emerge` resolves a bare name or a full atom — so the system stays fully
administrable offline and without the assistant.
- **Debian-Live installer appliance** (`installer/live/build.sh`, no root): a
bootable Phoebus installer ISO built by overlaying the static installer, the
OpenCode manifest and the Debian tools the live image lacks onto a Debian-Live
stable base, with a serial-visible auto-booting grub config. The target stays
Gentoo. See `docs/PLAN-DEBIAN-LIVE.md` and ADR 0005.
- Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`,
`scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`.
- Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`,
`ARCHITECTURE.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`, `GIT-WORKFLOW.md`,
`CHANGELOG.md`, and the top-level `AGENTS.md`.
- `.gitignore` covering the ISO, build output, transcripts and secrets.
## 2026-09-20 — AI guidance, desktop reliability, snapshots
### Added
- AI-assisted install guidance: an OpenAI-compatible provider layer for
**DeepSeek** and **OpenAI** plus a test transport
(`phoebus-ai::provider`), credential loading and a curl transport that keeps
the API key out of argv, config and logs (`phoebus-executor::ai`), and CLI
flags `--ai`, `--ai-provider`, `--ai-model`, `--ai-api-key-file`,
`--ai-proposal-file`, `--ai-facts`. The TUI offers
DeepSeek/ChatGPT/without-AI.
- Typed proposal extensions: scoped `package.use`, explicit build jobs and
binary-package preference. Every proposal now requires a non-empty reason and
duplicate/conflicting changes are rejected before anything is applied.
- `sys` history and update preparation are VM-verified on a Btrfs install.
### Changed
- `phoebus-session` now starts `dwl` first, waits for the Wayland socket before
launching waybar/mako/swaybg, establishes `XDG_RUNTIME_DIR` and a session bus,
starts the polkit authentication agent, and reaps helpers on logout.
- Portage policy: the unused `installkernel uki` flag is no longer forced, the
duplicate/empty PipeWire/WirePlumber lines are gone, and the signed binhost is
derived from the selected profile when unset.
- Update preparation records a successful distfile fetch as ready even when
`--buildpkgonly` is skipped because dependencies must be merged first, and the
state note now includes the redacted Portage reason.
### Fixed
- A high-risk `sys` action now creates its protective snapshot inside
`actions::execute` and **fails closed** if the `.snapshots` subvolume exists
but the snapshot cannot be created; corrupt snapshot history is surfaced
instead of being hidden as empty.
## 2026-09-20 — Retire the Bash installer (migration Phases 0–4)
### Added
- `phoebus-executor::opencode`: pinned-manifest parsing, architecture
detection, fetch through `Exec`, SHA-256 verification, fail-closed
placeholder checks, extraction and config writer (7 unit tests).
- `--bootstrap-opencode` on the CLI; `PHOEBUS_OPENCODE_MANIFEST` overrides the
embedded manifest for fixture verification.
- `cli_coverage` and golden plan tests (`plan_golden.rs`, `tests/golden/`).
- `docs/BASH-MIGRATION.md`: the evidence-gated retirement plan and ledger.
### Changed
- The disposable VM harness installs with the static Rust binary; full
encrypted install + detached boot re-verified (systemd PID 1, `running`,
0 failed units, LUKS, login).
- CI, the pre-commit hook, the Makefile and the commit/publish scripts gate on
Rust only (`cargo fmt`, `clippy`, `test`).
- `installer/doc/VM-BOOT-VERIFICATION.md` and `installer/doc/FINDINGS.md`
moved to `docs/`.
### Removed
- The Bash installer tree (entry point, libraries, TUI, configuration, shell
test suite and README), retired in favour of `installer-rs/`. The Bash
reference remains tagged `v0.1.0-bash-reference`. The disposable VM harness
under `installer/tests/vm/` is retained.
## 2026-09-20 — Rust installer parity, desktop, and foundations
### Added
- Rust workspace (`installer-rs/`): `phoebus-core`, `phoebus-executor`,
`phoebus-ai`, `phoebus-tui`, `phoebus-installer` (~9.4k LOC, 45 files).
- Typed `InstallConfig` supporting TOML and the legacy flat format.
- `TargetRoot` (host/target path safety), `SecretString`/`Redactor`,
`DestructiveAuthorization`, central `Exec` command layer with dry-run.
- Storage backend: GPT, ESP, LUKS2, Btrfs layout, fstab/crypttab, swapfile.
- Stage3 fetch with pinned SHA-256 (or signed DIGESTS), Portage configuration,
signed binary use, source builds, kernel, dracut, systemd-boot BLS.
- Desktop/Flatpak: selects `default/linux/amd64/23.0/desktop/systemd`, writes
`/usr/local/bin/phoebus-session`; flathub remote configured.
- Package policy instrumentation: measured compile times parsed from
`emerge.log` (326 entries recorded in the desktop run), persisted to
`/var/lib/phoebus/compile-times.tsv`.
- Snapshots: read-only Btrfs snapshots + TOML transaction history.
- Background update preparation (`--fetchonly` + `--buildpkgonly`).
- Typed `SystemAction` schema, privileged broker, and the `sys` command.
- AI privacy boundary (`PrivacyPolicy`, `ContextBundle`, forbidden paths).
- Release tooling: `phoebus-release` manifest/verify/sha256/assemble.
- ratatui TUI with plan review and ERASE confirmation.
- Recovery BLS entry booting `rescue.target`.
### Fixed
- Subvolumes mounted before creation.
- fstab/crypttab overwritten by stage3 extraction (moved to `fstab_generate`).
- Missing `/var/tmp` breaking `kernel-install`.
- `installkernel` requiring `uki_generator` even for BLS.
- dracut `crypt` module and `systemd-cryptsetup` missing.
- LUKS cmdline using `rd.luks.uuid` instead of `rd.luks.name`.
- dracut UKI missing the kernel command line (BLS adopted).
- `@swap` not mounted, breaking swap activation.
- Portage GPG verify user unable to read the getuto keyring.
- Transient rsync mirror quarantine (sync retries).
- Pillow/HarfBuzz documentation circular dependency.
- Legacy config silently parsed as TOML with defaults.
### Verified
- Full encrypted UEFI install and boot with the ISO detached: `systemd` PID 1,
`is-system-running = running`, 0 failed units, 10.73 s boot.
- Desktop stack headless: dwl, waybar, mako, swaybg, `grim` screenshot,
`wl-copy`/`wl-paste`, `wpctl`, `flatpak 1.18.1` + flathub.
- No secret leakage in the installer log.
## 2026-09-19 — Bash installer prototype and first VM boot
### Added
- Bash + `dialog` installer (`installer/`) with deterministic backend, TUI,
plan/review, dry-run, logging, and destructive confirmation.
- Read-only hardware/disk discovery with live-medium protection.
- GPT/LUKS2/Btrfs backend, systemd stage3, Portage, kernel, systemd-boot,
users/services/desktop modules.
- Unit/regression suite and a disposable VM harness.
### Verified
- First complete encrypted UEFI VM install and boot with the Bash installer.
### Fixed
- The subvolume-ordering, fstab-timing, `/var/tmp`, `rd.luks.name`,
`uki_generator`, cryptsetup, `@swap`, and `local root="$1" dir=...` bugs
(these are the class of bug the Rust port is designed to prevent).