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).
21 KiB
21 KiB
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
- OpenCode connection workflow and capability probe. New ADR 0011 and
docs/OPENCODE.mdseparate the four components (client, server, model service, Phoebus broker) and document host-local and tunnelled remote use.phoebus-executor::opencode_serverprobes/global/healthand/config/providersand reports a typed state (disconnected,authentication_required,incompatible,reachable_no_model,ready) instead of assuming a TCP connect or HTTP 200 means compatibility. Exposed asphoebus-installer --opencode-probe <url>(read-only, nonzero unless a model is available). Never returns provider credentials. Verified against the installedopencode 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_preparere-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 tohttp,https, redirects stay disabled (so anAuthorizationheader cannot follow a redirect to another origin), and the response is size-bounded (max-filesize). TargetRootrefuses symlink escapes.write/ensure_dirreject 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_requiredfor a passwordless LAN bind rather thanready.
Fixed
- Disk sizes are no longer reported as
0 B.probe_disksinvokedlsblkwithout-b, so human-readable sizes (30G) failed the byte parse and every disk displayed0 B; the size-based disk-identity check was also blind. The-bflag 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.pyvalidates every writable drive (qcow2, insidePHOEBUS_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 (noos.system), and returns nonzero on any failed assertion, timeout, EOF or missing result. Statuses arePASS/FAIL/BLOCKED/SKIPPED/NOT RUN.make testnow runs the harness unit tests;installer/tests/vm/report.pybuilds 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,ERASEauthorization, progress and completion. Duplicate installer sessions are prevented. The TUI/CLI remains the fallback. See ADR 0010 anddocs/VM-BOOT-VERIFICATION.md. - Typed JSON GUI bridge.
phoebus-installer --gui-bridgeexposes a narrow, fail-closed protocol over stdin/stdout that reuses the sameInstallConfig, validation, plan,DestructiveAuthorizationand 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_observedand anInstallObservertrait were added;Installer::installis unchanged. - Phoebus brand system.
phoebus-core::brandprovides 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.confnow pins the newest real kernel entry, and the snapshot recovery entry carries asort-keythat 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 bootsystemd.unit=rescue.targetafter 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_disksalso inspects/run/live/mediumand/run/live/rootfs, so the ISO is labelled as the installation medium (and remains protected). - The installer shortcut is live-only.
phoebus-installand 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.profileselectsmango; Flatpak and PipeWire are on by default. Explicitnone,minimal,dwlandfullcontinue 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.shnow 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 ascreendumpcaptured 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-assetand 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/mangowm0.17.2 (wlroots 0.20) plusgui-apps/dankmaterialshell1.5.3 / Quickshell 0.3.1 / scenefx 0.5, installed through the GURU community overlay with scoped~amd64keywords (never global). The installer writes GURU'srepos.conf, bootstrapsdev-vcs/git, and syncs the overlay. Aphoebus-session-mangoentry point, a packaged Mango config seeded once into the user's config, DMS keybindings, amango-session.targetbinding for DMS, andphoebus-mango.desktop/phoebus-dwl.desktopsession 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 BLSrootflags=subvol=, selects a boot entry whose kernel modules match the restored/lib/modules, and writes "previous" and snapshot-based "recovery" entries. A persistedrollback-state.tomlmakes 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 statusand the high-riskundotyped 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 askfalls 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 whensystemd-runis unavailable. - Resolved package effects and approval binding (
phoebus-core::effects):emerge --pretendis 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 actionsflatpak_install/flatpak_remove/flatpak_listandnix_prepare. - Transaction log (
phoebus-core::transaction): assistant andsysactions record their actions, result and recovery point;sys historyshows 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-goodlatest.iso.prev, and signing/verification command helpers. - New VM harness for the Debian-Live appliance:
installer/tests/vm/appliance-driver.py,appliance-guest.shandappliance-test.conf.example.
Changed
- Nix build isolation is enforced:
sandbox = true,sandbox-fallback = false, with store bounds (min-free/max-free) andauto-optimise-store. Lifecycle operations (remove/purge, gc) and a boundednix_prepareaction were added; the Portage-owned ebuild approach is documented in ADR 0008. See ADR 0006. - Desktops install
swayidle/swaylocksession helpers and a Waybar configuration;phoebus-sessionstarts the idle daemon.
Added
- Nix bootstrap (on by default, VM-verified).
phoebus-executor::nixfetches the pinned, SHA-256-verified official Nix release and bootstraps it into the target with discrete commands (store copy,nix-store --load-db,nixbldusers, state dirs, profile and daemon units). A desktop VM confirmednix-daemon.serviceactive andnix shell nixpkgs#helloprintingHello, world!. A binary ebuild was ruled out: the upstream installer has noDESTDIRand runsnix-store --load-dbagainst the real root. finalizenow flushes the target (sync) before unmounting, so late writes such as/usr/local/bin/phoebus-sessionand 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, orPHOEBUS_NO_AI=1) is used. A newlocalprovider (Ollama/llama.cpp/ LM Studio) and--ai-endpointsupport a model the user downloaded; no model is shipped. - Desktop installs now include
sys-apps/xdg-desktop-portal,xdg-desktop-portal-gtkandxdg-desktop-portal-wlr, so Flatpak and Wayland apps get file choosers and screencast support.
Added
sysoffline package commands:sys install <name>,sys remove <name>,sys search <query>(plus theremove_package/search_packagestyped actions). They are deterministic Portage operations with no model involved —emergeresolves 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. Seedocs/PLAN-DEBIAN-LIVE.mdand 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-levelAGENTS.md. .gitignorecovering 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. syshistory and update preparation are VM-verified on a Btrfs install.
Changed
phoebus-sessionnow startsdwlfirst, waits for the Wayland socket before launching waybar/mako/swaybg, establishesXDG_RUNTIME_DIRand a session bus, starts the polkit authentication agent, and reaps helpers on logout.- Portage policy: the unused
installkernel ukiflag 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
--buildpkgonlyis skipped because dependencies must be merged first, and the state note now includes the redacted Portage reason.
Fixed
- A high-risk
sysaction now creates its protective snapshot insideactions::executeand fails closed if the.snapshotssubvolume 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 throughExec, SHA-256 verification, fail-closed placeholder checks, extraction and config writer (7 unit tests).--bootstrap-opencodeon the CLI;PHOEBUS_OPENCODE_MANIFESToverrides the embedded manifest for fixture verification.cli_coverageand 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.mdandinstaller/doc/FINDINGS.mdmoved todocs/.
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 taggedv0.1.0-bash-reference. The disposable VM harness underinstaller/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
InstallConfigsupporting TOML and the legacy flat format. TargetRoot(host/target path safety),SecretString/Redactor,DestructiveAuthorization, centralExeccommand 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
SystemActionschema, privileged broker, and thesyscommand. - AI privacy boundary (
PrivacyPolicy,ContextBundle, forbidden paths). - Release tooling:
phoebus-releasemanifest/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/tmpbreakingkernel-install. installkernelrequiringuki_generatoreven for BLS.- dracut
cryptmodule andsystemd-cryptsetupmissing. - LUKS cmdline using
rd.luks.uuidinstead ofrd.luks.name. - dracut UKI missing the kernel command line (BLS adopted).
@swapnot 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:
systemdPID 1,is-system-running = running, 0 failed units, 10.73 s boot. - Desktop stack headless: dwl, waybar, mako, swaybg,
grimscreenshot,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 +
dialoginstaller (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, andlocal root="$1" dir=...bugs (these are the class of bug the Rust port is designed to prevent).