# 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 ` (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 ` / `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 `): 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 `, `sys remove `, `sys search ` (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).