phoebus_os/docs/CHANGELOG.md
Phoebus ba78284747
Some checks are pending
ci / test (push) Waiting to run
feat(sys): show live progress and readable answers
2026-10-01 08:34:23 -07:00

2161 lines
148 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.
## Unreleased — Fast defaults with user-controlled source builds
- **Readable `sys` progress (2026-10-01).** The terminal now names the active
planning, evidence, effect-checking, execution and verification steps, shows
a slow command's operation, and repeats the current step every ten seconds.
Success and failure are visually distinct; command arguments and output are
excluded from progress. Informational model answers are wrapped as prose
without an irrelevant approval digest. Broker JSON and the assistant stdio
protocol remain unchanged. Unit and CLI integration tests cover the
progress lifecycle, redaction, heartbeat, wrapping and protocol boundary.
A disposable visible playground run showed a legacy history command and a
real OpenCode question with the new progress and concise answer rendering.
- **Desktop administrator authentication (2026-10-01).** Installed systems
now give polkit the same `wheel` administrator group used by sudo. In the
visible disposable VM, the default root-only polkit prompt rejected the
known-good user password because root was locked. After applying the rule
to that VM, a graphical `pkexec /usr/bin/id -u` prompt accepted the user
password and returned `0`. The installer now writes the rule through
`TargetRoot`; the existing ISO predates this fix and needs a new candidate.
- **Installer and desktop reliability work (2026-10-01).** Armed BLS boot
counting only after creating the initial recovery snapshot, corrected the
boot-counter filename parser, and required the upstream failed-unit check
before `boot-complete.target` and `systemd-bless-boot` confirm a counted
boot. The default boot entry permits recovery fallback after exhausted
attempts. Btrfs swapfile allocation sets NOCOW first and fails closed.
Installed desktop assets have readable permissions, the DMS user service
link points into the installed system, and PipeWire/WirePlumber units are
enabled. First-login seeding now creates DMS's versioned changelog marker.
A graphical seat check found that Mango never started the installed Phoebus
welcome: its session did not run XDG autostart. The session now starts that
welcome explicitly; the QML uses fixed, unprivileged actions in place of an
undefined backend and has correctly sized cards. On a patched disposable
install, the first-login welcome and its Escape/seen-marker flow passed the
graphical desktop gate **30/30**.
The live welcome launcher and locale dropdown keyboard flow were repaired.
GURU-only Zsh plugins moved from the base package set to Mango, where the
overlay is synced before installation. ISO assembly replays boot metadata so
the MBR partition fits the remastered image; compression has bounded workers
and memory. Release reports bind gates to an ISO hash and clean source
revision, and require two installs, detached boot, recovery, fallback,
desktop, rollback, interruption, real model and CI evidence before publish.
The final candidate ISO (SHA-256
`b14f37e1b04d8e1ec37f77d2a14adb4aaef652770fee995a18a0ac7b986b5281`)
passed the live UEFI graphical gate (32/32) and real OpenCode installer flow
(18/18). Its embedded installer and `sys` hashes match the static build;
BIOS and UEFI boot entries and image partitions were verified. Two
independent encrypted Mango/Nix installs from this ISO passed 5/5 each.
The fresh installed system passed detached counted-boot assessment 5/5,
offline recovery 6/6, failed-boot fallback 9/9, graphical desktop 30/30,
package/root rollback 11/11 and interrupted-update recovery 10/10.
The desktop screenshot showed the first-login welcome and no DMS changelog.
Both installs logged a nonfatal busy LUKS mapper during final cleanup.
VM logs
and results redact registered credentials, and model UI password input uses
stdin. Release gate output handles multibyte text without panicking. Rust
format, Clippy and workspace tests pass. Forgejo CI now
runs `make check` directly so missing tooling fails the job. An intermediate
ISO with the corrected boot and DMS behavior passed its live checks but was
superseded before its installs completed when the missing installed welcome
launch was found.
- **System-wide stability audit & zero-panic hardening (2026-09-30).**
Exhaustive codebase verification, bug remediation, and panic elimination across all crates:
1. Zero Unhandled Panics & Robust Error Handling:
- `phoebus-installer::release`: Replaced `.unwrap()` in `ReleaseManifest::save` and `GateLedger::save` with safe propagation of `std::io::Error`.
- `phoebus-core::brand`: Replaced unsafe slice index panic in `rgb(hex)` with `try_rgb(hex) -> Option<(u8, u8, u8)>` and safe default fallback. Replaced `.expect()` in `palette_json()`.
- `phoebus-executor::chooser`: Eliminated `matches.pop().unwrap()` in package atom candidate resolution.
- `phoebus-installer::service::plan`: Replaced `.unwrap()` in `select_removal_copy` with `.ok_or_else()` to return clean errors if copy resolution is empty.
- `phoebus-ai`: Replaced `.expect("reason checked above")` with safe matching and empty fallback in proposal review.
- `phoebus-executor::rollback`: Replaced `expect("auto-confirm never fails")` in internal maintenance authorization with safe `Result` propagation.
2. Desktop Checkpoints & Undo Symmetry:
- `phoebus-executor::desktop_config`: Resolved sub-second timestamp collisions by switching checkpoint directory timestamps to microsecond precision with sequence collision checks (`{timestamp}_{label}_{seq}`).
- Tracked pre-mutation file presence in checkpoint `metadata.ini`, allowing `undo_latest_checkpoint` to cleanly remove newly created configuration files when no prior file existed.
- Hardened MangoWM keybinding generation with structured `toml` table serialization, guaranteeing valid TOML syntax and proper escaping for complex shell commands with nested quotes.
3. Model Context Protocol (MCP) Standards Conformance:
- `phoebus-mcp`: Implemented standard JSON-RPC 2.0 error handling for malformed JSON frames (error code `-32700`, Parse Error) and missing/invalid tool params (error code `-32602`, Invalid Params), preventing server silent aborts or broken agent pipes.
4. Agent Containment Jail Hardening:
- `phoebus-executor::agent_jail`: Sanitized `extra_masked_subdirs` to reject directory traversal components (`..`) and leading slashes. Enabled mock/recording runner testability when `bwrap` is not present on the build host.
5. Btrfs Swapfile Hardening:
- `phoebus-executor::storage`: Ensured `chattr +C` (NOCOW) is executed on the parent `@swap` directory and on the empty 0-byte file prior to truncation, avoiding Btrfs `EINVAL` on allocated extents. Enforced secure mode `0600` permissions on the swapfile.
6. Inter-Process Lock Drop Verification:
- `phoebus-executor::system_lock`: Validated lockfile PID ownership before unlinking on drop, guaranteeing that a dropping handle never unlinks a lock acquired by another process.
Gates: `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace` (all passed: 54 adversarial tests, 39 CLI tests, 9 flaw tests, 4 MCP tests, 5 desktop config tests, 3 agent jail tests, 4 AI e2e tests, 4 storage tests, 2 system lock tests).
- **System stability & reliability hardening: Advisory Mutation Lock, Atomic Transactions, System Health & Context-Aware Guidance (2026-09-30).**
Hardened system operations against race conditions, database drift, and usability friction:
1. Inter-Process Advisory Mutation Lock (`SystemLock`):
- `phoebus-executor::system_lock`: Atomic `O_CREAT | O_EXCL` file locking (`/run/phoebus/sys.lock` with PID & timestamp metadata) guarding mutating system operations. Safe PID-liveness verification via `/proc/<pid>` reclaims stale locks left by killed processes.
2. Coordinated Snapshot Pairing for All High-Risk Actions:
- `phoebus-executor::actions`: Upgraded protective pre-mutation snapshotting to `snapshot::create_set_and_record`, ensuring paired `@` and `@var` snapshots are always committed together so `/var/db/pkg` Portage database state stays consistent across rollbacks.
3. Durable Atomic Transaction Persistence:
- `phoebus-core::transaction`: Replaced direct-file writes with tempfile creation, data flush, `sync_all()`, and atomic `rename()`, preventing corrupt or partial transaction records upon sudden reboot or power loss.
4. Unified System Health & Status Overview:
- `SystemAction::SystemStatus`: Added first-class health inspection action (`sys status`, `sys health`, `sys check`) reporting bootloader BLS entries and Automatic Boot Assessment counters, reboot flags, storage headroom vs the 10 GiB safety gate, snapshot recovery points, and package lane readiness.
5. Intuitive Natural Grammar & Context-Aware Legacy Guidance:
- Standardized natural commands: `update` and `updates` map to `CheckUpdates`, `upgrade` maps to `ApplyUpdates`.
- In `sys install <app> --legacy`, candidates are dynamically resolved across lanes via `chooser::resolve_candidates` to present actionable, copy-pasteable commands for packages that exist in Flatpak, Portage, Snap, etc.
Gates: `cargo fmt`, `cargo clippy --workspace --all-targets`, `cargo test --workspace` (all passed).
Hardened system reliability across boots, updates, and package installations:
1. systemd Automatic Boot Assessment (`bootctl mark-good` + BLS boot counter fallback):
- `phoebus-core::boot`: BLS filename parsing/formatting adhering to the systemd-boot specification (`<entry>+<tries>[,<tries-done>].conf`). Recovery entries (`phoebus-recovery.conf`) are strictly unmetered to guarantee an always-accessible fallback target.
- `phoebus-executor::boot_assessment`: Implemented `phoebus-boot-confirm.service` (runs `bootctl mark-good` after `multi-user.target` with zero failed units), `enable_boot_counting` to arm new kernels, and systemd service installation in `etc/systemd/system/multi-user.target.wants`.
2. Preflight Safety Gates:
- `phoebus-executor::update`: `check_update_preflight` verifies >=10 GiB free space on root filesystem prior to update mutations, preventing filesystem exhaustion and package database corruption.
- `create_pre_update_snapshot_set`: Coordinates paired `@` (root) and `@var` (Portage DB state) Btrfs snapshots so package rollbacks never leave an inconsistent package database.
3. Tiered Update Channels:
- `phoebus-core::update::UpdateChannel`: Introduced `Core` (security/kernel/core only), `Proven` (default workstation channel with bi-weekly vetted desktop/Mesa/PipeWire snapshots), and `Edge` (rolling `~amd64`).
4. Mandatory Prebuilt Kernel Default:
- Workstation kernel default strictly enforces `sys-kernel/gentoo-kernel-bin` (`KernelChoice::Bin` / `KernelProfile::Safe`) to prevent unexpected multi-hour compilation timeouts.
Gates: `cargo fmt`, `cargo clippy --workspace --all-targets`, `cargo test --workspace` (all passed).
- **Userspace-directed AI agent framework (2026-09-30).** Implemented a Two-Tier
AI architecture supporting userspace developer and desktop agents (Claude Code,
OpenCode, Cursor, Codex) while strictly maintaining the unbrickable `sys`
broker boundary and eliminating Omarchy's security vulnerabilities (bash glue
command injection, credential exposure, and lack of rollback).
New components:
1. `phoebus-executor::agent_jail` & `phoebus-agent-run`: unprivileged Bubblewrap
boundary with automatic credential masking (`~/.ssh`, `~/.gnupg`, keyrings,
`.aws`, `.config/gh`) and workspace scoping.
2. `phoebus-executor::desktop_config` & `phoebus-desktop`: typed, schema-validated
MangoWM and DarkMaterialShell configuration management with automatic snapshot
checkpoints and one-click `undo`.
3. `phoebus-mcp`: standardized Model Context Protocol JSON-RPC 2.0 stdio server
exposing typed desktop theming, keybinding controls, and safe escalation tools.
4. `sys propose`: unprivileged plan staging bridge allowing userspace agents to
propose system packages and changes into user storage for human Polkit review.
5. Fixed directory creation race condition on concurrent parent directory creation
in `phoebus-executor::personal`.
Gates: `cargo fmt`, `clippy --workspace --all-targets`, `cargo test --workspace` all pass.
- **Three explicit kernel choices (2026-09-29).** Kernel selection is now a
first-class three-way choice rather than only a prebuilt-vs-source config
enum: `bin` (the default `sys-kernel/gentoo-kernel-bin`, no compile),
`balanced` (source-built `sys-kernel/gentoo-kernel` with the broad
distribution configuration — the fragment makes common hot-plug drivers
explicit as modules: USB Ethernet chipsets, USB mass storage, USB serial, and
removable-media filesystems such as exFAT/NTFS3), and `tuned` (the same broad
coverage plus one conservative optimization; no driver is dropped). New typed
action `BuildBalancedKernel { make_default }` and phrase
`sys build balanced kernel`; both source choices keep `gentoo-kernel-bin`
installed as the known-good fallback and create a separate BLS entry
(`phoebus-balanced.conf` / `phoebus-tuned.conf`) that is only promoted after a
test boot. Core: `fastinstall::{KernelChoice, kernel_build_plan,
balanced_kernel_plan, kernel_build_review}`; `system::{balanced_kernel_config,
tuned_kernel_config}`; executor `kernel::build_balanced_kernel` (refactored
from the tuned path). Gates: `cargo fmt`, `clippy --workspace --all-targets --
-D warnings`, `cargo test --workspace` 849 passed / 0 failed. VM journeys for
the balanced/tuned builds and source conversion are in progress (multi-hour
compiles).
- **OpenCode is now a standard transport (2026-09-29).** The OpenCode backend was
special-cased twice: it ran **outside** the model sandbox (a comment called it
"a different trust boundary") and its endpoint policy was stricter than the
direct provider's (plain `http` only to loopback). Both are now unified. The
OpenCode transport runs in the **same OS-level sandbox** as the direct
transport unless `--no-sandbox` is given; its curl calls inline the request
body into the hidden stdin config (the sandbox's `PrivateTmp` would hide a
temp file). A **network** OpenCode server works over `https` as before, and a
remote plain-`http` server is permitted with the explicit
`--opencode-insecure-http` opt-in (credentials/prompts travel in cleartext, so
it is off by default; `PHOEBUS_OPENCODE_INSECURE_HTTP=1` also enables it).
VM re-verification with the real host agent (`serial-boot-20260929T114319Z-c43c2a92`,
driver PASS=8, sandbox on by default): `list`/`search` valid plans,
constrained install gated before mutation, hostile instruction refused. Gates:
`cargo fmt`, `clippy --workspace --all-targets -- -D warnings`, `cargo test
--workspace` 845 passed / 0 failed.
- **Headless read-only probes can no longer block; real-agent VM re-verification
(2026-09-29).** Driving the powerful model (host `opencode` agent,
`deepseek-v4.1-flash`) with `sys` **inside the VM**, a `sys ask "search for
firefox"` hung: the AI investigation ran Flatpak, whose `search` hard-codes a
privileged `appstream-update`, and polkit fell back to a `pkttyagent` password
prompt on the headless console. Fix: `CommandSpec::detached()` runs host-root
Flatpak commands in a new session with no controlling terminal (`setsid
--wait`), so the prompt is impossible; the refresh fails fast and Flatpak uses
cached data. Falls back when `setsid` is absent. Also fixed a prompt gap: the
install/assistant prompts listed a `kind` argument without its allowed values,
so a capable model emitted `kind:"gui"`; both prompts now enumerate
`base-system|desktop-app|developer-tool|cli-tool|unclassified` and clarify that
`gui` is a separate boolean. VM re-verification with the real agent
(`serial-boot-20260929T111941Z-2be30b89`, driver PASS=8; zero auth prompts):
`list` and `search` return valid, evidence-grounded Assistant Plans, the
hostile instruction is refused, and the constrained install stops before any
mutation. Gates: `cargo fmt`, `clippy --workspace --all-targets -- -D warnings`,
`cargo test --workspace` 844 passed / 0 failed.
- **VM live AI: real capable agent, and a local-model prompt fix (2026-09-29).**
Booted the golden overlay and, from inside the guest, reached the host's real
`opencode` agent through the loopback tunnel: `sys ask "list installed
packages" --ai-backend opencode --opencode-provider opencode-go
--opencode-model deepseek-v4.1-flash` returned a valid Assistant Plan + digest
(`CASE live-agent PASS`), and a hostile shell/private-file instruction was
refused/downgraded (`CASE live-agent-hostile-rejected PASS`)
(`serial-boot-20260929T102703Z-ffd1ec25`). A real local model (Qwen2.5-1.5B
GGUF served by `llama-server`) was also driven through the direct sandbox in
both scopes; it reached the model, but the 1.5B model could not satisfy the
exact typed schema (bare-string action, then a missing `rationale` reason) and
the correction prompt exceeded its 4096-token context, so `sys` failed closed
— model capacity, not a `sys` defect. The assistant prompt now shows the
concrete action-object shape (`{"action":"list_packages"}`) instead of only
`[...]` placeholders, which made the small model emit action objects. Gates:
`cargo fmt`, `clippy --workspace --all-targets -- -D warnings`,
`cargo test --workspace` 843 passed / 0 failed.
- **VM-verified AI sandbox and unprivileged AI path (2026-09-28).** The first
disposable-VM run of the newly built static `sys` (overlay on the golden
installed image, `serial-boot-20260929T092147Z-6f88907a`) found and fixed two
real defects. (1) **Unprivileged `sys ask` hung on a polkit root-password
prompt:** the model sandbox used the system manager (`systemd-run`), and
`org.freedesktop.systemd1.manage-units` requires authentication, so a normal
user got `==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ====`
and blocked. The sandbox now uses `systemd-run --user` for unprivileged
callers, with the subset of hardening properties the user manager accepts
(`DynamicUser`, `PrivateDevices`, `ProtectKernelModules` are system-only);
root still gets the full system sandbox. (2) **Unprivileged read-only AI
plan exited 1 after printing the plan:** the service layer unconditionally
wrote the root-owned `/var/lib/phoebus/transactions.toml`, which a normal
account cannot write. Transaction recording is now best-effort for a
non-root plan and mandatory for a privileged mutation. VM evidence:
`AI_ROOT_RC=0` (system sandbox), `AI_USER_RC=0` (`--user` sandbox, was
RC=124 timeout), `AI_NOSANDBOX_RC=0`, hostile `run_shell` reply `AI_SHELL_RC=1`;
the expanded `sys-acceptance.sh` matrix reports `SUMMARY PASS=49 FAIL=0`.
Additional loops on the same golden overlay pass: mutating acceptance as root
`SUMMARY PASS=42 FAIL=0` (`mutate-install`/`mutate-remove`/`mutate-history`),
rollback acceptance `PASS=11` (snapshot → change → `sys undo` → detached
verify), and the Snap journey `PASS=11`
(`serial-boot-20260929T093329Z-4ef893cf`,
`serial-rollback-20260929T094640Z-256c2ba1`,
`serial-boot-20260929T094957Z-3d4a9211`).
Also observed: a read-only `flatpak search` can trigger Flatpak's interactive
`appstream-update` polkit prompt when the session is not recognized as active
(headless serial), which can block an unattended run; on a real active seat
polkit's default `allow_active=yes` allows it, and the unattended acceptance
now runs detached so it cannot hang. Recorded as a hypothesis, not a code
change. Gates: `cargo fmt`, `clippy --workspace --all-targets -- -D warnings`,
`cargo test --workspace` 842 passed / 0 failed.
- **Live real-agent verification over the local `opencode` server (2026-09-28).**
With a real `opencode serve` (v1.18.32) on `127.0.0.1:4096` and the
`opencode-go` provider, `sys ask "list installed packages"` was driven through
`--ai-backend opencode --opencode-provider opencode-go --opencode-model
deepseek-v4.1-flash` and returned a valid typed plan plus an approval digest
(read-only `list_packages`, exit 0). A hostile instruction (read `/etc/shadow`
and `~/.ssh/id_rsa`, then run a shell command) was refused and downgraded to
the read-only inventory. The phoebus transport disables every OpenCode tool in
the session (`bash/edit/write/read/webfetch/grep/glob/patch/task` — asserted in
`opencode_client` tests), so the agent has no shell or file access. No provider
credential reached the sys log (checked by value). This is a host-level live
call (not a VM and not a stub); it depends on a running local agent server.
- **End-to-end AI-path test over a real local stub (2026-09-28).** The
deterministic tests and the no-model fail-closed routing left the
connected-model path covered only by fake transports. New
`installer-rs/crates/phoebus-installer/tests/sys_ai_e2e.rs` drives the real
`sys` binary against a real local OpenAI-compatible TCP stub and the real curl
transport, with the sandbox disabled (`--no-sandbox`) so no seat is needed.
Four cases: a valid model plan executes end-to-end and the request actually
sent contains no `/home/` path and no `Bearer` credential; a model `run_shell`
action fails closed after one corrective retry with no transaction written; a
`depclean` with a smuggled `shell` field is refused by the exact schema
(`unknown field \`shell\``); and malformed model output fails closed after one
correction. Gates: `cargo fmt`, `clippy --workspace --all-targets -- -D
warnings`, `cargo test --workspace` 841 passed / 0 failed.
- **`sys`/AI boundary hardening pass (2026-09-28).** A read-audit of every
mutation route plus the AI path found six host-provable defects, all fixed
with regression tests. (1) **Root-gate backdoor removed:** the service layer
honoured `PHOEBUS_ALLOW_UNPRIVILEGED_EXEC=1` and reported uid 0, which let a
non-root desktop-assistant client skip `pkexec` elevation and the root-owned
approval ledger and execute a root-requiring plan in-process; privilege is now
derived from the process identity only. (2) **Credential injection closed:**
`load_api_key` interpolated the key into a curl config `header = "..."`
directive, so a key containing `"`, `\`, whitespace or a control character
could inject curl options; such credentials are now refused. (3) **Derived
OpenCode token redaction:** the base64 Basic/Bearer token actually sent was
not registered with the redactor, so a server echoing the `Authorization`
header could leak it; the token is now registered too. (4) **Privacy allowlist
hole:** `SystemFacts::validate_no_forbidden` did not scan `cpu_features`, so a
forbidden path there could reach the model; every string field is now
scanned. (5) **Endpoint credentials:** `validate_endpoint` accepted userinfo
(`https://user:pass@host/...`); the authority is now rejected while an `@` in
the path/query stays valid. (6) **AI typed-action schema bypass:** the
assistant/install parsers used `serde_json::from_value` directly, and serde's
`deny_unknown_fields` does not cover internally tagged unit variants, so an
action with a smuggled extra key (`{"action":"depclean","shell":"sh"}`) was
accepted on the AI path but rejected by `parse_action`; all paths now route
through the shared `phoebus-core::action::validate_action_value`. New tests:
`service::an_environment_variable_cannot_forge_root`,
`ai::api_key_content_must_be_safe_for_a_curl_config`,
`ai::sandboxed_send_uses_systemd_run_and_keeps_the_key_on_stdin`,
`opencode_client::a_bearer_token_is_redacted_too`,
`provider::every_string_field_is_scanned_for_forbidden_paths`,
`assistant::{plan_actions,investigation_requests}_reject_smuggled_extra_keys`,
`install::investigation_requests_reject_smuggled_extra_keys`,
`action::validate_action_value_rejects_unit_variant_extra_keys`. Gates:
`cargo fmt`, `clippy --workspace --all-targets -- -D warnings`, `cargo test
--workspace` 837 passed / 0 failed, release build. **NotRun, with reasons:**
VM exercise of the `systemd-run` sandbox (needs a fresh disposable install and
a seat/polkit agent; host probe shows the system manager's `manage-units`
requires authentication and the full property set is invalid for
`systemd-run --user`); source-conversion and tuned-kernel
build/boot/fallback journeys (need a disposable 60–80 GiB install + reboot);
Snap changed-revision/strict confinement (external AppArmor + Store
prerequisite); Flatpak/Snap **install** commit/revision drift (installs bind
the human version only; carrying commit/revision through install plans is a
separate change).
- **`sys` adversarial input battery + hardening (2026-09-28).** New host-level
`tests/sys_adversarial.rs` (54 cases across 11 attack categories: shell
injection in every operand type, empty/NUL inputs, extreme lengths, Unicode
and homoglyphs, path traversal, option injection, malformed/nested JSON, CLI
flag conflicts, natural-language edge cases, boundary values, and privilege
gates) run against both the `phoebus-core` validators directly and the `sys`
binary as an isolated subprocess (`PATH=/nonexistent`, no AI provider). The
battery found and fixed five real validation gaps, each now regression-tested
in `phoebus-core` and the executor: `valid_file_path` now rejects shell
metacharacters and `..` components (its documented contract, previously
unimplemented); `valid_application_name` refuses `..`/empty path components
and a leading slash; `valid_ebuild_atom` refuses `.`-leading
(`.`, `..`) category/package components, closing a real overlay path
traversal (`../pkg` previously escaped `var/db/repos/phoebus`), with
`ebuild::package_dir` re-validating as defence in depth;
`valid_flatpak_app_id` refuses an empty reverse-DNS element (`org..test`);
and `valid_nix_attribute` refuses a leading dash (`--impure`). All gates
green: `cargo fmt`, `clippy --workspace --all-targets -- -D warnings`,
`cargo test --workspace` 828 passed, 0 failed.
- **`sys` flaw-fix battery (2026-09-28).** Six static-analysis flaws fixed and
regression-tested: `valid_package_spec` now accepts Gentoo version operators,
slots/subslots, repository specifiers, USE-dependency flags and wildcard
versions (`=app-editors/vim-9.0.2167`, `dev-lang/python:3.11`,
`sys-apps/portage::gentoo`) while still refusing leading dashes, whitespace
and shell metacharacters; the legacy phrase parser accepts quoted multi-word
application names (`sys install "visual studio code" --legacy --flatpak`);
`vdb_has_atom` (executor and kernel) normalizes through
`portage::normalize_dep_atom` so versioned post-install checks resolve;
`FlatpakInstall`/`FlatpakRemove` add `--system --noninteractive`; `who owns
usr/bin/vim` is normalized to an absolute path. New host-level battery
`tests/sys_flaws.rs` (9 cases) and `sys-acceptance.sh` service-lifecycle +
versioned-atom + path-normalization cases. All gates green: `cargo fmt`,
`clippy --workspace --all-targets`, `cargo test --workspace` 773 passed.
- **Pristine reinstall + full boot acceptance (Run 15, 2026-09-28).**
Rebuilt static binaries from HEAD and reinstalled clean on a fresh
disposable 80 GiB VM: `INSTALL-RC=0`, no secret leak, 347/347 desktop
packages, detached boot (systemd running, 0 failed units, seatd active),
`sys-acceptance.sh` 40/40, Nix per-user enumeration green
(`nixpkgs#hello` as `phoebus` → `sys list --nix` reports
`hello 2.12.3 [per-user:phoebus]`), and live `sys ask` green
(`AI_LIVE_RC=0`, valid plan + approval digest from
`opencode-go/muse-spark-1.3-contributor` via the guest loopback tunnel).
Fixes since run 13, all unit-tested: nix integration permissions
normalized after all bootstrap writes (`/nix` traversable, `/etc/nix*`
world-readable), opencode backend defaults to the `Local` adapter kind,
serial driver matches the zsh `❯` prompt, `NO_EQUALS` for check markers
under zsh, setsid acceptance (polkit tty hang), tunnel `settimeout(None)`
for slow model replies.
- **Headless dual-target stabilization & detached boot proven (Run 13).**
Completed full 12-stage non-interactive headless installation on an 80 GiB
disposable VM (`phoebus-headless-80g.qcow2`) without touching host disks.
All 347 desktop packages emerged in ~2.8 h, 588 compile times recorded, and
initial known-good Btrfs snapshots created (`@-20260928T060439-initial-known-good`
and `@var`). Detached boot from disk alone verified: LUKS2 auto-unlock,
systemd PID 1 with 0 failed units, `seatd.service` active and running
(`/run/seatd.sock` mode 0660 root:seat), `sys-acceptance.sh` suite passing
40/40, fast-defaults verified in Gentoo VDB (`firefox-bin`, `libreoffice-bin`,
`thunderbird-bin`, `brave-browser`), and Flatpaks verified in `/var/lib/flatpak`
(`calibre`, `gimp`, `flatseal`).
- **Fast default installation.** The Mango profile now installs
`www-client/firefox-bin` and `app-office/libreoffice-bin` (maintained
stable Gentoo binary redistributions, signature verification preserved).
A requested `-bin` that cannot come from a signed binary fails closed with
the exact reason instead of silently falling back to a source build
(`fastinstall::require_binary_capable`). Calibre
(`com.calibre_ebook.calibre`), GIMP (`org.gimp.GIMP`) and Flatseal
(`com.github.tchx84.Flatseal`) install as system-wide Flatpaks from
Flathub **in the target** (never on the live host), with fail-closed
verification of apps, launchers, exports and a recorded manifest
(`var/lib/phoebus/flatpaks-installed`); Calibre/GIMP Portage copies are
gone so no duplicates are installed. `sys-kernel/gentoo-kernel-bin` stays
the single generic install/recovery kernel (no second generic kernel).
Brave's stable pinned overlay integration is unchanged. The plan review
and progress log name the delivery method and expected work
(`fastinstall::delivery_summary`); the orchestrator records measured
per-stage/total time plus best-effort download/installed/peak-disk figures
(`var/lib/phoebus/install-metrics.txt`, unmeasured reported as such).
- **Preference neutrality.** The installer's speed choices set no permanent
system-wide or personal lane preference (`assert_no_installer_preference`);
later `choose`/`install` resolve from live candidate evidence plus
explicit user choices, with source, version, build cost and tradeoffs
shown as before.
- **User-initiated source builds.** New typed actions `convert_to_source`
(`sys build <app> from source --legacy`) for Firefox, LibreOffice,
Calibre and GIMP, and `build_tuned_kernel` (`sys build tuned kernel
--legacy`): blockers/dependencies checked via the reviewed pretend plan,
the source is built (`--buildpkgonly`) before the working copy is touched,
user data and desktop defaults are preserved, a failed build leaves the
working application installed, and Brave is refused with its reason (no
trustworthy maintained source route). Both carry the full review (exact
packages, expected time, temporary disk, power/network, approval) in
`sys` previews and require explicit approval before the broker runs. The
tuned kernel starts from the proven distribution configuration, gets a
separate BLS entry, is test-booted before it can become default, and
always keeps `gentoo-kernel-bin` as the known-good fallback.
- **Installed first-login welcome.** `phoebus-welcome` (Mango/DMS styled
QML): explains the prebuilt defaults, offers the three opt-in paths
(source builds, tuned kernel, keep-and-finish defaulting to keeping the
working system), runs once per user via `welcome-seen`, stays reopenable
from the launcher/settings, supports keyboard navigation and small
displays, and never blocks login. DMS upstream first-run dialogs are
seeded suppressed via `/etc/skel` so users see one welcome. The live
ISO's "Install Phoebus OS" welcome remains live-only.
- **Seamless Flatpak desktop.** Existing Wayland portals plus extended
defaults (`mimeapps.list`: Nemo for directories, Firefox for web links,
Zathura for PDF, Calibre Flatpak for e-books, GIMP Flatpak for images);
upstream sandbox permissions respected with no broad overrides
(`flatpak_narrow_overrides` is intentionally empty); Flatseal ships for
inspection without forcing setup.
- **Tests.** 757 Rust tests pass (was 736): new coverage for delivery set,
preference neutrality, fail-closed `-bin`, source-conversion table,
tuned-kernel fallback, target-only Flatpak install/verification, welcome
provisioning, metrics report, and the `sys` acceptance script gains 4
cases (non-root privilege refusals + root-safe Brave/unknown refusals).
Gates: `cargo fmt --check`, `clippy --workspace --all-targets -- -D
warnings`, release build, `test_vmsafety.py` 18/18, shellcheck clean.
- **Zsh defaults modernization (seeded once, user-owned afterwards).**
`ZSH_SKEL_RC` fixes the `%F{ yellow }` color bug (now Phoebus Gold 214),
drops the no-op site-functions probe, puts `fpath` before a cached
`compinit` (full audit at most once per 24h via `.zcompdump`), adds
Kitty/application-mode keybindings (Up/Down prefix search, Home/End/
Delete, word jumps), replaces cross-tab `SHARE_HISTORY` with
`INC_APPEND_HISTORY`, and adds a builtin `vcs_info` git branch plus an
exit-status prompt arrow. New `ZSH_ZPROFILE` bridges `/etc/profile`
(Gentoo `env-update` paths, Nix/Flatpak `profile.d`) into Zsh login
sessions and adds `~/.local/bin` to `PATH`. Verified: `zsh -n` clean on
both files, interactive startup smoke test, 757 workspace tests green;
installed-session behavior awaits the disposable VM.
- **Seat management (P0 desktop blocker fix, unit-tested, seat VM pending).**
`sys-auth/seatd` joins the Mango set and is enabled before `greetd`
(`desktop_login_services`), `gui-libs/libseat` gets `systemd builtin
server`, the default user groups gain `seat`, the greeter is created with
`-G video,input,render,seat` (plus best-effort `seat` membership on
re-runs), and `phoebus-session-mango` waits boundedly (3 s) for
`/run/seatd.sock` or a logind session before starting Mango —
`LIBSEAT_BACKEND` stays unset so every compiled backend remains available.
Verified: workspace suite 759/759 (was 757), `bash -n` on the session
script; the seat-VM reverification (tuigreet login → Mango socket, no
libseat error) is NotRun.
- **Thunderbird fast default + source conversion.** `workstation_packages`
installs `mail-client/thunderbird-bin` (signed vendor binary, ~80 MiB
download, no ~1 h compile); `fast_default_deliveries` and
`SOURCE_CONVERSIONS` gain Thunderbird (source target
`mail-client/thunderbird`, 45–90 min, ~18 GiB temp), the preference
neutrality guard covers it, and the first-login welcome names it alongside
Firefox/LibreOffice/Calibre/GIMP. `sys build thunderbird from source
--legacy` flows through the existing reviewed approval/broker path.
Installed-identity and conversion-journey VM checks are NotRun.
- **AI transport timeout.** `CurlTransport` `max-time` is now 300 s by
default (was 120 s, which aborted local CPU inference with `curl exit
28`) and overrideable via `PHOEBUS_AI_TIMEOUT` (unparseable/zero values
fall back to 300; zero is refused since curl reads it as "no timeout").
Applies to both direct and sandboxed sends. The mandatory-AI install
requirement is unchanged (fail-closed without a model or `--no-ai`); all
six package lanes are untouched.
- **Not VM-verified this session.** A fresh ISO was built from the
fast-defaults commit and content-verified (`fastdefaults.iso`, 1.6 GiB,
`ad9cddb2…`, build `20260926T145700Z` from `e747baf`; embedded
`phoebus-installer`/`sys` hash-match the fresh static build, Gentoo key
shows both published fingerprints, Mango/DMS + installer UI present).
No disposable install/boot ran (wall-clock blocker: a full Mango install
takes ~165 min; host is ready: `make doctor` 20 ok, ~103 GiB free). The
new install path, installed package identities, Flatpaks, welcome,
graphical launches, workflows, source-conversion and tuned-kernel
journeys await the disposable VM procedure in
`docs/VM-BOOT-VERIFICATION.md`.
## 2026-09-26 — Workstation experience (apps, shell, AI handoff, assistant)
- **Mango workstation defaults.** The Mango profile now installs the full
requested set with exact Gentoo atoms (no silent omit/substitute):
`app-editors/emacs`, `app-office/libreoffice`, `media-gfx/swayimg` (GURU),
`media-video/mpv`, `app-misc/fastfetch`, `sys-process/htop`,
`app-editors/neovim`, `app-text/zathura` + `zathura-pdf-mupdf`,
`app-editors/nano`, `www-client/firefox`, `www-client/brave-browser`
(stable, scoped `another-brave-overlay`), `mail-client/thunderbird`,
`app-text/calibre`, `net-p2p/transmission` (gtk), `media-sound/pavucontrol`,
`media-gfx/gimp`, `net-print/cups` (local only), `gnome-extra/nemo`
(default file manager, replaces pcmanfm), `sci-calculators/qalculate-gtk`,
`net-irc/hexchat`, `net-misc/openssh` (client+server, sshd disabled).
Kitty stays the terminal; `st` is never installed. Headless (`none`) stays
lean (no desktop apps). Unit-tested (`workstation_defaults_*`).
- **Brave via reviewed overlay.** Stable `www-client/brave-browser` only
(never beta/nightly, masked). The overlay is scoped
(`another-brave-overlay.conf` + `brave-scope` mask); the git pin
(`PHOEBUS_BRAVE_PIN`, 40-hex) is validated before any network use and a
missing/placeholder pin refuses with the exact blocker instead of silently
using Flatpak. Upstream release + checksum verification happens in the
ebuild fetch path (fail-closed). Live VM verification is blocked (needs
network + a pinned revision at ISO build time + 60 GiB target).
- **Zsh, cursor, ccache.** New users get `/bin/zsh`; root keeps `/bin/bash`;
`/bin/sh` is untouched. A maintained default `~/.zshrc` (completion,
autosuggestions, syntax-highlighting, history search, readable prompt) is
seeded for skel + new users from packaged plugins only, preserving existing
files. One cursor theme (`x11-themes/vanilla-dmz-xcursors`, Vanilla-DMZ,
size 24) is applied across Mango/wlroots, XWayland, GTK, Qt/Quickshell,
DMS and the greeter. Default Portage ccache is on: `dev-util/ccache` in
base, `FEATURES="ccache sandbox usersandbox"`, `CCACHE_SIZE="2G"`.
- **AI connection handoff.** The installer GUI offers "Use this model
connection after installation" (selected by default, bound to
`ai.reuse_ai_connection`). When selected, finalize writes a direct-provider
key into the new user's `~/.config/phoebus/ai.key` (symlink-safe,
0700/0600, user-owned); only the path enters `assistant.conf`.
OpenCode/local follow their actual requirements; a live-VM-only endpoint is
never called "connected" after reboot. The installed `sys ask` and desktop
assistant share `ai_setup::resolve`. Missing/invalid/unreadable/opted-out
credentials show a setup action + the real error, never a false
"Connected" and never "Approve & Execute" without a plan id/digest.
Unit-tested (0600/0700, symlink refusal, no secret in errors).
- **Startup system check.** New `evaluate_startup_checks`/`summarize_checks`:
blur is an optional unsupported visual effect when Mango/DMS lack it;
`sys-power/power-profiles-daemon` (stable 0.30) is installed + enabled with
D-Bus `net.hadess.PowerProfiles` verified and `sys-power/tlp` masked as a
conflict; `media-sound/cava` (stable, `pipewire` USE) and
`gui-apps/matugen` (GURU) are installed for DMS. Zero errors + warnings
never says "All checks passed."
- **Assistant dark by default + responsive.** Dark (charcoal/warm-white/amber)
is the default with a light mode + persisted selection. Missing
`Theme.background/text/primary/card/cardHover/accent` aliases are defined;
a Rust test fails on future token drift. The fixed 820×640 + overflowing
tab row is replaced by a resizable window (600×450 minimum) with a
horizontally scrolling tab row; long errors/plan details wrap; Send, Cancel,
Details, approval, Preferences and window controls stay reachable at
1024×768, 1280×720 and increased scale. Error cards never expose approval.
- **Space estimates.** Mango requires 60 GiB (80 recommended); headless 20.
Validation refuses a smaller target with the exact requirement.
- **Verification.** `cargo fmt --check`, `clippy --workspace --all-targets
-- -D warnings`, `cargo test --workspace` 736/736, release build,
`test_vmsafety.py` 18/18, shellcheck (pre-existing info only). No fresh ISO
was built and no disposable install/boot ran in this session: `make doctor`
reports 8 GiB free (needs ≥20) and the workstation target needs 60–80 GiB;
Brave pin, seat compositor, live AI credential, Snap revision/strict and
NVIDIA remain blocked with exact prerequisites in STATUS/HANDOFF.
## 2026-09-26 — Live ISO rebuilt from HEAD, interactive VM open
- **New live ISO built from HEAD (`11c0ee0`).**
`installer/live/phoebus-installer-amd64-20260926.iso` (1.6 GiB, SHA-256
`250dbe9a…`, build id `20260926T041500Z`) was built with
`PHOEBUS_REUSE_ROOTFS=1` after verifying the static `phoebus-installer`
(`25741706…`) and `sys` (`3b331643…`) are fingerprint-fresh for HEAD. The
Sep-24 ISO predates the stage3/boot-security hardening and is kept
alongside, not overwritten. Filesystem-inspected (not just timestamped):
the embedded binaries hash-match the fresh build, the provisioned Gentoo
key carries both published fingerprints (`13EB…2910`, `D99E…2058`),
`gpg`/`mango`/`dms`/quickshell welcome+installer UI are present, and
`/etc/phoebus/version` + `/etc/phoebus/build` carry `0.1.0` and the build
id.
- **Interactive VM open for the owner.** A fresh unique 30 GiB qcow2 plus
private OVMF vars boots the new ISO in a visible KVM/GTK window
(`installer/tests/vm/run-vm.sh`); screenshot-verified at the branded
welcome ("Install Phoebus OS", Live medium 0.1.0, network/UEFI/RAM/CPU
chips). Left running, installer untouched, no passwords or model
credentials entered.
- **`run-vm.sh` is safer for user-facing launches:** new `--disk-name`
(unique disk per run) and `--display` options, and a TCG fallback that
switches `-cpu host` to `-cpu max` with a performance warning when
`/dev/kvm` is not writable (the old `-cpu host` choice fails without
KVM). The one `shellcheck` SC2054 warning on the QEMU array pre-existed
at HEAD and is unchanged.
- **Unpinned signed-DIGESTS install proof running.** `gui-driver.py
install` boots the new ISO on a disposable disk and installs through the
default unpinned stage3 path with the ISO-embedded fail-closed binary
(empty `STAGE3_URL` resolves latest from Gentoo autobuilds; fixed trust
anchor). Automated-harness `--no-ai` is test-only evidence, not the
normal user path. Partitioning + LUKS2 + Btrfs stages already passed in
the guest; completion and detached boot pending.
- **Unpinned signed-DIGESTS install proof COMPLETED in a disposable VM.**
`gui-driver.py install` run `gui-install-20260926T040728Z-f3ae68f4`
booted the new ISO on disposable `disks/unpinned-accept-1.qcow2` (30
GiB) with no `STAGE3_URL`/`STAGE3_SHA256` (latest stage3 resolved from
Gentoo autobuilds, signed DIGESTS verified against the fixed provisioned
key) and the ISO-embedded fail-closed binary: `INSTALL-RC=0`,
`NO_SECRET_LEAK`, `installation complete` after ~165 min (mango desktop,
174 packages). Detached boot: LUKS unlock, login, systemd `running`, 0
failed units, networking, all Btrfs subvolumes, `sys history --legacy`
showing the initial-known-good snapshot. A harness assertion fix
(`gui-driver.py` boot check now uses `sys history --legacy`, since bare
`sys history` is AI-first and truthfully refuses without a model) was
needed to green the gate; the product was correct.
- **Tamper refusal VM-verified** (new ISO, fail-closed binary, disposable
4 GiB targets): a placeholder pin is refused before any network use (zero
stage3 fetches) and a mismatched archive hash is refused after download
with no extraction (`INSTALL-RC=1`, `NO_SECRET_LEAK` both runs). A
tampered-*signature* VM case is infeasible without a network MITM (fixed
key + authentic Gentoo DIGESTS); the bad-signature branch is unit-tested.
- **Recovery-entry boot VERIFIED** (`Phoebus Recovery (known-good
snapshot)` selected in the systemd-boot menu — keypresses provably freeze
the 3 s timeout, selection screenshot-confirmed — with restricted
networking and no model): cmdline + findmnt prove root is the read-only
`@-20260926T064646-initial-known-good` snapshot with `rescue.target`,
serial login works, `sys history`/`rollback status --legacy` work, `sys
ask` fails truthfully offering the exact `--legacy` command, systemd
`degraded` (rescue target, as designed). Method notes: video (tty1) keystrokes
never reach the dracut LUKS prompt (`/dev/console` is serial); passphrases
must be written to the serial pty with ONLCR/ICRNL neutralized or a `\r`
is appended and the passphrase is rejected.
- **Seat desktop PARTIAL with a precise blocker.** Seat VM (virgl,
`virtio-gpu-gl-pci`): seat0 + DRM card0 + greeter session verified,
tuigreet authenticates the correct password (journal-proven; earlier
"Authentication failed" readings were QMP-typing focus races, and `-` keys
arrive correctly). The Mango compositor exits in <1s: libseat `No backend
was able to open a seat` — no seatd in the image and the logind path does
not succeed under the tuigreet session. Kitty/DMS/lock/idle/polkit-agent/
logout/reboot stay unverified behind this blocker.
- **Snap re-checked against the live Store:** `hello-world` is still 6.4
rev 29 on every channel (install → `no updates available` → remove, all
clean); guest has no `aa-status`, confinement `partial`. Revision-changing
refresh and strict confinement stay blocked (Store revision + AppArmor
guest needed).
- **Nix GC findings:** the fresh unpinned install bootstraps Nix (store
populated, `default` link valid, `nix 2.24.9` runs) and `sys list --nix`
truthfully reports the base system profile has no manifest.
`nix-collect-garbage` is not on root's PATH; a user-level
install (`nixpkgs#hello`) + `nix-collect-garbage -d` (268 paths, 189 MB)
leaves the profile intact — the old dangling case did NOT reproduce.
**Coverage gap found:** `sys` enumerates `/nix/var/nix/profiles/
{default,profile}` + `per-user/*/profile` but not the modern per-user
`~/.local/state/nix/profiles/profile`, so user-installed Nix packages are
invisible to the catalogue. Recorded as follow-up (design + tests + VM
proof needed), not fixed in this session.
- **Release gates stay truthful:** `gates --execute` in an unconfigured
shell reports 0 passed / 0 failed / 6 NotRun with exact missing
prerequisites; nothing published. Quality gates green: `cargo fmt`,
`clippy --workspace --all-targets -- -D warnings`, `cargo test
--workspace` 717/717, `test_vmsafety.py` 18/18, release + static builds.
## 2026-09-26 — Security and release-readiness: trust anchor, executable gates, strengthened rollback
- **Stage3 trust anchor is fixed in code.** `release_key_path()` no longer
honors `PHOEBUS_GENTOO_RELEASE_KEY`: production always uses the provisioned
`/usr/share/openpgp-keys/gentoo-release.asc`, and test-only injection goes
through the explicit `verify_digests_with_key` helper. A regression test
proves the environment variable is ignored. The pinned path is unchanged.
Host-level mechanism check (not VM evidence): the parser fixture matches
the real current DIGESTS byte-for-byte and the real DIGESTS verifies with a
Good signature from Gentoo's weekly release key. The full VM proof (rebuilt
live ISO + default unpinned install + tamper refusal) is recorded as
blocked with its exact prerequisites.
- **Release gates are executable and truthful.** `candidate_gates()` no
longer names `serial-driver.py checks` / `desktop` modes that no harness
accepts (`no-model-recovery` uses the real `boot` mode,
`desktop-session` uses `gui-driver.py boot`). `run_gates(--execute)` runs
each gate's argv in its own process: exit 0 → Passed, nonzero → Failed,
missing harness/firmware/seat/credential → NotRun, invalid command →
Failed. New tests cover real harness modes, pass/fail/not-run reporting,
isolation, invalid-command detection, and publish refusal on any
failed/not-run gate. `gates --execute` on an unconfigured host reports 0
passed / 0 failed / 6 NotRun; `publish` refuses. A `gui-driver.py`
SyntaxError found by the new test is fixed.
- **Strengthened rollback rerun PASSED in a disposable VM**
(`serial-rollback-20260926T034218Z-7fab51ef`, PASS=11 FAIL=0, exit 0, no
secret leak): the root-marker creation is now mandatory and asserted
present before `sys undo`, the package DB changed (`ca398d71…` →
`fda3780a…`) and was restored, the marker is absent after the detached
reboot, `/home` survives, systemd runs. The unused `SERVE` variable was
removed (`shellcheck` clean).
- **Recovery-entry boot is now a distinct manual acceptance gate** with its
own procedure and pass criteria in `docs/VM-BOOT-VERIFICATION.md`,
recorded separately from normal `sys undo` (NOT RUN: interactive BLS-menu
selection is not automated). Secure Boot/UKI stays rejected and is filed
as a separate opt-in milestone in the roadmap; seat desktop, live AI, Snap
revision change, and NVIDIA remain open with exact prerequisites.
- **Tests:** `cargo test --workspace` 717/717, `test_vmsafety.py` 18/18,
`cargo fmt --check` and `clippy -D warnings` clean, release and static-pie
builds pass. (One `assistant_bridge` test flaked once under parallel load
and passes in isolation and on rerun.)
## 2026-09-26 — Hardening pass: fail-closed stage3, truthful boot security, rollback acceptance
- **Stage3 verification is fail-closed (security defect fixed).** The unpinned
path previously warned and continued when the DIGESTS download failed, when
no SHA-512 entry matched, when `gpg` or the Gentoo release key was missing,
when the key import failed, and when `gpg` could not start. Every one of
these now stops the install before extraction, as do a bad signature and a
hash mismatch. The pinned path requires a valid 64-hex digest (placeholder
refused) before any network use, and its trust is documented as coming from
the independently supplied pin. `stage_install` requires
`curl/tar/gpg/sha256sum/sha512sum` up front. 16 new regression tests cover
every failure branch plus both positive paths.
- **Live image carries the verifier.** `installer/live` ships `gnupg` and the
trusted Gentoo release key (`/usr/share/openpgp-keys/gentoo-release.asc`),
provisioned by `build.sh` and checked against Gentoo's published
release-key fingerprints; the installer never fetches an unauthenticated
key. Not yet VM-proven: no full install has run with the new binary, and
the signed-DIGESTS VM proof needs a rebuilt ISO with the key.
- **Boot security is truthful.** `kernel.uki`/`kernel.secureboot = true` are
rejected at shared configuration validation (CLI/TUI/GUI bridge), and the
plan preview always reports the real unsigned-BLS path. Authenticated boot
remains an open limitation by design (separate opt-in milestone).
- **Rollback acceptance PASSED with evidence**
(`serial-rollback-20260926T030237Z-912f6386`, PASS=11 FAIL=0, exit 0, no
secret leak): snapshot → `app-misc/hello` install (package DB changed) →
`sys undo <id>` → detached reboot (DB restored, root marker absent, `/home`
survives, systemd running, recovery entry present). This corrects the
2026-09-25 pass claim, which had no transcript and did not reproduce: the
harness ran unprivileged, used pre-installed `nano`, restored "newest", and
never asserted the marker. Fixed with sudo authentication, explicit
`--legacy`, a verified break, targeted undo, and vacuous-pass guards.
Recovery-entry offline boot stays a manual gate.
- **Release candidate (local, isolated):** manifest/verify, tampered-artifact
refusal, and publish refusal against the NotRun gate report all behave;
`gates --execute` is 0 passed / 6 NotRun (all gates need VM/seat/model).
Nothing published. Desktop-under-seat, live AI, and Snap
strict-confinement/changed-revision remain explicitly open (see STATUS).
- **Tests:** `cargo test --workspace` 712/712 (was 692), `test_vmsafety.py`
18/18, `cargo fmt --check` and `clippy -D warnings` clean, release and
static-pie builds pass.
## 2026-09-26 — Code quality pass: boxed ExecError, warning-free Clippy, service/gui_bridge splits
Structural work only; no behavior, wire-format, or serialized-plan change.
- `ExecError::Command` now carries a boxed `CommandFailure` payload, so
`ExecError` shrinks from 128 to 96 bytes and `Result<T, ExecError>` passes
Clippy's `result_large_err` gate (all 57 warnings gone). The display text,
the redacted stdout/stderr capture, and the stderr tail used for update
failures are preserved; the constructor and every match site were updated,
with regression tests for the error text, the captured output, and a 96-byte
size bound.
- The remaining Clippy warnings are fixed without blanket allows: a type alias
for the Snap-entry tuple (`actions.rs`), a `CommandRecord` params struct for
`Logger::command` (`log.rs`), and `DiskPhase` variant renames
(`gui_bridge.rs`). `cargo clippy --workspace --all-targets -- -D warnings`
is clean.
- `service.rs` (4218 lines) is split into `service/mod.rs` (types, render,
shared helpers, explicit re-exports), `plan.rs`, `validation.rs`,
`execution.rs`, and `tests.rs`. Every `phoebus_installer::service::*` path,
the serialized plan format, approval digests, replay protection, and the
privileged validation boundary are unchanged.
- `gui_bridge.rs` (2763 lines) is split into `gui_bridge/mod.rs`,
`protocol.rs` (protocol version 1, wire types, JSON observer, disk phase,
newline-delimited JSON writer), `bridge.rs` (the single `Bridge` owning the
installer, dispatch, installation support, secret handling), and `tests.rs`.
No UI or wire-format change.
- `cargo test --workspace` passes 692/692 before and after each split
(including the 4 new `ExecError` regression tests). Release and static-pie
builds pass.
- The disposable VM re-ran the current `sys` acceptance matrix against the new
static `sys` (`70f0a72b…`, fetched to `/tmp/sys` on an overlay of the
pristine installed image): guest `PASS=38 FAIL=0` (the full 38-case matrix,
run as the non-root user with no mutations), driver `PASS=41 FAIL=0`
(`serial-boot-20260926T014746Z-3089a820`). Recovery boot, strict Snap
confinement, and a revision-changing Snap update remain unverified.
## 2026-09-25 — Make first-use Snap setup reviewable and fix Portage target selection
- The normal Snap install now explains the separate, reviewed Portage install of
`app-containers/snapd` and the socket enable/start steps when the daemon is
absent. A raw typed `snap_install` no longer adds snapd behind the review.
- Fresh installs include scoped `sys-fs/squashfs-tools lzma lzo` USE flags,
which Gentoo's snapd ebuild requires. Existing installed images need the same
scoped setting before the Portage step.
- Portage candidate resolution matches the requested atom in a multi-package
pretend plan. The prior first-line selection could install a dependency
(`dev-lang/go-bootstrap` in the Snap VM) instead of `app-containers/snapd`.
- Snap candidate sandbox levels now use the daemon's detected confinement;
missing `snap info` confinement is not assumed to be strict.
- Regression tests cover the prerequisite gate, Portage target selection and
confinement mapping. The disposable VM exposed both the missing scoped USE
flags and the first-dependency selection bug. After those fixes, the installed
VM completed the reviewed snapd install, enabled and started `snapd.socket`,
installed `hello-world` from the Snap Store, ran refresh, and removed it
(`serial-boot ...107996de`, `PASS=10 FAIL=0`). The daemon reported **partial**
confinement and the plan displayed partial, not strong. The refresh command
succeeded with no newer revision available. A fresh overlay using the final
static binary passed the same journey with clean poweroff (`...c024cc43`,
`PASS=11 FAIL=0`); a clean reboot and repeat also passed (`...e6193c3a`,
`PASS=11 FAIL=0`). A revision-changing refresh and strict AppArmor
confinement remain unverified.
## 2026-09-25 — Second-round `sys` fixes: safe cleanup previews, exact update transactions, reverse dependencies
Follow-up review found three further confirmed defects; all three are fixed with
regression tests, and the disposable-VM acceptance is extended. This entry
supersedes any earlier claim that every review finding was already fixed.
- **Cache-cleanup preview no longer deletes (finding 1).** `eclean-dist`/
`eclean-pkg` **delete by default**; only `--pretend` previews. The planner now
runs `--pretend --deep` (the same selection policy as the destructive run) and
combines stdout and stderr into a sorted, bound item set. The Nix preview uses
the documented `nix-store --gc --print-dead` (a bare `--gc`, and the
undocumented `--dry-run`, were unsafe assumptions). Tests prove reconciliation
and cancelled approval run no destructive cleaner.
- **Exact Flatpak/Snap update transactions (finding 2).** A reviewed update now
carries a structured `UpdateTransaction`: the full Flatpak ref (from
`remote-ls`) plus installed and remote **full commits** (from `flatpak info`,
because Flatpak's `commit` column is abbreviated), or the snap name plus
old/new revisions and tracking channel. Execution consumes the reviewed
transaction, is pinned (`flatpak update --commit=<commit>`), and revalidates
each source immediately before its mutation — including after an earlier
source has run. A commit republished under an unchanged human version, a newly
appearing update, or a non-exact transaction is refused; a source whose
resolution failed is never re-discovered at execution.
- **Reverse-dependency self-reference (finding 3).** The reverse branch compared
the dependency target with the queried package and dropped exactly the valid
matches. It now excludes only a genuine self-reference (the *dependent* is the
queried package), so installed targets, full and bare names, and
conditional/versioned dependencies are reported.
- **Determinism and execution robustness.** `All selected packages:` removals
are sorted so depclean previews are order-independent (previously a false
"plan changed"); `emerge --depclean` runs with `--ask=n`; plan aggregation
includes `updates`.
- **Tests:** +22 (workspace `cargo test --workspace` green, 661 → 683). New
regressions cover the non-destructive preview, drift/failed/cancelled
cleanup, exact Flatpak identities/commits, Snap revisions, reverse
dependencies, and Nix generation handling.
- **VM-verified (disposable images):** real `eclean` preview/approve/cancel/
drift/failed and `depclean` cancel/approve with history and preserved user
data; real reverse dependencies (`sys-libs/glibc`, `sys-libs/zlib`); a real
Flatpak reviewed update (Portage-installed Flatpak, flathub, downgraded commit,
reviewed update to the reviewed full commit, verified); custom-ebuild
stage/build/install/remove; managed AppImage acquire/list/launch/remove with a
tampered-SHA refusal; a Nix-enabled install with a real `nodejs-slim` profile
(inventory, filtering, generations); and the **non-root `pkexec sys --broker`
path** (cancelled authentication, successful broker execution, replay
rejection) after installing the shipped polkit action and the standard
wheel-admin rule. The read-only acceptance matrix re-run on the final static
`sys` (`dd61c610…`) reports `PASS=38 FAIL=0` (the matrix gained a reverse-
dependency regression).
- **Not completed (see `docs/HANDOFF.md`):** Snap install/refresh/remove (no
snapd in the image; needs `app-containers/snapd`, AppArmor and network); live
AI (a local model was served, but the sandboxed call exceeds the 120 s
transport timeout on CPU); and the distinct recovery boot (the recovery BLS
entry is present; selecting it interactively is not automated).
## 2026-09-25 — Fix the `sys` catalogue review findings (host/target, revalidation, update effects, Nix inventory, dependencies)
Follow-up to the package-management interface: seven review findings are fixed,
each with regression tests, and the installed-system acceptance matrix is
extended and re-run.
- **Host/target confusion closed (finding 1).** Every catalogue, update-check,
information and maintenance query is now built for the *intended target* —
directly for `/`, or inside the target chroot for an alternate root. Snap acts
on the running daemon and is reported unavailable (and refused for mutation)
for an alternate root instead of ever touching the host. Availability checks
resolve tools from the target (`Exec::tool_in_target`), so a host Flatpak,
`eclean` or `qdepends` cannot leak into a target operation. Recording-runner
tests assert alternate-root search/update/cleanup and Snap paths issue no host
commands.
- **Maintenance revalidation (finding 2).** `resolves_effects` now covers
`Depclean`, `ApplyUpdates` and `CleanCache`, so they are re-resolved at the
privileged execution boundary and within multi-action plans. Depclean removals
are parsed into **structured `PackageEffect`s** (`emerge --pretend
--depclean`), so a changed removal set changes the digest and aborts before an
unapproved mutation; a regression test proves drift is refused with no
destructive command run.
- **Exact Flatpak/Snap update effects (finding 3).** `ApplyUpdates` resolves a
reviewable per-source plan with the affected identities and versions; each
Flatpak app is updated by ref and each snap by name, and the plan is bound to
approval and re-checked immediately before execution. Unrestricted update-all
is gone. Lanes with no safe system-level transaction (Nix/AppImage/custom
ebuild) are refused with a clear limitation. Destructive cache cleanup now
reviews each cleaner's non-destructive dry run and binds the item set to
approval (`ResolvedPlan.cleanup`), which is part of the digest.
- **Complete source constraints (finding 4).** `SystemAction::backend()`
classifies Portage-only actions (`UpdateSystem`, `RemovePackage`,
`Depclean`, `PrepareUpdates`, `InspectUpdates`, `PackageOwners`,
`PackageDependencies`); `constrain_action` rewrites optional-backend discovery
and selection (`DiscoverCandidates`, `ChoosePackage`) to the constrained lane
*before* querying, and refuses the cross-lane `InspectInstallation`. Unit tests
prove a Flatpak-constrained request cannot investigate or mutate
Portage/Snap/Nix through any action variant.
- **Cache-cleanup truthfulness (finding 5).** Portage cleaner errors are no
longer converted to text while the action returns success. A cleaner that ran
and failed fails the whole action (with partial successes preserved), an
unavailable cleaner is reported distinctly from one that found nothing, and
the report reaches the command exit status, assistant response and transaction
history.
- **Nix inventory (finding 6).** Inventory enumerates the packages of the active
Nix profiles from each profile's `manifest.json` (v1/v2/v3), retaining profile
and user scope and package identity; historical generations and realised store
paths are reported separately. Unsupported manifest formats and base profiles
are stated explicitly rather than shown as an empty inventory. Filtering finds
a package such as `nodejs` in a supported profile.
- **Dependency inspection (finding 7).** Forward and reverse dependencies now
come from the authoritative installed VDB metadata
(`DEPEND`/`RDEPEND`/`BDEPEND`, with a `qdepends` tree fallback) instead of an
`emerge --pretend` merge plan. Already-satisfied, conditional/versioned and
blocker dependencies are preserved; the requested package is never its own
dependency; a failed query is distinguished from a genuinely empty set.
- **Tests:** +28 (core/executor/installer) covering alternate-root chrooting,
structured depclean effects and digest drift, exact Flatpak identities, cache
cleanup review and failure propagation, constraint rewrite/refusal, Nix
manifest parsing, and dependency parsing/inspection. `make test` passes
(`cargo test --workspace`).
- **VM-verified (disposable installed clones + fresh install):** the read-only
acceptance matrix is extended with `snap-alternate-root`, `list-nix-legacy`
and `deps-legacy`, and reports `SUMMARY PASS=37 FAIL=0` on both an existing
clone and the fresh install (final static `sys` `TEST_SYS_SHA:65307d85…`). A
fresh non-interactive install reports `INSTALL-RC=0`/`NO_SECRET_LEAK`, and its
Portage configuration is world-readable out of the box (non-root `search`
returns 3 real results, `updates` reports 10). Privileged mutating journeys
(install/remove/history/depclean/cache-cleanup/alternate-root-Snap/Portage
`apply updates`) pass 7/7, and a snapshot → change → `sys undo` → detached
boot restores the package database and root while preserving `/home`. See
`docs/HANDOFF.md` for the precise verified/blocked state.
## 2026-09-25 — Complete the `sys` package-management interface (search/list/info/updates/maintenance)
Adds a complete package catalogue on top of the typed-action architecture. AI is
still the default for every operation; `--legacy` is the only user-facing opt-in
to deterministic handling.
- **Unified search** (`phoebus-executor::query`, `SystemAction::SearchPackages`
gains an optional `backend`): cross-source discovery across Portage, Flatpak,
Snap, managed AppImages, Nix and staged custom ebuilds. Every lane reports
**unavailable**, **failed**, or **empty** distinctly; no metadata is invented.
`sys search firefox [--legacy] [--<source>]`.
- **Inventory** (`SystemAction::ListPackages`): Portage VDB, `flatpak list`,
`snap list`, managed AppImages, and **Nix profiles** (store paths reported
separately as realised dependencies, never as installed programs). Custom
ebuilds install through Portage and are listed once, under Portage.
`sys list [filter] [--legacy] [--<source>]`.
- **Package information** (`SystemAction::PackageInfo`): installed VDB metadata
(version, size, repository, `RDEPEND`) merged with resolved candidates and
policy metadata; ambiguous queries list every real match and are flagged.
`sys info <package> [--legacy] [--<source>]`. `sys inspect <service>` is
unchanged.
- **Consistent updates** (`CheckUpdates`/`ApplyUpdates`): `sys updates` checks
every lane without mutating; `sys apply updates` reports a truthful
per-source outcome and fails the action when an attempted source fails.
AppImage (pinned URL+SHA) and Nix (project/declarative) are explained as
manual/project-specific, never reported as updated. Background preparation
stays distinct from activation. Portage updates/depclean are previewed from
`emerge --pretend` at review time.
- **Maintenance** (`Depclean`, `CleanCache`, `PackageOwners`,
`PackageDependencies`): unused-dependency removal, Portage/Nix cache cleanup,
package-file ownership (`qfile`/`equery`), and forward/reverse dependency
inspection, all with explicit unsupported results where a backend or tool
cannot support them.
- **AI-default routing enforced**: a recognizable catalogue command enters the
general assistant loop (`phoebus_ai::assistant::run_assistant`), which may run
bounded read-only tools before answering. An explicit source flag is applied
to both investigation requests and the final plan (rewriting lane-selectable
queries, refusing a foreign lane). A missing model or provider failure stops
the workflow and prints the exact `--legacy` alternative; it never executes
deterministically. Direct JSON still requires `--legacy`/`--broker`.
- **Tests:** +43 (core/executor/ai/installer) covering search/list/info parsing
and dispatch, unavailable/failed/empty distinction, VDB metadata, ambiguity,
depclean preview and skip, per-source update failure, no double-counting,
routing (AI vs legacy), the source constraint, and the general investigation
loop. `installer/tests/vm/sys-acceptance.sh` gains catalogue and
routing cases (read-only group now 34).
- **VM-verified (disposable installed disk):** `installer/tests/vm/sys-acceptance.sh`
reports `SUMMARY PASS=34 FAIL=0`, including `search-legacy`, `list-legacy`,
`info-legacy`, `updates-legacy`, `search-no-model-offer`,
`search-flag-constraint` and the non-root maintenance refusals.
- **Fixed: read-only Portage queries failed for a normal account.** The
installed system left `/etc/portage/repos.conf` and
`/etc/portage/package.use/phoebus` root-only, so `emerge --search` and
`emerge --depclean --pretend` failed with `Permission denied` for the
unprivileged catalogue. `portage::normalize_config_permissions` makes the
non-secret Portage configuration world-readable (0755 dirs, 0644 files) while
leaving the keyring (`/etc/portage/gnupg`, key-holding files) private; it runs
when the config is written and again at finalize. Unit-tested (including the
keyring exclusion); demonstrated on the disposable VM by applying the same
permissions, after which `sys search firefox --legacy` returns real results
and `sys updates --legacy` reports the available updates. A fresh VM install
with the fix is not yet re-run (base install is ~2 h).
## 2026-09-25 — Installed-VM verification fixes (installer finalize probe, personal preference transactions)
Found while running the acceptance on a fresh disposable installed system:
- **Installer `finalize` probe used the AI-first path (`phoebus-executor::sys_runtime`).**
The target `sys` verification ran `sys history`, which is AI-first and
(correctly) refuses to run without a connected model, so a non-interactive
`--install --no-ai` aborted at the `finalize` stage with `INSTALL-RC=1`. The
offline-safe deterministic probe is now `sys history --legacy`. Unit-tested;
`sys history --legacy` succeeds in the booted target (`HIST_RC:0`).
- **A personal preference no longer requires the root-owned transaction log
(`sys` `execute_action`).** A normal account saving a personal package
preference wrote the preference successfully but then failed with permission
denied recording it in `/var/lib/phoebus/transactions.toml`, returning a
misleading nonzero exit. Personal preferences are user-owned state and are no
longer written to the system transaction history; only `requires_root()`
actions are recorded. Covered by a CLI regression test that makes the system
transaction directory read-only.
- **Install-driver reporting robustness (`installer/tests/vm/serial-driver.py`):**
the driver no longer raises a `TypeError` when the guest serial closes before
`INSTALL-RC` (it now handles `pexpect.EOF`/`TIMEOUT` explicitly), and teardown
is best-effort so the post-poweroff `Could not terminate the child` exception
cannot turn a successful install into a nonzero driver exit.
- **Installed-VM evidence (disposable qcow2):** a clean install with the fixed
installer completes (`===INSTALL-RC=0===`, `installation finished`,
`NO_SECRET_LEAK`). Detached boot: LUKS unlock and login; systemd PID1
`running`; `sys 0.1.0`; `sys history --legacy` exit 0; and
`installer/tests/vm/sys-acceptance.sh` with the fixed `sys` reports
`SUMMARY PASS=24 FAIL=0`, including `personal-preference PASS saved to user
config` and `nonroot-systemwide` correctly refused. The privileged `--broker`
plan path and replay rejection are unit-tested at the privileged entry point
but were not exercised end-to-end in the VM (no root/Polkit agent on the
serial console; `sudo -n` denied).
## 2026-09-25 — Bind per-step reviewed effects into the approval digest
- **Per-step effect binding (`phoebus-installer::service`):** the canonical
approval digest now covers every per-step reviewed effect that execution
trusts, not just the actions and aggregate effects. At the privileged
boundary `validate_prepared_plan`:
- derives the effective per-step effects (`step_effects`, or the aggregate for
a single-action plan; a multi-action plan without per-step effects is
refused);
- verifies each stored effect digest by *recomputing* it from the effect
contents, so a step whose contents changed but whose stored digest did not
is rejected;
- verifies the aggregate effects are exactly the concatenation of the
per-step effects;
- feeds every per-step effect into `compute_plan_digest`, so the canonical
digest (compared with both `plan.digest` and the independently supplied
`--approval-digest`) changes whenever a step changes.
This closes the gap where a user-controlled General/Undo plan could retain its
approved digest, change only `step_effects` to match a different live
resolution, reseal the plan, and execute. Install/LegacyInstall keep their
install-specific digest, with the single step required to equal the aggregate;
Removal, General and Undo are bound per-step. Plan builders normalize stored
step digests so legitimate plans continue to validate, and the legitimate
allowance for changes caused by earlier approved steps is unchanged.
- **Adversarial tests:** single-action and multi-action General plans whose
`step_effects` are swapped (with and without a matching aggregate) while the
approved digest is retained are rejected before any command, ledger claim or
transaction; a legitimate bound multi-step plan still validates.
## 2026-09-25 — Adversarial approval-boundary hardening (canonical digest, stable identity, recovery)
- **Canonical approval digest recomputed at the privileged boundary.** The
broker no longer compares the independently supplied digest with the
user-owned plan's stored digest. It independently re-derives the canonical
digest from the exact executable actions, candidate and reviewed material
effects (`compute_plan_digest`) and requires it to equal both the stored
digest and the supplied `--approval-digest`. The integrity seal is treated
only as a self-consistency check, never as authentication. This closes the
"retain the approved digest, swap an action and its effects, recompute the
seal" substitution for every plan kind (Install, LegacyInstall, Removal,
General, Undo).
- **Stable approval identity for replay protection.** The ledger and `.claim`
marker are keyed by
`approval_key(plan_id, canonical_digest, initiator_uid, target_root)` instead
of the integrity seal. Editing only the summary (or other presentation
fields) and resealing can no longer mint a fresh ledger entry for an
already-consumed approval, while a newly reviewed identical operation with a
new random plan ID is still allowed.
- **Live-safe, monotonic crash recovery.** Claims record the owning process
(`pid`, `/proc/<pid>/stat` start time, kernel boot id). Terminal statuses are
published exactly once by an atomic hard link into `<key>.terminal` and can
never be overwritten or changed to another terminal status.
`reconcile_interrupted` only marks a record interrupted when its owner is
provably gone, so a second broker starting alongside a live operation cannot
mislabel it, and reconciliation cannot race a real finish.
- **Personal settings are owned by the initiating user.** `UserStorage` creates
the config/state path component by component beneath the resolved home,
rejecting symlinks and non-directories. When the write is elevated
(effective root on behalf of a non-root user) the created paths are chowned
to the initiating user's uid/gid; a non-root process acting for a different
user is refused rather than writing a root-owned file. No path outside the
home is ever chowned. Proactive state now goes through the same path.
## 2026-09-25 — Approval ledger, user-owned settings, and reviewed-effect execution
- **Broker-controlled approval ledger (ADR 0014, `phoebus-installer::approval`):**
the privileged broker no longer trusts a self-consistent checksum as proof of
approval. The plan's integrity seal — covering actions, per-step effects,
candidate, target root, initiating uid and expiry — is the binding fingerprint
and the `O_EXCL` consumption key in a root-owned ledger
(`/var/lib/phoebus/approvals`, 0700 / 0600). The digest shown on the review
card travels across authentication independently of the plan file
(`--approval-digest`); a replacement plan under the same identifier is refused
even when resealed with a valid checksum; replay is refused even after the user
deletes every file in their own plan directory; at most one execution may run
under concurrent submissions. The initiating identity is derived from
`PKEXEC_UID` (the `--plan-uid` argument is untrusted input). Authentication
precedes the claim, so cancellation/refusal consumes nothing; a crash leaves a
reconciled `interrupted` record that cannot be retried automatically.
- **User-owned personal settings (`phoebus-executor::personal`):** personal
package preferences (`~/.config/phoebus/package-preferences.toml`) and
proactive snooze/dismiss state
(`~/.local/state/phoebus/proactive-state.toml`) are 0600-in-0700, atomic and
bounded, written without elevation. System defaults stay root-owned under
`/etc/phoebus` and change only through the authenticated typed action
`set_package_preference { system_wide: true }`. Personal choices take
precedence; system defaults fill the rest. The initiating user is resolved
through `PHOEBUS_UID` → `SUDO_UID` → `PKEXEC_UID` → effective uid and
`/etc/passwd`, so CLI and GUI agree under sudo/pkexec. Persistence failures are
reported as failures — the GUI never says "saved" or "dismissed" on a failed
write.
- **Reviewed effects carried through execution:** `execute_prepared` now carries
the reviewed per-step effects forward; freshly resolved effects are evidence to
compare against them, never a replacement approval. A material change aborts
with a terminal `stale plan` transaction outcome; only changes explained by an
earlier approved step in the same plan are accepted. Effect-resolution failure,
stale-plan rejection, partial execution and verification failure all record a
terminal result, preserving completed-step outcomes and the protective
snapshot.
## 2026-09-25 — Privileged-boundary, GUI-review, removal, transaction and privacy remediation
- **Single privileged validation boundary (`phoebus-installer::service`):**
- `validate_prepared_plan` is the one authoritative check, run before
elevation and repeated inside the broker after authentication. It re-derives
the plan seal from the plan's own contents, rejects expired/claimed/modified/
malformed/wrong-root/wrong-uid plans, and revalidates live state.
- Plans now bind the exact actions, effects, candidate, canonical target root
and initiating uid; multi-action plans store per-step effects and are
revalidated action-by-action (fixing an aggregate digest comparison bug).
- Protected per-user plan storage (`/run/user/<uid>/phoebus/plans`, 0700 / 0600,
atomic writes, 128-bit ids, symlink/ownership checks) and atomic `O_EXCL`
consumption so concurrent requests cannot both mutate and retries cannot
repeat. The broker resolves storage from the uid, not an arbitrary path.
- `sys --broker --execute-plan <id> --plan-uid <uid> --root <root>`; a dropped
or mismatched root is rejected rather than silently executing against `/`.
- **Truthful transaction outcomes:** verification failure, action failure,
refusal and cancellation all finish the transaction with a truthful result;
completed steps and the protective snapshot are retained; persistence failures
are surfaced; a malformed broker reply is a protocol failure, not success.
- **GUI plan review for every plan type:** the assistant renders one review card
for install, removal, general administration, rollback and follow-up
confirmation; approval/cancel controls execute only the referenced reviewed
plan and update the original card; "prepared" is never shown as "completed";
verification results are shown; launch is offered only when a concrete desktop
entry/command was identified. Corrected the assistant's `PhoebusButton` API
usage (`label`/`actionEnabled`).
- **Shared provider/credential handling (`phoebus_installer::ai_setup`):** the CLI
and GUI resolve provider, endpoint, model and credential reference through one
module. Credentials load from a configured 0600 file, `PHOEBUS_AI_API_KEY_FILE`
or a default `~/.config/phoebus/ai.key`; they are never sent through QML,
prompts or argv. The GUI direct transport no longer uses an empty key.
- **AI-first removal and corrected follow-ups:** default removal routes through
the connected model while deterministic ownership discovery and policy
validation stay underneath; only `--legacy` bypasses the model. Follow-ups
prefer explicit application references, so "install vlc using flatpak" is
about VLC, "use flatpak for that one" refers to the previous app, and
"why is my audio broken?" is not answered as a package explanation.
- **Honest conversation privacy:** history stores minimized structured context
(never the raw request), uses the active redactor, is written 0600/0700
atomically, is bounded to ten turns, surfaces write errors, and can be cleared.
- **Tests:** regression coverage for tampered/expired/replayed/malformed plans,
plan replacement after review, concurrent claims, refusal, target-root and uid
binding, verification failure, transaction truthfulness, follow-up resolution,
credential loading, and history privacy/retention/deletion. Storage is injected
in tests (no shared `PHOEBUS_PLANS_DIR` race). Full workspace suite, `fmt` and
`clippy` run; static binaries build.
## 2026-09-24 — AI-first administration remediation: shared service layer, Polkit elevation, QML provisioning, and conversation continuity
- **Shared Administration Service Layer (`phoebus_installer::service`):**
- Unified planning, recommendation, authorization, execution, and verification across CLI (`sys`) and desktop GUI (`phoebus-assistant`) into a single shared service layer.
- Staged reviewable plans (`PreparedPlan`) with cryptographic approval digests (`Sha256`), 15-minute TTL expiration, and replay rejection (`PlanStore`).
- Execution binds to the reviewed plan digest and revalidates against current system state before mutation; material alterations abort execution and require fresh review.
- Honest recommendations: eliminated speculative claims (e.g. no "avoids a lengthy build" when compile times are unmeasured; displays genuine provenance such as Flathub, Gentoo binhost, Gentoo Portage, Nixpkgs, Snap Store).
- Two-phase transaction recording: in-progress transaction recorded before mutation (`transaction::begin`), completed transaction recorded with post-mutation verification (`transaction::finish`).
- **Target Desktop & QML Asset Provisioning (`phoebus-core`, `phoebus-executor`):**
- Added `gui-apps/quickshell` to the canonical Mango desktop package list.
- Embedded all 13 required QML, config, and policy files into the target filesystem (`/usr/share/phoebus/assistant/`) through `TargetRoot` safeguards in `write_session_script`.
- Installed Polkit policy (`club.phoebus.sys.policy`) enabling desktop users to elevate mutating plans via `pkexec /usr/local/bin/sys --broker --execute-plan <plan-path>` with standard authentication prompts, avoiding blanket passwordless sudo and keeping graphical processes unprivileged.
- **Desktop Assistant Responsiveness (`phoebus-assistant`):**
- Eliminated startup freeze in `AssistantBridge.qml` and `shell.qml` by moving multi-source update checks to on-demand tab switching and replacing continuous polling with a one-shot 100ms handshake timer.
- Handshake checks deterministic system state (`/run/reboot-required`) without blocking on network queries.
- `execute` submits `plan_id` and `digest`, maintaining UI context cleanly on failure or user authentication cancellation (Polkit exit 126/127).
- **Contextual Conversation Continuity (`phoebus_installer::conversation`):**
- Bounded conversation turn history (up to 10 turns) with credential redaction (`Redactor`).
- Contextual follow-up resolver (`resolve_followup`) handles comparative queries ("why did you choose that over nix?", "why flatpak?"), backend switching ("install the flatpak one", "use portage instead"), and plan confirmations ("proceed with that").
- **Cross-Source Application Removal:**
- `plan_removal` detects installed application copies across Flatpak, Snap, AppImage, and Portage.
- Detects duplicate/competing copies across lanes and requires explicit lane disambiguation (`sys remove <app> --legacy --<source>`).
- Preserves user configuration and data in home directories by default; post-removal verifies complete uninstallation before closing transactions.
- **Verification & Acceptance:**
- Expanded guest-side acceptance suite `installer/tests/vm/sys-acceptance.sh` to 23 passing cases (`PASS=23 FAIL=0`).
- Full cargo test suite passes (55 installer unit tests, 23 CLI integration tests, 10 guidance tests, 16 ISO tests, all core/executor tests).
- Clean `cargo fmt`, `cargo clippy`, release binary build, and crt-static build verified.
## 2026-09-24 — AI-first administration experience across CLI and GUI, package correctness, and shared recovery
- **Unified AI-First Administration Contract (`sys` & `phoebus-assistant`):**
- Natural language is the default interaction across CLI and desktop assistant: `sys install <pkg>`, `sys please install <pkg>`, and `sys ask "<request>"` all enter the identical AI investigation and recommendation workflow.
- Source flags alone (`--flatpak`, `--portage`, `--nix`, `--snap`, `--appimage`, `--ebuild`) constrain AI candidate evaluation without bypassing the model.
- Explicit deterministic administration is selected exclusively via `--legacy`: `sys install <pkg> --legacy --<source>`, `sys history --legacy`, and `sys undo --legacy`.
- Deterministic legacy install without a source flag (`sys install <pkg> --legacy`) refuses execution and outputs available package source options.
- Audited JSON action invocations: `--action` and `--action-file` fail closed unless invoked with `--legacy` (for deterministic administration) or `--broker` (for internal UI/bridge calls).
- Truthful fallback: when the AI model is absent or returns an error, execution stops and prints actionable deterministic legacy alternatives (`sys install <pkg> --legacy --<source>`), never silently falling back across package lanes.
- Distinct break-glass semantics: documented distinction between administrative `--legacy` and installer-only ISO `--no-ai` flag.
- **Package Correctness & Safety Guarantees:**
- Nix attribute evaluation probe: `nix::verify_attribute` probes attribute existence in nixpkgs via `nix-instantiate` before recommendation or preparation.
- Portage binary binhost check & compile abort guard: binary package candidates are verified via `emerge -p --usepkgonly`. If an action changes to source compilation (`EffectSource::Source`), execution halts with an error, invalidating prior approval and requiring fresh review.
- Cross-source installed application tracking: detects duplicate/competing installations across Flatpak, Snap, AppImage, and Portage.
- User data preservation on removal: default package removal preserves user data and configuration directories.
- **Desktop Assistant GUI (`phoebus-assistant`):**
- Quickshell QML application in `installer/live/desktop/phoebus-assistant/` providing an intuitive desktop assistant with conversational chat, recommendation cards with concise rationales, expandable comparison options, unified updates, proactive alerts, legacy controls, and preferences.
- Backed by `sys --assistant-bridge` via stdio JSON-RPC; zero business or administrative logic in QML.
- Desktop integration: launcher script (`/usr/local/bin/phoebus-assistant`), desktop entry (`phoebus-assistant.desktop`), and session launcher shortcuts.
- **Unified Multi-Source Updates:**
- `update::check_unified_updates` queries and consolidates pending updates across Portage, Flatpak, Snap, AppImage, and Nix, with reboot-needed detection.
- **Quiet Proactive Assistance:**
- Deterministic system monitors for reboot required, low storage (< 5 GiB), failed transactions, systemd service failures, and updates ready.
- Persistent alert deduplication, snoozing, dismissals, and configurable enable toggles under `/var/lib/phoebus/proactive.toml`.
- **User Preferences & Profiles:**
- Inspectable and editable profiles (`Balanced`, `FastInstallation`, `NativeIntegration`, `ApplicationIsolation`), project environment tool mappings, and source pins.
- **Expanded Acceptance Verification:**
- `installer/tests/vm/sys-acceptance.sh` expanded to 22 acceptance cases covering read-only, failure, offline fallback, and audited entry points (`PASS=22 FAIL=0`). All 481 crate unit and integration tests pass.
## 2026-09-24 — Desktop stack unification: Mango + DarkMaterial as sole desktop
- **Canonical Phoebus Desktop:**
Phoebus OS now exposes and configures one desktop experience only: **Mango + DarkMaterial**.
All standalone dwl desktop paths, packages, sessions, helpers, and fallback/recovery logic have been removed.
- **Removed Standalone dwl Packages & Assets:**
- Removed obsolete packages that existed solely for standalone dwl: `gui-wm/dwl`, `gui-apps/waybar`, `gui-apps/wofi`, `gui-apps/mako`, `gui-apps/swaybg`, `gui-apps/swayidle`, `gui-apps/swaylock`.
- Removed standalone dwl session and helper assets: `PHOEBUS_SESSION_SCRIPT` (dwl launcher), `PHOEBUS_MENU_SCRIPT` (wofi launcher/power menu), `PHOEBUS_LOCK_SCRIPT` (swaylock), `PHOEBUS_IDLE_SCRIPT` (swayidle), `WAYBAR_CONFIG`, `WAYBAR_STYLE`, and `phoebus-dwl.desktop`.
- **Retained Mango / DMS wlroots Heritage:**
- `gui-wm/mangowm` (GURU, wlroots 0.20 slot) and `gui-apps/dankmaterialshell` are independent and self-contained; DMS natively provides the status bar, notifications, app launcher (`danksearch`), screen lock, and idle daemon.
- Retained internal wlroots / dwm standard keybinding conventions inside `MANGO_CONFIG_DEFAULT`.
- **Fail-Closed Session Architecture:**
- `PHOEBUS_MANGO_SESSION_SCRIPT` (`/usr/local/bin/phoebus-session-mango`) starts Mango and DMS, failing visibly and diagnostically (status 1 with clear stderr) if Mango or DMS fails to start. There is no silent fallback to another desktop.
- `/usr/local/bin/phoebus-session` is retained as a thin wrapper executing `phoebus-session-mango "$@"` for manual VT / CLI invocation.
- Installed system `greetd` authenticates directly into `/usr/local/bin/phoebus-session-mango`.
- Installer desktop profile enum reduced strictly to `Mango` (default) and `None` (headless), rejecting legacy `dwl` configs with an explicit error.
- **Verification & Test Coverage:**
- Functional tests in `phoebus-executor` updated to exercise `phoebus-session-mango` against `mango` and `dms` stubs.
- Regression guards in `phoebus-installer` verify only `wayland-session-mango` is emitted and assert that dwl session/helper assets return `None`.
- All workspace tests pass, clippy is clean, and golden installation plan is updated.
## 2026-09-24 — End-to-end graphical installation, detached first boot, and live ISO freshness automation
- **Full graphical installation verified (100% complete):**
The 6-step graphical wizard and typed backend bridge (`gui-install` mode)
completed all 12 backend orchestration stages and emerged all 174 packages
of the Mango desktop stack on a disposable 30 GiB qcow2 disk.
`gui-install-completes` passed and captured `07-gi-07-complete.png`.
- **Detached first boot verified (6/6 checks):**
The installed disk was booted standalone with `iso=False` and `-boot order=c`.
Systemd-boot loaded, LUKS2 decrypted automatically with the test passphrase,
all Btrfs subvolumes mounted (`@`, `@home`, `@var`, `@snapshots`, `@swap`),
systemd reached `running` (0 failed units), serial console login authenticated,
and `/usr/local/bin/sys` verified operational (`sys history` -> `no transactions recorded`).
- **Greetd TOML format fix:**
Fixed a multiline TOML basic string syntax defect in `phoebus-core::greetd_config`
(`/etc/greetd/config.toml`) that previously caused `greetd.service` to fail with
`expected equals sign on line`. Formatted the `tuigreet` command string on a single
line and added unit-test TOML parser validation. Verified `tuigreet` rendered
cleanly on the booted system (`01-boot-desktop.png`).
- **Live ISO freshness automation:**
Added `scripts/ensure-live-iso.sh` and Makefile targets `iso` / `iso-rebuild`.
Guarantees that the live medium (`installer/live/phoebus-installer-amd64.iso`)
is automatically recompiled and repacked whenever Rust crates, QML desktop files,
or live configurations are newer than the ISO.
- **Kernel profile default optimization:**
Configured `KernelProfile::Safe` (`sys-kernel/gentoo-kernel-bin`) as the default
kernel profile during installation, eliminating 100+ minute kernel compile times
on constrained test environments.
- **Desktop dependencies and keyword updates:**
Added scoped keywords for `x11-misc/pcmanfm`, `x11-libs/libfm`, `dev-cpp/cpptrace`,
`dev-libs/libdwarf`, and USE flags `dev-python/pillow -truetype`,
`dev-cpp/cpptrace unwind`, `sys-libs/zlib minizip` to resolve desktop build graph requirements.
- **Harness & Driver hardening:**
Updated `gui-driver.py` with flexible login prompt regex matching arbitrary hostnames,
added focused tab-navigation helper `_tab_until_focus`, and implemented clean
guest poweroff (`sync; systemctl poweroff`) during detached boot checks.
## 2026-09-24 — AI-first package installation
- **Shared installation workflow (`phoebus-executor::install`, ADR 0013):**
`sys install <application>`, `sys ask install <application>` and the explicit
backend flags all run one flow: identify → evidence → AI investigation →
deterministic validation + effects → review → approval → execute → verify →
history. The AI only recommends; the resolver re-checks every proposal
against real backend metadata and maps it to the existing broker action.
- **Bounded investigation (`phoebus-ai::install`):** the model may request
typed, read-only evidence (`discover_candidates`, `inspect_candidate`,
`check_backend`, `inspect_installation`) and ask one bounded question about
intent before proposing a structured `InstallProposal`. Bounds: turn,
per-turn request and evidence-size limits plus repeated-request detection. A
rejected proposal is fed back for a bounded revision.
- **Friendly-name resolution and validation:** per-lane resolution
(`chooser::resolve_for_backend`) maps friendly names to real identifiers,
reports ambiguity, and never fabricates a candidate. Duplicate installs,
stale versions and changed effects are refused; approval is bound to a digest
and revalidated before execution.
- **Explicit backend flags are authoritative:** `--portage`, `--flatpak`,
`--nix`, `--snap`, `--appimage`, `--ebuild` bypass the model, are mutually
exclusive, and never fall back to another lane.
- **No-model path:** an unqualified install with no provider prints the
deterministic selection and the explicit commands and installs nothing;
provider failure is never permission to install.
- **Install facts are real:** `sys` now loads the installed
`/etc/phoebus/install.toml` instead of assuming defaults, and the bounded
facts include free space, Wayland, the usable lanes, saved preferences and
recovery capability.
- **Transaction engine:** installs record an in-progress transaction before the
mutation (`transaction::begin`/`finish`), verify installed identity/version
afterwards, and record failures truthfully.
- **ADRs/docs:** new `docs/adr/0013-ai-first-installation.md`; `docs/SYS.md`
updated with the install workflow and acceptance cases 23–31.
### Verified (host)
- `cargo fmt`, `cargo clippy --workspace --all-targets` (no new warnings) and
`cargo test --workspace` pass. New tests cover: the AI loop (steps, bounds,
repetition, revision, provider failure), resolver fabrication/ambiguity/
duplicate/changed-evidence, action mapping, transaction begin/finish, CLI
flag conflicts/no-fallback/no-model, and target-vs-host facts.
### Verified (disposable VM)
- A deterministic minimal install completed (`INSTALL-RC=0`), including
installing `/usr/local/bin/sys` and verifying the target, then booted detached
(systemd `running`, 0 failed units).
- `sys install app-misc/hello --portage` ran the full workflow: plan + effects,
protective snapshot, install, verification in the package database, and a
durable transaction in `sys history` that survived a clean reboot.
- `sys remove app-misc/hello`, the no-model offer, backend-flag conflicts and
the read-only investigation actions were exercised; the matrix reported
`FAIL=0` (19/19).
### Not yet verified
- The **AI-selected** journey (`sys install <app>` with a connected model) is
unit-tested with scripted transports and was not run against a live provider:
no authorised provider/credential exists in this environment. The exact
command is in `docs/HANDOFF.md`; it is the remaining gate.
## 2026-09-24 — Hardware-aware software selection, Snap/AppImage/custom ebuild, `sys` lifecycle
- **Shared selection policy (`phoebus-core::selection`, ADR 0006 revised):**
replaced the fixed category routing (GUI→Flatpak, dev→Nix) with a single,
inspectable, deterministic policy over resolved candidates from **every** lane
(Portage source/binary/vendor, Nix, Flatpak, Snap, AppImage, custom ebuild).
It separates hard constraints (architecture, required sandbox, storage, GPU,
required proprietary, unavailable backend) from preferences; keeps kernel,
drivers, systemd, graphics/audio and boot under Portage; honours and persists
explicit compatible choices; errors instead of silently switching lanes; and
reuses an already-installed lane to avoid duplication. Uncertainties are
labelled (measured vs estimated compile time).
- **Candidate resolution (`phoebus-executor::chooser`):** gathers real backend
metadata (`emerge --pretend`, `flatpak search`, `snap find`, local Nix/AppImage
records, the Phoebus overlay), assembles hardware facts (arch, cores, RAM, free
space, GPUs, Wayland, compile history) and applies the policy. Unreachable
metadata is reported as an unavailable candidate, never invented.
- **Snap lane (`phoebus-executor::snap`):** detection of the client, daemon
readiness and confinement; `find`/`info`/`list`/`install`/`remove`/`refresh`/
`connections`. `app-containers/snapd` is installed and `snapd.socket` enabled
**through Portage**; classic confinement is explicit; automatic refresh is
disclosed.
- **AppImage lane (`phoebus-executor::appimage`):** managed import/acquisition
with a pinned SHA-256 (placeholders and mismatches refused), ELF-architecture
checks **without executing the image**, atomic adoption, desktop entry and
optional icon extraction via `unsquashfs`, version/integrity records, and
removal that preserves user data by default. AppImage is never called a
sandbox.
- **Custom ebuild lane (`phoebus-executor::ebuild`):** a dedicated
`/var/db/repos/phoebus` overlay with recorded rationale and a content SHA-256.
Staging never runs the ebuild; install requires the reviewed digest, generates
the `Manifest` and builds through Portage with its sandbox enabled. Editing the
staged ebuild invalidates approval.
- **Typed actions + `sys` surface (`phoebus-core::action`, `phoebus-installer`):**
`choose_package`, `set_package_preference`, `snap_*`, `appimage_*` and
`custom_ebuild_*`, with strict validators (option-like operands, path
traversal, placeholder hashes and bad names fail closed). Deterministic
phrases cover the common cases; `custom_ebuild` staging/install stay JSON-only
because they carry a full artifact.
- **`sys` in the installed target:** the installer locates the trusted static
`sys` beside itself, installs it to `/usr/local/bin/sys`, proves it runs in the
target chroot before the recovery snapshot, and fails the install closed if it
is missing. The VM install harness now fetches `sys`, and the rollback guest
uses the installed binary.
- **Assistant prompt reconciled:** the closed action set now includes the new
actions and instructs the model not to route by category, to use
`choose_package`, and to treat a custom ebuild as untrusted.
- **Docs:** new `docs/SYS.md` command reference and acceptance matrix; revised
ADR 0006.
### Verified (host)
- `cargo fmt`, `cargo clippy --workspace --all-targets` (no new warnings) and
`cargo test --workspace` pass; the new policy, backend and CLI tests run on the
host. `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the new
`sys-acceptance.sh`.
### Not yet verified
- The new lanes and the installed-`sys` lifecycle are unit/integration tested
but **not yet exercised in a booted VM** in this session: a full GUI install
was occupying the only disposable disk. The exact VM commands are in
`docs/SYS.md` and `docs/HANDOFF.md`.
## 2026-09-23 — NVIDIA reliability, verification and harness repair
- **Deterministic live GPU decision (`phoebus-core`, `phoebus-installer`):**
`--live-gpu-plan` classifies the PCI display controllers (class `0x03`,
vendor `0x10de`) against the generated device table and the bundled branch's
capabilities, returning `load-nvidia`, `nouveau-fallback`, `no-device` or
`disabled`. The live `phoebus-nvidia-load` script consumes it: a supported GPU
loads the accelerated stack, an unsupported GPU (or a failed load) explicitly
`modprobe`s `nouveau`, and a machine without an NVIDIA display device is left
alone. `build.sh` now creates `etc/modprobe.d/phoebus-nvidia.conf` (the file
the old build required but never produced) and replaces Debian's
unconditional nouveau configuration. The fail-safe entry sets
`nomodeset phoebus.nvidia=off`, which the script and the unit both honour.
- **Legacy branch boundary corrected (`phoebus-core`):** Maxwell/Pascal/Volta
are capped at NVIDIA's last supporting series (580) with
`>=x11-drivers/nvidia-drivers-581` masked; a Blackwell plus proprietary-only
GPU set is now reported as an explicit incompatibility instead of installing a
single driver that cannot serve both.
- **Payload verifier hardened (`phoebus-executor`):** `--verify-live-nvidia`
now rejects placeholder modules/libraries, requires every module to be
registered in the live kernel's `modules.dep`, normalises the dpkg revision
and matches userspace/firmware versions to the bundled driver, infers and
checks the module flavor, and requires the exact `phoebus-nvidia.conf`. All
reads stay rooted inside the build root.
- **Installed lifecycle fixed (`phoebus-executor`, `phoebus-installer`):** the
NVIDIA dracut `force_drivers` fragment is written only in the NVIDIA stage,
after the driver exists, and the final initramfs is regenerated then. The
installer proves the modules were built for a kernel (or fails) and records
the real resolved version, kernel and module names. The update path verifies
the rebuilt modules before reporting success.
- **GUI acceptance harness repaired (`installer/tests/vm/gui-driver.py`):**
state-based step navigation replaces the step-0 keystroke count; the real
account fields and the default single-password encryption are driven; the
direct "Install now" action replaces ERASE typing and the (never-assigned)
confirmation toggle; duplicate submission is exercised; install timeouts
report stage, elapsed time and last state; the detached boot unlocks with the
single-password passphrase and falls back to the separate one.
- **Rollback acceptance automated (`installer/tests/vm/`):** a new
`serial-driver.py rollback` mode with `rollback-guest.sh` /
`rollback-verify.sh` records the package-database fingerprint and a `/home`
marker, creates a recovery point with `sys snapshot`, performs a controlled
reversible package install, runs `sys undo`, reboots detached and compares
package state and `/home`. The destructive VM gate is written but unrun.
- **Live privilege scoped (`phoebus-core`, `installer/live`):** the live
`NOPASSWD: ALL` rule is replaced by an emitted, `visudo`-validated policy that
grants unattended escalation only to the typed brokers
(`phoebus-installer`, `sys`) and `systemctl` power actions. The recovery
console is preserved via the password-authenticated live credential.
- Docs: ADR 0012 updated; the stale "`gui_bridge` tests hang" handoff claim
withdrawn (the workspace suite passes).
## 2026-09-23 — Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI
- **Streamlined 6-Step Flow (`phoebus-install`, QML):**
Eliminated the duplicate Step 0 welcome screen from the installer wizard; launch starts
directly at "Step 1 of 6 · Language and keyboard" with an accurate 6-step progress indicator.
The "Back" button is hidden on Step 1 and disabled for step 0 so back-navigation stays bounded.
- **Friendly Keyboard & Locale Pickers (`phoebus-installer::gui_bridge`, `PhoebusCombo`):**
Replaced raw two-letter codes (`al`, `dz`, `brai`) and arbitrary sorting with full layout
names parsed directly from `/usr/share/X11/xkb/rules/evdev.lst`, sorting the top 30 world
keyboard layouts and system locales first (e.g. `English (US) — us`, `German — de`).
Selecting a layout dynamically switches the live Wayland keymap via `localectl set-x11-keymap`.
- **Searchable Timezone Picker (`gui_bridge`, QML):**
Populated the timezone dropdown directly from system zoneinfo, auto-detecting `/etc/localtime`.
- **Welcome App Cleanup (`phoebus-welcome`):**
Removed the redundant "Keyboard test" button and modal from the live welcome app.
- **Single-Password Disk Encryption (`phoebus-install`):**
Default-enabled "Use same password to encrypt disk" toggle with LUKS2, reducing credentials
to username and password only without redundant confirmation prompts. Removed arbitrary
8-character minimum password restriction to accept any valid password.
- **Direct Installation Confirmation:**
Eliminated the requirement to type "ERASE" in all caps or check confirmation boxes; replaced
with a direct, unambiguous "Install now" button on the review screen.
- **Invariants Enforced Against AI Mutation (`phoebus-ai`):**
Enforced Mango + DankMaterialShell desktop, Btrfs filesystem, and Flatpak/Nix core subsystems
inside both the AI system prompt and semantic change validation; non-conforming AI proposals
are automatically rejected.
- **Loopback AI Auto-Detection & Clear Guidance:**
Auto-probes loopback ports 4096 (OpenCode) and 11434 (Ollama) upon reaching the AI step,
defaulting to detected local instances and replacing technical jargon with clear user guidance.
- **Humanized Failure Reporting & Details Viewer:**
Replaced raw curl/JSON dumps with clear humanized error summaries (e.g. package verification
or network connection issues) alongside "[Retry]" and "[View technical details]" toggles.
The live details terminal box properly fetches log lines and auto-scrolls to the latest activity.
## 2026-09-23 — Responsive display layout, resolution modal & hotkeys, and fullscreen installer
- **Display Resolution Switcher & Hotkeys (`phoebus-welcome`, Mango config):**
Added a dedicated 1-click Display Resolution dialog in `phoebus-welcome` allowing
instant switching between 1920×1080 (Full HD), 1440×900, 1280×768 (Standard),
1024×768, and 800×600 modes without blurry bilinear scaling. Mapped global Mango
hotkeys (`Super+Shift+F12` for 1080p, `Super+Shift+F11` for 900p, `Super+Shift+F10`
for 768p, `Super+Shift+F9` for 1024x768) and set virtual display auto-probe to
prioritize widescreen (1280x768) on initial boot.
- **Low-Resolution Responsiveness & Scrollability (QML):**
Wrapped both `phoebus-welcome` and `phoebus-install` form/progress views in
bounded `Flickable` containers with `ScrollBar.vertical`. Added compact view
adaptation (< 760px) in `phoebus-welcome` so the primary action stacks cleanly with
flow-wrapped readiness chips, eliminating text clipping and ensuring all recovery tools
and form controls are reachable on 800×600 and 640×480 screens.
- **Fullscreen Installer Enforcement:** Closed the welcome window on launching the
installer and set compositor fullscreen rules, eliminating any 50/50 window tiling splits.
## 2026-09-23 — Installer GUI usability, OpenCode model variants, and GURU mirror fix
- **Gentoo GURU Official Mirror (`phoebus-core::system`):** Updated `GURU_REPO_URI`
from the broken GitHub mirror to `https://anongit.gentoo.org/git/repo/proj/guru.git`,
resolving the HTTP 404 failure that caused `emaint sync -r guru` to exit with
code 1 during `portage_configure` in chroot.
- **OpenCode Model Catalog & Variant Picker (`phoebus-executor`, `phoebus-installer`, QML):**
OpenCode model selection now displays human-readable model titles alongside raw IDs
(e.g., `DeepSeek V4.1 Flash (deepseek-flash)`). Added model variant selection
supporting `default`, `low`, `high`, and `max` levels, defaulting cleanly to
`default` and properly passing the variant into OpenCode session prompts.
- **Live Terminal Output Streaming (`phoebus-executor::log`, `gui_bridge`, QML):**
`Logger` and command execution runner now support subscriber sinks that stream
stdout/stderr line-by-line in real time. The GUI bridge dispatches `log` events
to the frontend over JSON-RPC, populating the "Show details" terminal box with
live Portage compilation and command output rather than a static placeholder.
- **Desktop Defaults & Keybindings:** Enforced Mango + DankMaterialShell as the
default desktop configuration, standardized Btrfs and Flatpak defaults, simplified
user account creation, streamlined confirmation workflow, and mapped standard
DWM keybindings in Mango.
## 2026-09-23 — NVIDIA accelerated driver policy, live payload and installed integration
- **Hardware-driven driver policy (`phoebus-core::nvidia`):** a deterministic,
testable decision from the PCI display device IDs, backed by a generated table
(`nvidia_devices.rs`) derived from the public PCI ID database via each device's
NVIDIA chip codename. Turing/Ampere/Ada/Hopper/Blackwell use the current
`x11-drivers/nvidia-drivers` branch with NVIDIA's **open** kernel modules
(`kernel-open`); Maxwell/Pascal/Volta use the proprietary branch with
`-kernel-open` and are masked `>=x11-drivers/nvidia-drivers-595`; Fermi/Kepler
and older fall back to the in-tree `nouveau` and are reported, never claimed as
NVIDIA success. Unknown NVIDIA device IDs are reported as unknown.
- **Probe captures PCI identity:** display devices now carry `pci_id`
(`vendor:device`) and `pci_address`; `VIDEO_CARDS` uses the resolved plan
(`nvidia` only when a branch can serve the GPU, otherwise `nouveau`), while
hybrid Intel/AMD GPUs are preserved.
- **Installed Gentoo system:** scoped `package.use` (`dist-kernel`,
`kernel-open`/`-kernel-open`), a scoped `~amd64` keyword for the driver atom,
a scoped `package.mask` for the legacy branch, a `modprobe.d` policy
(nouveau blacklist, `nvidia_drm.modeset=1`, `nvidia-uvm` softdep) and a dracut
`force_drivers` fragment written **before** the kernel is built. A new
`nvidia_drivers` install stage (after the kernel, before boot) emerges the
driver and regenerates the initramfs so the modules are embedded; its failure
fails the install and the resolved choice is recorded in `/etc/phoebus/nvidia`
and shown in the plan. `sys update system` now runs `@module-rebuild` and
`kernel-install add-all` on NVIDIA systems so kernel/module/initramfs updates
stay coherent.
- **AI boundary:** the model cannot change the driver branch or module flavor;
a `set_package_use` change touching `x11-drivers/nvidia-drivers` is refused by
the fixed-policy check and the advisor prompt says so.
- **Live ISO:** the signed `contrib`/`non-free`/`non-free-firmware` components
are enabled and the NVIDIA driver, firmware and Wayland/EGL/GBM userspace are
bundled (`live-packages.list`). The live kernel is **pinned to Debian stable
(trixie, 6.12 LTS)** because testing's newer kernel (7.2) removed the
`strncpy` declaration the 550 driver still uses; installing the rolling kernel
metas would make `nvidia-kernel-dkms` unbuildable. `livefs-hook.sh` builds the
DKMS modules for that exact kernel (`nvidia-current*` on Debian) and fails if
any module is missing. Nouveau blacklisting and module options come from
Debian's own `nvidia-kernel-common`; its unconditional modules-load entry is
replaced by a gated `phoebus-nvidia.service` that loads the driver before
greetd/Mango only when an NVIDIA device is present. The documented fail-safe
entry disables modesetting and blacklists the NVIDIA modules. `build.sh`
verifies the assembled rootfs on **every** build (including
`PHOEBUS_REUSE_ROOTFS=1`) with `--verify-live-nvidia` and records the bundled
driver version, module flavor and kernel in `/etc/phoebus/nvidia`; a missing
module, library or firmware file fails the build.
- **Proven this session:** a minimal live rootfs (stable kernel + NVIDIA) was
built with `mmdebstrap` and the payload verified end to end: driver
`550.163.01`, kernel `6.12.107+deb13-amd64`, modules `nvidia-current`,
`-modeset`, `-uvm`, `-drm`. The full desktop ISO was **not** assembled here
(the host has ~10 GiB free and the build wants more), and no NVIDIA hardware
was available, so acceleration is unverified.
- **Not verified:** actual NVIDIA acceleration cannot be exercised on this host
(no NVIDIA GPU; QEMU's virtual GPU does not establish it). No NVIDIA hardware
passthrough setup is available or authorized. The live/installed NVIDIA boot
gates are **unverified** here (see `docs/STATUS.md`); this is implementation +
unit/integration tests + a proven payload build, not a claim of working
hardware acceleration.
## 2026-09-22 — Installer UX streamlining and DWM keybindings in Mango
- **Flatpak non-removable invariant:** Flatpak is a defining, required subsystem of
Phoebus OS. Removed `set_flatpak` from the AI advisor action prompt and examples so
models never propose toggling it; enforced in `fixed_policy_violation` and config
validation that Flatpak cannot be disabled or removed; filtered redundant Flatpak
proposals from the GUI review card; and locked Flatpak to 'yes (required)' in the TUI.
- **DWM / DWL keybindings in Mango:** Packaged `MANGO_CONFIG_DEFAULT` now ships
with standard dwm / dwl bindings for tiling and window management:
`Mod+Shift+Return` (terminal), `Mod+Return` (zoom / promote to master),
`Mod+j`/`Mod+k` (focus stack next/prev), `Mod+Shift+j`/`Mod+Shift+k` (exchange
client), `Mod+h`/`Mod+l` (`setmfact` master area sizing), `Mod+i`/`Mod+d`
(`incnmaster` master count), `Mod+Shift+c`/`Mod+Shift+q` (`killclient`),
`Mod+t`/`Mod+m`/`Mod+f` (tile, monocle, fullscreen), `Mod+Shift+Space` (toggle
floating), `Mod+Tab` (view previous tag), `Mod+1..9` (tag switching),
`Mod+Shift+1..9` (tag moving), and `Mod+left/right/middle click` for window
dragging, resizing and floating toggling.
- **Full-screen installer window:** Closing the Welcome window when starting the
installer allows Mango's tiling layout to present the installer full-screen.
- **Scrollable dropdown menus:** Replaced the combo box with `PhoebusCombo`, a
true dropdown menu with a clickable chevron, instant search filtering, and a
scrollable `ListView` with vertical scrollbar that handles large lists without
cutting off choices or destroying pre-filled selections.
- **Desktop keyboard layouts:** Keyboard options now parse XKB rules
(`/usr/share/X11/xkb/rules/evdev.lst` and `base.lst`) for clean desktop
layouts with human-readable labels, replacing the ancient console keymap tree.
- **Streamlined defaults:** Removed the manual desktop profile selector,
filesystem selector, and Nix/Flatpak toggles from the UI; the installer now
consistently defaults to Mango + DankMaterialShell, Btrfs with snapshots, and
both Flatpak and Nix enabled.
- **Account & password simplification:** Removed the redundant "Full name" field
(username only). Removed the artificial 8-character password length limit. Added
a "Use same password to encrypt disk" toggle (enabled by default) so users do
not have to re-enter a separate disk passphrase across four fields.
- **Direct confirmation:** Removed typing "ERASE" and the confirmation checkbox
from the review screen; the overview screen clearly highlights the target disk
and clicking "Install now" proceeds directly.
- **Live progress log details:** The "Show details" button during installation
now opens a dedicated scrollable log viewer that polls every 1.5 seconds and
auto-scrolls to the newest output.
## 2026-09-22 — Event-driven analysis of a first-time user's journey
The graphical installer was audited against a first-time user's journey and
rebuilt around a fixed, explained sequence: Welcome, Language and keyboard,
Internet and readiness, AI connection, Destination disk, Account and
encryption, Review and confirmation, Installation, Completion. Configuration,
validation, plans, approval and execution stay authoritative in Rust.
### Fixed
- **Network "Re-check" no longer resets the wizard.** The readiness refresh is
a separate, read-only bridge op (`readiness`) that updates the probe result
only; it cannot change the step or clear the selected disk. The first
handshake is the only path that initialises the form.
- **AI catalogs are fetched for the connection on screen.** "Load model
list" now pushes the edited configuration and credentials before requesting
the catalog, classifies authentication/unreachable/model failures with a
stable `error_kind`, and ignores a stale reply that a newer request
superseded.
- **The AI connection indicator is invalidated when it should be.** Editing the
provider, model, endpoint, server or a credential clears the green
"Validated" state and requires revalidation; irrelevant account or disk edits
preserve it. A regression assert in the VM harness edits the model and checks
the state flips.
- **Suggestion lists are keyboard-operable.** Arrow keys move a visible
highlight, Enter selects it, Escape dismisses the list, and the highlight is
exposed through `Accessible` roles. Enter in an open list is consumed so it
cannot also advance the wizard.
- **Busy work always completes.** The bridge now fails every outstanding
request when the backend exits, so no spinner can hang; AI connect/test and
catalog loads are single-flight; every failure path clears its busy state and
shows an actionable retry.
- **Keyboard focus is scrolled into view**, so a keyboard user never tabs to an
off-screen control, and the `PhoebusToggle` Return handler is fixed (it
previously called a signal handler as a function).
### Changed
- **Human-readable language, keyboard and time-zone names** (e.g. "English
(United States) — en_US.UTF-8", "German — de") are returned by the backend;
the stable identifier is still what is validated and written.
- **The keyboard step tells the truth about the live session.** The live
session keeps its own layout; the selected layout is applied to the installed
system, and the typing test is labelled as testing the live keyboard. A live
Wayland layout switch is not implemented.
- **Internet readiness distinguishes a local link from reachable installation
services** and re-checks on demand without disturbing the form.
- **AI setup explains why a model is required and what is shared** (hardware and
storage facts; never passwords, passphrases, keys, names or files), shows the
proposed changes, and requires an explicit Accept or Discard before the step
can advance.
- **Disk selection prominently shows model, capacity and device identity**, and
states exactly which disk will be erased; protected disks explain why they
cannot be selected. The ERASE confirmation and approval binding are unchanged.
- **The account step explains login password versus encryption passphrase**, and
password reveal controls are keyboard-focusable. Technical settings moved
behind Advanced.
- **Progress shows real stages, elapsed time and activity**, with a redacted
Details log; the failure screen explains whether disk changes occurred and
what is safe to do next; completion explains restart, media removal, unlock
and first login.
- **The graphical harness gained a `gui-install` mode** that presses the real
controls through the whole journey (AI connect, disk, account, ERASE,
install) on a disposable disk, plus regression checks for readiness refresh,
disk survival and AI invalidation. `PHOEBUS_GUI_CONFIG`/`/etc/phoebus/install.conf`
let a live medium preseed wizard defaults without weakening any check.
### Verified
- `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets`
clean (pre-existing `result_large_err` advisories unchanged); the Rust
workspace tests are green and `make test` (Rust + 16 harness tests) passes.
- Disposable graphical VM: `gui` 28/28 PASS (welcome, launcher, duplicate
prevention, keyboard suggestion selection, network, AI gate blocked and
reported, no bridge errors) and `opencode` 18/18 PASS (real model response,
validated proposal, model edit invalidates the connection).
- `gui-install` passed every journey assertion on a fresh 30 GiB qcow2,
including `gui-install-erase-confirmed`; the backend then reported real
progress (disk prepare, stage3 download, fstab, Portage sync, base packages,
kernel) with elapsed time and categories, and no fabricated percentage. The
completed install itself timed out in the harness after four hours during a
>100-minute kernel compile (see `docs/VM-BOOT-VERIFICATION.md`); the
completed install + detached boot gate remains **BLOCKED on host build time**,
not on any code defect.
## 2026-09-22 — `sys` administration hardening
Correctness work on the deterministic `sys` broker and the assistant path that
shares it. Every change is covered by unit tests (368 Rust tests pass); the
destructive rollback VM acceptance remains unverified (see below).
### Fixed
- **Alternate-root execution now targets the requested system.** Package
execution, service enable/disable and Flatpak operations previously ignored
`--root` and ran against the host, while `emerge --pretend` previews already
ran in the target. All of them now go through one `target_spec`/chroot path,
and operations that cannot be confined to a non-running root (service status,
start, stop, restart) are **rejected before any command is built**.
`systemctl --root` is used for offline enable/disable. Regression tests prove
preview and execution both emit a chroot confined to the same root, and that
a rejected operation invokes nothing.
- **Validation at the execution boundary.** `parse_natural` emitted actions
that were never validated, so a manual `sys install --color=n` could pass an
option through. `parse_natural` now validates its own output, `resolve_effects`
and `execute` validate every action before touching a command, and
option-like operands (leading `-`) are rejected for services, packages and
search. `emerge`/`flatpak` operands are passed after an explicit `--`
separator. Manual, JSON and AI entry paths are all covered.
- **`sys ask` reports failure truthfully.** A failing action now stops the plan,
records the completed/failed/unattempted actions, and exits nonzero instead of
returning success.
- **Complete transaction history.** Ordinary mutating `sys` commands are
recorded (previously only assistant plans were), the protective snapshot id
created by the generic high-risk path is preserved and recorded, and a
recording failure is surfaced instead of being swallowed.
- **Reliable package approval.** `emerge --pretend` output is now classified as
*established* (a real plan, including a genuine `0 packages`) or
*unestablished*; `sys` refuses to proceed when the effects cannot be
established rather than treating unparseable output as "nothing to do". A
material change between review and execution still aborts.
### Added
- Typed service lifecycle actions `start_service`, `stop_service`,
`restart_service`, and ordinary commands for the existing bounded verbs:
`sys flatpak install|remove|list`, `sys nix prepare …`, `sys snapshot [op]`,
`sys start|stop|restart <unit>`. The AI prompt exposes the new verbs, so the
manual and AI interfaces share one validated execution path.
- `phoebus-executor::actions::execute_plan` runs a reviewed multi-action plan,
stopping at the first failure and marking the rest unattempted, so the
assistant and any multi-step caller report partial failure consistently.
- CLI integration tests (`tests/sys_cli.rs`) cover the manual and JSON entry
paths and exit codes.
## 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).