phoebus_os/docs/CHANGELOG.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

26 KiB
Raw Permalink Blame History

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

  • Fail-closed CI with a full gate set. .forgejo/workflows/ci.yml now runs one command, make ci (fmt-check, clippy, workspace tests, VM-harness safety tests, release build, static installer build). It provisions the pinned toolchain or fails with a clear message; a missing Cargo/rustfmt/clippy is never reported as a pass. The toolchain is pinned in installer-rs/rust-toolchain.toml and dependencies are checked with --locked. See ADR 0012.

  • Executable, evidence-bound release gates. phoebus-release gates now records passed/failed/blocked/skipped/not_run (only passed is a pass), actually runs host gates, and imports evidence from the existing VM harness results.json (--harness-results) instead of a competing harness. --candidate binds the report to an artifact digest, and the harness records the digest it verified from PHOEBUS_VM_ARTIFACT[_SHA256], so stale evidence is refused. Gates without automation (no-model-recovery, updates-and-rollback, desktop-session) are always blocked.

  • Publication authorization. phoebus-release publish refuses unless the report is bound to the exact candidate digest, every gate passed, the candidate matches its manifest, and a detached signature verifies. Check failures happen before the destination is touched, and atomic_publish restores the previous release if the final rename fails.

  • 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

  • Release evidence cannot be replayed across builds. A gate report and imported harness evidence are bound to a candidate name and SHA-256; a report for a different digest (or unbound evidence) fails rather than authorizing a publication.
  • 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).