feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations
Some checks are pending
ci / test (push) Waiting to run

- Mango + DankMaterialShell desktop option (desktop.profile = "mango") through
  the GURU overlay with scoped ~amd64 keywords, a sealed session entry point and
  a dwl fallback session (ADR 0009).
- Coherent rollback/recovery: coordinated @ + @var snapshots, fstab and BLS
  root-subvolume rewriting, matching-kernel selection, snapshot recovery entry,
  retention/space gates and sys undo (ADR 0007).
- Installed assistant (sys ask) with an OS-level systemd sandbox boundary and
  fail-closed typed plans; resolved package effects bound to approval.
- Nix build isolation enforced (sandbox, no fallback) plus lifecycle/cleanup.
- Desktop helpers (menu/lock/idle), transaction log, release gates with atomic
  publish and signing helpers, and a Debian-Live appliance VM harness.
This commit is contained in:
Phoebus 2026-09-21 03:46:52 -07:00
parent b12b2768b4
commit 25f7381b4a
45 changed files with 5808 additions and 181 deletions

View file

@ -39,6 +39,10 @@ Pure, non-privileged logic with no external commands except reading `/proc`,
- `target` — `TargetRoot`, which rejects absolute paths and `..` traversal.
- `secret` — `SecretString` (redacted `Debug`, zeroized on drop) + `Redactor`.
- `snapshot` — deterministic snapshot names + TOML transaction history.
- `boot` — BLS entry parse/render and root-subvolume selection for rollback.
- `rollback` — rollback state machine, retention and mount/fstab planners.
- `effects` — parse `emerge --pretend` into resolved effects + plan digest.
- `transaction` — the user-queryable log of executed actions and outcomes.
- `action` — closed `SystemAction` schema and a small deterministic parser.
- `update` — preparation policy and real Portage argument builders.
@ -57,17 +61,24 @@ The only crate that runs privileged commands.
`desktop` — the install backend, mirroring the proven order.
- `probe` — read-only hardware and disk discovery.
- `snapshot`, `update`, `admin`, `actions` — post-install foundations.
- `rollback` — coordinated root/`var`/fstab/BLS rollback (ADR 0007).
- `nix` — pinned Nix bootstrap, sandboxed build config, lifecycle and cleanup.
- `sandbox` — the hardened `systemd-run` boundary for model execution.
- `transaction` — persists the transaction log into the target.
### phoebus-ai
- Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell).
- `assistant` — the installed conversational plan schema (`AssistantPlan`) and
its fail-closed parser; the model proposes the same actions `sys` executes.
- `privacy` — `PrivacyPolicy` + `ContextBundle`; forbidden-path checks. The
collector in `phoebus-executor::admin` only reads system sources.
### phoebus-installer
- `orchestrate` — `Installer` runs the plan stages and stops on first failure.
- `release` — `ReleaseManifest` create/verify, assemble command.
- `release` — `ReleaseManifest` create/verify, candidate gates, atomic publish
and signing command helpers.
- Binaries: `phoebus-installer`, `sys`, `phoebus-release`.
## Safety model
@ -81,7 +92,40 @@ The only crate that runs privileged commands.
- Secrets travel over stdin only and are registered with the redactor before
any logging. They never enter the config.
- The AI cannot execute; it can only propose typed changes that the backend
validates and the user approves.
validates and the user approves. The assistant's model call additionally runs
inside an unprivileged, hardened `systemd-run` unit (`sandbox`), so the
boundary is enforced by the OS and not only by the schema.
- Approval is bound to the reviewed resolved plan: package effects are resolved
again before execution and a material change aborts.
## Rollback and recovery
A recovery point is a snapshot set: `@` and the separate `@var` (Portage state)
together; `/home` is excluded. Rollback creates a writable root generation,
rewrites `subvol=` in both the restored root's fstab and the BLS entry options
(the explicit argument overrides the Btrfs default), selects a kernel entry
whose modules match the restored root, and writes previous/recovery entries.
See ADR 0007.
## Desktop profiles
Two sessions are generated, and each starts exactly one compositor and one set
of shell services:
- **dwl** (`desktop.profile = "dwl"`): the proven session — dwl, waybar, wofi,
mako, swaybg, swayidle, swaylock, the polkit agent. Entry point
`/usr/local/bin/phoebus-session`, session file `phoebus-dwl.desktop`.
- **Mango + DankMaterialShell** (`desktop.profile = "mango"`): `gui-wm/mangowm`
plus the DMS shell (panel, launcher, notifications, lock, idle, audio/network/
Bluetooth/display controls) from the GURU overlay. Entry point
`/usr/local/bin/phoebus-session-mango`, session file `phoebus-mango.desktop`.
The dwl session is installed alongside as a fallback. The Mango session never
starts the dwl helpers. See ADR 0009.
`desktop.profile` selects both the Gentoo desktop/systemd profile and the
package set; the plan shows the selected session before installation, and the
installer writes both session entry points for the Mango profile so the user can
return to dwl.
## Installation order (do not regress)
@ -105,13 +149,17 @@ the actual execution, so the UI cannot diverge from the backend.
## Post-install foundations
- **Snapshots**: read-only Btrfs snapshots under `/.snapshots`, recorded in a
TOML history. `/home` is intentionally not snapshotted by default.
TOML history. A snapshot set captures `@` and the separate `@var`; `/home` is
intentionally not snapshotted so user documents survive a rollback.
- **Rollback**: `sys undo` restores a committed snapshot as the next boot root
with coordinated fstab, BLS and kernel selection (ADR 0007); a persisted state
file makes an interrupted rollback resumable.
- **Background updates**: `emerge --fetchonly` then `--buildpkgonly` stage
distfiles and reusable local binary packages without installing; activation
stays explicit.
- **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel`
(optimized), dracut initramfs, systemd-boot BLS entries, plus a recovery
entry booting `rescue.target`.
(optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based
recovery entry that does not depend on the live root.
## Extension points

View file

@ -7,6 +7,72 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased
### 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

View file

@ -76,6 +76,45 @@ python3 installer/tests/vm/serial-driver.py boot
`installer/tests/vm/run-vm.sh` launches an interactive VM instead.
### Debian-Live appliance harness
The appliance ISO (`installer/live/build.sh`) boots its own GRUB, so it has its
own driver. It is the fastest path to a full install on hosts where the Gentoo
LiveGUI ISO is unavailable:
```sh
cd installer-rs
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
cd ..
BASE_ISO=/path/to/debian-live-standard.iso installer/live/build.sh
# Serve the stage3, config and 0600 secrets (host 10.0.2.2:8000):
mkdir -p /path/serve && cd /path/serve
cp /path/to/stage3-amd64-systemd-*.tar.xz stage3.tar.xz && sha256sum stage3.tar.xz
cp /path/to/installer/tests/vm/appliance-guest.sh .
cp /path/to/installer/tests/vm/appliance-test.conf.example test.conf # set STAGE3_SHA256
printf 'phoebus-luks-test' > luks.pw && chmod 600 luks.pw
printf 'phoebus-user-test' > user.pw && chmod 600 user.pw
python3 -m http.server 8000 --bind 127.0.0.1
qemu-img create -f qcow2 /path/target.qcow2 24G
cp /usr/share/OVMF/OVMF_VARS_4M.fd /path/OVMF_VARS.fd
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/path/OVMF_VARS.fd \
DISK=/path/target.qcow2 \
ISO=/path/to/installer/live/phoebus-installer-amd64.iso \
python3 installer/tests/vm/appliance-driver.py install
# Detached boot (no ISO):
DISK=/path/target.qcow2 OVMF_CODE=... OVMF_VARS=... \
python3 installer/tests/vm/appliance-driver.py boot
```
`INSTALL_TIMEOUT` and `CHECKS_TIMEOUT` bound the long steps. A full base install
still fetches and merges the Gentoo stage3 and base packages, so it takes tens
of minutes.
### Verifying the graphical stack
The serial-only VM has no logind seat, so wlroots' DRM backend cannot start
@ -88,7 +127,9 @@ grim /tmp/shot.png # proves the compositor renders
```
On a real machine the installer writes `/usr/local/bin/phoebus-session`
(dwl + waybar + mako + swaybg + the polkit agent).
(dwl + waybar + mako + swaybg + swayidle + the polkit agent) and the helpers
`phoebus-menu` (wofi drun launcher / power menu), `phoebus-lock` (swaylock) and
`phoebus-idle` (swayidle).
### Physical VT / real-seat check (needs a person)
@ -107,17 +148,50 @@ Check, in order:
log a failed Wayland connection).
3. Open a terminal: `kitty`. Run an X11 app to exercise XWayland (e.g.
`xterm` or `env -u WAYLAND_DISPLAY kitty` if no X app is installed).
4. Trigger a privilege prompt (e.g. `pkexec true` or a polkit-gnome dialog) and
4. Run `phoebus-menu` and confirm the application launcher (wofi) appears; run
`phoebus-menu --power` and confirm lock/suspend/log out/reboot/shut down are
offered.
5. Check Waybar shows network and audio controls; click the power module.
6. Run `phoebus-lock` and confirm the session locks (and unlocks).
7. Trigger a privilege prompt (e.g. `pkexec true` or a polkit-gnome dialog) and
confirm the authentication agent appears.
5. Log out (`Mod+Shift+e` for dwl). Confirm `waybar`, `mako`, `swaybg` and the
polkit agent are gone (`pgrep -a 'waybar|mako|swaybg|polkit-gnome'` prints
nothing) and that the session returns to the VT login.
6. Reboot and confirm the same result.
8. Log out (`Mod+Shift+e` for dwl). Confirm `waybar`, `mako`, `swaybg`,
`swayidle` and the polkit agent are gone
(`pgrep -a 'waybar|mako|swaybg|swayidle|polkit-gnome'` prints nothing) and
that the session returns to the VT login.
9. Reboot and confirm the same result.
Record the result (date, kernel, GPU, pass/fail per step) in
`docs/VM-BOOT-VERIFICATION.md`. A headless wlroots session is not physical-seat
verification.
### Mango + DankMaterialShell
Select the profile with `DESKTOP_PROFILE='mango'` (or `[desktop] profile =
"mango"`). The installer writes GURU's `repos.conf`, installs `dev-vcs/git`,
syncs the overlay with `emaint sync -r guru`, and installs Mango, DMS,
Quickshell and scenefx with **scoped** `~amd64` keywords. To return to dwl,
select `desktop.profile = "dwl"` (the dwl session and the dwl package set are
also installed by the Mango profile as a fallback, so both session entries exist
at the login screen).
Session entry points:
```sh
/usr/local/bin/phoebus-session-mango # Mango + DMS
/usr/local/bin/phoebus-session # dwl fallback
```
To inspect the resolved effect of the transition before installing, use
`emerge --pretend gui-wm/mangowm gui-apps/dankmaterialshell` and review the
`~amd64` list; add only reviewed atoms to
`/etc/portage/package.accept_keywords/phoebus`. Never run a global
`~amd64` switch.
**Acceptance is a graphical VM with a real seat.** Headless compositor tests do
not qualify. The gates are listed in `docs/VM-BOOT-VERIFICATION.md`; until they
pass, Mango is selectable but not the default.
## Inspecting the reference ISO without booting
```sh

View file

@ -3,57 +3,62 @@
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
- **Last updated:** commit `b2f5181` (2026-09-20)
- **Current focus:** four workstreams — AI-assisted install guidance, desktop
session reliability, signed-binary reuse, and snapshots/safe updates.
- **Last updated:** commit `b12b276` + this session (2026-09-21)
- **Current focus:** coherent rollback/recovery, the installed AI assistant with
an OS-level sandbox, Nix build isolation, resolved package effects, desktop
completeness, and release gates. A new **Mango + DankMaterialShell** desktop
profile (`desktop.profile = "mango"`, ADR 0009) is implemented and selectable
with a dwl fallback; it is **not yet graphical-VM verified** and is not the
default.
- **Last verified:** static Rust binary install + detached boot
(`docs/VM-BOOT-VERIFICATION.md`); in this session additionally: the Debian-Live
appliance ISO (firmware boot, full install, detached boot), the mandatory-AI
gate, desktop portals, and the **built-in Nix lane** (`nix-daemon` active,
`nix shell nixpkgs#hello` -> `Hello, world!`); `sys` snapshot/history and
update preparation on an installed Btrfs VM; and the AI guided path by
fixtures.
(`docs/VM-BOOT-VERIFICATION.md`); in this session additionally: a fresh
Debian-Live appliance install on a disposable qcow2 (recorded in
`docs/VM-BOOT-VERIFICATION.md` when it completes), plus unit/functional tests
for rollback, effects, transactions, the assistant schema, the sandbox argv,
and the desktop helpers.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Re-verify the finalize `sync`** (build `3ba913ba`): the Nix lane is
VM-verified (`nix-daemon` active, `nix shell` works) and on by default, but
the one-line durability fix that should make `/usr/local/bin/phoebus-session`
survive a forced poweroff was not re-run end to end (host root was ~98% full
and the base emerge became pathologically slow). A binary Nix ebuild was
ruled out (upstream has no `DESTDIR`).
2. **Physical-seat desktop**: run `/usr/local/bin/phoebus-session` on a real VT
and check kitty, XWayland, the polkit agent, logout/reap and reboot
(`docs/DEVELOPMENT.md` -> "Physical VT / real-seat check").
3. **Matching signed binhost**: the official Gentoo binhost is OpenRC/hardened,
so systemd/desktop packages compile from source. Publish (or point at) a
systemd/desktop binhost to raise binary reuse; verify with `emerge -pv`.
4. **Rollback gate**: implement Btrfs default-subvolume + ESP handling and pass
a detached-boot test before exposing `sys undo`.
5. **Live AI provider call**: exercise DeepSeek/OpenAI/local with a real 0600
key file; the path is currently fixture-verified only.
6. **Desktop graphical login**: exercise a real logind seat.
1. **Rollback VM acceptance**: deliberately break an update in the disposable
VM, run `sys undo`, reboot detached, verify package-state consistency
(`/var/db/pkg` matches `/`), then boot the snapshot recovery entry with no
network or model (ADR 0007).
2. **Live AI provider call**: exercise `sys ask` with a real 0600 key file and
confirm the `systemd-run` sandbox properties apply; the path is
fixture-verified only.
3. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
4. **Matching signed binhost / binary strategy**: keep the official binhost for
matching USE and Flatpak/Nix elsewhere; do not publish a private binhost
(ADR 0006). Verify with `emerge -pv`.
5. **Release gates on a CI runner**: run `phoebus-release gates --execute` and
`phoebus-release publish` once a runner exists; no gate has executed.
## Known blockers / risks
- No live DeepSeek/OpenAI call has been made (no key in this environment).
- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml`
only runs once one is registered.
- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml` only
runs once one is registered.
- Desktop graphical login / physical seat has not been exercised; the serial
VM has no logind seat.
- NVIDIA is not verified on hardware.
- Rollback is not implemented (by design, gated).
- Rollback and the AI sandbox are implemented and unit-tested but not
VM-verified.
## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy installed.
- Reference ISO is `livegui-amd64-20260913T163055Z.iso` (gitignored).
- Forgejo token for API tasks: `~/.config/phoebus/forgejo.token` (0600).
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`); the appliance ISO builds without root.
- The appliance harness is `installer/tests/vm/appliance-driver.py` +
`appliance-guest.sh` + `appliance-test.conf.example`; serve the stage3,
config and 0600 secret files over `python3 -m http.server 8000`.
- The VM harness disks are disposable qcow2 files on `/` (not `/tmp`, which is
a small tmpfs on the dev host); never point `DISK` at `/dev/*`.
- The VM harness honours `CHECKS_TIMEOUT` for long guest checks.
a small tmpfs); never point `DISK` at `/dev/*`.
- The VM harness honours `CHECKS_TIMEOUT` / `INSTALL_TIMEOUT` for long runs.
## Definition of a good stopping point

View file

@ -10,16 +10,16 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| 3 | Port the deterministic core | Done | `phoebus-core` (config, plan, policy, validation, models) |
| 4 | Port the destructive backend | Done | `phoebus-executor` (storage, LUKS2, Btrfs, Portage, boot, users, services) |
| 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s |
| 6 | Finish the desktop | Partial | session script race-free + polkit + helper cleanup (functional test); headless compositor verified; physical seat + interactive login pending |
| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; no app installed yet |
| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries) |
| 6 | Finish the desktop | Partial | dwl helpers, lock, idle/suspend and Waybar controls added; Mango + DankMaterialShell profile added via GURU (selectable, dwl fallback); graphical-VM verification of both sessions pending |
| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; bounded typed `flatpak_*` actions added; no app installed yet |
| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries); resolved-effect previews added |
| 9 | Background update preparation | Partial | distfile fetch VM-verified; `--buildpkgonly` skipped while deps need merging (recorded Ready); activation explicit |
| 10 | Snapshots / rollback | Partial | snapshot create + history VM-verified on Btrfs; rollback not implemented |
| 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary + guided DeepSeek/OpenAI proposal review; OS sandbox not implemented |
| 12 | `sys` operations | Partial | history, enable/disable, inspect, install, prepare-updates VM-verified |
| 10 | Snapshots / rollback | Partial | snapshot sets + history VM-verified on Btrfs; coordinated rollback, `sys undo`, recovery entry, retention and free-space gate implemented + unit-tested; destructive VM acceptance test pending |
| 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary + guided proposal review + OS-level sandbox (systemd-run hardening) + approval-bound resolved effects; live call/sandbox not VM-verified |
| 12 | `sys` operations | Partial | history, enable/disable, inspect, install, prepare-updates VM-verified; `undo`, `undo status`, `ask` added (unit-tested, VM gate pending) |
| 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists |
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; no scheduling/publish/smoke test |
| 15 | Recovery environment | Later | recovery BLS entry generated; full recovery image not built |
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; release gates, atomic publish and signing helpers added; no CI runner has executed a gate |
| 15 | Recovery environment | Later | recovery BLS entry generated; snapshot-based recovery entry written at install; full recovery image not built |
| — | Rust TUI | Partial | ratatui UI with plan/ERASE and AI provider selection; not yet the default on all paths |
| — | AI-guided install optimization | Partial | DeepSeek/OpenAI/local providers, evidence-gated typed review, mandatory at install with `--no-ai` break-glass; fixture-verified, no live call |
| — | Nix as a built-in second lane | Partial | pinned-release bootstrap; `nix-daemon` active and `nix shell nixpkgs#hello` VM-verified; on by default |
@ -28,16 +28,22 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
## Immediate next steps
1. **Physical-seat desktop**: run `phoebus-session`/dwl on a real VT (or a
`seatd`-backed session) and verify kitty, wofi, XWayland, the polkit agent,
logout and reboot interactively (`docs/DEVELOPMENT.md`).
2. **Desktop binary strategy**: match the desktop USE set to a signed binhost
(or publish one) so desktop installs stop compiling ~26 minutes of packages.
The official binhost is OpenRC/hardened; a systemd/desktop host is needed.
3. **Rollback as a safety gate**: implement Btrfs default-subvolume + ESP
handling and pass a detached-boot test before exposing `sys undo`
(snapshot/history/prepare-updates are now VM-verified).
4. **Live AI provider call**: exercise DeepSeek/OpenAI with a real 0600 key
file; the guided path is currently fixture-verified only.
`seatd`-backed session) and verify kitty, wofi, `phoebus-menu`,
`phoebus-idle`, the polkit agent, logout and reboot interactively
(`docs/DEVELOPMENT.md`).
2. **Mango + DankMaterialShell acceptance**: install the `mango` profile in a
graphical, seat-providing VM and run the gates in
`docs/VM-BOOT-VERIFICATION.md`; only then consider promoting it to the
default desktop. The profile is selectable now (ADR 0009).
3. **Rollback VM acceptance**: deliberately break an update in the disposable
VM, run `sys undo`, reboot detached, verify package-state consistency, then
boot the recovery entry with no network or model (ADR 0007).
4. **Binary strategy**: keep the official signed binhost for packages whose USE
matches and use Flatpak/Nix for other binaries; do not publish a private
Gentoo binhost (ADR 0006). Verify with `emerge -pv` and record reuse.
5. **Live AI provider call**: exercise `sys ask` and the installer guided path
with a real 0600 key file; the path is currently fixture-verified only, and
the `systemd-run` sandbox is not yet VM-verified.
## Later

View file

@ -63,11 +63,22 @@ on the install path (Bash migration Phase 2, see
| Package policy + measured history | yes | yes | yes (326 entries) | no |
| Background update preparation | yes | yes | yes (fetch; buildpkgonly skipped) | no |
| Btrfs snapshots + history | yes | yes | yes | no |
| Btrfs rollback | no | no | no | no |
| Coordinated snapshot sets (`@` + `@var`) | yes | yes | no | no |
| Btrfs rollback (`sys undo`) | yes | yes | no | no |
| Recovery/known-good BLS entry | yes | yes | no | no |
| Snapshot retention + free-space gate | yes | yes | no | no |
| AI typed proposals + evidence review | yes | yes | fixture end-to-end | n/a |
| AI guided install (DeepSeek/OpenAI) | yes | yes | fixture path only (no live call) | n/a |
| AI privacy boundary (facts only) | yes | yes | no | n/a |
| AI OS sandbox | no | no | no | no |
| AI OS sandbox (systemd hardened unit) | yes | yes | no | no |
| Installed assistant (`sys ask`) | yes | yes | fixture path only (no live call) | n/a |
| Resolved package effects + approval binding | yes | yes | no | n/a |
| Transaction log | yes | yes | no | no |
| Flatpak/Nix bounded typed actions | yes | yes | no | no |
| Desktop session helpers (menu/lock/idle) | yes | yes | functional test (stubs) | no |
| Mango + DankMaterialShell profile | yes | yes | no (graphical VM gate pending) | no |
| GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no |
| Release gates + atomic publish | yes | yes | no | n/a |
| `sys` verbs | yes | yes | yes | no |
| OpenCode pinned bootstrap | yes | yes | no | n/a |
| Release manifest/verify | yes | yes | no | n/a |
@ -85,10 +96,27 @@ on the install path (Bash migration Phase 2, see
- **NVIDIA** is architecturally allowed but not verified on hardware.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **Rollback** is not implemented; snapshots and history are.
- **AI sandbox** is not enforced; only typed actions and the privacy boundary.
- **Release automation** stops at manifest/verify; no scheduler, smoke test,
signing or atomic publish.
- **Rollback** is implemented and unit-tested end to end at the command/text
layer (snapshot sets, root/var generation, fstab and BLS rewriting, kernel
selection, interruption resume, retention, free-space gate), but the
destructive VM acceptance test (deliberately broken update -> `sys undo` ->
detached reboot -> package-state check -> recovery with no network/model) has
not been run. `sys undo` is present; treat VM verification as the gate before
relying on it.
- **Mango + DankMaterialShell** is implemented as `desktop.profile = "mango"`
(Mango 0.17.2, DMS 1.5.3, Quickshell 0.3.1, scenefx 0.5 via the GURU overlay),
with a dwl fallback session and scoped `~amd64` keywords. It has not been
installed or booted in a graphical VM: no build, no seat, no interactive
verification. It is therefore **selectable, not default**, and no desktop
stability is claimed. The exact gates are listed in
`docs/VM-BOOT-VERIFICATION.md`.
- **AI sandbox** is implemented (`systemd-run` hardening properties, tested at
the argv level) and fails closed without `systemd-run`; it has not been
exercised in a VM. Only typed actions and the privacy boundary were previously
enforced.
- **Release automation** now has gates, a report, atomic publish and signing
command helpers, but no gate has been executed by a configured CI runner; the
report records unexecuted gates as `NotRun`.
- The desktop transaction compiles heavily because desktop USE does not match
the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM).
The official Gentoo binhost is OpenRC/hardened, so a systemd system can only
@ -100,5 +128,6 @@ on the install path (Bash migration Phase 2, see
key.
- The installer rebuilds `sys-apps/systemd` from source because
boot/policykit/cryptsetup USE differ from the binhost.
- `sys undo` is intentionally not implemented: rollback needs default-subvolume
and ESP handling plus a detached-boot test, which is a separate safety gate.
- `sys undo` is implemented with the default-subvolume, fstab, kernel-cmdline
and BLS handling described in ADR 0007; its destructive VM acceptance test is
the remaining safety gate.

View file

@ -347,6 +347,46 @@ never configuration.
been re-run end to end (host disk pressure). Until it is, treat the session
script as **unverified** in the shipped ISO.
## Mango + DankMaterialShell acceptance (NOT RUN)
The `mango` profile (ADR 0009) is implemented and source-tested but has not been
installed or booted. These gates must pass in a **graphical, seat-providing**
disposable VM before the profile is promoted to default. Headless wlroots tests
do not count.
Prerequisites: the `mango` install needs the GURU overlay to sync (git) and
Quickshell/DMS/scenefx to compile; the base install alone is tens of minutes.
1. Fresh install with `DESKTOP_PROFILE='mango'` reaches `systemctl
is-system-running = running` with 0 failed units; `emerge --pretend` shows
only the reviewed `~amd64` atoms.
2. Detached encrypted boot; LUKS unlock; login on a real seat.
3. `phoebus-mango.desktop` starts the session; exactly one compositor (mango),
one shell (dms), one lock/idle (DMS) and one polkit agent are running; no
waybar/mako/swaybg/swayidle/swaylock processes.
4. Panel, launcher (Mod+Space), notifications, tray, and the DMS settings panel
work; the shortcut guide matches the packaged config.
5. Audio output/input selection, volume, mic mute (WirePlumber); network and
Bluetooth controls from the panel.
6. Lock (Mod+Alt+L) and unlock; idle lock/suspend; repeated suspend/resume.
7. Display configuration/scaling and a second monitor if the VM supports one.
8. Clipboard history (Mod+V), screenshots, kitty terminal, file manager, and
`phoebus-assistant` opening `sys ask` (no model required for deterministic
`sys`).
9. An actual Flatpak app: launch, file chooser, and portal screen sharing.
10. Logout reaps DMS and session processes without touching the dwl fallback;
reboot; then boot the `phoebus-dwl.desktop` session and confirm it still
works.
11. Shell-failure handling: kill `dms` and confirm the compositor keeps running
and locking still locks; restart the shell without losing windows.
12. Upgrade from an existing dwl install keeps user configuration
(`~/.config/mango/config.conf`, DMS fragments, `~/.config/waybar`) intact.
13. Idle memory/CPU and startup time measured against the dwl session under
comparable conditions.
Until this list is recorded here with results, the Mango profile is selectable
but not default, and no desktop stability is claimed.
## Known remaining work
- The graphical session was verified with the **headless** wlroots backend

View file

@ -1,6 +1,6 @@
# ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in)
- **Status:** Proposed
- **Status:** Accepted
- **Date:** 2026-09-20
## Context
@ -133,11 +133,35 @@ drivers → Portage only; GUI → Flatpak; per-project/dev → Nix.
## Next steps
1. Finish Flatpak integration: `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends),
a documented app-install path, desktop integration.
2. Author the Phoebus overlay `sys-apps/nix` ebuild (+ `nix-daemon.service`),
install it from the installer, and verify in the disposable VM that a Nix
dev environment works and the base system still boots without using it.
3. Add the `CreateDevEnvironment` typed action with a bounded input set and
tests.
4. Only then consider a thin `sys`-level source chooser (not a general `pkg`).
1. Finish Flatpak integration: a documented app-install path and desktop
integration. The `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends) are
installed, bounded `flatpak_install`/`flatpak_remove`/`flatpak_list` typed
actions exist, and flathub is configured; an actual app install and the file
chooser/screencast portals still need VM verification.
2. Author the Phoebus overlay `sys-apps/nix` ebuild (a bootstrap-style ebuild;
see ADR 0008) so `emerge` owns installation, upgrades and removal. Until it
ships, the installer provisions the same lifecycle directly.
3. `CreateDevEnvironment`/`nix_prepare` bounded typed actions: `nix_prepare` is
implemented; a richer per-project environment action remains.
4. Consider a thin `sys`-level source chooser (not a general `pkg`).
## Binary strategy (reconciled)
The roadmap once proposed publishing a private signed binhost to stop the
desktop set compiling. That conflicts with the rejection of a private/third-party
binhost above and would add infrastructure and trust obligations silently.
The sustainable strategy is:
- **Portage source or the official signed Gentoo binhost**, whichever matches the
package's USE. Signature verification stays on (ADR 0004); no private binhost
is maintained.
- **Flatpak** for sandboxed GUI applications that the official binhost cannot
serve (Chromium, Spotify, Electron).
- **Nix** for developer tools, alternate versions and reproducible per-project
environments (ADR 0008).
Packages the official OpenRC/hardened binhost cannot satisfy (systemd, polkit,
NetworkManager, a desktop USE set) compile from source. That cost is accepted
and measured (`docs/STATUS.md` records the compile times), not hidden behind a
new binhost.

View file

@ -0,0 +1,101 @@
# ADR 0007: Coherent rollback and recovery
- **Status:** Accepted
- **Date:** 2026-09-21
## Context
Btrfs snapshots and transaction history existed, but rollback was deliberately
unimplemented. The proven layout separates the filesystems that must move
together:
```
GPT: 1 GiB FAT32 ESP (mounted /efi)
LUKS2 -> Btrfs: @ / @home /home @var /var @snapshots /.snapshots @swap /swap
```
Three facts make a naive rollback wrong:
1. **`/var` is a separate subvolume.** The Portage package database
(`/var/db/pkg`), Portage state (`/var/lib/portage`), the update state and the
snapshot/transaction history all live in `@var`. Restoring `@` alone leaves
the package manager describing packages that do not exist in the restored
root.
2. **The kernel command line carries an explicit root subvolume.**
`rootflags=subvol=@` overrides the Btrfs default subvolume, so changing the
default alone does not change what boots.
3. **The kernel and initramfs live on the ESP, which is not snapshotted.**
A restored older root has older `/lib/modules`; it must boot a kernel whose
modules match, or it will fail to load drivers.
The ESP also holds the BLS entries, so a recovery entry that reuses the live
root's kernel/options still depends on the root being healthy.
## Decision
Rollback is a **coordinated** operation over four things, implemented in
`phoebus-executor::rollback` and planned by `phoebus-core::rollback`:
1. **Snapshot set.** A recovery point captures `@` *and* the separately mounted
`@var` under one timestamp/operation name. `/home` is intentionally excluded
so rollback never discards user documents. `/nix` is inside `@`, so the Nix
store rolls back with the OS package state (consistent by construction).
2. **Root generation.** Rollback creates a *writable* clone of the chosen
snapshot (`@restore-<utc>`) and, when present, `@varrestore-<utc>`. The
running root is preserved by the pre-rollback snapshot; the previous root is
also offered as a boot entry.
3. **Boot arguments, in both places.** The restored root's `/etc/fstab` is
rewritten to mount `subvol=<new root>` and `subvol=<new var>`, *and* the BLS
entries are rewritten (`rootflags=subvol=<new root>`). The Btrfs default
subvolume is set to match, as a fallback for a mount without an argument.
4. **Kernel/initramfs pairing.** The restored root's `/lib/modules` versions are
used to select the newest BLS entry with matching modules. A "Phoebus OS
(previous)" entry and a "Phoebus Recovery" entry that boots the chosen
snapshot directly into `rescue.target` are written, so recovery does not
depend on the live root.
### State machine and interruption safety
`var/lib/phoebus/rollback-state.toml` records `Idle | Planned | Activated |
Verified | Failed`. The safety snapshot is taken first; boot entries are
switched last; a `sync` runs before completion. An interruption therefore leaves
the system booting a known root, and re-running resumes (an already-staged
restored root is detected and reused). `sys undo status` promotes `Activated`
to `Verified` once the restored subvolume is the running root.
### Retention and space
Retention keeps the newest `DEFAULT_KEEP_SNAPSHOTS` (8) committed snapshots and
never prunes the newest, an in-flight rollback target, or `Created`/`Failed`
records. Rollback refuses to start unless at least 1 GiB is free on the target.
### Exposure
`sys undo` is the only acceptance test for a rollback. `sys undo` restores the
newest committed snapshot; `sys undo <id>` selects one; `sys undo status`
reports state. It requires root and a reviewed typed action, like every other
high-risk mutation.
## Consequences
- More subvolumes accumulate (`@restore-*`, `@varrestore-*`); retention bounds
them and the operator can delete them explicitly.
- A rollback is a reboot-level operation; it changes the *next* boot, not the
running system. This is deliberate: swapping the mounted root in place is not
safe.
- The path is unit-tested for the command sequence, fstab/boot-entry rewriting,
kernel selection, interruption resume and retention. End-to-end VM
verification (broken update, rollback, detached boot, package-state check) is
the acceptance gate recorded in `docs/STATUS.md`.
## Alternatives rejected
- **Changing only the Btrfs default subvolume.** Rejected: the explicit
`rootflags=subvol=` wins, so this does not boot the restored root.
- **Renaming the mounted root subvolume.** Rejected: unsafe while it is the live
root.
- **Snapshotting the ESP.** Impossible (vfat, not Btrfs); handled instead by
selecting a matching kernel entry and keeping a known-good entry.

View file

@ -0,0 +1,93 @@
# ADR 0008: Nix lifecycle, build isolation, and packaging
- **Status:** Accepted
- **Date:** 2026-09-21
## Context
The first Nix bootstrap wrote `sandbox = false`, and the lifecycle (upgrade,
removal, store cleanup) was undefined. ADR 0006 claimed a normal binary ebuild
is impossible because the upstream installer hardcodes `/nix`, calls `sudo` and
uses `nix-store --load-db` with no `DESTDIR`. That claim was re-examined rather
than assumed.
## Decision
### Build isolation is on and does not silently fall back
`/etc/nix/nix.conf` now sets:
```
sandbox = true
sandbox-fallback = false
auto-optimise-store = true
min-free = 1073741824
max-free = 10737418240
```
The Nix sandbox uses Linux user namespaces. `sandbox-fallback = false` means a
build that cannot be sandboxed fails instead of silently building with host
access. This is the same principle as "never weaken a protection for
convenience": a build-time sandbox that can be transparently disabled provides
no guarantee. The Phoebus kernel (distribution kernel plus the conservative
fragments) includes `CONFIG_USER_NS`.
`min-free`/`max-free` bound the store so `/nix` cannot fill the root
filesystem; `auto-optimise-store` deduplicates.
### Store cleanup and rollback interaction
- `/nix` lives inside `@`, so a system rollback restores the store together with
the OS package state. This is intended: the Nix store is OS state.
- Garbage collection is explicit (`nix-store --gc`, bounded by `min-free`/
`max-free`), never automatic on a timer.
- Removing Nix removes the daemon units and profile wiring; purging the store is
a separate, explicit choice, because it also removes user environments.
### Portage-managed lifecycle
The requirement is that Portage owns Nix: installation, upgrades, daemon
integration and removal. The upstream installer's lack of `DESTDIR` blocks a
*conventional binary ebuild*, but it does **not** block an ebuild that performs
the same bootstrap the installer performs:
- `src_unpack` fetches the pinned, SHA-256-verified release tarball.
- `src_install` copies the release's `store/` into `${D}` (the ebuild's image),
so the files are package-owned.
- `pkg_postinst` runs `nix-store --load-db` against the live root, creates the
`nixbld` group/users, and enables `nix-daemon.service`/`.socket`.
This is a *bootstrap-style* ebuild, not a `DESTDIR` install of a build tree; it
is the standard technique for packages that must initialise state at install
time (the same shape as `sys-apps/portage`'s news/`env-update` handling). It
belongs in the Phoebus overlay as `sys-apps/nix`.
Until the overlay ebuild is published, the installer provisions the same
lifecycle directly (discrete, no `curl | sh`, no `sh -c`), and the runtime
lifecycle operations are implemented in `phoebus-executor::nix`:
`install`, `remove(purge)`, `gc`, and `valid_nix_attribute` for bounded
developer-package realisation. `sys` exposes `nix_prepare { packages }` as a
bounded typed action.
### Authority
Nix remains a **developer lane only** (ADR 0006): no core component, service,
library or boot path depends on it. Portage owns the kernel, drivers, systemd,
Mesa, PipeWire, core libraries and the boot stack.
## Consequences
- A build that needs user namespaces now fails closed where they are absent.
- The store is bounded; growth is visible and managed.
- The overlay ebuild is the remaining Portage-ownership step; it is documented
and its lifecycle is already exercised by the installer and `nix_*`
operations. It is not yet shipped in a repository.
## Verification
- Unit tests assert the generated `/etc/nix/nix.conf` enables the enforced
sandbox and store bounds, and that removal unlinks units and only purges on
request.
- VM verification of a sandboxed source build (`nix build` of a package with a
derivation that would fail without isolation) and of the ebuild lifecycle is
recorded in `docs/STATUS.md` as outstanding.

View file

@ -0,0 +1,99 @@
# ADR 0009: Mango + DankMaterialShell desktop option
- **Status:** Accepted
- **Date:** 2026-09-21
## Context
Phoebus's flagship desktop is a hand-assembled dwl session (dwl, waybar, wofi,
mako, swaybg, swayidle, swaylock, polkit-gnome). It is lightweight and proven,
but it requires the user to assemble everyday desktop functions. Mango
(`gui-wm/mangowm`, a wlroots dwl derivative) plus DankMaterialShell (DMS, a
Quickshell shell providing panel, launcher, notifications, network/Bluetooth/
audio controls, locking, idle and display management) is a complete, coherent
desktop that fits the Wayland/systemd/PipeWire architecture.
The task is to offer it as an explicit profile, keep dwl as a fallback, and
promote Mango to the default only after verification.
## Upstream and packaging facts (verified 2026-09-21)
| Component | Package | Version | Source | License | Keyword |
|-----------|---------|---------|--------|---------|---------|
| Compositor | `gui-wm/mangowm` | 0.17.2 | GURU (community) | CC0-1.0 / GPL-3+ / MIT | `~amd64` |
| Shell | `gui-apps/dankmaterialshell` | 1.5.3 | GURU (community) | MIT | `~amd64` |
| Framework | `gui-apps/quickshell` | 0.3.1 | GURU (community) | LGPL-3 | `~amd64` |
| Search | `gui-apps/danksearch` | 0.3.2 | GURU (community) | MIT | `~amd64` |
| Effects lib | `gui-libs/scenefx` | 0.5 | GURU (community) | MIT | `~amd64` |
- `mangowm` depends on the **wlroots 0.20 slot** and `scenefx:0.5`.
- `gui-wm/dwl` (the fallback) depends on the **wlroots 0.18 slot**. The two are
different slots, so dwl and mangowm install side by side without a forced
wlroots upgrade.
- DMS is installed from DMS's **released** tarballs (its ebuild `SRC_URI`
points at GitHub release assets); no live/git package is used.
- GURU is git-only, so `dev-vcs/git` is installed from the main tree before the
overlay is synced.
- Upstream (Quickshell/DMS) requires Qt 6.6+, which the selected
`default/linux/amd64/23.0/desktop/systemd` profile provides.
## Decision
1. **A new explicit profile** `desktop.profile = "mango"` installs Mango + DMS
and *also* the dwl session as a fallback. Legacy values (`none`, `minimal`,
`dwl`, `full`) keep their exact meaning.
2. **Portage owns the stack.** The installer writes `repos.conf` for GURU
(git), installs `dev-vcs/git`, syncs GURU with `emaint sync -r guru`, and
installs the packages with `emerge`. There is no `curl | sh`, no Nix, and no
live package.
3. **Testing keywords are scoped.** `package.accept_keywords/phoebus` lists only
`gui-wm/mangowm`, `gui-apps/dankmaterialshell`, `gui-apps/danksearch`,
`gui-apps/quickshell` and `gui-libs/scenefx`. `~amd64` is never enabled
globally, and Portage is not silently auto-unmasked: additional `~amd64`
dependencies must be reviewed and added deliberately.
4. **Two session entry points, one shell each.** `/usr/share/wayland-sessions`
gets `phoebus-mango.desktop` (default when the Mango profile is installed)
and `phoebus-dwl.desktop` (fallback). The Mango session starts *only* mango,
DMS (panel, launcher, notifications, lock, idle), and the shell's polkit
agent; it never starts waybar/mako/swaybg/swayidle/swaylock. The dwl session
is unchanged.
5. **User configuration is separate from packaged defaults.** The session seeds
`~/.config/mango/config.conf` from `/etc/xdg/mango/config.conf` only when
absent, and DMS manages `~/.config/mango/dms/*.conf`. Portage upgrades never
overwrite user files.
6. **Administration stays behind `sys`.** DMS's system-update controls are not
wired up; updates continue through `sys`/Portage. The assistant is reachable
from a launcher (`phoebus-assistant`) that simply runs `sys ask`, keeping the
typed-action and approval boundary.
7. **Default promotion is gated on verification.** Until the graphical-VM gates
in `docs/VM-BOOT-VERIFICATION.md` pass, the Mango profile is *selectable*,
not the default; `desktop.profile = "dwl"` remains the recommended default.
## Update procedure
GURU is synced by `emaint sync -r guru` on every Portage sync. To move to a new
upstream release, bump the reviewed versions in the keyword list only after
`emerge --pretend` confirms the dependency set, then rebuild the profile's
packages. The overlay is community-maintained; its ebuilds are attributed to
their maintainers (see each `metadata.xml`).
## Consequences and risks
- The Mango install pulls Qt, Quickshell and scenefx, so it is much heavier to
build than the dwl session; a matching signed binhost does not exist for these
GURU packages, so they compile.
- GURU is a community overlay: provenance is documented but it is not the main
Gentoo tree. The keyword scope keeps the risk limited to the listed packages.
- DMS is a fast-moving project; the integration pins a reviewed release and
documents the update path rather than tracking `9999`.
- If DMS's polkit integration does not cover every prompt, a fallback
`PHOEBUS_POLKIT_AGENT` hook is available but defaults off to avoid two agents.
## Verification status
Unit and source-level tests cover the profile, package set, keyword scope,
generated session scripts, config seeding and the two session entries. The
graphical-VM acceptance gates (real seat, launcher/panel/notifications/polkit,
lock/unlock, shell restart, logout cleanup, suspend/resume, Flatpak portals,
idle/memory under load) are **not yet passed**; the profile therefore stays
selectable and is not promoted to default. See `docs/STATUS.md`.

View file

@ -10,5 +10,10 @@ and link it here.
| [0002](0002-bls-over-uki.md) | BLS entries instead of UKI for the boot path | Accepted |
| [0003](0003-desktop-systemd-profile.md) | Desktop installs inherit the Gentoo desktop/systemd profile | Accepted |
| [0004](0004-portage-verify-keyring.md) | Relax the getuto keyring for the dropped-privilege verifier | Accepted |
| [0005](0005-debian-live-appliance.md) | Debian-Live appliance ISO with a Gentoo target | Accepted |
| [0006](0006-package-lanes.md) | Package lanes — Portage, Flatpak, and Nix (built in) | Accepted |
| [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted |
| [0008](0008-nix-isolation-lifecycle.md) | Nix lifecycle, build isolation, and packaging | Accepted |
| [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted |
Format: Context / Decision / Consequences / Status.

View file

@ -497,6 +497,7 @@ version = "0.1.0"
dependencies = [
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror",
"toml",

View file

@ -0,0 +1,287 @@
//! Installed conversational assistant: natural request -> validated typed plan.
//!
//! The model is given only bounded system facts and a closed action schema. It
//! returns an [`AssistantPlan`] whose actions deserialize into the same
//! `SystemAction` enum `sys` executes. Nothing here runs with privilege: the
//! caller shows the plan, obtains approval, and the deterministic broker in
//! `phoebus-executor` executes it.
use phoebus_core::action::SystemAction;
use serde::{Deserialize, Serialize};
use crate::provider::{ChatMessage, ChatRequest, ModelTransport, ProviderKind, SystemFacts};
use crate::AiError;
/// One reason per proposed action.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AssistantRationale {
pub action: String,
pub reason: String,
}
/// A validated plan from the model.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AssistantPlan {
pub version: u32,
/// A short, human-readable explanation of the plan.
pub summary: String,
#[serde(default)]
pub actions: Vec<SystemAction>,
#[serde(default)]
pub rationale: Vec<AssistantRationale>,
}
impl AssistantPlan {
pub fn render(&self) -> String {
let mut out = String::new();
out.push_str(&format!("{}\n", self.summary));
if self.actions.is_empty() {
out.push_str("(no system actions proposed)\n");
}
for action in &self.actions {
out.push_str(&format!(" - {}\n", action.describe()));
if let Some(r) = self
.rationale
.iter()
.find(|r| r.action == action_tag(action))
{
out.push_str(&format!(" reason: {}\n", r.reason));
}
}
out
}
}
/// The serde tag of an action (`install_package`, ...).
pub fn action_tag(action: &SystemAction) -> String {
serde_json::to_value(action)
.ok()
.and_then(|v| v.get("action").and_then(|a| a.as_str()).map(str::to_string))
.unwrap_or_default()
}
/// The system prompt for the installed assistant. The action set is closed and
/// there is no shell or file action.
pub const ASSISTANT_PROMPT: &str = "\
You are the Phoebus OS system assistant. You can ONLY propose actions from this \
closed set: inspect_service, enable_service, disable_service, inspect_package, \
install_package, remove_package, search_packages, flatpak_install, flatpak_remove, \
flatpak_list, nix_prepare, create_snapshot, undo, rollback_status, history, \
update_system, prepare_updates, inspect_updates.
Reply with ONLY a JSON object:
{\"version\":1,\"summary\":\"...\",\"actions\":[{\"action\":\"...\",...}],\
\"rationale\":[{\"action\":\"...\",\"reason\":\"...\"}]}
Rules: give every action a non-empty reason; prefer inspection before mutation; \
never propose disabling verification, enabling ~amd64 globally, weakening \
LUKS2/Btrfs/systemd/UEFI, or any shell, file or arbitrary command action. You do \
not have a shell, credentials, or access to private files. A human reviews and \
authenticates every mutation.";
/// Parse and validate an assistant plan, fail-closed.
pub fn parse_plan(text: &str) -> Result<AssistantPlan, AiError> {
let plan: AssistantPlan = serde_json::from_str(text)?;
if plan.version != 1 {
return Err(AiError::UnsupportedVersion(plan.version));
}
if plan.summary.trim().is_empty() {
return Err(AiError::Rejected("plan has no summary".into()));
}
for action in &plan.actions {
action
.validate()
.map_err(|e| AiError::Rejected(format!("{}: {e}", action.describe())))?;
let tag = action_tag(action);
let has_reason = plan
.rationale
.iter()
.any(|r| r.action == tag && !r.reason.trim().is_empty());
if !has_reason {
return Err(AiError::Rejected(format!(
"{}: missing a non-empty reason",
action.describe()
)));
}
}
Ok(plan)
}
/// Build the chat request for a user instruction plus system facts.
pub fn build_request(
provider: ProviderKind,
model: &str,
facts: &SystemFacts,
instruction: &str,
) -> ChatRequest {
let model = if model.trim().is_empty() {
provider.default_model().to_string()
} else {
model.trim().to_string()
};
let user = format!(
"Bounded system facts (JSON):\n{}\n\nUser request: {instruction}\n\n\
Respond with a version 1 assistant plan.",
facts.render()
);
ChatRequest {
model,
messages: vec![
ChatMessage {
role: "system".into(),
content: ASSISTANT_PROMPT.into(),
},
ChatMessage {
role: "user".into(),
content: user,
},
],
temperature: 0.0,
response_format: Some(crate::provider::ResponseFormat {
kind: "json_object".into(),
}),
}
}
/// Ask the provider for a plan and parse it, fail-closed at every step.
pub fn complete_plan(
provider: ProviderKind,
endpoint: &str,
model: &str,
facts: &SystemFacts,
instruction: &str,
transport: &dyn ModelTransport,
) -> Result<AssistantPlan, AiError> {
if provider == ProviderKind::None {
return Err(AiError::ProviderUnavailable(
"no AI provider selected".into(),
));
}
if endpoint.trim().is_empty() {
return Err(AiError::ProviderUnavailable(
"no provider endpoint configured".into(),
));
}
facts.validate_no_forbidden()?;
let request = build_request(provider, model, facts, instruction);
let body = serde_json::to_string(&request)?;
let response = transport.send(provider, endpoint, &body)?;
let content = crate::provider::extract_content(&response)?;
parse_plan(&content)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::provider::TestTransport;
use phoebus_core::hardware::HardwareReport;
use phoebus_core::InstallConfig;
fn facts() -> SystemFacts {
SystemFacts::from_system(
&InstallConfig::default(),
&HardwareReport::default(),
&std::collections::HashMap::new(),
true,
None,
)
}
fn wrap(plan_json: &str) -> String {
serde_json::json!({
"choices": [{ "message": { "content": plan_json } }]
})
.to_string()
}
#[test]
fn parses_a_valid_plan() {
let text = r#"{
"version": 1,
"summary": "Check ssh and install vim",
"actions": [
{"action":"inspect_service","name":"sshd"},
{"action":"install_package","atom":"app-editors/vim"}
],
"rationale": [
{"action":"inspect_service","reason":"confirm it is present"},
{"action":"install_package","reason":"the user asked for vim"}
]
}"#;
let plan = parse_plan(text).unwrap();
assert_eq!(plan.actions.len(), 2);
assert!(plan.render().contains("install package app-editors/vim"));
assert!(plan.render().contains("reason: the user asked for vim"));
}
#[test]
fn unknown_actions_and_shell_fail_closed() {
let text = r#"{"version":1,"summary":"x","actions":[{"action":"run_shell","command":"rm -rf /"}],"rationale":[{"action":"run_shell","reason":"no"}]}"#;
assert!(parse_plan(text).is_err());
}
#[test]
fn actions_require_a_reason() {
let text = r#"{"version":1,"summary":"x","actions":[{"action":"enable_service","name":"sshd"}],"rationale":[]}"#;
assert!(matches!(parse_plan(text), Err(AiError::Rejected(_))));
let empty_reason = r#"{"version":1,"summary":"x","actions":[{"action":"enable_service","name":"sshd"}],"rationale":[{"action":"enable_service","reason":" "}]}"#;
assert!(parse_plan(empty_reason).is_err());
}
#[test]
fn invalid_values_are_rejected() {
let text = r#"{"version":1,"summary":"x","actions":[{"action":"install_package","atom":"bad atom"}],"rationale":[{"action":"install_package","reason":"x"}]}"#;
assert!(parse_plan(text).is_err());
}
#[test]
fn transport_round_trip_and_unavailable_provider() {
let plan = r#"{"version":1,"summary":"look","actions":[{"action":"history"}],"rationale":[{"action":"history","reason":"user asked"}]}"#;
let transport = TestTransport::new(wrap(plan));
let parsed = complete_plan(
ProviderKind::DeepSeek,
"https://api.deepseek.com/chat/completions",
"",
&facts(),
"what changed?",
&transport,
)
.unwrap();
assert_eq!(parsed.actions.len(), 1);
assert!(complete_plan(ProviderKind::None, "", "", &facts(), "hi", &transport).is_err());
assert!(complete_plan(ProviderKind::Local, "", "", &facts(), "hi", &transport).is_err());
}
#[test]
fn malformed_responses_are_reported_not_ignored() {
let transport = TestTransport::new(wrap("not json at all"));
assert!(complete_plan(
ProviderKind::Local,
"http://127.0.0.1:11434/v1/chat/completions",
"m",
&facts(),
"hi",
&transport
)
.is_err());
// A response with no choices is a provider error.
let empty = TestTransport::new("{\"choices\":[]}");
assert!(complete_plan(
ProviderKind::Local,
"http://127.0.0.1:11434/v1/chat/completions",
"m",
&facts(),
"hi",
&empty
)
.is_err());
}
#[test]
fn action_tag_matches_the_schema() {
assert_eq!(action_tag(&SystemAction::History), "history");
assert_eq!(action_tag(&SystemAction::FlatpakList), "flatpak_list");
}
}

View file

@ -6,6 +6,7 @@
//! the typed configuration. Privileged execution is a separate, human-approved
//! step performed by the deterministic backend.
pub mod assistant;
pub mod privacy;
pub mod provider;

View file

@ -11,6 +11,7 @@ toml.workspace = true
serde_json.workspace = true
thiserror.workspace = true
zeroize.workspace = true
sha2 = "0.10"
[dev-dependencies]
tempfile.workspace = true

View file

@ -26,14 +26,50 @@ pub enum Risk {
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)]
pub enum SystemAction {
InspectService { name: String },
EnableService { name: String },
DisableService { name: String },
InspectPackage { atom: String },
InstallPackage { atom: String },
RemovePackage { atom: String },
SearchPackages { query: String },
CreateSnapshot { operation: String },
InspectService {
name: String,
},
EnableService {
name: String,
},
DisableService {
name: String,
},
InspectPackage {
atom: String,
},
InstallPackage {
atom: String,
},
RemovePackage {
atom: String,
},
SearchPackages {
query: String,
},
/// Install a sandboxed Flatpak application from flathub.
FlatpakInstall {
app_id: String,
},
FlatpakRemove {
app_id: String,
},
FlatpakList,
/// Realise bounded nixpkgs development packages into the Nix store.
NixPrepare {
packages: Vec<String>,
},
CreateSnapshot {
operation: String,
},
/// Restore a committed snapshot as the next boot root. `snapshot` selects a
/// specific id; unset means the newest committed snapshot.
Undo {
#[serde(default, skip_serializing_if = "Option::is_none")]
snapshot: Option<String>,
},
/// Report the rollback state (no mutation).
RollbackStatus,
History,
UpdateSystem,
PrepareUpdates,
@ -54,9 +90,22 @@ impl SystemAction {
SystemAction::SearchPackages { query } => {
format!("search packages for `{query}`")
}
SystemAction::FlatpakInstall { app_id } => {
format!("install Flatpak app {app_id} from flathub")
}
SystemAction::FlatpakRemove { app_id } => format!("remove Flatpak app {app_id}"),
SystemAction::FlatpakList => "list installed Flatpak apps".to_string(),
SystemAction::NixPrepare { packages } => {
format!("realise Nix development packages: {}", packages.join(", "))
}
SystemAction::CreateSnapshot { operation } => {
format!("create a Btrfs snapshot before: {operation}")
}
SystemAction::Undo { snapshot } => match snapshot {
Some(id) => format!("roll back to snapshot {id} (restore as next boot root)"),
None => "roll back to the newest committed snapshot".to_string(),
},
SystemAction::RollbackStatus => "show the rollback state".to_string(),
SystemAction::History => "show system transaction history".to_string(),
SystemAction::PrepareUpdates => {
"prepare background updates (fetch + build binary packages, do not activate)"
@ -76,13 +125,19 @@ impl SystemAction {
| SystemAction::SearchPackages { .. } => Risk::Low,
SystemAction::History => Risk::Low,
SystemAction::InspectUpdates => Risk::Low,
SystemAction::RollbackStatus => Risk::Low,
SystemAction::FlatpakList => Risk::Low,
SystemAction::PrepareUpdates => Risk::Medium,
SystemAction::EnableService { .. }
| SystemAction::DisableService { .. }
| SystemAction::CreateSnapshot { .. } => Risk::Medium,
| SystemAction::CreateSnapshot { .. }
| SystemAction::FlatpakInstall { .. }
| SystemAction::FlatpakRemove { .. }
| SystemAction::NixPrepare { .. } => Risk::Medium,
SystemAction::InstallPackage { .. }
| SystemAction::RemovePackage { .. }
| SystemAction::UpdateSystem => Risk::High,
| SystemAction::UpdateSystem
| SystemAction::Undo { .. } => Risk::High,
}
}
@ -96,6 +151,8 @@ impl SystemAction {
| SystemAction::SearchPackages { .. }
| SystemAction::History
| SystemAction::InspectUpdates
| SystemAction::RollbackStatus
| SystemAction::FlatpakList
)
}
@ -132,6 +189,28 @@ impl SystemAction {
Err(format!("invalid search query: {query}"))
}
}
SystemAction::FlatpakInstall { app_id } | SystemAction::FlatpakRemove { app_id } => {
if valid_flatpak_app_id(app_id) {
Ok(())
} else {
Err(format!("invalid Flatpak application id: {app_id}"))
}
}
SystemAction::FlatpakList => Ok(()),
SystemAction::NixPrepare { packages } => {
if packages.is_empty() {
return Err("nix prepare requires at least one package".into());
}
if packages.len() > 32 {
return Err("too many Nix packages (max 32)".into());
}
for package in packages {
if !valid_nix_attribute(package) {
return Err(format!("invalid nixpkgs attribute: {package}"));
}
}
Ok(())
}
SystemAction::CreateSnapshot { operation } => {
if operation.is_empty() {
Err("snapshot operation must not be empty".into())
@ -139,10 +218,15 @@ impl SystemAction {
Ok(())
}
}
SystemAction::Undo { snapshot } => match snapshot {
Some(id) if !valid_token(id) => Err(format!("invalid snapshot id: {id}")),
_ => Ok(()),
},
SystemAction::History
| SystemAction::UpdateSystem
| SystemAction::PrepareUpdates
| SystemAction::InspectUpdates => Ok(()),
| SystemAction::InspectUpdates
| SystemAction::RollbackStatus => Ok(()),
}
}
}
@ -181,11 +265,55 @@ pub fn valid_search_query(query: &str) -> bool {
.all(|c| c.is_ascii_alphanumeric() || " ._+@/-".contains(c))
}
/// A Flatpak application id: reverse-DNS, e.g. `org.chromium.Chromium`. No
/// slashes, spaces, or shell metacharacters.
pub fn valid_flatpak_app_id(app_id: &str) -> bool {
!app_id.is_empty()
&& app_id.len() <= 128
&& app_id.contains('.')
&& !app_id.starts_with('.')
&& !app_id.ends_with('.')
&& app_id
.chars()
.all(|c| c.is_ascii_alphanumeric() || ".-_".contains(c))
}
/// A bounded nixpkgs attribute name (`nodejs`, `python312`). No slashes, URLs,
/// or flake references, so the assistant cannot make Nix evaluate arbitrary
/// remote inputs.
pub fn valid_nix_attribute(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 64
&& value
.chars()
.all(|c| c.is_ascii_alphanumeric() || "+-._".contains(c))
&& !value.contains('/')
&& !value.contains(':')
}
/// A small deterministic parser for common `sys` phrases.
///
/// Free-form requests that do not match are left to the AI path
/// (`--action-file`), which still produces the same typed schema.
pub fn parse_natural(text: &str) -> Option<SystemAction> {
// Snapshot ids are case-sensitive (`@-20260101T000000-...`), so parse the
// undo form from the original text before the general lowercasing.
let raw = text.trim();
let raw_lower = raw.to_ascii_lowercase();
for prefix in ["undo ", "rollback "] {
if raw_lower.starts_with(prefix) {
let id = raw[prefix.len()..].trim();
if id.eq_ignore_ascii_case("status") {
return Some(SystemAction::RollbackStatus);
}
if !id.is_empty() {
return Some(SystemAction::Undo {
snapshot: Some(id.to_string()),
});
}
}
}
let t = text.trim().to_lowercase();
let rest = |prefix: &str| t.strip_prefix(prefix).map(|r| r.trim().to_string());
@ -224,6 +352,20 @@ pub fn parse_natural(text: &str) -> Option<SystemAction> {
return Some(SystemAction::InspectService { name });
}
}
if let Some(id) = rest("undo ").or_else(|| rest("rollback ")) {
if id == "status" {
return Some(SystemAction::RollbackStatus);
}
if !id.is_empty() {
return Some(SystemAction::Undo { snapshot: Some(id) });
}
}
if t == "undo" || t == "rollback" {
return Some(SystemAction::Undo { snapshot: None });
}
if t.contains("rollback status") || t.contains("undo status") {
return Some(SystemAction::RollbackStatus);
}
if t == "history" || t.starts_with("history ") {
return Some(SystemAction::History);
@ -343,4 +485,71 @@ mod tests {
Risk::High
);
}
#[test]
fn undo_is_high_risk_and_mutating() {
let undo = parse_action(r#"{"action":"undo"}"#).unwrap();
assert_eq!(undo.risk(), Risk::High);
assert!(undo.is_mutating());
assert_eq!(undo, SystemAction::Undo { snapshot: None });
let specific =
parse_action(r#"{"action":"undo","snapshot":"@-20260101T000000-sys-update"}"#).unwrap();
assert_eq!(
specific,
SystemAction::Undo {
snapshot: Some("@-20260101T000000-sys-update".into())
}
);
// Unknown fields and bad ids fail closed.
assert!(parse_action(r#"{"action":"undo","shell":"sh"}"#).is_err());
assert!(parse_action(r#"{"action":"undo","snapshot":"bad id"}"#).is_err());
let status = parse_action(r#"{"action":"rollback_status"}"#).unwrap();
assert!(!status.is_mutating());
assert_eq!(status.risk(), Risk::Low);
}
#[test]
fn natural_undo_phrases() {
assert_eq!(
parse_natural("undo"),
Some(SystemAction::Undo { snapshot: None })
);
assert_eq!(
parse_natural("undo status"),
Some(SystemAction::RollbackStatus)
);
assert_eq!(
parse_natural("undo @-20260101T000000-sys-update"),
Some(SystemAction::Undo {
snapshot: Some("@-20260101T000000-sys-update".into())
})
);
}
#[test]
fn flatpak_and_nix_actions_are_bounded() {
let install =
parse_action(r#"{"action":"flatpak_install","app_id":"org.chromium.Chromium"}"#)
.unwrap();
assert_eq!(install.risk(), Risk::Medium);
assert!(install.is_mutating());
assert!(parse_action(r#"{"action":"flatpak_install","app_id":"bad id"}"#).is_err());
assert!(parse_action(r#"{"action":"flatpak_install","app_id":"nodots"}"#).is_err());
let list = parse_action(r#"{"action":"flatpak_list"}"#).unwrap();
assert!(!list.is_mutating());
let nix =
parse_action(r#"{"action":"nix_prepare","packages":["nodejs","python312"]}"#).unwrap();
assert_eq!(nix.risk(), Risk::Medium);
assert!(nix.is_mutating());
assert!(parse_action(r#"{"action":"nix_prepare","packages":[]}"#).is_err());
assert!(
parse_action(r#"{"action":"nix_prepare","packages":["github:evil/repo"]}"#).is_err()
);
assert!(valid_nix_attribute("python312"));
assert!(!valid_nix_attribute("nixpkgs#x/y"));
assert!(valid_flatpak_app_id("com.spotify.Client"));
assert!(!valid_flatpak_app_id("com/spotify"));
}
}

View file

@ -0,0 +1,293 @@
//! Boot Loader Specification (BLS) entry parsing and root-selection planning.
//!
//! systemd-boot reads `/loader/entries/*.conf` on the ESP. A rollback must edit
//! those entries, not just the Btrfs default subvolume: the kernel command line
//! carries an explicit `rootflags=subvol=...`, which overrides the default.
//! These are pure functions so the exact text written into the ESP is testable
//! without a real disk.
/// One BLS entry, preserving unknown keys verbatim.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BlsEntry {
pub file_name: String,
pub title: String,
pub linux: String,
pub initrds: Vec<String>,
pub options: String,
pub extra: Vec<String>,
}
impl BlsEntry {
/// Parse a BLS entry. Returns `None` when there is no `linux` line, which
/// means it is not a bootable kernel entry.
pub fn parse(file_name: &str, text: &str) -> Option<Self> {
let mut title = String::new();
let mut linux = String::new();
let mut initrds = Vec::new();
let mut options = String::new();
let mut extra = Vec::new();
for line in text.lines() {
let trimmed = line.trim();
if trimmed.is_empty() || trimmed.starts_with('#') {
continue;
}
let (key, value) = match trimmed.split_once(char::is_whitespace) {
Some((k, v)) => (k, v.trim()),
None => (trimmed, ""),
};
match key {
"title" => title = value.to_string(),
"linux" => linux = value.to_string(),
"initrd" => initrds.push(value.to_string()),
"options" => options = value.to_string(),
_ => extra.push(trimmed.to_string()),
}
}
if linux.is_empty() {
return None;
}
Some(Self {
file_name: file_name.to_string(),
title,
linux,
initrds,
options,
extra,
})
}
/// Render back to BLS text.
pub fn render(&self) -> String {
let mut out = String::new();
if !self.title.is_empty() {
out.push_str(&format!("title {}\n", self.title));
}
out.push_str(&format!("linux {}\n", self.linux));
for initrd in &self.initrds {
out.push_str(&format!("initrd {initrd}\n"));
}
if !self.options.trim().is_empty() {
out.push_str(&format!("options {}\n", self.options.trim()));
}
for line in &self.extra {
out.push_str(line);
out.push('\n');
}
out
}
/// The kernel version implied by the `linux` path
/// (`/<machine-id>/<version>/linux`).
pub fn kernel_version(&self) -> Option<String> {
let parts: Vec<&str> = self.linux.split('/').filter(|p| !p.is_empty()).collect();
// The segment immediately before the kernel file name is the version.
let last = parts.last()?;
if *last == "linux" || last.ends_with("vmlinuz") {
parts
.get(parts.len().checked_sub(2)?)
.map(|s| s.to_string())
} else {
None
}
}
/// Return a copy whose `options` selects a different root subvolume.
pub fn with_root_subvol(&self, subvol: &str) -> Result<Self, String> {
let mut entry = self.clone();
entry.options = replace_root_subvol(&self.options, subvol)?;
Ok(entry)
}
/// Return a copy with an extra option appended (e.g. `systemd.unit=`).
pub fn with_option(&self, extra: &str) -> Self {
let mut entry = self.clone();
entry.options = format!("{} {}", entry.options.trim(), extra)
.trim()
.to_string();
entry
}
pub fn with_title(&self, title: &str) -> Self {
let mut entry = self.clone();
entry.title = title.to_string();
entry
}
}
/// Replace the `rootflags=subvol=<name>` component of a kernel command line.
///
/// The reader must not assume the Btrfs default subvolume changes what is
/// mounted: an explicit `subvol=` argument always wins, so rollback edits it.
pub fn replace_root_subvol(options: &str, subvol: &str) -> Result<String, String> {
if subvol.is_empty() || subvol.contains(char::is_whitespace) || subvol.contains(',') {
return Err(format!("invalid root subvolume name: {subvol}"));
}
let mut replaced = false;
let mut out: Vec<String> = Vec::new();
for token in options.split_whitespace() {
if let Some(rest) = token.strip_prefix("rootflags=") {
let mut parts: Vec<String> = Vec::new();
for part in rest.split(',') {
if part.starts_with("subvol=") {
parts.push(format!("subvol={subvol}"));
replaced = true;
} else if !part.is_empty() {
parts.push(part.to_string());
}
}
if !parts.iter().any(|p| p.starts_with("subvol=")) {
parts.push(format!("subvol={subvol}"));
replaced = true;
}
out.push(format!("rootflags={}", parts.join(",")));
} else if token == "subvol=" {
out.push(format!("subvol={subvol}"));
replaced = true;
} else {
out.push(token.to_string());
}
}
if !replaced {
return Err("command line has no rootflags=subvol= to replace".into());
}
Ok(out.join(" "))
}
/// Compare kernel versions as numeric components (e.g. `6.12.9` > `6.12.10`?
/// no: `6.12.10` > `6.12.9` because components are compared numerically).
pub fn version_key(version: &str) -> Vec<u64> {
version
.split(|c: char| !c.is_ascii_digit())
.filter(|s| !s.is_empty())
.filter_map(|s| s.parse::<u64>().ok())
.collect()
}
/// The newest BLS entry whose kernel version is present in `available`
/// (the restored root's `/lib/modules`), so a rolled-back root boots a kernel
/// that still has matching modules.
pub fn choose_entry_for_versions<'a>(
entries: &'a [BlsEntry],
available: &[String],
) -> Option<&'a BlsEntry> {
let mut best: Option<&BlsEntry> = None;
for entry in entries {
let Some(version) = entry.kernel_version() else {
continue;
};
if !available.iter().any(|v| v == &version) {
continue;
}
let better = match best {
None => true,
Some(current) => {
let a = version_key(&version);
let b = current
.kernel_version()
.map(|v| version_key(&v))
.unwrap_or_default();
a > b
}
};
if better {
best = Some(entry);
}
}
best
}
/// The kernel versions present under a restored root's `lib/modules` listing.
pub fn kernel_versions_from_module_dirs(names: &[String]) -> Vec<String> {
names
.iter()
.filter(|n| {
!n.is_empty()
&& n.chars()
.next()
.map(|c| c.is_ascii_digit())
.unwrap_or(false)
})
.cloned()
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
const ENTRY: &str = "title Gentoo Linux\n\
linux /abcd/6.12.9/linux\n\
initrd /abcd/6.12.9/initrd\n\
options rd.luks.name=u=cryptroot root=/dev/mapper/cryptroot rootfstype=btrfs rootflags=subvol=@ rw quiet\n";
#[test]
fn parses_and_renders_roundtrip() {
let entry = BlsEntry::parse("abcd-6.12.9.conf", ENTRY).unwrap();
assert_eq!(entry.kernel_version().as_deref(), Some("6.12.9"));
let rendered = entry.render();
assert!(rendered.contains("title Gentoo Linux"));
assert!(rendered.contains("linux /abcd/6.12.9/linux"));
assert!(rendered.contains("initrd /abcd/6.12.9/initrd"));
assert!(BlsEntry::parse("x.conf", "# only a comment\n").is_none());
}
#[test]
fn replaces_the_explicit_root_subvolume() {
let entry = BlsEntry::parse("e.conf", ENTRY).unwrap();
let updated = entry.with_root_subvol("@restore-20260101T000000").unwrap();
assert!(updated
.options
.contains("rootflags=subvol=@restore-20260101T000000"));
assert!(!updated.options.contains("subvol=@ "));
// Other rootflags are preserved.
assert!(updated.options.contains("rootfstype=btrfs"));
}
#[test]
fn replace_handles_missing_subvol_and_rejects_empty() {
assert!(replace_root_subvol("root=/dev/x rootflags=rw", "@new")
.unwrap()
.contains("subvol=@new"));
assert!(replace_root_subvol("root=/dev/x", "@new").is_err());
assert!(replace_root_subvol("rootflags=subvol=@", "").is_err());
assert!(replace_root_subvol("rootflags=subvol=@", "bad name").is_err());
}
#[test]
fn chooses_the_newest_entry_with_matching_modules() {
let a = BlsEntry::parse(
"a.conf",
"title A\nlinux /id/6.12.9/linux\noptions rootflags=subvol=@\n",
)
.unwrap();
let b = BlsEntry::parse(
"b.conf",
"title B\nlinux /id/6.12.10/linux\noptions rootflags=subvol=@\n",
)
.unwrap();
let c = BlsEntry::parse(
"c.conf",
"title C\nlinux /id/6.13.1/linux\noptions rootflags=subvol=@\n",
)
.unwrap();
let entries = vec![a, b, c];
let modules = vec!["6.12.9".to_string(), "6.12.10".to_string()];
let chosen = choose_entry_for_versions(&entries, &modules).unwrap();
assert_eq!(chosen.title, "B");
// No matching modules at all -> refuse to select.
assert!(choose_entry_for_versions(&entries, &["5.0.0".to_string()]).is_none());
}
#[test]
fn module_dir_filter_ignores_non_versions() {
let names = vec![
"6.12.9".to_string(),
"modules.order".to_string(),
"6.12.9-gentoo".to_string(),
];
let versions = kernel_versions_from_module_dirs(&names);
assert!(versions.contains(&"6.12.9".to_string()));
assert!(versions.contains(&"6.12.9-gentoo".to_string()));
assert!(!versions.iter().any(|v| v == "modules.order"));
}
}

View file

@ -60,7 +60,7 @@ string_enum!(Encryption { None => "none", Luks2 => "luks2" });
string_enum!(Bootloader { SystemdBoot => "systemd-boot" });
string_enum!(KernelProfile { Safe => "safe", Optimized => "optimized", Aggressive => "aggressive" });
string_enum!(PackagePolicy { Balanced => "balanced", SourceFirst => "source_first", BinaryFirst => "binary_first" });
string_enum!(DesktopProfile { None => "none", Minimal => "minimal", Dwl => "dwl", Full => "full" });
string_enum!(DesktopProfile { None => "none", Minimal => "minimal", Dwl => "dwl", Mango => "mango", Full => "full" });
impl Bootloader {
pub fn default_systemd_boot() -> Self {

View file

@ -0,0 +1,386 @@
//! Resolved package effects and plan binding.
//!
//! A generic "install X" preview is not enough: an update can pull in package
//! upgrades, downgrades, rebuilds and removals, choose signed binaries or source
//! builds, and consume real bandwidth and disk. These types parse Portage's
//! `--pretend` output into a concrete effect list, compute a digest, and let the
//! caller bind an approval to exactly the reviewed plan. Before execution the
//! plan is resolved again and a material change aborts.
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
/// What a package entry will do.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EffectKind {
New,
Upgrade,
Downgrade,
Rebuild,
Remove,
/// A package that Portage will not change, or an unclassified line.
Other,
}
/// Where the package comes from. Provenance is explicit so Portage authority is
/// visible in the preview.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EffectSource {
/// A signed binary package from a configured binhost.
Binary,
/// A source build.
Source,
/// No artifact (removal).
None,
}
/// One resolved package effect.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PackageEffect {
/// The full atom Portage reported (e.g. `dev-lang/python-3.12.6:3.12`).
pub target: String,
/// The previous version for an upgrade/downgrade, when reported.
pub previous: Option<String>,
pub kind: EffectKind,
pub source: EffectSource,
}
/// A fully resolved, human-reviewable plan.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct ResolvedPlan {
pub effects: Vec<PackageEffect>,
pub download_bytes: Option<u64>,
/// A recovery point that will exist before the change (snapshot id).
pub recovery_point: Option<String>,
/// Material consequences shown to the human before approval.
pub consequences: Vec<String>,
/// Stable digest of the effect list, used to bind approval to the review.
pub digest: String,
}
impl ResolvedPlan {
pub fn additions(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::New)
.count()
}
pub fn upgrades(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::Upgrade)
.count()
}
pub fn downgrades(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::Downgrade)
.count()
}
pub fn removals(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::Remove)
.count()
}
pub fn source_builds(&self) -> usize {
self.effects
.iter()
.filter(|e| e.source == EffectSource::Source)
.count()
}
pub fn binary_packages(&self) -> usize {
self.effects
.iter()
.filter(|e| e.source == EffectSource::Binary)
.count()
}
/// Recompute the digest from the effect list. Always called after parsing so
/// the digest cannot drift from the effects.
pub fn recompute_digest(&mut self) {
let mut hasher = Sha256::new();
for effect in &self.effects {
hasher.update(effect.target.as_bytes());
hasher.update(b"\0");
hasher.update(format!("{:?}", effect.kind).as_bytes());
hasher.update(b"\0");
hasher.update(format!("{:?}", effect.source).as_bytes());
hasher.update(b"\0");
if let Some(prev) = &effect.previous {
hasher.update(prev.as_bytes());
}
hasher.update(b"\n");
}
self.digest = format!("{:x}", hasher.finalize());
}
/// A concrete, human-readable effect preview.
pub fn render(&self) -> String {
let mut out = String::new();
out.push_str("Resolved effects:\n");
if self.effects.is_empty() {
out.push_str(" (no package changes)\n");
}
for effect in &self.effects {
let source = match effect.source {
EffectSource::Binary => "binary",
EffectSource::Source => "source",
EffectSource::None => "remove",
};
match &effect.previous {
Some(prev) if effect.kind != EffectKind::New => {
out.push_str(&format!(
" [{:?}] {} ({} -> {}), {source}\n",
effect.kind, effect.target, prev, effect.target
));
}
_ => out.push_str(&format!(
" [{:?}] {}, {source}\n",
effect.kind, effect.target
)),
}
}
out.push_str(&format!(
" totals: {} new, {} upgrade, {} downgrade, {} remove; \
{} source / {} binary\n",
self.additions(),
self.upgrades(),
self.downgrades(),
self.removals(),
self.source_builds(),
self.binary_packages()
));
if let Some(bytes) = self.download_bytes {
out.push_str(&format!(" download: {} MiB\n", bytes / (1024 * 1024)));
}
for consequence in &self.consequences {
out.push_str(&format!(" ! {consequence}\n"));
}
if let Some(point) = &self.recovery_point {
out.push_str(&format!(" recovery point: {point}\n"));
}
out.push_str(&format!(" plan digest: {}\n", self.digest));
out
}
}
/// Parse the totals line's `Size of downloads` value.
fn parse_download_bytes(text: &str) -> Option<u64> {
for line in text.lines() {
if let Some(idx) = line.find("Size of downloads:") {
let rest = line[idx + "Size of downloads:".len()..].trim();
// e.g. "10,000 KiB" or "1.5 MiB"
let mut number = String::new();
for c in rest.chars() {
if c.is_ascii_digit() || c == '.' {
number.push(c);
} else if c == ',' {
// Portage uses commas as thousands separators.
continue;
} else if !number.is_empty() {
break;
}
}
let value: f64 = number.parse().ok()?;
let unit = rest.to_ascii_lowercase();
let multiplier = if unit.contains("gib") {
1024.0 * 1024.0 * 1024.0
} else if unit.contains("mib") {
1024.0 * 1024.0
} else {
1024.0
};
return Some((value * multiplier) as u64);
}
}
None
}
fn kind_and_source(bracket: &str) -> (EffectKind, EffectSource) {
let lower = bracket.to_ascii_lowercase();
let source = if lower.contains("binary") {
EffectSource::Binary
} else if lower.contains("uninstall") || lower.contains("clean") {
EffectSource::None
} else {
EffectSource::Source
};
// The action letter follows the program name: `ebuild U`, `binary N`.
// It is case-sensitive: U is an upgrade, D a downgrade, R a rebuild.
let action = bracket.split_whitespace().nth(1).unwrap_or("");
let kind = if lower.contains("uninstall") {
EffectKind::Remove
} else if action.contains('D') {
EffectKind::Downgrade
} else if action.contains('U') {
EffectKind::Upgrade
} else if action.contains('N') {
EffectKind::New
} else if action.contains('R') {
EffectKind::Rebuild
} else {
EffectKind::Other
};
(kind, source)
}
/// Parse real `emerge --pretend` output into a resolved plan.
pub fn parse_emerge_pretend(text: &str) -> ResolvedPlan {
let mut plan = ResolvedPlan::default();
for line in text.lines() {
let trimmed = line.trim_start();
if !trimmed.starts_with('[') {
continue;
}
let Some(close) = trimmed.find(']') else {
continue;
};
let bracket = &trimmed[1..close];
let rest = trimmed[close + 1..].trim();
if rest.is_empty() {
continue;
}
let (kind, source) = kind_and_source(bracket);
// For an upgrade, the new atom is the first token. The old version, if
// present, is in a following `[...]`.
let target = rest
.split_whitespace()
.next()
.unwrap_or("")
.trim_end_matches(',')
.to_string();
if target.is_empty() {
continue;
}
let previous = rest
.find('[')
.and_then(|start| rest.find(']').map(|end| (start, end)))
.and_then(|(start, end)| {
let inner = rest[start + 1..end].trim();
inner.split_whitespace().next().map(|s| s.to_string())
})
.filter(|_| matches!(kind, EffectKind::Upgrade | EffectKind::Downgrade));
plan.effects.push(PackageEffect {
target,
previous,
kind,
source,
});
}
plan.download_bytes = parse_download_bytes(text);
if plan.removals() > 0 {
plan.consequences
.push(format!("{} package(s) will be removed", plan.removals()));
}
if plan.source_builds() > 0 {
plan.consequences.push(format!(
"{} package(s) compile from source; this can take a long time",
plan.source_builds()
));
}
if plan.downgrades() > 0 {
plan.consequences.push(format!(
"{} package(s) will be downgraded",
plan.downgrades()
));
}
plan.recompute_digest();
plan
}
/// Whether two plans differ materially (anything but the digest itself).
pub fn changed_materially(approved: &ResolvedPlan, current: &ResolvedPlan) -> bool {
let mut a = approved.clone();
let mut b = current.clone();
a.digest.clear();
b.digest.clear();
a.recovery_point = None;
b.recovery_point = None;
a != b
}
#[cfg(test)]
mod tests {
use super::*;
const PRETEND: &str = "\
These are the packages that would be merged, in order:
Calculating dependencies... done!
[ebuild N ] app-editors/vim-9.1.0 USE=\"-python\"
[ebuild U ] dev-lang/python-3.12.6:3.12::gentoo [3.12.5:3.12::gentoo]
[binary N ] net-misc/wget-1.24.5
[ebuild UD ] app-misc/foo-2.0 [1.0]
[uninstall ] app-misc/old-1.0
Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 KiB
";
#[test]
fn parses_effects_kinds_and_sources() {
let plan = parse_emerge_pretend(PRETEND);
assert_eq!(plan.effects.len(), 5);
assert_eq!(plan.additions(), 2);
assert_eq!(plan.upgrades(), 1);
assert_eq!(plan.downgrades(), 1);
assert_eq!(plan.removals(), 1);
assert_eq!(plan.binary_packages(), 1);
assert_eq!(plan.source_builds(), 3);
assert_eq!(plan.download_bytes, Some(10_240 * 1024));
let python = plan
.effects
.iter()
.find(|e| e.target.starts_with("dev-lang/python"))
.unwrap();
assert_eq!(python.kind, EffectKind::Upgrade);
assert_eq!(python.previous.as_deref(), Some("3.12.5:3.12::gentoo"));
let foo = plan
.effects
.iter()
.find(|e| e.target.starts_with("app-misc/foo"))
.unwrap();
assert_eq!(foo.kind, EffectKind::Downgrade);
}
#[test]
fn digest_is_stable_and_detects_material_change() {
let a = parse_emerge_pretend(PRETEND);
let b = parse_emerge_pretend(PRETEND);
assert_eq!(a.digest, b.digest);
assert!(!changed_materially(&a, &b));
let other = PRETEND.replace("app-misc/foo-2.0", "app-misc/foo-2.1");
let c = parse_emerge_pretend(&other);
assert_ne!(a.digest, c.digest);
assert!(changed_materially(&a, &c));
}
#[test]
fn empty_output_is_a_no_change_plan() {
let plan = parse_emerge_pretend("Calculating dependencies... done!\n\nTotal: 0 packages\n");
assert!(plan.effects.is_empty());
assert_eq!(plan.additions(), 0);
assert!(plan.render().contains("no package changes"));
// The digest is still defined.
assert_eq!(plan.digest.len(), 64);
}
#[test]
fn render_states_source_binary_and_consequences() {
let plan = parse_emerge_pretend(PRETEND);
let text = plan.render();
assert!(text.contains("binary"));
assert!(text.contains("source"));
assert!(text.contains("will be removed"));
assert!(text.contains("download:"));
}
}

View file

@ -4,17 +4,21 @@
//! Nothing in this crate executes external commands or touches disks.
pub mod action;
pub mod boot;
pub mod config;
pub mod disk;
pub mod effects;
pub mod emergelog;
pub mod error;
pub mod hardware;
pub mod plan;
pub mod policy;
pub mod rollback;
pub mod secret;
pub mod snapshot;
pub mod system;
pub mod target;
pub mod transaction;
pub mod update;
pub mod validate;

View file

@ -169,6 +169,11 @@ impl InstallPlan {
config.packages.accept_license
));
o.push_str(&format!(" Desktop : {}\n", config.desktop.profile));
if config.desktop.profile == crate::config::DesktopProfile::Mango {
o.push_str(
" Session : Mango + DankMaterialShell (GURU overlay; dwl fallback)\n",
);
}
o.push_str(&format!(
" Flatpak : {}\n",
if config.desktop.flatpak { "yes" } else { "no" }

View file

@ -0,0 +1,403 @@
//! Rollback and recovery model.
//!
//! Rollback is deliberately explicit about the pieces that must move together:
//! the root subvolume selection (kernel command line *and* fstab *and* the Btrfs
//! default), the separately mounted `@var` volume (package database, Portage
//! state, caches), and the kernel/initramfs pairing on the ESP. These are pure
//! types and planners; the privileged executor performs the commands.
//!
//! The reader must never assume that changing the Btrfs default subvolume
//! overrides the explicit `rootflags=subvol=...` in the kernel command line: the
//! explicit argument wins, so boot entries are rewritten as well.
use serde::{Deserialize, Serialize};
use crate::snapshot::{compact_utc, SnapshotHistory, SnapshotRecord, SnapshotStatus};
/// Snapshot subvolumes kept by default before the oldest committed ones are
/// pruned.
pub const DEFAULT_KEEP_SNAPSHOTS: usize = 8;
/// Root generations (`@restore-*`) kept by default.
pub const DEFAULT_KEEP_ROOT_GENERATIONS: usize = 3;
/// Free space required before a rollback, on top of the snapshot's own usage.
pub const MIN_FREE_SPACE_BYTES: u64 = 1024 * 1024 * 1024;
/// The lifecycle of a rollback. A rollback is only `Verified` after the system
/// has booted from the restored root and the package state checked out.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum RollbackStatus {
/// No rollback has been attempted.
#[default]
Idle,
/// Subvolumes were prepared; boot entries still point at the previous root
/// until activation completes. An interruption here is safe: the system
/// boots the previous root.
Planned,
/// Boot entries now select the restored root; awaiting the next boot.
Activated,
/// The system booted the restored root and the package state is consistent.
Verified,
/// A step failed. The system still boots a known root; re-running resumes.
Failed,
}
impl RollbackStatus {
/// Whether a rollback is in flight and its target must be protected from
/// retention pruning.
pub fn in_flight(self) -> bool {
matches!(self, RollbackStatus::Planned | RollbackStatus::Activated)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct RollbackState {
pub status: RollbackStatus,
/// Monotonic generation number, for human diagnostics and ordering.
pub generation: u64,
/// The snapshot id that was selected as the restore source.
pub target_snapshot: String,
/// The paired `@var` snapshot, when one was captured.
pub target_var_snapshot: Option<String>,
/// The root subvolume that was active before the rollback.
pub previous_root: String,
/// The new root subvolume booted after the rollback.
pub root_subvol: String,
/// The paired new `/var` subvolume, when applicable.
pub var_subvol: Option<String>,
/// The BLS entry file selected to boot the restored root.
pub boot_entry: Option<String>,
pub started_unix: u64,
pub finished_unix: u64,
pub note: String,
}
impl Default for RollbackState {
fn default() -> Self {
Self {
status: RollbackStatus::Idle,
generation: 0,
target_snapshot: String::new(),
target_var_snapshot: None,
previous_root: "@".into(),
root_subvol: "@".into(),
var_subvol: None,
boot_entry: None,
started_unix: 0,
finished_unix: 0,
note: String::new(),
}
}
}
impl RollbackState {
/// The subvolume id/name that should be protected from pruning.
pub fn protected_subvols(&self) -> Vec<String> {
let mut out = vec![self.root_subvol.clone()];
if let Some(var) = &self.var_subvol {
out.push(var.clone());
}
out
}
}
/// A root generation created by a rollback (a writable clone of a snapshot).
pub fn restore_root_name(ts: u64) -> String {
format!("@restore-{}", compact_utc(ts))
}
/// The paired `/var` generation created by a rollback.
pub fn restore_var_name(ts: u64) -> String {
format!("@varrestore-{}", compact_utc(ts))
}
/// A safety snapshot of the current root, taken before a rollback overwrites
/// the boot selection.
pub fn pre_rollback_snapshot_name(ts: u64) -> String {
format!("@-{}-pre-rollback", compact_utc(ts))
}
/// A safety snapshot of the current `/var`.
pub fn pre_rollback_var_snapshot_name(ts: u64) -> String {
format!("@var-{}-pre-rollback", compact_utc(ts))
}
/// The subvolume path of a snapshot record relative to the Btrfs top level
/// (subvolid 5): snapshots live under the `@snapshots` subvolume.
pub fn snapshot_top_level_path(name: &str) -> String {
format!("@snapshots/{name}")
}
/// The device backing the running root, from `/proc/self/mounts` text
/// (`source mountpoint fstype options dump pass`).
pub fn root_device_from_mounts(text: &str) -> Option<String> {
for line in text.lines() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() >= 3 && fields[1] == "/" {
return Some(fields[0].to_string());
}
}
None
}
/// The ESP mount point (a vfat filesystem, conventionally `/efi`), from
/// `/proc/self/mounts` text.
pub fn esp_mount_from_mounts(text: &str) -> Option<String> {
for line in text.lines() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() >= 3 && fields[2] == "vfat" && fields[1] != "/" {
return Some(fields[1].to_string());
}
}
None
}
/// Rewrite the `subvol=` component of the fstab line for `mountpoint`,
/// preserving every other field and option. Returns the text unchanged when no
/// matching line exists so the caller can detect the miss separately.
pub fn rewrite_fstab_subvol(text: &str, mountpoint: &str, new_subvol: &str) -> String {
let mut out = String::new();
for line in text.lines() {
let trimmed = line.trim_start();
if trimmed.starts_with('#') || trimmed.is_empty() {
out.push_str(line);
out.push('\n');
continue;
}
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() >= 4 && fields[1] == mountpoint {
let opts = fields[3];
let mut parts: Vec<String> = Vec::new();
let mut replaced = false;
for part in opts.split(',') {
if part.starts_with("subvol=") {
parts.push(format!("subvol={new_subvol}"));
replaced = true;
} else if !part.is_empty() {
parts.push(part.to_string());
}
}
if !replaced {
parts.push(format!("subvol={new_subvol}"));
}
let new_opts = parts.join(",");
let mut rebuilt = line.to_string();
if let Some(pos) = line.find(opts) {
rebuilt.replace_range(pos..pos + opts.len(), &new_opts);
}
out.push_str(&rebuilt);
out.push('\n');
} else {
out.push_str(line);
out.push('\n');
}
}
out
}
/// Whether an fstab line exists for `mountpoint`.
pub fn fstab_has_mountpoint(text: &str, mountpoint: &str) -> bool {
text.lines().any(|line| {
let trimmed = line.trim_start();
!trimmed.starts_with('#')
&& line
.split_whitespace()
.nth(1)
.map(|m| m == mountpoint)
.unwrap_or(false)
})
}
/// The newest committed snapshot, skipping records without a real subvolume.
pub fn latest_committed(history: &SnapshotHistory) -> Option<&SnapshotRecord> {
history
.records
.iter()
.rev()
.find(|r| r.status == SnapshotStatus::Committed && !r.snapshot_subvol.is_empty())
}
/// Whether the history contains the given id as a committed snapshot.
pub fn is_committed(history: &SnapshotHistory, id: &str) -> bool {
history
.records
.iter()
.any(|r| r.id == id && r.status == SnapshotStatus::Committed)
}
/// Generic newest-first retention: return the items to delete, keeping the
/// newest `keep`, never deleting anything in `protect`.
///
/// Input order is oldest-first (the order the history is appended in).
pub fn retention_deletions(items: &[String], keep: usize, protect: &[String]) -> Vec<String> {
if items.len() <= keep {
return Vec::new();
}
let cutoff = items.len() - keep;
items
.iter()
.take(cutoff)
.filter(|id| !protect.iter().any(|p| p == *id))
.cloned()
.collect()
}
/// Prune the snapshot history to at most `keep` committed snapshots.
///
/// Records that are still in flight (`Created`) or `Failed` are never selected,
/// and the newest committed snapshot is always retained so a recovery point
/// survives.
pub fn snapshot_retention_deletions(
history: &SnapshotHistory,
keep: usize,
protect: &[String],
) -> Vec<String> {
let mut committed: Vec<String> = history
.records
.iter()
.filter(|r| r.status == SnapshotStatus::Committed)
.map(|r| r.id.clone())
.collect();
committed.dedup();
if committed.is_empty() {
return Vec::new();
}
let newest = committed.last().cloned();
let mut protect = protect.to_vec();
if let Some(n) = newest {
if !protect.contains(&n) {
protect.push(n);
}
}
retention_deletions(&committed, keep, &protect)
}
#[cfg(test)]
mod tests {
use super::*;
fn record(id: &str, status: SnapshotStatus) -> SnapshotRecord {
SnapshotRecord {
id: id.into(),
created_unix: 0,
operation: "op".into(),
source_subvol: "@".into(),
snapshot_subvol: id.into(),
var_snapshot: None,
status,
}
}
#[test]
fn names_are_deterministic_and_safe() {
let ts = 1_700_000_000;
assert_eq!(restore_root_name(ts), "@restore-20231114T221320");
assert_eq!(restore_var_name(ts), "@varrestore-20231114T221320");
assert_eq!(
pre_rollback_snapshot_name(ts),
"@-20231114T221320-pre-rollback"
);
assert_eq!(snapshot_top_level_path("@-x"), "@snapshots/@-x");
for name in [restore_root_name(ts), restore_var_name(ts)] {
assert!(!name.contains('/'));
assert!(!name.contains(char::is_whitespace));
}
}
#[test]
fn retention_keeps_the_newest_and_protects_in_flight() {
let items: Vec<String> = (0..5).map(|i| format!("s{i}")).collect();
let deletions = retention_deletions(&items, 2, &["s2".to_string()]);
assert_eq!(deletions, vec!["s0", "s1"]);
// Nothing to delete when under the limit.
assert!(retention_deletions(&items, 9, &[]).is_empty());
}
#[test]
fn retention_never_deletes_the_newest_committed() {
let history = SnapshotHistory {
records: vec![
record("a", SnapshotStatus::Committed),
record("b", SnapshotStatus::Committed),
record("c", SnapshotStatus::Committed),
],
};
let deletions = snapshot_retention_deletions(&history, 0, &[]);
// `c` is the newest and is always kept.
assert_eq!(deletions, vec!["a", "b"]);
assert!(!deletions.contains(&"c".to_string()));
}
#[test]
fn retention_skips_in_flight_and_failed_records() {
let history = SnapshotHistory {
records: vec![
record("a", SnapshotStatus::Committed),
record("b", SnapshotStatus::Created),
record("c", SnapshotStatus::Failed),
record("d", SnapshotStatus::Committed),
],
};
let deletions = snapshot_retention_deletions(&history, 1, &[]);
assert_eq!(deletions, vec!["a"]);
}
#[test]
fn status_in_flight_is_planned_or_activated() {
assert!(RollbackStatus::Planned.in_flight());
assert!(RollbackStatus::Activated.in_flight());
assert!(!RollbackStatus::Verified.in_flight());
assert!(!RollbackStatus::Idle.in_flight());
}
#[test]
fn latest_committed_prefers_the_last_record() {
let history = SnapshotHistory {
records: vec![
record("a", SnapshotStatus::Committed),
record("b", SnapshotStatus::Failed),
record("c", SnapshotStatus::Committed),
],
};
assert_eq!(latest_committed(&history).unwrap().id, "c");
assert!(is_committed(&history, "a"));
assert!(!is_committed(&history, "b"));
}
#[test]
fn mount_parsers_find_root_device_and_esp() {
let mounts = "/dev/mapper/cryptroot / btrfs rw,subvol=/\t0 0\n\
/dev/vda1 /efi vfat umask=0077\t0 0\n\
proc /proc proc rw\t0 0\n";
assert_eq!(
root_device_from_mounts(mounts).as_deref(),
Some("/dev/mapper/cryptroot")
);
assert_eq!(esp_mount_from_mounts(mounts).as_deref(), Some("/efi"));
assert!(root_device_from_mounts("").is_none());
assert!(esp_mount_from_mounts("proc /proc proc rw 0 0").is_none());
}
#[test]
fn fstab_subvol_rewrite_only_touches_the_requested_mountpoint() {
let fstab = "\
# /etc/fstab
UUID=AAAA-1111\t/efi\tvfat\tumask=0077,shortname=winnt\t0\t2
/dev/mapper/cryptroot\t/\tbtrfs\tnoatime,compress=zstd:3,subvol=@\t0\t1
/dev/mapper/cryptroot\t/home\tbtrfs\tnoatime,compress=zstd:3,subvol=@home\t0\t2
/dev/mapper/cryptroot\t/var\tbtrfs\tnoatime,compress=zstd:3,subvol=@var\t0\t2
/swap/swapfile\tnone\tswap\tdefaults\t0\t0
";
let out = rewrite_fstab_subvol(fstab, "/", "@restore-20260101T000000");
assert!(out.contains("subvol=@restore-20260101T000000\t0\t1"));
// /var is untouched here; it is rewritten separately.
assert!(out.contains("\t/var\tbtrfs\tnoatime,compress=zstd:3,subvol=@var\t0\t2"));
assert!(out.contains("subvol=@home"));
let var = rewrite_fstab_subvol(&out, "/var", "@varrestore-20260101T000000");
assert!(var.contains("subvol=@varrestore-20260101T000000\t0\t2"));
assert!(fstab_has_mountpoint(&var, "/"));
assert!(fstab_has_mountpoint(&var, "/var"));
assert!(!fstab_has_mountpoint(&var, "/nonexistent"));
}
}

View file

@ -27,6 +27,12 @@ pub struct SnapshotRecord {
pub operation: String,
pub source_subvol: String,
pub snapshot_subvol: String,
/// The paired `@var` snapshot. `/var` is a separate subvolume holding the
/// package database and Portage state, so it is captured with the root and
/// restored with it; otherwise a restored root would see inconsistent
/// package state.
#[serde(default)]
pub var_snapshot: Option<String>,
pub status: SnapshotStatus,
}
@ -130,6 +136,7 @@ mod tests {
operation: "sys update".into(),
source_subvol: "@".into(),
snapshot_subvol: "@-20231114T221320-sys-update".into(),
var_snapshot: None,
status: SnapshotStatus::Committed,
});
history.save(&path).unwrap();

View file

@ -41,7 +41,25 @@ pub fn desktop_packages(profile: DesktopProfile) -> Vec<&'static str> {
"gui-libs/wayland-protocols",
"x11-base/xwayland",
],
DesktopProfile::Dwl | DesktopProfile::Full => vec![
DesktopProfile::Dwl => dwl_desktop_packages(),
// Mango + DankMaterialShell ships the dwl session as a fallback, so the
// user always has a second compositor if the new session misbehaves.
DesktopProfile::Mango => mango_desktop_packages(),
DesktopProfile::Full => {
let mut out = dwl_desktop_packages();
out.extend([
"sys-apps/flatpak",
"net-wireless/bluez",
"gnome-base/gnome-keyring",
]);
out
}
}
}
/// The proven dwl session (also the fallback for the Mango profile).
pub fn dwl_desktop_packages() -> Vec<&'static str> {
vec![
"gui-wm/dwl",
"gui-apps/waybar",
"gui-apps/wofi",
@ -63,19 +81,30 @@ pub fn desktop_packages(profile: DesktopProfile) -> Vec<&'static str> {
"sys-apps/xdg-desktop-portal",
"sys-apps/xdg-desktop-portal-gtk",
"gui-libs/xdg-desktop-portal-wlr",
],
}
.into_iter()
.chain(if profile == DesktopProfile::Full {
vec![
"sys-apps/flatpak",
"net-wireless/bluez",
"gnome-base/gnome-keyring",
]
} else {
vec![]
})
.collect()
}
/// Mango + DankMaterialShell, plus a minimal terminal/file-manager set.
///
/// The shell (panel, launcher, notifications, lock, idle, audio/network/
/// Bluetooth controls and displays) is `gui-apps/dankmaterialshell`, which
/// depends on `gui-apps/quickshell`. Both are shipped through the GURU overlay;
/// `dev-vcs/git` is required to sync that git-only overlay. `gui-wm/mangowm`
/// uses the wlroots 0.20 slot, so it coexists with dwl (wlroots 0.18).
pub fn mango_desktop_packages() -> Vec<&'static str> {
let mut out = dwl_desktop_packages();
out.extend([
"gui-wm/mangowm",
"gui-apps/dankmaterialshell",
"gui-apps/danksearch",
"dev-vcs/git",
"sys-apps/accountsservice",
"sys-power/upower",
"kde-frameworks/kimageformats",
"x11-misc/pcmanfm",
"net-wireless/bluez",
]);
out
}
pub fn desktop_audio_packages() -> Vec<&'static str> {
@ -88,7 +117,7 @@ pub fn network_target_services() -> Vec<&'static str> {
pub fn desktop_services(profile: DesktopProfile) -> Vec<&'static str> {
let mut out = vec!["NetworkManager", "systemd-resolved"];
if profile == DesktopProfile::Full {
if matches!(profile, DesktopProfile::Full | DesktopProfile::Mango) {
out.push("bluetooth");
}
out
@ -209,6 +238,46 @@ pub fn repos_conf() -> String {
o
}
/// The GURU community overlay, which packages Mango and DankMaterialShell.
///
/// GURU is git-only (no rsync), so `dev-vcs/git` must be installed before it
/// can be synced. It is a reviewed, signed-over-git community overlay; the
/// installer scopes `~amd64` to the specific packages rather than unmasking it.
pub const GURU_REPO_URI: &str = "https://anongit.gentoo.org/git/proj/guru.git";
pub fn guru_repos_conf() -> String {
let mut o = String::new();
o.push_str("[guru]\n");
o.push_str("location = /var/db/repos/guru\n");
o.push_str("sync-type = git\n");
o.push_str(&format!("sync-uri = {GURU_REPO_URI}\n"));
o.push_str("auto-sync = yes\n");
o
}
/// Whether the selected desktop needs the GURU overlay.
pub fn uses_guru(config: &InstallConfig) -> bool {
config.desktop.profile == DesktopProfile::Mango
}
/// The reviewed `~amd64` keyword set for the Mango + DankMaterialShell stack.
///
/// These are the GURU packages and the GURU-only dependency (`scenefx`). The
/// comment is explicit that this is scoped, not a global `~amd64` switch, and
/// that Portage must not silently unmask further packages: an operator reviews
/// `emerge --pretend` output and extends the file deliberately.
pub fn accept_keywords_mango() -> String {
let mut o = String::new();
o.push_str("# Mango + DankMaterialShell: reviewed, scoped testing keywords.\n");
o.push_str("# This is NOT a global ~amd64 switch. GURU ships these as ~amd64.\n");
o.push_str("gui-wm/mangowm\n");
o.push_str("gui-apps/dankmaterialshell\n");
o.push_str("gui-apps/danksearch\n");
o.push_str("gui-apps/quickshell\n");
o.push_str("gui-libs/scenefx\n");
o
}
pub const BINHOST_OPENRC: &str =
"https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64";
pub const BINHOST_HARDENED: &str =
@ -499,10 +568,339 @@ else
echo "phoebus-session: polkit agent not found; graphical authentication may fail" >&2
fi
# Idle handling and screen locking (swayidle + swaylock). Locking before sleep
# means resuming never reveals the desktop.
if command -v phoebus-idle >/dev/null 2>&1; then
start_helper phoebus-idle
fi
# Run until the compositor exits, then the EXIT trap stops the helpers.
wait "$DWL_PID"
"#;
/// The `phoebus-menu` launcher / power menu (wofi).
pub const PHOEBUS_MENU_SCRIPT: &str = r#"#!/bin/bash
# Phoebus application launcher and power menu.
# phoebus-menu application launcher (wofi drun)
# phoebus-menu --power lock / suspend / log out / reboot / shut down
set -u
if [ "${1:-}" = "--power" ]; then
choice="$(printf '%s\n' 'Lock' 'Suspend' 'Log out' 'Reboot' 'Shut down' \
| wofi --dmenu --prompt 'Power')"
case "$choice" in
Lock) exec phoebus-lock ;;
Suspend) exec systemctl suspend ;;
'Log out') exec pkill -TERM dwl ;;
Reboot) exec systemctl reboot ;;
'Shut down') exec systemctl poweroff ;;
esac
fi
exec wofi --show drun --prompt Applications
"#;
/// Screen locker.
pub const PHOEBUS_LOCK_SCRIPT: &str = r#"#!/bin/bash
# Lock the session. `-f` fails closed if the lock cannot be established.
set -u
exec swaylock -f -c 1e1e2e
"#;
/// Idle daemon: lock, then suspend, and always lock before sleeping.
pub const PHOEBUS_IDLE_SCRIPT: &str = r#"#!/bin/bash
# Idle handling: dim/lock after inactivity and lock before suspend.
set -u
exec swayidle -w \
timeout 300 'phoebus-lock' \
timeout 600 'systemctl suspend' \
before-sleep 'phoebus-lock'
"#;
/// System-wide Waybar configuration (network, audio, battery, clock, power).
pub const WAYBAR_CONFIG: &str = r#"{
"layer": "top",
"position": "top",
"height": 30,
"modules-left": ["sway/workspaces", "sway/mode"],
"modules-center": ["sway/window"],
"modules-right": ["wireplumber", "network", "battery", "clock", "tray", "custom/power"],
"wireplumber": {
"format": "{icon} {volume}%",
"format-muted": "muted",
"on-click": "pavucontrol-qt || pavucontrol"
},
"network": {
"format-wifi": "wifi {essid}",
"format-ethernet": "ethernet",
"format-disconnected": "offline",
"on-click": "nm-connection-editor || nmtui"
},
"battery": {
"format": "bat {capacity}%",
"format-charging": "chg {capacity}%"
},
"clock": {
"format": "{:%a %H:%M}",
"tooltip-format": "{:%Y-%m-%d %H:%M}"
},
"custom/power": {
"format": "power",
"on-click": "phoebus-menu --power",
"tooltip": "Lock, suspend, log out, reboot"
}
}
"#;
/// System-wide Waybar styling.
pub const WAYBAR_STYLE: &str = r#"* {
font-family: monospace;
font-size: 13px;
}
window#waybar {
background: #1e1e2e;
color: #cdd6f4;
}
#workspaces button.focused,
#custom-power:hover {
background: #89b4fa;
color: #1e1e2e;
}
"#;
// ---------------------------------------------------------------------------
// Mango + DankMaterialShell
// ---------------------------------------------------------------------------
/// The Mango session entry point written to `/usr/local/bin/phoebus-session-mango`.
///
/// It starts exactly one compositor (mango), one shell, notification, lock and
/// idle implementation (all provided by DankMaterialShell), and one polkit
/// agent (Quickshell's, enabled by the shell's `policykit` feature). It does
/// **not** start the dwl helpers (waybar/mako/swaybg/swayidle/swaylock), so the
/// two sessions never compete. It seeds user configuration from the packaged
/// defaults only when absent, so upgrades never overwrite customization.
pub const PHOEBUS_MANGO_SESSION_SCRIPT: &str = r#"#!/bin/bash
# Phoebus Mango + DankMaterialShell session (generated by the installer).
#
# Hotkeys (also shown in the DMS shortcut overlay):
# Mod+Space launcher (DMS spotlight) Mod+Return terminal
# Mod+V clipboard history Mod+N notifications
# Mod+Comma settings Mod+M task manager
# Mod+a Phoebus assistant Mod+Alt+L lock
# Mod+Shift+q close window Mod+Shift+e exit session
set -u
if [ -z "${XDG_RUNTIME_DIR:-}" ]; then
export XDG_RUNTIME_DIR="/run/user/$(id -u)"
fi
if [ ! -d "$XDG_RUNTIME_DIR" ]; then
echo "phoebus-session-mango: XDG_RUNTIME_DIR $XDG_RUNTIME_DIR is missing" >&2
exit 1
fi
# Deterministic socket name so the environment exported to the systemd user
# manager matches the compositor.
export WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}"
export XDG_SESSION_TYPE=wayland
export XDG_CURRENT_DESKTOP=mango
export XDG_SESSION_DESKTOP=mango
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export QT_QPA_PLATFORMTHEME=gtk3
export QT_QPA_PLATFORMTHEME_QT6=gtk3
export GDK_BACKEND=wayland,x11
export ELECTRON_OZONE_PLATFORM_HINT=auto
export _JAVA_AWT_WM_NONREPARENTING=1
if [ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ] && command -v dbus-run-session >/dev/null 2>&1; then
exec dbus-run-session -- "$0" "$@"
fi
# Seed user configuration from the packaged defaults exactly once; never
# overwrite what the user has customized.
mango_conf="$HOME/.config/mango/config.conf"
mkdir -p "$HOME/.config/mango/dms"
if [ ! -e "$mango_conf" ] && [ -r /etc/xdg/mango/config.conf ]; then
cp /etc/xdg/mango/config.conf "$mango_conf"
fi
# DMS manages these fragments; they must exist before Mango sources them.
for f in colors layout outputs; do
[ -e "$HOME/.config/mango/dms/$f.conf" ] || : > "$HOME/.config/mango/dms/$f.conf"
done
socket="${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}"
HELPERS=""
start_helper() {
"$@" >/dev/null 2>&1 &
HELPERS="$HELPERS $!"
}
cleanup() {
trap - EXIT INT TERM
for pid in $HELPERS; do
kill "$pid" 2>/dev/null || true
done
if command -v systemctl >/dev/null 2>&1; then
systemctl --user stop mango-session.target >/dev/null 2>&1 || true
fi
}
trap cleanup EXIT INT TERM
mango &
MANGO_PID=$!
waited=0
while [ ! -S "$socket" ]; do
if ! kill -0 "$MANGO_PID" 2>/dev/null; then
echo "phoebus-session-mango: mango exited before creating $socket" >&2
exit 1
fi
if [ "$waited" -ge 100 ]; then
echo "phoebus-session-mango: timed out waiting for $socket" >&2
kill "$MANGO_PID" 2>/dev/null || true
exit 1
fi
sleep 0.1
waited=$((waited + 1))
done
# Export the graphical environment to the systemd user manager so user
# services (dms.service, portals) can reach the compositor.
if command -v dbus-update-activation-environment >/dev/null 2>&1; then
dbus-update-activation-environment --systemd \
WAYLAND_DISPLAY XDG_CURRENT_DESKTOP XDG_SESSION_TYPE XDG_RUNTIME_DIR \
QT_QPA_PLATFORM >/dev/null 2>&1 || true
fi
# Exactly one shell: DMS, bound to mango-session.target. Fall back to a direct
# `dms run` only when the user manager is unavailable.
if command -v systemctl >/dev/null 2>&1 \
&& systemctl --user start mango-session.target >/dev/null 2>&1; then
:
elif command -v dms >/dev/null 2>&1; then
start_helper dms run
else
echo "phoebus-session-mango: dms not found; the shell will not start" >&2
fi
# Run until the compositor exits; the EXIT trap stops the shell and helpers.
wait "$MANGO_PID"
"#;
/// Packaged default Mango configuration. DMS writes its managed fragments under
/// `~/.config/mango/dms/`; this file only provides a sane baseline and the
/// DMS keybindings. It is copied to the user's config on first session start.
pub const MANGO_CONFIG_DEFAULT: &str = r#"# Phoebus default Mango configuration (packaged; copied once, then user-owned).
# DMS manages colors/layout/outputs in ~/.config/mango/dms/*.conf.
source=~/.config/mango/dms/colors.conf
source=~/.config/mango/dms/layout.conf
source=~/.config/mango/dms/outputs.conf
env=QT_QPA_PLATFORM,wayland
env=ELECTRON_OZONE_PLATFORM_HINT,auto
env=QT_QPA_PLATFORMTHEME,gtk3
border_radius=12
borderpx=0
focused_opacity=1.0
unfocused_opacity=0.9
gappih=5
gappiv=5
gappoh=5
gappov=5
shadows=1
shadow_only_floating=1
shadows_size=10
shadows_blur=15
layerrule=noanim:1,layer_name:^dms
windowrule=isfloating:1,appid:^com.danklinux.dms$
# Application launchers and DMS panels
bind=SUPER,space,spawn,dms ipc call spotlight toggle
bind=SUPER,v,spawn,dms ipc call clipboard toggle
bind=SUPER,m,spawn,dms ipc call processlist focusOrToggle
bind=SUPER,comma,spawn,dms ipc call settings focusOrToggle
bind=SUPER,n,spawn,dms ipc call notifications toggle
bind=SUPER,Return,spawn,kitty
bind=SUPER,a,spawn,phoebus-assistant
# Security
bind=SUPER+ALT,l,spawn,dms ipc call lock lock
# Audio
bind=NONE,XF86AudioRaiseVolume,spawn,dms ipc call audio increment 3
bind=NONE,XF86AudioLowerVolume,spawn,dms ipc call audio decrement 3
bind=NONE,XF86AudioMute,spawn,dms ipc call audio mute
# Brightness
bind=NONE,XF86MonBrightnessUp,spawn,dms ipc call brightness increment 5
bind=NONE,XF86MonBrightnessDown,spawn,dms ipc call brightness decrement 5
# Session
bind=SUPER+SHIFT,q,killclient,
bind=SUPER+SHIFT,e,quit,
"#;
/// The systemd user target the DMS service is bound to. Using a target means
/// the shell starts and stops with the Mango session and does not run under
/// another desktop.
pub const MANGO_SESSION_TARGET: &str = r#"# Phoebus Mango session target (generated by the installer).
[Unit]
Description=Phoebus Mango + DankMaterialShell session
Requires=graphical-session.target
After=graphical-session.target
"#;
/// The `phoebus-assistant` launcher: opens a terminal for `sys ask`, which
/// proposes typed actions and requires explicit approval. It never grants the
/// model privilege.
pub const PHOEBUS_ASSISTANT_SCRIPT: &str = r#"#!/bin/bash
# Open the Phoebus assistant in a terminal. `sys ask` uses the same typed-action
# broker and approval boundary as the rest of the system.
set -u
if command -v kitty >/dev/null 2>&1; then
exec kitty --title "Phoebus Assistant" -e bash -lc \
'read -rp "Phoebus assistant request: " r; sudo sys ask "$r"; \
echo; read -rp "Press Enter to close"'
fi
echo "phoebus-assistant: kitty is required for the assistant launcher" >&2
exit 1
"#;
/// A Wayland session entry for `/usr/share/wayland-sessions`.
pub fn wayland_session_entry(profile: DesktopProfile) -> Option<(&'static str, String)> {
match profile {
DesktopProfile::Mango => Some((
"phoebus-mango.desktop",
"# Phoebus Mango session (generated by the installer).\n\
[Desktop Entry]\n\
Name=Phoebus (Mango)\n\
Comment=Mango compositor with DankMaterialShell\n\
Exec=/usr/local/bin/phoebus-session-mango\n\
TryExec=/usr/local/bin/phoebus-session-mango\n\
Type=Application\n\
DesktopNames=mango\n"
.to_string(),
)),
DesktopProfile::Dwl | DesktopProfile::Full => Some((
"phoebus-dwl.desktop",
"# Phoebus dwl session (generated by the installer).\n\
[Desktop Entry]\n\
Name=Phoebus (dwl)\n\
Comment=Lightweight dwl Wayland session\n\
Exec=/usr/local/bin/phoebus-session\n\
TryExec=/usr/local/bin/phoebus-session\n\
Type=Application\n\
DesktopNames=phoebus\n"
.to_string(),
)),
_ => None,
}
}
/// Btrfs mount options, matching the proven behavior.
pub fn btrfs_mount_opts(compress: &str, ssd: bool) -> String {
let mut opts = format!("noatime,compress={compress},space_cache=v2");
@ -521,6 +919,27 @@ pub fn fstab(
root_source: &str,
efi_uuid: Option<&str>,
btrfs_opts: &str,
) -> String {
fstab_with_subvols(
config,
root_source,
efi_uuid,
btrfs_opts,
&config.storage.root_subvolume(),
"@var",
)
}
/// As `fstab`, but for an explicit root and `/var` subvolume. A rollback
/// rewrites the restored root's fstab so it mounts its own generation rather
/// than the name the snapshot happened to be captured under.
pub fn fstab_with_subvols(
config: &InstallConfig,
root_source: &str,
efi_uuid: Option<&str>,
btrfs_opts: &str,
root_subvol: &str,
var_subvol: &str,
) -> String {
let mut o = String::new();
o.push_str(&format!("# /etc/fstab: {}\n", config.system.distro_name));
@ -533,9 +952,9 @@ pub fn fstab(
));
}
for (subvol, mountpoint, pass) in [
("@", "/", 1),
(root_subvol, "/", 1),
("@home", "/home", 2),
("@var", "/var", 2),
(var_subvol, "/var", 2),
("@snapshots", "/.snapshots", 2),
("@swap", "/swap", 2),
] {
@ -563,6 +982,23 @@ pub fn kernel_cmdline(
config: &InstallConfig,
luks_uuid: Option<&str>,
root_source: &str,
) -> Result<String, String> {
kernel_cmdline_with_root(
config,
luks_uuid,
root_source,
&config.storage.root_subvolume(),
)
}
/// As `kernel_cmdline`, but selecting an explicit root subvolume. The explicit
/// `rootflags=subvol=` always wins over the Btrfs default subvolume, so a
/// rollback must rewrite it here as well as in the boot loader entry.
pub fn kernel_cmdline_with_root(
config: &InstallConfig,
luks_uuid: Option<&str>,
root_source: &str,
root_subvol: &str,
) -> Result<String, String> {
let mut cmdline = String::new();
if config.is_encrypted() {
@ -578,7 +1014,9 @@ pub fn kernel_cmdline(
}
cmdline.push_str(&format!("root={root_source} "));
}
cmdline.push_str("rootfstype=btrfs rootflags=subvol=@ rw quiet");
cmdline.push_str(&format!(
"rootfstype=btrfs rootflags=subvol={root_subvol} rw quiet"
));
if !config.kernel.console.is_empty() {
cmdline.push(' ');
cmdline.push_str(&config.kernel.console);
@ -792,6 +1230,36 @@ mod tests {
assert!(script.contains("trap cleanup EXIT INT TERM"));
assert!(script.contains("wait \"$DWL_PID\""));
assert!(!script.contains("exec dwl"));
// Idle handling starts with the session.
assert!(script.contains("start_helper phoebus-idle"));
}
#[test]
fn desktop_helpers_cover_launch_lock_idle_and_power() {
let menu = PHOEBUS_MENU_SCRIPT;
assert!(menu.contains("wofi --show drun"));
for action in ["Lock", "Suspend", "Log out", "Reboot", "Shut down"] {
assert!(menu.contains(action), "power menu missing {action}");
}
assert!(menu.contains("systemctl suspend"));
assert!(menu.contains("systemctl reboot"));
assert!(menu.contains("systemctl poweroff"));
assert!(menu.contains("pkill -TERM dwl"));
assert!(PHOEBUS_LOCK_SCRIPT.contains("swaylock -f"));
assert!(PHOEBUS_IDLE_SCRIPT.contains("swayidle"));
assert!(PHOEBUS_IDLE_SCRIPT.contains("before-sleep 'phoebus-lock'"));
assert!(PHOEBUS_IDLE_SCRIPT.contains("systemctl suspend"));
// Network and audio controls are present and actionable.
let waybar = WAYBAR_CONFIG;
assert!(waybar.contains("\"wireplumber\""));
assert!(waybar.contains("\"network\""));
assert!(waybar.contains("nm-connection-editor"));
assert!(waybar.contains("custom/power"));
assert!(waybar.contains("phoebus-menu --power"));
assert!(waybar.contains("battery"));
assert!(waybar.contains("clock"));
}
#[test]
@ -800,4 +1268,78 @@ mod tests {
assert_eq!(cfg.encryption.mode, Encryption::Luks2);
assert!(kernel_cmdline(&cfg, None, "").is_err());
}
#[test]
fn mango_profile_selects_guru_stack_and_keeps_dwl_fallback() {
let pkgs = desktop_packages(DesktopProfile::Mango);
assert!(pkgs.contains(&"gui-wm/mangowm"));
assert!(pkgs.contains(&"gui-apps/dankmaterialshell"));
assert!(pkgs.contains(&"gui-apps/danksearch"));
assert!(pkgs.contains(&"dev-vcs/git"));
// The dwl compositor and helpers remain as a fallback.
assert!(pkgs.contains(&"gui-wm/dwl"));
assert!(pkgs.contains(&"gui-apps/waybar"));
// Portals and the shared Wayland stack are present.
assert!(pkgs.contains(&"sys-apps/xdg-desktop-portal-gtk"));
assert!(pkgs.contains(&"gui-libs/xdg-desktop-portal-wlr"));
// An explicit Mango profile selects the desktop/systemd Gentoo profile.
let mut cfg = InstallConfig::default();
cfg.desktop.profile = DesktopProfile::Mango;
assert_eq!(selected_profile(&cfg), PROFILE_SYSTEMD_DESKTOP);
assert!(uses_guru(&cfg));
assert!(target_services(&cfg).contains(&"bluetooth".to_string()));
}
#[test]
fn mango_keywords_are_scoped_not_global() {
let text = accept_keywords_mango();
for atom in [
"gui-wm/mangowm",
"gui-apps/dankmaterialshell",
"gui-apps/quickshell",
"gui-libs/scenefx",
] {
assert!(text.contains(atom), "missing {atom}");
}
assert!(!text.contains("*/*"));
// No bare global keyword line; `~amd64` may only appear in comments.
assert!(!text.lines().any(|l| l.trim() == "~amd64"));
assert!(!text.contains("ACCEPT_KEYWORDS"));
let repos = guru_repos_conf();
assert!(repos.contains("[guru]"));
assert!(repos.contains("sync-type = git"));
assert!(repos.contains("anongit.gentoo.org"));
}
#[test]
fn mango_session_contract() {
let script = PHOEBUS_MANGO_SESSION_SCRIPT;
// Exactly one compositor and one shell.
assert!(script.contains("mango &"));
assert!(script.contains("dms run"));
assert!(script.contains("mango-session.target"));
// The dwl helpers must never start in the Mango session.
for helper in ["waybar", "mako", "swaybg", "swayidle", "swaylock"] {
assert!(
!script.contains(helper),
"Mango session must not start the dwl helper {helper}"
);
}
// User config is seeded, never overwritten.
assert!(script.contains("if [ ! -e \"$mango_conf\" ]"));
assert!(script.contains("dbus-update-activation-environment --systemd"));
assert!(script.contains("wait \"$MANGO_PID\""));
let config = MANGO_CONFIG_DEFAULT;
assert!(config.contains("dms ipc call lock lock"));
assert!(config.contains("dms ipc call spotlight toggle"));
assert!(config.contains("XF86AudioRaiseVolume"));
assert!(config.contains("XF86MonBrightnessDown"));
assert!(config.contains("phoebus-assistant"));
assert!(config.contains("source=~/.config/mango/dms/"));
let (name, entry) = wayland_session_entry(DesktopProfile::Mango).unwrap();
assert_eq!(name, "phoebus-mango.desktop");
assert!(entry.contains("Exec=/usr/local/bin/phoebus-session-mango"));
}
}

View file

@ -0,0 +1,150 @@
//! A user-queryable transaction log for assistant and `sys` actions.
//!
//! Snapshot history records recovery points; this records *what was run and
//! whether it succeeded*, including failures, so a later session can explain
//! what changed.
use std::path::Path;
use serde::{Deserialize, Serialize};
use crate::error::{CoreError, Result};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct TransactionRecord {
pub created_unix: u64,
/// Where the request came from: `sys` or `assistant`.
pub origin: String,
/// A short human-readable summary.
pub summary: String,
/// The validated typed actions, rendered.
pub actions: Vec<String>,
/// `ok` or a failure description.
pub result: String,
/// The recovery point protecting the change, when one was made.
pub snapshot: Option<String>,
/// The reviewed plan digest, when effects were resolved.
pub digest: Option<String>,
}
impl Default for TransactionRecord {
fn default() -> Self {
Self {
created_unix: 0,
origin: String::new(),
summary: String::new(),
actions: Vec::new(),
result: "ok".into(),
snapshot: None,
digest: None,
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct TransactionLog {
pub records: Vec<TransactionRecord>,
}
const MAX_RECORDS: usize = 500;
impl TransactionLog {
pub fn load(path: &Path) -> Result<Self> {
if !path.exists() {
return Ok(Self::default());
}
let text = std::fs::read_to_string(path).map_err(|e| CoreError::io(path, e))?;
if text.trim().is_empty() {
return Ok(Self::default());
}
Ok(toml::from_str(&text)?)
}
pub fn save(&self, path: &Path) -> Result<()> {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent, e))?;
}
std::fs::write(path, toml::to_string_pretty(self)?).map_err(|e| CoreError::io(path, e))?;
Ok(())
}
/// Append a record, bounding the log so it cannot grow without limit.
pub fn append(&mut self, record: TransactionRecord) {
self.records.push(record);
if self.records.len() > MAX_RECORDS {
let overflow = self.records.len() - MAX_RECORDS;
self.records.drain(0..overflow);
}
}
pub fn render(&self) -> String {
if self.records.is_empty() {
return "no transactions recorded".to_string();
}
let mut out = String::new();
for r in &self.records {
out.push_str(&format!(
"{:<12} {:<10} {:<8} {}",
r.created_unix, r.origin, r.result, r.summary
));
if let Some(snap) = &r.snapshot {
out.push_str(&format!(" [snapshot {snap}]"));
}
out.push('\n');
}
out
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn roundtrip_and_render() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("transactions.toml");
let mut log = TransactionLog::default();
log.append(TransactionRecord {
created_unix: 10,
origin: "assistant".into(),
summary: "install vim".into(),
actions: vec!["install package app-editors/vim".into()],
result: "ok".into(),
snapshot: Some("@-x".into()),
digest: Some("abc".into()),
});
log.save(&path).unwrap();
let loaded = TransactionLog::load(&path).unwrap();
assert_eq!(loaded, log);
assert!(loaded.render().contains("install vim"));
assert!(loaded.render().contains("@-x"));
}
#[test]
fn missing_and_corrupt_are_distinguished() {
let dir = tempfile::tempdir().unwrap();
assert!(TransactionLog::load(&dir.path().join("none.toml"))
.unwrap()
.records
.is_empty());
let path = dir.path().join("bad.toml");
std::fs::write(&path, "not = = toml [[[").unwrap();
assert!(TransactionLog::load(&path).is_err());
}
#[test]
fn log_is_bounded() {
let mut log = TransactionLog::default();
for i in 0..(MAX_RECORDS + 50) {
log.append(TransactionRecord {
created_unix: i as u64,
..Default::default()
});
}
assert_eq!(log.records.len(), MAX_RECORDS);
assert_eq!(log.records.first().unwrap().created_unix, 50);
}
}

View file

@ -6,6 +6,7 @@
use std::path::Path;
use phoebus_core::action::SystemAction;
use phoebus_core::effects::{changed_materially, parse_emerge_pretend, ResolvedPlan};
use crate::auth::DestructiveAuthorization;
use crate::command::CommandSpec;
@ -32,6 +33,78 @@ pub fn preview(action: &SystemAction) -> String {
out
}
/// The Portage arguments that produce a resolved pretend plan for an action,
/// or `None` when the action is not a Portage transaction.
fn pretend_args(action: &SystemAction) -> Option<Vec<String>> {
match action {
SystemAction::InstallPackage { atom } => {
Some(vec!["--pretend".into(), "--color=n".into(), atom.clone()])
}
SystemAction::RemovePackage { atom } => Some(vec![
"--pretend".into(),
"--unmerge".into(),
"--color=n".into(),
atom.clone(),
]),
SystemAction::UpdateSystem => Some(vec![
"--pretend".into(),
"--update".into(),
"--deep".into(),
"--newuse".into(),
"--color=n".into(),
"@world".into(),
]),
_ => None,
}
}
/// Resolve exactly what a package action will do. Non-Portage actions yield an
/// empty plan. A plan's digest can be bound to an approval.
pub fn resolve_effects(exec: &Exec, action: &SystemAction, root: &Path) -> Result<ResolvedPlan> {
let Some(args) = pretend_args(action) else {
return Ok(ResolvedPlan::default());
};
let out = if root == Path::new("/") {
exec.run_capture(CommandSpec::new("sys", "resolve effects", "emerge").args(args))?
} else {
let mut chroot_args = vec![root.to_string_lossy().to_string(), "emerge".to_string()];
chroot_args.extend(args);
exec.run_capture(CommandSpec::new("sys", "resolve effects", "chroot").args(chroot_args))?
};
let mut plan = parse_emerge_pretend(&out.stdout_lossy());
if root.join(snapshot::SNAPSHOT_DIR).is_dir() {
plan.recovery_point = Some("a protective snapshot before the change".into());
}
Ok(plan)
}
/// Execute an action after re-resolving it against the approved digest. If the
/// plan changed materially since review, execution is refused.
pub fn execute_checked(
exec: &Exec,
action: &SystemAction,
auth: Option<&DestructiveAuthorization>,
root: &Path,
approved: Option<&ResolvedPlan>,
) -> Result<ActionOutcome> {
if let Some(approved) = approved {
let current = resolve_effects(exec, action, root)?;
if changed_materially(approved, &current) {
return Err(ExecError::operation(
"sys",
"plan changed",
format!(
"the reviewed plan changed before execution (approved {}, now {}); \
re-run and review again",
&approved.digest[..approved.digest.len().min(12)],
&current.digest[..current.digest.len().min(12)]
),
));
}
}
execute(exec, action, auth, root)
}
pub fn execute(
exec: &Exec,
action: &SystemAction,
@ -42,6 +115,27 @@ pub fn execute(
return Err(ExecError::NotAuthorized(action.describe()));
}
// Rollback moves the root, `/var` and the boot selection together and takes
// its own pre-rollback snapshot, so it must not run through the generic
// protective-snapshot path below.
if let SystemAction::Undo { snapshot } = action {
let auth = auth.ok_or_else(|| ExecError::NotAuthorized(action.describe()))?;
let outcome = crate::rollback::execute(exec, auth, root, snapshot.as_deref())?;
let mut output = format!(
"rollback activated: {} -> {}\nnext boot uses {}\nreboot to complete; \
a known-good previous entry is kept",
outcome.state.target_snapshot, outcome.state.root_subvol, outcome.state.root_subvol
);
for warning in &outcome.warnings {
output.push_str(&format!("\nwarning: {warning}"));
}
return Ok(ActionOutcome {
action: action.clone(),
output,
snapshot: Some(outcome.state.target_snapshot),
});
}
// A protective snapshot must exist before a high-risk change. If the
// snapshots subvolume is present but the snapshot cannot be created, fail
// closed rather than proceed without a recovery point. A system without a
@ -112,6 +206,40 @@ pub fn execute(
)?;
format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy())
}
SystemAction::FlatpakInstall { app_id } => {
exec.run(
CommandSpec::new("sys", "install flatpak", "flatpak")
.args(["install", "-y", "flathub", app_id]),
)?;
format!("installed Flatpak app {app_id}")
}
SystemAction::FlatpakRemove { app_id } => {
exec.run(CommandSpec::new("sys", "remove flatpak", "flatpak").args([
"uninstall",
"-y",
app_id,
]))?;
format!("removed Flatpak app {app_id}")
}
SystemAction::FlatpakList => {
let out = exec.runner.execute(
&CommandSpec::new("sys", "list flatpaks", "flatpak").args([
"list",
"--app",
"--columns=application,version,branch",
]),
)?;
let text = format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy());
if text.trim().is_empty() {
"no Flatpak applications installed".to_string()
} else {
text
}
}
SystemAction::NixPrepare { packages } => {
let prepared = crate::nix::prepare_dev_packages(exec, root, packages)?;
format!("realised Nix development packages: {}", prepared.join(", "))
}
SystemAction::UpdateSystem => {
exec.run(
CommandSpec::new("sys", "update system", "emerge")
@ -125,6 +253,8 @@ pub fn execute(
snapshot_id = Some(record.id.clone());
format!("snapshot created: {}", record.id)
}
// Handled before the match (it has its own snapshot/safety path).
SystemAction::Undo { .. } => "rollback handled by the dedicated path".to_string(),
SystemAction::PrepareUpdates => {
let cores = std::thread::available_parallelism()
.map(|n| n.get() as u32)
@ -141,15 +271,32 @@ pub fn execute(
}
SystemAction::History => {
let history = snapshot::read_history(root)?;
if history.records.is_empty() {
"no transaction history".to_string()
} else {
let mut s = String::new();
if history.records.is_empty() {
s.push_str("no snapshot history\n");
} else {
s.push_str("snapshots:\n");
for r in &history.records {
s.push_str(&format!("{:<40} {:<16?} {}\n", r.id, r.status, r.operation));
}
}
let log = crate::transaction::read(root)?;
s.push_str("transactions:\n");
s.push_str(&log.render());
s
}
SystemAction::RollbackStatus => {
// Reading the state may also promote an activated rollback to
// verified once the restored root is the running root.
let state = crate::rollback::verify(exec, root)?;
format!(
"status: {:?}\nroot subvolume: {}\n/var subvolume: {}\ntarget: {}\nnote: {}",
state.status,
state.root_subvol,
state.var_subvol.as_deref().unwrap_or("(none)"),
state.target_snapshot,
state.note
)
}
};
Ok(ActionOutcome {
@ -291,4 +438,23 @@ mod tests {
assert_eq!(spec.program, "systemctl");
assert_eq!(spec.args, vec!["enable", "sshd"]);
}
#[test]
fn undo_requires_authorization() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let action = SystemAction::Undo { snapshot: None };
let err = execute(&exec, &action, None, Path::new(&exec.root)).unwrap_err();
assert!(matches!(err, ExecError::NotAuthorized(_)));
}
#[test]
fn rollback_status_reports_default_state() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let action = SystemAction::RollbackStatus;
let outcome = execute(&exec, &action, None, Path::new(&exec.root)).unwrap();
assert!(outcome.output.contains("Idle"));
assert!(outcome.snapshot.is_none());
}
}

View file

@ -47,6 +47,7 @@ pub fn load_api_key(path: &Path) -> Result<SecretString> {
pub struct CurlTransport<'a> {
exec: &'a Exec,
api_key: Option<SecretString>,
sandboxed: bool,
}
impl<'a> CurlTransport<'a> {
@ -54,7 +55,18 @@ impl<'a> CurlTransport<'a> {
if let Some(key) = &api_key {
exec.register_secret(key);
}
Self { exec, api_key }
Self {
exec,
api_key,
sandboxed: false,
}
}
/// Run the network call inside the OS-level model sandbox (installed
/// assistant). Fails closed when `systemd-run` is unavailable.
pub fn sandboxed(mut self) -> Self {
self.sandboxed = true;
self
}
}
@ -65,6 +77,9 @@ impl ModelTransport for CurlTransport<'_> {
url: &str,
body: &str,
) -> std::result::Result<String, AiError> {
if self.sandboxed {
return self.send_sandboxed(url, body);
}
let mut request = tempfile::Builder::new()
.prefix("phoebus-ai-request.")
.tempfile()
@ -100,6 +115,34 @@ impl ModelTransport for CurlTransport<'_> {
}
}
impl CurlTransport<'_> {
/// Sandboxed variant: the request body is embedded in the curl config on
/// stdin (never on disk, never in argv), and curl runs inside a hardened,
/// unprivileged unit. `PrivateTmp=yes` is therefore safe.
fn send_sandboxed(&self, url: &str, body: &str) -> std::result::Result<String, AiError> {
let auth = match &self.api_key {
Some(key) => format!("header = \"Authorization: Bearer {}\"\n", key.expose()),
None => String::new(),
};
let escaped = body.replace('\\', "\\\\").replace('"', "\\\"");
let config = format!(
"url = \"{url}\"\n\
header = \"Content-Type: application/json\"\n\
{auth}\
data = \"{escaped}\"\n\
silent\nshow-error\nfail-with-body\nmax-time = 120\n"
);
let out = crate::sandbox::run(
self.exec,
"curl",
&["-sS".into(), "-K".into(), "-".into()],
config.into_bytes(),
)
.map_err(|e| AiError::Provider(e.to_string()))?;
Ok(out.stdout_lossy())
}
}
#[cfg(test)]
mod tests {
use super::*;

View file

@ -161,6 +161,72 @@ pub fn write_recovery_entry(exec: &Exec, config: &InstallConfig) -> Result<()> {
Ok(())
}
/// Write a recovery entry that boots an existing read-only snapshot directly.
///
/// Unlike the `rescue.target` entry derived from the live root, this does not
/// depend on the current root being healthy: it points `rootflags=subvol=` at a
/// snapshot under `@snapshots`, so a broken update can still be repaired.
pub fn write_snapshot_recovery_entry(
exec: &Exec,
config: &InstallConfig,
snapshot_subvol: &str,
) -> Result<()> {
use phoebus_core::boot::{version_key, BlsEntry};
let entries = esp_path(exec, config).join("loader/entries");
if !entries.is_dir() {
return Ok(());
}
let mut newest: Option<BlsEntry> = None;
for entry in std::fs::read_dir(&entries).map_err(|e| ExecError::io(entries.clone(), e))? {
let entry = entry.map_err(|e| ExecError::io(entries.clone(), e))?;
if entry.path().extension().and_then(|e| e.to_str()) != Some("conf") {
continue;
}
let name = entry.file_name().to_string_lossy().to_string();
if name.starts_with("phoebus-") {
continue;
}
let text = match std::fs::read_to_string(entry.path()) {
Ok(t) => t,
Err(_) => continue,
};
let Some(parsed) = BlsEntry::parse(&name, &text) else {
continue;
};
let better = match &newest {
None => true,
Some(current) => {
let a = parsed
.kernel_version()
.map(|v| version_key(&v))
.unwrap_or_default();
let b = current
.kernel_version()
.map(|v| version_key(&v))
.unwrap_or_default();
a > b
}
};
if better {
newest = Some(parsed);
}
}
let Some(best) = newest else {
return Ok(());
};
let subvol = format!("@snapshots/{snapshot_subvol}");
let recovery = best
.with_root_subvol(&subvol)
.map_err(|e| ExecError::operation("boot_install", "rewrite recovery entry", e))?
.with_title("Phoebus Recovery (known-good snapshot)")
.with_option("ro systemd.unit=rescue.target");
let dest = entries.join("phoebus-recovery.conf");
std::fs::write(&dest, recovery.render()).map_err(|e| ExecError::io(dest.clone(), e))?;
exec.logger
.info(format!("wrote snapshot recovery entry -> {}", subvol));
Ok(())
}
pub fn verify(exec: &Exec, config: &InstallConfig) -> Result<()> {
let esp = esp_path(exec, config);
let loader_a = esp.join("EFI/systemd/systemd-bootx64.efi");

View file

@ -55,6 +55,31 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> {
return Ok(());
}
let target = exec.target();
// A launcher for the installed assistant. It opens `sys ask`, which keeps
// privilege and approval in the deterministic broker.
write_script(
&target,
"usr/local/bin/phoebus-assistant",
sysgen::PHOEBUS_ASSISTANT_SCRIPT,
)?;
match config.desktop.profile {
DesktopProfile::Mango => {
write_mango_session(exec, &target)?;
// The dwl session stays installed as a fallback.
write_dwl_session(exec, &target)?;
}
DesktopProfile::Dwl | DesktopProfile::Full => {
write_dwl_session(exec, &target)?;
}
// Minimal has no session entry point.
_ => {}
}
Ok(())
}
fn write_dwl_session(exec: &Exec, target: &phoebus_core::TargetRoot) -> Result<()> {
let script = sysgen::PHOEBUS_SESSION_SCRIPT;
let path = target.resolve("usr/local/bin/phoebus-session")?;
target.write("usr/local/bin/phoebus-session", script)?;
@ -68,6 +93,31 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> {
format!("session script missing after write: {}", path.display()),
));
}
// Launcher/power menu, screen locker and idle daemon. Installing these (and
// the Waybar configuration below) completes the discoverable desktop: a
// user can launch apps, control network/audio, lock and suspend without
// editing configuration by hand.
write_script(
&target,
"usr/local/bin/phoebus-menu",
sysgen::PHOEBUS_MENU_SCRIPT,
)?;
write_script(
&target,
"usr/local/bin/phoebus-lock",
sysgen::PHOEBUS_LOCK_SCRIPT,
)?;
write_script(
&target,
"usr/local/bin/phoebus-idle",
sysgen::PHOEBUS_IDLE_SCRIPT,
)?;
target.write("etc/xdg/waybar/config", sysgen::WAYBAR_CONFIG)?;
target.write("etc/xdg/waybar/style.css", sysgen::WAYBAR_STYLE)?;
if let Some((name, entry)) = sysgen::wayland_session_entry(DesktopProfile::Dwl) {
target.write(&format!("usr/share/wayland-sessions/{name}"), entry)?;
}
exec.logger.info(format!(
"wrote /usr/local/bin/phoebus-session ({})",
path.display()
@ -75,6 +125,53 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> {
Ok(())
}
fn write_mango_session(exec: &Exec, target: &phoebus_core::TargetRoot) -> Result<()> {
write_script(
target,
"usr/local/bin/phoebus-session-mango",
sysgen::PHOEBUS_MANGO_SESSION_SCRIPT,
)?;
target.write("etc/xdg/mango/config.conf", sysgen::MANGO_CONFIG_DEFAULT)?;
target.write(
"usr/lib/systemd/user/mango-session.target",
sysgen::MANGO_SESSION_TARGET,
)?;
// Bind dms.service to the session target when the DMS package provides it;
// the session script falls back to `dms run` otherwise.
let dms_unit = target.resolve("usr/lib/systemd/user/dms.service")?;
if dms_unit.exists() {
let wants = target.resolve("etc/systemd/user/mango-session.target.wants/dms.service")?;
if let Some(parent) = wants.parent() {
std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?;
}
let _ = std::fs::remove_file(&wants);
std::os::unix::fs::symlink(&dms_unit, &wants)
.map_err(|e| ExecError::io(wants.clone(), e))?;
}
if let Some((name, entry)) = sysgen::wayland_session_entry(DesktopProfile::Mango) {
target.write(&format!("usr/share/wayland-sessions/{name}"), entry)?;
}
exec.logger
.info("wrote /usr/local/bin/phoebus-session-mango (Mango + DMS)");
Ok(())
}
fn write_script(target: &phoebus_core::TargetRoot, rel: &str, contents: &str) -> Result<()> {
use std::os::unix::fs::PermissionsExt;
let path = target.resolve(rel)?;
target.write(rel, contents)?;
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
.map_err(|e| ExecError::io(path.clone(), e))?;
if !path.is_file() {
return Err(ExecError::operation(
"desktop",
"write session helper",
format!("helper missing after write: {}", path.display()),
));
}
Ok(())
}
pub fn configure_flatpak(exec: &Exec, config: &InstallConfig) -> Result<()> {
if !config.desktop.flatpak {
return Ok(());
@ -135,6 +232,37 @@ mod tests {
);
}
#[test]
fn session_helpers_and_waybar_config_are_installed() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let mut cfg = InstallConfig::default();
cfg.desktop.profile = DesktopProfile::Dwl;
write_session_script(&exec, &cfg).unwrap();
for rel in [
"usr/local/bin/phoebus-menu",
"usr/local/bin/phoebus-lock",
"usr/local/bin/phoebus-idle",
"etc/xdg/waybar/config",
"etc/xdg/waybar/style.css",
] {
let path = exec.root.join(rel);
assert!(path.is_file(), "{rel} was not installed");
}
use std::os::unix::fs::PermissionsExt;
for rel in [
"usr/local/bin/phoebus-menu",
"usr/local/bin/phoebus-lock",
"usr/local/bin/phoebus-idle",
] {
let mode = std::fs::metadata(exec.root.join(rel))
.unwrap()
.permissions()
.mode();
assert_ne!(mode & 0o111, 0, "{rel} must be executable");
}
}
#[test]
fn no_session_script_for_none_profile() {
let runner = RecordingRunner::new();
@ -143,4 +271,38 @@ mod tests {
write_session_script(&exec, &cfg).unwrap();
assert!(!exec.root.join("usr/local/bin/phoebus-session").exists());
}
#[test]
fn mango_profile_installs_both_sessions_and_no_dwl_helpers_in_mango() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let mut cfg = InstallConfig::default();
cfg.desktop.profile = DesktopProfile::Mango;
write_session_script(&exec, &cfg).unwrap();
for rel in [
"usr/local/bin/phoebus-session-mango",
"usr/local/bin/phoebus-session",
"usr/local/bin/phoebus-assistant",
"etc/xdg/mango/config.conf",
"usr/lib/systemd/user/mango-session.target",
"usr/share/wayland-sessions/phoebus-mango.desktop",
"usr/share/wayland-sessions/phoebus-dwl.desktop",
] {
assert!(exec.root.join(rel).is_file(), "{rel} was not installed");
}
let mango =
std::fs::read_to_string(exec.root.join("usr/local/bin/phoebus-session-mango")).unwrap();
for helper in ["waybar", "mako", "swaybg", "swayidle", "swaylock"] {
assert!(
!mango.contains(helper),
"Mango session must not start {helper}"
);
}
assert!(mango.contains("dms run") || mango.contains("mango-session.target"));
let dwl = std::fs::read_to_string(exec.root.join("usr/local/bin/phoebus-session")).unwrap();
assert!(
dwl.contains("dwl &"),
"dwl fallback session must be present"
);
}
}

View file

@ -20,10 +20,13 @@ pub mod nix;
pub mod opencode;
pub mod portage;
pub mod probe;
pub mod rollback;
pub mod sandbox;
pub mod services;
pub mod snapshot;
pub mod stage3;
pub mod storage;
pub mod transaction;
pub mod update;
pub mod users;

View file

@ -26,6 +26,25 @@ fn nix_store_bin() -> String {
format!("/nix/store/{NIX_STORE_NAME}/bin/nix-store")
}
/// The generated `/etc/nix/nix.conf`.
///
/// Build isolation is on and does not silently fall back: the Nix sandbox uses
/// Linux user namespaces, which the Phoebus kernel enables. `min-free` and
/// `max-free` bound the store so it cannot fill the root filesystem, and
/// `auto-optimise-store` deduplicates.
pub fn nix_conf() -> &'static str {
"# Phoebus: Nix as a second package lane (developer tools only).\n\
build-users-group = nixbld\n\
sandbox = true\n\
sandbox-fallback = false\n\
auto-optimise-store = true\n\
min-free = 1073741824\n\
max-free = 10737418240\n\
experimental-features = nix-command flakes\n\
substituters = https://cache.nixos.org\n\
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\n"
}
fn target_path(root: &Path, rel: &str) -> PathBuf {
root.join(rel)
}
@ -148,17 +167,10 @@ fn bootstrap(exec: &Exec, root: &Path, tarball: &Path) -> Result<()> {
);
}
// Configuration and profile wiring.
write_file(
root,
"etc/nix/nix.conf",
"# Phoebus: Nix as a second package lane.\n\
build-users-group = nixbld\n\
sandbox = false\n\
experimental-features = nix-command flakes\n\
substituters = https://cache.nixos.org\n\
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\n",
)?;
// Configuration and profile wiring. Build isolation is enabled: the Nix
// sandbox uses user namespaces and fails closed rather than silently
// building unsandboxed, so a compromised build cannot reach the host.
write_file(root, "etc/nix/nix.conf", nix_conf())?;
let profile = "nix/var/nix/profiles";
std::fs::create_dir_all(target_path(root, profile))
.map_err(|e| ExecError::io(target_path(root, profile), e))?;
@ -200,6 +212,85 @@ fn bootstrap(exec: &Exec, root: &Path, tarball: &Path) -> Result<()> {
Ok(())
}
/// Whether the Nix store is present in the target.
pub fn installed(root: &Path) -> bool {
target_path(root, &format!("nix/store/{NIX_STORE_NAME}")).is_dir()
}
/// Remove Nix's system integration: the daemon units and profile wiring. The
/// store is only deleted when `purge` is set, because the store may back
/// user environments that should be removed deliberately.
pub fn remove(exec: &Exec, root: &Path, purge: bool) -> Result<()> {
let _ = crate::portage::chroot(exec, root, "systemctl", &["disable", "nix-daemon.service"]);
let _ = crate::portage::chroot(exec, root, "systemctl", &["disable", "nix-daemon.socket"]);
for rel in [
"etc/systemd/system/nix-daemon.service",
"etc/systemd/system/nix-daemon.socket",
"etc/systemd/system/multi-user.target.wants/nix-daemon.service",
"etc/systemd/system/sockets.target.wants/nix-daemon.socket",
"root/.nix-profile",
"etc/profile.d/nix.sh",
] {
let path = target_path(root, rel);
let _ = std::fs::remove_file(&path);
}
let _ = std::fs::remove_file(target_path(root, "nix/var/nix/profiles/default"));
if purge {
let nix_dir = target_path(root, "nix");
if let Err(e) = std::fs::remove_dir_all(&nix_dir) {
if e.kind() != std::io::ErrorKind::NotFound {
return Err(ExecError::io(nix_dir, e));
}
}
}
exec.logger.info(format!(
"removed Nix integration{}",
if purge { " (store purged)" } else { "" }
));
Ok(())
}
/// Run the Nix garbage collector, bounded by the `min-free`/`max-free` settings
/// in `/etc/nix/nix.conf`.
pub fn gc(exec: &Exec, root: &Path) -> Result<()> {
let binary = format!("{}/bin/nix-store", "/nix/var/nix/profiles/default");
crate::portage::chroot(exec, root, &binary, &["--gc"])?;
exec.logger.info("Nix store garbage collection complete");
Ok(())
}
/// Realise a bounded set of development packages so they are available offline.
///
/// Each entry is a bare nixpkgs attribute name (`nodejs`, `python312`); URLs and
/// flake references are refused, so the assistant cannot make Nix evaluate
/// arbitrary remote inputs.
pub fn prepare_dev_packages(exec: &Exec, root: &Path, packages: &[String]) -> Result<Vec<String>> {
let mut prepared = Vec::new();
let binary = "/nix/var/nix/profiles/default/bin/nix";
for package in packages {
if !valid_nix_attribute(package) {
return Err(ExecError::operation(
"nix",
"prepare package",
format!("invalid nixpkgs attribute: {package}"),
));
}
crate::portage::chroot(
exec,
root,
binary,
&["shell", &format!("nixpkgs#{package}"), "-c", "true"],
)?;
prepared.push(package.clone());
}
Ok(prepared)
}
/// A bounded nixpkgs attribute: no slashes, URLs, or flake references.
pub fn valid_nix_attribute(value: &str) -> bool {
phoebus_core::action::valid_nix_attribute(value)
}
fn write_file(root: &Path, rel: &str, contents: &str) -> Result<()> {
let path = target_path(root, rel);
if let Some(parent) = path.parent() {
@ -257,4 +348,40 @@ mod tests {
assert!(!crate::opencode::checksum_ok(&file, &"0".repeat(64)).unwrap());
assert!(!crate::opencode::checksum_ok(&file, "deadbeef").unwrap());
}
#[test]
fn conf_enables_enforced_sandbox_and_store_bounds() {
let conf = nix_conf();
assert!(conf.contains("sandbox = true"));
assert!(conf.contains("sandbox-fallback = false"));
assert!(conf.contains("min-free ="));
assert!(conf.contains("max-free ="));
assert!(!conf.contains("sandbox = false"));
}
#[test]
fn nixpkg_attribute_is_bounded() {
assert!(valid_nix_attribute("nodejs"));
assert!(valid_nix_attribute("python312"));
assert!(valid_nix_attribute("gcc13"));
assert!(!valid_nix_attribute(""));
assert!(!valid_nix_attribute("github:owner/repo"));
assert!(!valid_nix_attribute("nixpkgs#x/y"));
assert!(!valid_nix_attribute("a b"));
}
#[test]
fn remove_unlinks_units_and_optionally_purges() {
let runner = RecordingRunner::new();
let exec = make_exec(runner, false);
let root = Path::new(&exec.root);
std::fs::create_dir_all(root.join("etc/systemd/system")).unwrap();
std::fs::write(root.join("etc/systemd/system/nix-daemon.service"), "x").unwrap();
std::fs::create_dir_all(root.join("nix/store")).unwrap();
remove(&exec, root, false).unwrap();
assert!(!root.join("etc/systemd/system/nix-daemon.service").exists());
assert!(root.join("nix/store").exists());
remove(&exec, root, true).unwrap();
assert!(!root.join("nix").exists());
}
}

View file

@ -26,14 +26,51 @@ pub fn write_config(exec: &Exec, config: &InstallConfig, hardware: &HardwareRepo
"etc/portage/package.use/phoebus",
sysgen::package_use(config),
)?;
let mut keywords = sysgen::accept_keywords_policy();
if sysgen::uses_guru(config) {
// The Mango + DankMaterialShell stack lives in GURU and is `~amd64`.
// The keyword set is scoped to those packages and the GURU-only
// dependency; it is never a global `~amd64` switch.
root.write(
"etc/portage/package.accept_keywords/phoebus",
sysgen::accept_keywords_policy(),
"etc/portage/repos.conf/guru.conf",
sysgen::guru_repos_conf(),
)?;
keywords.push('\n');
keywords.push_str(&sysgen::accept_keywords_mango());
}
root.write("etc/portage/package.accept_keywords/phoebus", keywords)?;
exec.logger.info("wrote Portage configuration");
Ok(())
}
/// The packages that must be present before the GURU overlay (git-only) can be
/// synced. `dev-vcs/git` is installed from the main tree first.
pub fn guru_bootstrap_packages() -> Vec<&'static str> {
vec!["dev-vcs/git"]
}
/// Sync the GURU overlay after `dev-vcs/git` is available. No-op when the
/// selected profile does not use GURU.
pub fn sync_guru(exec: &Exec, root: &Path, config: &InstallConfig) -> Result<()> {
if !sysgen::uses_guru(config) {
return Ok(());
}
let mut last_err = None;
for attempt in 1..=3 {
match chroot(exec, root, "emaint", &["sync", "-r", "guru"]) {
Ok(()) => return Ok(()),
Err(e) => {
exec.logger
.warn(format!("guru sync attempt {attempt} failed: {e}"));
last_err = Some(e);
}
}
}
Err(last_err.unwrap_or_else(|| {
ExecError::operation("portage_configure", "emaint sync -r guru", "sync failed")
}))
}
pub fn select_profile(exec: &Exec, config: &InstallConfig) -> Result<()> {
let root = exec.target();
let link = root.etc("portage/make.profile")?;

View file

@ -0,0 +1,747 @@
//! Coordinated rollback and recovery.
//!
//! A rollback moves four things together, because moving only one of them
//! produces an inconsistent or unbootable system:
//!
//! 1. the root subvolume (the running root is preserved and a writable clone of
//! the chosen snapshot becomes the new root generation);
//! 2. the separately mounted `/var` volume, which holds the Portage package
//! database and update state;
//! 3. the kernel command line / fstab in the restored root (`rootflags=subvol=`
//! always wins over the Btrfs default subvolume, so both are edited);
//! 4. the boot entries on the ESP, including a known-good "previous" entry and
//! a recovery entry that boots a snapshot directly, so a broken normal boot
//! is still repairable.
//!
//! An interruption is safe: the safety snapshot is written first, the boot
//! entries are only switched at the end, and the persisted state lets a re-run
//! finish. `sys undo` is exposed only after this path is verified on a
//! disposable VM.
use std::path::{Path, PathBuf};
use phoebus_core::boot::{choose_entry_for_versions, kernel_versions_from_module_dirs, BlsEntry};
use phoebus_core::rollback::{
esp_mount_from_mounts, pre_rollback_snapshot_name, restore_root_name, restore_var_name,
rewrite_fstab_subvol, root_device_from_mounts, snapshot_retention_deletions,
snapshot_top_level_path, RollbackState, RollbackStatus, DEFAULT_KEEP_SNAPSHOTS,
};
use phoebus_core::snapshot::{SnapshotHistory, SnapshotStatus};
use crate::auth::DestructiveAuthorization;
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
use crate::exec::Exec;
use crate::snapshot;
pub const STATE_REL: &str = "var/lib/phoebus/rollback-state.toml";
pub fn state_path(root: &Path) -> PathBuf {
root.join(STATE_REL)
}
pub fn load_state(root: &Path) -> RollbackState {
let path = state_path(root);
if !path.exists() {
return RollbackState::default();
}
std::fs::read_to_string(&path)
.ok()
.and_then(|t| toml::from_str(&t).ok())
.unwrap_or_default()
}
pub fn save_state(exec: &Exec, root: &Path, state: &RollbackState) -> Result<()> {
let path = state_path(root);
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?;
}
let text = toml::to_string_pretty(state)
.map_err(|e| ExecError::operation("rollback", "serialize state", e.to_string()))?;
std::fs::write(&path, text).map_err(|e| ExecError::io(path.clone(), e))?;
exec.logger
.info(format!("rollback state -> {}", path.display()));
Ok(())
}
/// The device and ESP mount used to stage a rollback.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RollbackEnv {
pub root_device: String,
pub esp_mount: String,
}
/// Determine the root device and ESP from `/proc/self/mounts` text.
pub fn detect_env(mounts: &str) -> Result<RollbackEnv> {
let root_device = root_device_from_mounts(mounts)
.ok_or_else(|| ExecError::operation("rollback", "detect root", "no root mount found"))?;
let esp_mount = esp_mount_from_mounts(mounts).unwrap_or_else(|| "/efi".to_string());
Ok(RollbackEnv {
root_device,
esp_mount,
})
}
/// A resolved rollback target.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RollbackPlan {
pub target_snapshot: String,
pub target_var_snapshot: Option<String>,
pub root_subvol: String,
pub var_subvol: Option<String>,
pub previous_root: String,
pub ts: u64,
pub reason: String,
}
/// Resolve the snapshot to restore. With `snapshot_id` unset the newest
/// committed snapshot is used. A missing or uncommitted id is refused.
pub fn plan(
root: &Path,
history: &SnapshotHistory,
snapshot_id: Option<&str>,
ts: u64,
) -> Result<RollbackPlan> {
let record = match snapshot_id {
Some(id) => history
.records
.iter()
.rev()
.find(|r| r.id == id)
.ok_or_else(|| {
ExecError::operation(
"rollback",
"select snapshot",
format!("no snapshot with id `{id}`"),
)
})?,
None => phoebus_core::rollback::latest_committed(history).ok_or_else(|| {
ExecError::operation(
"rollback",
"select snapshot",
"no committed snapshot to restore",
)
})?,
};
if record.status != SnapshotStatus::Committed {
return Err(ExecError::operation(
"rollback",
"select snapshot",
format!(
"snapshot `{}` is {:?}, not committed; refusing to restore",
record.id, record.status
),
));
}
let snapshot_dir = snapshot::snapshots_path(root).join(&record.snapshot_subvol);
if !snapshot_dir.exists() {
return Err(ExecError::operation(
"rollback",
"select snapshot",
format!("snapshot subvolume {} is missing", snapshot_dir.display()),
));
}
let var_subvol = record.var_snapshot.as_ref().map(|_| restore_var_name(ts));
Ok(RollbackPlan {
target_snapshot: record.snapshot_subvol.clone(),
target_var_snapshot: record.var_snapshot.clone(),
root_subvol: restore_root_name(ts),
var_subvol,
previous_root: "@".to_string(),
ts,
reason: record.operation.clone(),
})
}
#[derive(Debug)]
pub struct RollbackOutcome {
pub state: RollbackState,
pub warnings: Vec<String>,
}
fn read_entries(entries_dir: &Path) -> Vec<BlsEntry> {
let mut out = Vec::new();
let Ok(dir) = std::fs::read_dir(entries_dir) else {
return out;
};
for entry in dir.flatten() {
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("conf") {
continue;
}
let name = entry.file_name().to_string_lossy().to_string();
if let Ok(text) = std::fs::read_to_string(&path) {
if let Some(parsed) = BlsEntry::parse(&name, &text) {
out.push(parsed);
}
}
}
out.sort_by(|a, b| a.file_name.cmp(&b.file_name));
out
}
/// Find the subvolume id for a path from `btrfs subvolume list -o` output.
pub fn subvol_id_for_path(list_output: &str, target: &str) -> Option<String> {
for line in list_output.lines() {
// e.g. "ID 256 gen 10 top level 5 path @restore-20260101T000000"
let fields: Vec<&str> = line.split_whitespace().collect();
let id = fields
.iter()
.position(|f| *f == "ID")
.and_then(|i| fields.get(i + 1));
let path = fields
.iter()
.position(|f| *f == "path")
.and_then(|i| fields.get(i + 1));
if let (Some(id), Some(path)) = (id, path) {
if *path == target {
return Some((*id).to_string());
}
}
}
None
}
/// Perform an already-resolved rollback. Exposed for tests with an explicit
/// environment; `execute` wraps it with real mount detection.
pub fn run_with_env(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
env: &RollbackEnv,
plan: &RollbackPlan,
) -> Result<RollbackOutcome> {
let mut warnings = Vec::new();
// 0. A recovery point for the current state, before anything moves.
let safety = snapshot::create_set_and_record(exec, auth, root, "/", "pre-rollback")?;
exec.logger
.info(format!("pre-rollback snapshot: {}", safety.id));
// 1. Stage the Btrfs top level so subvolumes can be cloned as siblings.
let stage = exec.state_dir.join("rollback-stage");
std::fs::create_dir_all(&stage).map_err(|e| ExecError::io(stage.clone(), e))?;
exec.run(
CommandSpec::new("rollback", "mount Btrfs top level", "mount")
.args(["-o", "subvolid=5"])
.arg(&env.root_device)
.arg(stage.to_string_lossy().to_string()),
)?;
let result = activate(exec, root, env, plan, &stage, &mut warnings);
// Always try to leave the staging mount cleanly.
let _ = exec.run(
CommandSpec::new("rollback", "unmount top level", "umount")
.arg(stage.to_string_lossy().to_string()),
);
result?;
let state = RollbackState {
status: RollbackStatus::Activated,
generation: plan.ts,
target_snapshot: plan.target_snapshot.clone(),
target_var_snapshot: plan.target_var_snapshot.clone(),
previous_root: plan.previous_root.clone(),
root_subvol: plan.root_subvol.clone(),
var_subvol: plan.var_subvol.clone(),
boot_entry: Some("phoebus-current.conf".into()),
started_unix: plan.ts,
finished_unix: plan.ts,
note: format!("restore from {} ({})", plan.target_snapshot, plan.reason),
};
save_state(exec, root, &state)?;
exec.logger.info(format!(
"rollback activated: next boot uses {}",
plan.root_subvol
));
Ok(RollbackOutcome { state, warnings })
}
fn activate(
exec: &Exec,
root: &Path,
_env: &RollbackEnv,
plan: &RollbackPlan,
stage: &Path,
warnings: &mut Vec<String>,
) -> Result<()> {
// 2. Writable clones of the target snapshot(s) as new root generations.
let root_src = stage.join(snapshot_top_level_path(&plan.target_snapshot));
let root_dst = stage.join(&plan.root_subvol);
if root_dst.join("etc/fstab").exists() {
// Resuming an interrupted activation: the clone already exists.
exec.logger.warn(format!(
"restored root {} already staged; resuming",
root_dst.display()
));
} else if root_dst.exists() {
return Err(ExecError::operation(
"rollback",
"clone root",
format!("{} already exists", root_dst.display()),
));
} else {
exec.run(
CommandSpec::new("rollback", "clone root snapshot", "btrfs")
.args(["subvolume", "snapshot"])
.arg(root_src.to_string_lossy().to_string())
.arg(root_dst.to_string_lossy().to_string()),
)?;
}
if let (Some(var_target), Some(var_subvol)) = (&plan.target_var_snapshot, &plan.var_subvol) {
let var_src = stage.join(snapshot_top_level_path(var_target));
let var_dst = stage.join(var_subvol);
if !var_dst.exists() {
exec.run(
CommandSpec::new("rollback", "clone /var snapshot", "btrfs")
.args(["subvolume", "snapshot"])
.arg(var_src.to_string_lossy().to_string())
.arg(var_dst.to_string_lossy().to_string()),
)?;
}
}
// 3. fstab of the restored root must mount its own generation.
let fstab = root_dst.join("etc/fstab");
let text = std::fs::read_to_string(&fstab).map_err(|e| ExecError::io(fstab.clone(), e))?;
let mut rewritten = rewrite_fstab_subvol(&text, "/", &plan.root_subvol);
if let Some(var) = &plan.var_subvol {
if phoebus_core::rollback::fstab_has_mountpoint(&rewritten, "/var") {
rewritten = rewrite_fstab_subvol(&rewritten, "/var", var);
} else {
warnings.push("restored root has no /var fstab entry".into());
}
}
std::fs::write(&fstab, rewritten).map_err(|e| ExecError::io(fstab.clone(), e))?;
// 4. Select a kernel whose modules exist in the restored root.
let modules_dir = root_dst.join("lib/modules");
let modules: Vec<String> = std::fs::read_dir(&modules_dir)
.map(|dir| {
dir.flatten()
.map(|e| e.file_name().to_string_lossy().to_string())
.collect()
})
.unwrap_or_default();
let versions = kernel_versions_from_module_dirs(&modules);
let esp = root.join(_env.esp_mount.trim_start_matches('/'));
let entries_dir = esp.join("loader/entries");
let entries = read_entries(&entries_dir);
let chosen = choose_entry_for_versions(&entries, &versions).or_else(|| {
entries.iter().max_by_key(|e| {
e.kernel_version()
.map(|v| phoebus_core::boot::version_key(&v))
})
});
let Some(chosen) = chosen else {
return Err(ExecError::operation(
"rollback",
"select kernel",
"no boot entry available on the ESP",
));
};
if !versions
.iter()
.any(|v| Some(v) == chosen.kernel_version().as_ref())
{
warnings.push(format!(
"no boot entry matched the restored modules; using {}",
chosen.file_name
));
}
// 5. Write the current, previous and recovery entries.
let current = chosen
.with_root_subvol(&plan.root_subvol)
.map_err(|e| ExecError::operation("rollback", "rewrite current entry", e))?
.with_title("Phoebus OS");
write_entry(&entries_dir, "phoebus-current.conf", &current)?;
let newest = entries.iter().max_by_key(|e| {
e.kernel_version()
.map(|v| phoebus_core::boot::version_key(&v))
});
if let Some(previous) = newest {
let previous = previous.with_title("Phoebus OS (previous)");
write_entry(&entries_dir, "phoebus-previous.conf", &previous)?;
}
let recovery = chosen
.with_root_subvol(&snapshot_top_level_path(&plan.target_snapshot))
.map_err(|e| ExecError::operation("rollback", "rewrite recovery entry", e))?
.with_option("systemd.unit=rescue.target")
.with_title("Phoebus Recovery");
write_entry(&entries_dir, "phoebus-recovery.conf", &recovery)?;
// 6. Make the restored root the default, for both the explicit argument and
// a mount without one.
set_default(exec, stage, &plan.root_subvol)?;
if let Some(var) = &plan.var_subvol {
let _ = set_default(exec, stage, var);
}
write_loader_default(&esp, "phoebus-current.conf")?;
// 7. Flush so a forced poweroff right after activation cannot lose the
// rewritten fstab or boot entries.
exec.run(CommandSpec::new("rollback", "flush restored root", "sync"))?;
Ok(())
}
fn write_entry(dir: &Path, name: &str, entry: &BlsEntry) -> Result<()> {
std::fs::create_dir_all(dir).map_err(|e| ExecError::io(dir.to_path_buf(), e))?;
let path = dir.join(name);
std::fs::write(&path, entry.render()).map_err(|e| ExecError::io(path, e))
}
fn set_default(exec: &Exec, stage: &Path, subvol: &str) -> Result<()> {
let out = exec.run_capture(
CommandSpec::new("rollback", "list subvolumes", "btrfs")
.args(["subvolume", "list", "-o"])
.arg(stage.to_string_lossy().to_string()),
)?;
let Some(id) = subvol_id_for_path(&out.stdout_lossy(), subvol) else {
exec.logger
.warn(format!("subvolume {subvol} not found for set-default"));
return Ok(());
};
exec.run(
CommandSpec::new("rollback", "set default subvolume", "btrfs")
.args(["subvolume", "set-default", &id])
.arg(stage.to_string_lossy().to_string()),
)?;
Ok(())
}
fn write_loader_default(esp: &Path, entry: &str) -> Result<()> {
let dir = esp.join("loader");
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let text = format!(
"# systemd-boot configuration\ndefault {entry}\ntimeout 5\nconsole-mode keep\neditor no\n"
);
let path = dir.join("loader.conf");
std::fs::write(&path, text).map_err(|e| ExecError::io(path, e))
}
/// Detect the environment from the running system and perform a rollback.
pub fn execute(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
snapshot_id: Option<&str>,
) -> Result<RollbackOutcome> {
let mounts = std::fs::read_to_string("/proc/self/mounts")
.map_err(|e| ExecError::io(PathBuf::from("/proc/self/mounts"), e))?;
let env = detect_env(&mounts)?;
let history = snapshot::read_history(root)?;
let ts = now_unix();
let plan = plan(root, &history, snapshot_id, ts)?;
exec.logger.info(format!(
"rollback target {} -> {} (reason: {})",
plan.target_snapshot, plan.root_subvol, plan.reason
));
let outcome = run_with_env(exec, auth, root, &env, &plan)?;
// Bound the recovery points now that the new root is selected.
let protect = outcome.state.protected_subvols();
if let Err(e) =
snapshot::apply_retention_with(exec, auth, root, DEFAULT_KEEP_SNAPSHOTS, &protect)
{
exec.logger.warn(format!("snapshot retention failed: {e}"));
}
Ok(outcome)
}
/// Mark an activated rollback as verified once the restored root is mounted.
pub fn verify(exec: &Exec, root: &Path) -> Result<RollbackState> {
let mut state = load_state(root);
if state.status != RollbackStatus::Activated {
return Ok(state);
}
let mounts = std::fs::read_to_string("/proc/self/mounts").unwrap_or_default();
let current = current_root_subvol(&mounts);
if current.as_deref() == Some(state.root_subvol.as_str()) {
state.status = RollbackStatus::Verified;
state.finished_unix = now_unix();
state.note = format!("verified on {}", state.root_subvol);
save_state(exec, root, &state)?;
exec.logger.info("rollback verified on the restored root");
if let Err(e) = snapshot::apply_retention_with(
exec,
&authorize_internal("verify"),
root,
DEFAULT_KEEP_SNAPSHOTS,
&state.protected_subvols(),
) {
exec.logger
.warn(format!("post-verify retention failed: {e}"));
}
}
Ok(state)
}
/// The root subvolume currently mounted at `/`, from `/proc/self/mounts` text.
pub fn current_root_subvol(mounts: &str) -> Option<String> {
for line in mounts.lines() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() >= 4 && fields[1] == "/" {
for token in fields[3].split(',') {
if let Some(v) = token.strip_prefix("subvol=") {
return Some(v.trim_start_matches('/').to_string());
}
}
}
}
None
}
/// A token for internal maintenance that is not user-facing.
fn authorize_internal(reason: &str) -> DestructiveAuthorization {
crate::auth::authorize(&crate::auth::AutoConfirm, "rollback", reason)
.expect("auto-confirm never fails")
}
fn now_unix() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0)
}
/// The names of root generations that retention should prune. Kept here so the
/// policy is one place.
pub fn root_generation_deletions(
generations: &[String],
keep: usize,
protect: &[String],
) -> Vec<String> {
snapshot_retention_deletions(
&SnapshotHistory {
records: generations
.iter()
.map(|g| phoebus_core::snapshot::SnapshotRecord {
id: g.clone(),
created_unix: 0,
operation: String::new(),
source_subvol: "@".into(),
snapshot_subvol: g.clone(),
var_snapshot: None,
status: SnapshotStatus::Committed,
})
.collect(),
},
keep,
protect,
)
}
/// The pre-rollback safety snapshot names for a timestamp (used by tests and
/// diagnostics).
pub fn safety_names(ts: u64) -> (String, String) {
(
pre_rollback_snapshot_name(ts),
phoebus_core::rollback::pre_rollback_var_snapshot_name(ts),
)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::RecordingRunner;
use crate::log::Logger;
use phoebus_core::snapshot::SnapshotRecord;
use phoebus_core::Redactor;
fn make_exec(runner: RecordingRunner) -> Exec {
let path = tempfile::tempdir().unwrap().keep();
let logger = Logger::open(path.join("l.log"), Redactor::new(), false);
Exec::new(Box::new(runner), logger, false, path.join("root"), path)
}
fn committed(id: &str, var: Option<&str>) -> SnapshotRecord {
SnapshotRecord {
id: id.into(),
created_unix: 1_700_000_000,
operation: "sys update".into(),
source_subvol: "@".into(),
snapshot_subvol: id.into(),
var_snapshot: var.map(|v| v.to_string()),
status: SnapshotStatus::Committed,
}
}
fn auth() -> crate::auth::DestructiveAuthorization {
crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap()
}
#[test]
fn detect_env_finds_device_and_esp() {
let mounts =
"/dev/mapper/cryptroot / btrfs rw,subvol=/@ 0 0\n/dev/vda1 /efi vfat umask=0077 0 0\n";
let env = detect_env(mounts).unwrap();
assert_eq!(env.root_device, "/dev/mapper/cryptroot");
assert_eq!(env.esp_mount, "/efi");
assert!(detect_env("proc /proc proc rw 0 0\n").is_err());
}
#[test]
fn plan_refuses_uncommitted_and_missing() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let root = Path::new(&exec.root);
let history = SnapshotHistory {
records: vec![SnapshotRecord {
status: SnapshotStatus::Created,
..committed("@-x", None)
}],
};
assert!(plan(root, &history, None, 1).is_err());
let history = SnapshotHistory {
records: vec![committed("@-x", Some("@var-x"))],
};
std::fs::create_dir_all(snapshot::snapshots_path(root).join("@-x")).unwrap();
let p = plan(root, &history, Some("@-x"), 1_700_000_000).unwrap();
assert_eq!(p.root_subvol, "@restore-20231114T221320");
assert_eq!(p.var_subvol.as_deref(), Some("@varrestore-20231114T221320"));
assert!(plan(root, &history, Some("@missing"), 1).is_err());
}
#[test]
fn activate_rewrites_fstab_and_boot_entries() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
let ts = 1_700_000_000u64;
let plan = RollbackPlan {
target_snapshot: "@-20231114T221320-sys-update".into(),
target_var_snapshot: Some("@var-20231114T221320-sys-update".into()),
root_subvol: restore_root_name(ts),
var_subvol: Some(restore_var_name(ts)),
previous_root: "@".into(),
ts,
reason: "sys update".into(),
};
// Simulate the state a real clone would have on the staging mount.
let stage = exec.state_dir.join("rollback-stage");
let restored = stage.join(&plan.root_subvol);
std::fs::create_dir_all(restored.join("etc")).unwrap();
std::fs::create_dir_all(restored.join("lib/modules/6.12.9")).unwrap();
std::fs::write(
restored.join("etc/fstab"),
"/dev/mapper/cryptroot\t/\tbtrfs\tnoatime,subvol=@\t0\t1\n\
/dev/mapper/cryptroot\t/var\tbtrfs\tnoatime,subvol=@var\t0\t2\n",
)
.unwrap();
// ESP entries, including a newer kernel with no modules in the restore.
let entries = root.join("efi/loader/entries");
std::fs::create_dir_all(&entries).unwrap();
std::fs::write(
entries.join("id-6.12.9.conf"),
"title Gentoo Linux\nlinux /id/6.12.9/linux\ninitrd /id/6.12.9/initrd\noptions root=/dev/mapper/cryptroot rootflags=subvol=@ rw\n",
)
.unwrap();
std::fs::write(
entries.join("id-6.12.10.conf"),
"title Gentoo Linux\nlinux /id/6.12.10/linux\ninitrd /id/6.12.10/initrd\noptions root=/dev/mapper/cryptroot rootflags=subvol=@ rw\n",
)
.unwrap();
let env = RollbackEnv {
root_device: "/dev/mapper/cryptroot".into(),
esp_mount: "/efi".into(),
};
let mut warnings = Vec::new();
activate(&exec, root, &env, &plan, &stage, &mut warnings).unwrap();
// fstab inside the restored root points at its own generation.
let fstab = std::fs::read_to_string(restored.join("etc/fstab")).unwrap();
assert!(fstab.contains(&format!("subvol={}\t0\t1", plan.root_subvol)));
assert!(fstab.contains(&format!(
"subvol={}\t0\t2",
plan.var_subvol.clone().unwrap()
)));
// The current entry selects the new root and the matching kernel.
let current = std::fs::read_to_string(entries.join("phoebus-current.conf")).unwrap();
assert!(current.contains("title Phoebus OS\n"));
assert!(current.contains(&format!("rootflags=subvol={}", plan.root_subvol)));
assert!(current.contains("/id/6.12.9/linux"));
// A previous entry is retained for a known-good boot choice.
let previous = std::fs::read_to_string(entries.join("phoebus-previous.conf")).unwrap();
assert!(previous.contains("Phoebus OS (previous)"));
assert!(previous.contains("subvol=@ "));
// Recovery boots the snapshot directly into rescue.
let recovery = std::fs::read_to_string(entries.join("phoebus-recovery.conf")).unwrap();
assert!(recovery.contains(&format!(
"subvol={}",
snapshot_top_level_path(&plan.target_snapshot)
)));
assert!(recovery.contains("systemd.unit=rescue.target"));
// loader.conf defaults to the new entry, and the top level was unmounted.
let loader = std::fs::read_to_string(root.join("efi/loader/loader.conf")).unwrap();
assert!(loader.contains("default phoebus-current.conf"));
let recorded = runner.recorded();
let programs: Vec<&str> = recorded.iter().map(|s| s.program.as_str()).collect();
assert!(programs.contains(&"sync"));
}
#[test]
fn activate_refuses_to_clobber_an_existing_generation() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let root = Path::new(&exec.root);
let plan = RollbackPlan {
target_snapshot: "@-x".into(),
target_var_snapshot: None,
root_subvol: "@restore-20231114T221320".into(),
var_subvol: None,
previous_root: "@".into(),
ts: 1_700_000_000,
reason: "x".into(),
};
let stage = exec.state_dir.join("rollback-stage");
std::fs::create_dir_all(stage.join(&plan.root_subvol)).unwrap();
let mut warnings = Vec::new();
let err = activate(
&exec,
root,
&RollbackEnv {
root_device: "/dev/x".into(),
esp_mount: "/efi".into(),
},
&plan,
&stage,
&mut warnings,
)
.unwrap_err();
assert!(err.to_string().contains("already exists"));
}
#[test]
fn subvol_id_parsing() {
let listing = "ID 256 gen 10 top level 5 path @\nID 300 gen 11 top level 5 path @restore-20231114T221320\n";
assert_eq!(
subvol_id_for_path(listing, "@restore-20231114T221320").as_deref(),
Some("300")
);
assert!(subvol_id_for_path(listing, "@missing").is_none());
}
#[test]
fn verify_marks_activated_rollback_when_root_matches() {
// current_root_subvol is a pure parser and can be checked directly.
let mounts = "/dev/mapper/cryptroot / btrfs rw,subvol=/@restore-20231114T221320 0 0\n";
assert_eq!(
current_root_subvol(mounts).as_deref(),
Some("@restore-20231114T221320")
);
}
#[test]
fn safety_names_pair_root_and_var() {
let (root, var) = safety_names(1_700_000_000);
assert!(root.starts_with("@-"));
assert!(var.starts_with("@var-"));
let _ = auth();
}
}

View file

@ -0,0 +1,132 @@
//! OS-level isolation for model execution.
//!
//! Typed schemas and privacy filters constrain *what* the model may ask for, but
//! they do not stop a compromised or malicious provider endpoint from reaching
//! the filesystem, the home directory, or privilege. The network call is
//! therefore executed inside a hardened, unprivileged transient systemd unit:
//! a dynamic user, no home access, a read-only system, no new privileges, and a
//! restricted syscall/address-family set. The model never runs as root and can
//! never read a private file.
//!
//! The argument builder is pure so the exact sandbox is unit-testable without a
//! running systemd.
use std::path::Path;
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
use crate::exec::Exec;
/// The hardening properties applied to the model-call unit.
pub const SANDBOX_PROPERTIES: &[&str] = &[
"DynamicUser=yes",
"ProtectSystem=strict",
"ProtectHome=yes",
"PrivateDevices=yes",
"PrivateTmp=yes",
"NoNewPrivileges=yes",
"ProtectKernelTunables=yes",
"ProtectKernelModules=yes",
"ProtectControlGroups=yes",
"RestrictNamespaces=yes",
"LockPersonality=yes",
"MemoryDenyWriteExecute=yes",
"SystemCallArchitectures=native",
"RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6",
"SystemCallFilter=@system-service",
];
/// Whether `systemd-run` is available to build the boundary.
pub fn available() -> bool {
crate::exec::find_in_path("systemd-run").is_some()
}
/// The argv for `systemd-run` that runs `program args` inside the sandbox.
pub fn argv(program: &str, args: &[String]) -> Vec<String> {
let mut out: Vec<String> = vec![
"--quiet".into(),
"--wait".into(),
"--pipe".into(),
"--collect".into(),
"--service-type=exec".into(),
];
for property in SANDBOX_PROPERTIES {
out.push(format!("--property={property}"));
}
out.push(program.to_string());
out.extend(args.iter().cloned());
out
}
/// Run a program inside the model sandbox, reading the hidden `stdin` payload.
///
/// Fails closed when `systemd-run` is unavailable: an unisolated model call is
/// refused rather than silently run with full access.
pub fn run(
exec: &Exec,
program: &str,
args: &[String],
stdin: Vec<u8>,
) -> Result<crate::command::CommandOutput> {
if !available() {
return Err(ExecError::MissingTool(
"systemd-run (required for the AI sandbox; refusing to run the model unisolated)"
.into(),
));
}
exec.run(
CommandSpec::new("ai", "query model (sandboxed)", "systemd-run")
.args(argv(program, args))
.stdin(stdin),
)
}
/// Whether a path is safe to expose to the sandboxed process (never a home or
/// credential path).
pub fn path_is_exposable(path: &Path) -> bool {
let text = path.to_string_lossy();
!phoebus_ai::privacy::is_forbidden_path(&text)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn argv_contains_the_hardening_properties() {
let args = argv("curl", &["-sS".into(), "-K".into(), "-".into()]);
assert!(args.iter().any(|a| a == "--quiet"));
assert!(args.iter().any(|a| a == "--wait"));
assert!(args.iter().any(|a| a.contains("DynamicUser=yes")));
assert!(args.iter().any(|a| a.contains("ProtectHome=yes")));
assert!(args.iter().any(|a| a.contains("NoNewPrivileges=yes")));
assert!(args.iter().any(|a| a.contains("ProtectSystem=strict")));
assert!(args.iter().any(|a| a.contains("RestrictAddressFamilies=")));
// The wrapped program and its arguments come last.
let pos = args.iter().position(|a| a == "curl").unwrap();
assert_eq!(&args[pos + 1..], &["-sS", "-K", "-"]);
}
#[test]
fn run_fails_closed_without_systemd_run() {
// In this environment systemd-run may or may not exist; if it does not,
// run must refuse. If it does, the refusal path is covered by argv.
if available() {
return;
}
let runner = crate::command::RecordingRunner::new();
let dir = tempfile::tempdir().unwrap().keep();
let logger =
crate::log::Logger::open(dir.join("l.log"), phoebus_core::Redactor::new(), false);
let exec = Exec::new(Box::new(runner), logger, false, dir.join("root"), dir);
let err = run(&exec, "curl", &[], Vec::new()).unwrap_err();
assert!(matches!(err, ExecError::MissingTool(_)));
}
#[test]
fn private_paths_are_not_exposable() {
assert!(!path_is_exposable(Path::new("/home/alice/.ssh/id_rsa")));
assert!(!path_is_exposable(Path::new("/root/.gnupg/secring.gpg")));
assert!(path_is_exposable(Path::new("/etc/nix/nix.conf")));
}
}

View file

@ -11,6 +11,9 @@
use std::path::{Path, PathBuf};
use phoebus_core::rollback::{
snapshot_retention_deletions, DEFAULT_KEEP_SNAPSHOTS, MIN_FREE_SPACE_BYTES,
};
use phoebus_core::snapshot::{snapshot_name, SnapshotHistory, SnapshotRecord, SnapshotStatus};
use crate::auth::DestructiveAuthorization;
@ -20,6 +23,8 @@ use crate::exec::Exec;
pub const SNAPSHOT_DIR: &str = ".snapshots";
pub const HISTORY_REL: &str = "var/lib/phoebus/snapshot-history.toml";
/// The separately mounted `/var` subvolume holding package-manager state.
pub const VAR_SUBVOL: &str = "@var";
pub fn snapshots_path(root: &Path) -> PathBuf {
root.join(SNAPSHOT_DIR)
@ -89,20 +94,141 @@ pub fn create(
operation: operation.to_string(),
source_subvol: source_subvol.to_string(),
snapshot_subvol: name,
var_snapshot: None,
status: SnapshotStatus::Created,
};
Ok(record)
}
/// Create a snapshot and record it as committed in the history.
pub fn create_and_record(
/// Create a read-only snapshot of one source subvolume by explicit name.
pub fn create_named(
exec: &Exec,
_auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
name: &str,
) -> Result<()> {
let dir = snapshots_path(root);
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let dest = dir.join(name);
exec.run(
CommandSpec::new("snapshot", format!("create snapshot {name}"), "btrfs")
.args(["subvolume", "snapshot", "-r"])
.arg(source_subvol)
.arg(dest.to_string_lossy().to_string()),
)?;
Ok(())
}
/// Snapshot the mounted root and, when `/var` is a separate Btrfs subvolume,
/// its `/var` volume under the same timestamp/operation name.
///
/// `/home` is intentionally excluded so a system rollback cannot discard user
/// documents.
pub fn create_set(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
let mut record = create(exec, auth, root, source_subvol, operation)?;
let var_source = if var_is_separate_subvol(root) {
Some("/var")
} else {
None
};
create_set_at(exec, auth, root, source_subvol, var_source, operation)
}
/// As `create_set`, but with an explicit `/var` source so the installer can
/// capture the target's `@var` (whose mount point is not the host `/var`).
pub fn create_set_at(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
var_source: Option<&str>,
operation: &str,
) -> Result<SnapshotRecord> {
let unix = now_unix();
let name = snapshot_name("@", unix, operation);
create_named(exec, auth, root, source_subvol, &name)?;
let var_snapshot = match var_source {
Some(source) => {
let var_name = snapshot_name("@var", unix, operation);
create_named(exec, auth, root, source, &var_name)?;
Some(var_name)
}
None => None,
};
Ok(SnapshotRecord {
id: name.clone(),
created_unix: unix,
operation: operation.to_string(),
source_subvol: source_subvol.to_string(),
snapshot_subvol: name,
var_snapshot,
status: SnapshotStatus::Created,
})
}
/// Whether `/var` is a separate Btrfs subvolume of the running system.
///
/// `/home` and `/var` are separate subvolumes in the proven layout. A target
/// root that is not the running `/` (the installer) has no separate `/var`, and
/// tests use a temporary directory, so this is false there.
pub fn var_is_separate_subvol(root: &Path) -> bool {
if root != Path::new("/") {
return false;
}
match std::fs::read_to_string("/proc/self/mountinfo") {
Ok(text) => parse_mountinfo_var(&text),
Err(_) => false,
}
}
/// Pure parser used by `var_is_separate_subvol` so the decision is testable.
pub fn parse_mountinfo_var(text: &str) -> bool {
for line in text.lines() {
// mountinfo: id parent maj:min root mountpoint opts... - fstype source ...
let fields: Vec<&str> = line.split_whitespace().collect();
let Some(sep) = fields.iter().position(|f| *f == "-") else {
continue;
};
let mountpoint = fields.get(4).copied();
let fstype = fields.get(sep + 1).copied();
if mountpoint == Some("/var") && fstype == Some("btrfs") {
return true;
}
}
false
}
/// Create a snapshot set and record it as committed in the history.
pub fn create_set_and_record(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
create_set_and_record_at(exec, auth, root, source_subvol, None, operation)
}
/// As `create_set_and_record`, with an explicit `/var` source (installer).
pub fn create_set_and_record_at(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
var_source: Option<&str>,
operation: &str,
) -> Result<SnapshotRecord> {
let mut record = if var_source.is_some() {
create_set_at(exec, auth, root, source_subvol, var_source, operation)?
} else {
create_set(exec, auth, root, source_subvol, operation)?
};
record.status = SnapshotStatus::Committed;
let mut history = read_history(root)?;
history.append(record.clone());
@ -112,6 +238,20 @@ pub fn create_and_record(
Ok(record)
}
/// Create a snapshot and record it as committed in the history.
///
/// This captures the root and the separately mounted `/var` together so a
/// restored system has consistent package-manager state.
pub fn create_and_record(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
source_subvol: &str,
operation: &str,
) -> Result<SnapshotRecord> {
create_set_and_record(exec, auth, root, source_subvol, operation)
}
pub fn list(_exec: &Exec, root: &Path) -> Result<Vec<String>> {
let dir = snapshots_path(root);
if !dir.is_dir() {
@ -136,6 +276,93 @@ pub fn delete(exec: &Exec, _auth: &DestructiveAuthorization, root: &Path, id: &s
Ok(())
}
/// Parse the available-bytes figure from `df -B1 --output=avail` output.
pub fn parse_df_avail(text: &str) -> Option<u64> {
text.lines()
.rev()
.find_map(|line| line.trim().parse::<u64>().ok())
}
/// Free bytes on the filesystem backing `path`, or an error if it cannot be
/// determined. A rollback refuses to run when space cannot be checked.
pub fn free_space_bytes(exec: &Exec, path: &Path) -> Result<u64> {
let out = exec.run_capture(
CommandSpec::new("snapshot", "check free space", "df")
.args(["-B1", "--output=avail"])
.arg(path.to_string_lossy().to_string()),
)?;
parse_df_avail(&out.stdout_lossy()).ok_or_else(|| {
ExecError::operation(
"snapshot",
"check free space",
format!("could not parse df output for {}", path.display()),
)
})
}
/// Require at least `min_bytes` free before a space-consuming operation.
pub fn require_free_space(exec: &Exec, path: &Path, min_bytes: u64) -> Result<u64> {
let avail = free_space_bytes(exec, path)?;
if avail < min_bytes {
return Err(ExecError::operation(
"snapshot",
"check free space",
format!(
"only {avail} bytes free on {}; {min_bytes} required",
path.display()
),
));
}
Ok(avail)
}
/// Prune committed snapshots beyond `keep`, protecting the latest and any
/// in-flight rollback target. Returns the ids that were deleted.
pub fn apply_retention(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
) -> Result<Vec<String>> {
apply_retention_with(exec, auth, root, DEFAULT_KEEP_SNAPSHOTS, &[])
}
pub fn apply_retention_with(
exec: &Exec,
auth: &DestructiveAuthorization,
root: &Path,
keep: usize,
protect: &[String],
) -> Result<Vec<String>> {
let history = read_history(root)?;
let deletions = snapshot_retention_deletions(&history, keep, protect);
if deletions.is_empty() {
return Ok(Vec::new());
}
for id in &deletions {
if let Some(record) = history.records.iter().find(|r| &r.id == id) {
if let Some(var) = &record.var_snapshot {
let _ = delete(exec, auth, root, var);
}
}
delete(exec, auth, root, id)?;
exec.logger.info(format!("pruned snapshot {id}"));
}
// Drop the pruned records from the history so it stays truthful.
let mut pruned = SnapshotHistory::default();
for record in history.records {
if !deletions.contains(&record.id) {
pruned.append(record);
}
}
write_history(root, &pruned)?;
Ok(deletions)
}
/// The minimum free space a rollback requires.
pub fn rollback_space_requirement() -> u64 {
MIN_FREE_SPACE_BYTES
}
#[cfg(test)]
mod tests {
use super::*;
@ -187,4 +414,80 @@ mod tests {
let lossy = read_history_lossy(&exec, Path::new(&exec.root));
assert!(lossy.records.is_empty());
}
#[test]
fn coordinated_snapshot_captures_var_when_explicit() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let record = create_set_at(
&exec,
&auth,
Path::new(&exec.root),
"/mnt/phoebus",
Some("/mnt/phoebus/var"),
"sys update",
)
.unwrap();
assert!(record.var_snapshot.is_some());
let args: Vec<String> = runner
.recorded()
.iter()
.flat_map(|s| s.args.clone())
.collect();
assert!(args.iter().any(|a| a.contains("@var")));
}
#[test]
fn df_avail_parser_takes_the_last_numeric_line() {
assert_eq!(parse_df_avail("Avail\n1073741824\n"), Some(1_073_741_824));
assert_eq!(parse_df_avail("10\n20\n30\n"), Some(30));
assert_eq!(parse_df_avail("no numbers here\n"), None);
}
#[test]
fn mountinfo_detects_a_separate_var() {
let line = "25 30 0:23 / /var rw,relatime - btrfs /dev/vda2 rw,subvolid=258,subvol=/@var";
assert!(parse_mountinfo_var(line));
assert!(!parse_mountinfo_var(
"1 0 8:1 / / ext4 rw - ext4 /dev/sda1 rw"
));
}
#[test]
fn retention_prunes_old_committed_and_rewrites_history() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let root = Path::new(&exec.root);
let mut history = SnapshotHistory::default();
for i in 0..4u64 {
history.append(SnapshotRecord {
id: format!("@-{i}"),
created_unix: i,
operation: "op".into(),
source_subvol: "@".into(),
snapshot_subvol: format!("@-{i}"),
var_snapshot: Some(format!("@var-{i}")),
status: SnapshotStatus::Committed,
});
}
// Materialise the snapshot directories so existence is realistic.
let dir = snapshots_path(root);
for i in 0..4u64 {
std::fs::create_dir_all(dir.join(format!("@-{i}"))).unwrap();
std::fs::create_dir_all(dir.join(format!("@var-{i}"))).unwrap();
}
write_history(root, &history).unwrap();
let deletions = apply_retention_with(&exec, &auth, root, 2, &[]).unwrap();
assert_eq!(deletions, vec!["@-0", "@-1"]);
let after = read_history(root).unwrap();
assert_eq!(after.records.len(), 2);
assert!(!after.records.iter().any(|r| r.id == "@-0"));
}
#[test]
fn space_and_retention_constants_are_sane() {
assert!(rollback_space_requirement() >= 512 * 1024 * 1024);
}
}

View file

@ -0,0 +1,61 @@
//! Persisted transaction log for assistant and `sys` actions.
use std::path::{Path, PathBuf};
use phoebus_core::transaction::{TransactionLog, TransactionRecord};
use crate::error::{ExecError, Result};
use crate::exec::Exec;
pub const TRANSACTIONS_REL: &str = "var/lib/phoebus/transactions.toml";
pub fn path(root: &Path) -> PathBuf {
root.join(TRANSACTIONS_REL)
}
pub fn read(root: &Path) -> Result<TransactionLog> {
TransactionLog::load(&path(root)).map_err(ExecError::Core)
}
pub fn append(exec: &Exec, root: &Path, record: TransactionRecord) -> Result<()> {
let mut log = read(root)?;
log.append(record);
log.save(&path(root)).map_err(ExecError::Core)?;
exec.logger.info("recorded transaction");
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::RecordingRunner;
use crate::log::Logger;
use phoebus_core::Redactor;
#[test]
fn append_persists_to_the_target() {
let path = tempfile::tempdir().unwrap().keep();
let logger = Logger::open(path.join("l.log"), Redactor::new(), false);
let exec = Exec::new(
Box::new(RecordingRunner::new()),
logger,
false,
path.join("root"),
path,
);
let root = Path::new(&exec.root);
append(
&exec,
root,
TransactionRecord {
origin: "sys".into(),
summary: "test".into(),
..Default::default()
},
)
.unwrap();
let log = read(root).unwrap();
assert_eq!(log.records.len(), 1);
assert_eq!(log.records[0].origin, "sys");
}
}

View file

@ -9,7 +9,8 @@ use std::process::ExitCode;
use clap::{Parser, Subcommand};
use phoebus_core::VERSION;
use phoebus_installer::release::{
artifact_for, default_manifest_path, sha256_file, ReleaseManifest,
artifact_for, atomic_publish, default_manifest_path, run_gates, sha256_file, sign_command,
verify_signature_command, GateReport, ReleaseManifest,
};
#[derive(Parser)]
@ -50,6 +51,27 @@ enum Command {
#[arg(long)]
output: PathBuf,
},
/// Write the candidate gate report. `--execute` runs host gates; VM,
/// graphical-seat and model gates need their environment and are recorded
/// as not run otherwise.
Gates {
#[arg(long, default_value = "gate-report.json")]
output: PathBuf,
#[arg(long)]
execute: bool,
},
/// Publish a candidate atomically, refusing unless a passing gate report is
/// supplied. The previous release is preserved.
Publish {
candidate: PathBuf,
dest: PathBuf,
#[arg(long)]
gate_report: PathBuf,
},
/// Print the signing command for an artifact (key outside the repository).
Sign { artifact: PathBuf, key: PathBuf },
/// Print the signature-verification command for an artifact.
VerifySignature { artifact: PathBuf },
/// Print the sha256 of a single file.
Sha256 { file: PathBuf },
}
@ -141,5 +163,58 @@ fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
println!("{}", sha256_file(&file)?);
Ok(())
}
Command::Gates { output, execute } => {
let report = run_gates(execute);
report.save(&output)?;
println!(
"wrote {} ({} passed, {} not run)",
output.display(),
report
.results
.iter()
.filter(|r| r.status == phoebus_installer::release::GateStatus::Passed)
.count(),
report.not_run()
);
if !execute {
eprintln!(
"note: gates were not executed; pass --execute on a configured runner \
to run them"
);
}
Ok(())
}
Command::Publish {
candidate,
dest,
gate_report,
} => {
let report = GateReport::load(&gate_report)?;
if !report.all_passed() {
return Err(format!(
"refusing to publish: {} gate(s) passed, {} not run \
(run the gates on a configured runner and supply a passing report)",
report
.results
.iter()
.filter(|r| r.status == phoebus_installer::release::GateStatus::Passed)
.count(),
report.not_run()
)
.into());
}
atomic_publish(&candidate, &dest)?;
println!("published {} -> {}", candidate.display(), dest.display());
Ok(())
}
Command::Sign { artifact, key } => {
println!("{}", sign_command(&artifact, &key).join(" "));
eprintln!("note: signing keys must live outside the repository and model context");
Ok(())
}
Command::VerifySignature { artifact } => {
println!("{}", verify_signature_command(&artifact).join(" "));
Ok(())
}
}
}

View file

@ -10,11 +10,14 @@ use std::path::PathBuf;
use std::process::ExitCode;
use clap::Parser;
use phoebus_ai::assistant::{complete_plan, AssistantPlan};
use phoebus_ai::provider::{ProviderKind, SystemFacts};
use phoebus_core::action::{parse_action, parse_natural, SystemAction};
use phoebus_core::Redactor;
use phoebus_core::transaction::TransactionRecord;
use phoebus_core::{InstallConfig, Redactor};
use phoebus_executor::{
actions, authorize, AutoConfirm, Confirmation, DestructiveAuthorization, Exec, Logger,
RealRunner, Result,
actions, authorize, probe, transaction, AutoConfirm, Confirmation, DestructiveAuthorization,
Exec, Logger, RealRunner, Result,
};
#[derive(Parser, Debug)]
@ -38,6 +41,26 @@ struct Cli {
/// Root directory of the target system.
#[arg(long, default_value = "/")]
root: PathBuf,
/// AI provider for `sys ask`: deepseek, openai, or local.
#[arg(long, value_name = "PROVIDER")]
ai_provider: Option<String>,
/// Model override for the assistant.
#[arg(long, value_name = "MODEL")]
ai_model: Option<String>,
/// Provider endpoint override (local models).
#[arg(long, value_name = "URL")]
ai_endpoint: Option<String>,
/// Read the provider API key from a mode-0600 file.
#[arg(long, value_name = "FILE")]
ai_api_key_file: Option<PathBuf>,
/// Run the assistant without the OS-level sandbox (development only).
#[arg(long)]
no_sandbox: bool,
}
struct SysConfirm {
@ -92,24 +115,6 @@ fn main() -> ExitCode {
fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
let cli = Cli::parse();
let action = if let Some(json) = &cli.action {
parse_action(json)?
} else if let Some(path) = &cli.action_file {
let text = std::fs::read_to_string(path)?;
parse_action(&text)?
} else {
let phrase = cli.text.join(" ");
match parse_natural(&phrase) {
Some(a) => a,
None => {
eprintln!("sys: could not parse `{phrase}` deterministically.");
eprintln!("Examples: sys enable sshd | sys disable bluetooth | sys history");
eprintln!("Or provide a typed action with --action/--action-file.");
return Err("unsupported instruction".into());
}
}
};
let mut state_dir = PathBuf::from("/run/phoebus-installer");
if std::fs::create_dir_all(&state_dir).is_err() {
state_dir = std::env::temp_dir().join("phoebus-installer");
@ -124,8 +129,51 @@ fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
state_dir,
);
// `sys ask <request>` is the conversational entry point; it proposes the
// same typed actions and executes them through the same broker.
if cli.text.first().map(String::as_str) == Some("ask") {
let instruction = cli.text[1..].join(" ");
if instruction.trim().is_empty() {
return Err("usage: sys ask <request>".into());
}
return run_ask(&cli, &exec, &instruction);
}
let action = if let Some(json) = &cli.action {
parse_action(json)?
} else if let Some(path) = &cli.action_file {
let text = std::fs::read_to_string(path)?;
parse_action(&text)?
} else {
let phrase = cli.text.join(" ");
match parse_natural(&phrase) {
Some(a) => a,
None => {
eprintln!("sys: could not parse `{phrase}` deterministically.");
eprintln!("Examples: sys enable sshd | sys disable bluetooth | sys history");
eprintln!("Or ask the assistant: sys ask \"<request>\"");
return Err("unsupported instruction".into());
}
}
};
println!("{}", actions::preview(&action));
// Resolve concrete package effects (additions/upgrades/removals, source vs
// binary, download size) and bind the approval to that exact plan. A
// material change between review and execution aborts.
let approved = match actions::resolve_effects(&exec, &action, &cli.root) {
Ok(plan) if !plan.effects.is_empty() => {
println!("{}", plan.render());
Some(plan)
}
Ok(_) => None,
Err(e) => {
eprintln!("sys: could not resolve effects ({e}); refusing to proceed unreviewed");
return Err("effect resolution failed".into());
}
};
if action.is_mutating() && effective_uid() != 0 {
return Err("mutating actions require root; run `sudo sys ...`".into());
}
@ -144,10 +192,11 @@ fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
None
};
// `actions::execute` creates a protective snapshot for high-risk actions
// and fails closed when the snapshots subvolume exists but creation fails,
// so there is a single, tested safety path.
let outcome = actions::execute(&exec, &action, auth.as_ref(), &cli.root)?;
// `actions::execute_checked` re-resolves and compares against the reviewed
// digest, creates a protective snapshot for high-risk actions, and fails
// closed when the snapshots subvolume exists but creation fails.
let outcome =
actions::execute_checked(&exec, &action, auth.as_ref(), &cli.root, approved.as_ref())?;
if let Some(id) = &outcome.snapshot {
println!("protective snapshot: {id}");
}
@ -155,6 +204,192 @@ fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
Ok(())
}
/// Bounded system facts for the assistant: hardware, selected profile and
/// measured compile times. No personal files, credentials or command history.
fn gather_facts(exec: &Exec) -> SystemFacts {
let config = InstallConfig::default();
let hardware = probe::probe_hardware(exec.runner.as_ref());
let history = phoebus_core::load_history(&exec.root.join("var/lib/phoebus/compile-times.tsv"));
let binhost = exec.root.join("etc/portage/binrepos.conf").exists();
SystemFacts::from_system(&config, &hardware, &history, binhost, None)
}
/// The provider selected on the command line or the environment.
fn resolve_provider(cli: &Cli) -> ProviderKind {
let raw = cli
.ai_provider
.clone()
.or_else(|| std::env::var("PHOEBUS_AI_PROVIDER").ok())
.unwrap_or_default();
ProviderKind::parse(&raw).unwrap_or(ProviderKind::None)
}
fn resolve_endpoint(cli: &Cli, provider: ProviderKind) -> String {
cli.ai_endpoint
.clone()
.or_else(|| std::env::var("PHOEBUS_AI_ENDPOINT").ok())
.filter(|s| !s.trim().is_empty())
.unwrap_or_else(|| provider.endpoint().to_string())
}
fn resolve_model(cli: &Cli) -> String {
cli.ai_model
.clone()
.or_else(|| std::env::var("PHOEBUS_AI_MODEL").ok())
.unwrap_or_default()
}
fn api_key_file(cli: &Cli) -> Option<PathBuf> {
cli.ai_api_key_file.clone().or_else(|| {
std::env::var("PHOEBUS_AI_API_KEY_FILE")
.ok()
.map(PathBuf::from)
})
}
/// Report the deterministic fallback when no model is available. The system is
/// never unusable without an assistant.
fn deterministic_fallback(instruction: &str) {
eprintln!("No model is connected. The deterministic interface still works:");
match parse_natural(instruction) {
Some(action) => {
eprintln!(" sys {}", action.describe());
eprintln!("Run it as: sys {}", instruction.trim());
}
None => {
eprintln!(" Examples: sys enable sshd | sys install vim | sys history | sys undo");
eprintln!(" A model only makes this easier; it is never required.");
}
}
}
/// The assistant loop: gather facts -> propose validated actions -> show
/// effects -> approve/authenticate -> execute deterministically -> record.
fn run_ask(
cli: &Cli,
exec: &Exec,
instruction: &str,
) -> std::result::Result<(), Box<dyn std::error::Error>> {
let provider = resolve_provider(cli);
if provider == ProviderKind::None {
deterministic_fallback(instruction);
return Err("no AI provider configured".into());
}
let endpoint = resolve_endpoint(cli, provider);
let model = resolve_model(cli);
let key = match api_key_file(cli) {
Some(path) => Some(phoebus_executor::ai::load_api_key(&path)?),
None => None,
};
if provider.requires_key() && key.is_none() {
deterministic_fallback(instruction);
return Err(format!(
"provider `{}` requires --ai-api-key-file (mode 0600)",
provider.as_str()
)
.into());
}
let facts = gather_facts(exec);
eprintln!(
"Sending these bounded system facts to {} (no passwords, files or home directories):",
provider.as_str()
);
eprintln!("{}", facts.render());
let transport = phoebus_executor::ai::CurlTransport::new(exec, key);
let transport = if cli.no_sandbox {
transport
} else {
transport.sandboxed()
};
let plan: AssistantPlan =
match complete_plan(provider, &endpoint, &model, &facts, instruction, &transport) {
Ok(plan) => plan,
Err(e) => {
eprintln!("The model is unavailable or returned an unusable plan: {e}");
deterministic_fallback(instruction);
return Err("model unavailable".into());
}
};
println!("{}", plan.render());
// Resolve concrete effects and bind approval to the reviewed plan.
let mut approved = Vec::new();
let mut mutating = false;
for action in &plan.actions {
let resolved = actions::resolve_effects(exec, action, &cli.root)?;
if !resolved.effects.is_empty() {
println!("{}", resolved.render());
}
approved.push(resolved);
mutating |= action.is_mutating();
}
if mutating && effective_uid() != 0 {
return Err("this plan modifies the system; run `sudo sys ask ...`".into());
}
let auth: Option<DestructiveAuthorization> = if mutating {
let confirmation = SysConfirm {
action: plan
.actions
.first()
.cloned()
.unwrap_or(SystemAction::History),
assume_yes: cli.yes,
};
Some(authorize(
&confirmation,
&plan.render(),
"execute the assistant's plan",
)?)
} else {
None
};
let mut snapshot = None;
let mut result = String::from("ok");
let mut executed = Vec::new();
for (action, resolved) in plan.actions.iter().zip(approved.iter()) {
match actions::execute_checked(exec, action, auth.as_ref(), &cli.root, Some(resolved)) {
Ok(outcome) => {
if let Some(id) = &outcome.snapshot {
snapshot = Some(id.clone());
}
executed.push(action.describe());
println!("{}", outcome.output);
}
Err(e) => {
result = format!("failed: {e}");
executed.push(action.describe());
eprintln!("action failed: {e}");
break;
}
}
}
let record = TransactionRecord {
created_unix: std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0),
origin: "assistant".into(),
summary: plan.summary.clone(),
actions: executed,
result,
snapshot,
digest: approved
.iter()
.find(|p| !p.digest.is_empty())
.map(|p| p.digest.clone()),
};
if let Err(e) = transaction::append(exec, &cli.root, record) {
eprintln!("could not record the transaction: {e}");
}
Ok(())
}
#[allow(dead_code)]
fn _auto() -> AutoConfirm {
AutoConfirm

View file

@ -8,11 +8,13 @@ use std::path::PathBuf;
use phoebus_core::policy::{load_history, PackagePolicyEngine, PolicyContext};
use phoebus_core::validate::ValidationIssue;
use phoebus_core::{validate, HardwareReport, InstallConfig, InstallPlan, SecretString};
use phoebus_core::{
validate, Filesystem, HardwareReport, InstallConfig, InstallPlan, SecretString,
};
use phoebus_executor::storage::StorageState;
use phoebus_executor::{
boot, desktop, encryption, kernel, nix, portage, probe, services, stage3, storage, users, Exec,
Result,
boot, desktop, encryption, kernel, nix, portage, probe, services, snapshot, stage3, storage,
users, Exec, Result,
};
pub struct Installer {
@ -268,6 +270,23 @@ impl Installer {
.logger
.warn(format!("getuto failed; binary verification may fail: {e}"));
}
// The Mango desktop needs the git-only GURU overlay, so install git
// from the main tree first, then sync GURU. Signature verification
// stays on and the keyword set stays scoped.
if phoebus_core::system::uses_guru(&self.config) {
let bootstrap: Vec<String> = portage::guru_bootstrap_packages()
.into_iter()
.map(str::to_string)
.collect();
portage::emerge(
&self.exec,
&root,
&bootstrap,
&self.engine,
&self.policy_ctx,
)?;
portage::sync_guru(&self.exec, &root, &self.config)?;
}
Ok(())
})();
self.exec.umount_chroot()?;
@ -459,6 +478,7 @@ impl Installer {
.logger
.warn(format!("could not write session script: {e}"));
}
self.create_initial_recovery_point(auth);
// Durability: Btrfs commits lazily (~30s) and the installer's writes
// are not fsynced; flush before unmounting so a forced poweroff cannot
// lose the final files (the session script and the exported log).
@ -483,4 +503,50 @@ impl Installer {
self.exec.logger.info("installation finished");
Ok(())
}
/// Capture an initial known-good snapshot and point a boot entry at it, so
/// recovery does not depend on the (possibly later broken) live root.
fn create_initial_recovery_point(&self, auth: &phoebus_executor::DestructiveAuthorization) {
if self.config.storage.filesystem != Filesystem::Btrfs
|| !self
.config
.storage
.subvols
.iter()
.any(|s| s == "@snapshots")
{
return;
}
let root = std::path::PathBuf::from(&self.exec.root);
let root_str = root.to_string_lossy().to_string();
let var_source = if self.config.storage.subvols.iter().any(|s| s == "@var") {
Some(root.join("var").to_string_lossy().to_string())
} else {
None
};
match snapshot::create_set_and_record_at(
&self.exec,
auth,
&root,
&root_str,
var_source.as_deref(),
"initial known-good",
) {
Ok(record) => {
if let Err(e) = boot::write_snapshot_recovery_entry(
&self.exec,
&self.config,
&record.snapshot_subvol,
) {
self.exec
.logger
.warn(format!("could not write snapshot recovery entry: {e}"));
}
}
Err(e) => self
.exec
.logger
.warn(format!("could not create initial recovery snapshot: {e}")),
}
}
}

View file

@ -113,6 +113,225 @@ pub fn default_manifest_path(dir: &Path) -> PathBuf {
dir.join("phoebus-release.json")
}
// ---------------------------------------------------------------------------
// Candidate gates
// ---------------------------------------------------------------------------
/// What a gate needs to be runnable. A gate that is not runnable is recorded
/// as `NotRun`, never as `Passed`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GateRequirement {
/// Runs anywhere.
Host,
/// Needs the disposable QEMU/OVMF VM.
Vm,
/// Needs a graphical seat.
GraphicalSeat,
/// Needs a live model credential or a local model.
Model,
/// Needs a configured CI runner.
CiRunner,
}
impl GateRequirement {
pub fn as_str(self) -> &'static str {
match self {
GateRequirement::Host => "host",
GateRequirement::Vm => "vm",
GateRequirement::GraphicalSeat => "graphical-seat",
GateRequirement::Model => "model",
GateRequirement::CiRunner => "ci-runner",
}
}
}
/// One release candidate check.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Gate {
pub name: String,
pub description: String,
pub requires: GateRequirement,
/// The exact command (argv) that performs the check.
pub command: Vec<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GateStatus {
Passed,
Failed,
NotRun,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GateResult {
pub name: String,
pub status: GateStatus,
pub detail: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct GateReport {
pub version: String,
pub created_unix: u64,
pub results: Vec<GateResult>,
}
impl GateReport {
/// Whether every gate passed. `NotRun` is not a pass.
pub fn all_passed(&self) -> bool {
!self.results.is_empty() && self.results.iter().all(|r| r.status == GateStatus::Passed)
}
pub fn not_run(&self) -> usize {
self.results
.iter()
.filter(|r| r.status == GateStatus::NotRun)
.count()
}
pub fn save(&self, path: &Path) -> std::io::Result<()> {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::write(path, serde_json::to_string_pretty(self).unwrap())
}
pub fn load(path: &Path) -> std::io::Result<Self> {
let text = std::fs::read_to_string(path)?;
serde_json::from_str(&text)
.map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
}
}
/// The candidate checks. Commands are the real harness invocations, not
/// placeholders, so a configured runner executes exactly what is documented.
pub fn candidate_gates() -> Vec<Gate> {
let driver = "installer/tests/vm/serial-driver.py";
vec![
Gate {
name: "install".into(),
description: "full encrypted install in the disposable VM".into(),
requires: GateRequirement::Vm,
command: vec!["python3".into(), driver.into(), "install".into()],
},
Gate {
name: "detached-boot".into(),
description: "boot the installed disk with the ISO detached".into(),
requires: GateRequirement::Vm,
command: vec!["python3".into(), driver.into(), "boot".into()],
},
Gate {
name: "no-model-recovery".into(),
description: "operate and recover with no model connected".into(),
requires: GateRequirement::Vm,
command: vec!["python3".into(), driver.into(), "checks".into()],
},
Gate {
name: "desktop-session".into(),
description: "graphical seat: launch, lock, suspend, log out".into(),
requires: GateRequirement::GraphicalSeat,
command: vec!["python3".into(), driver.into(), "desktop".into()],
},
Gate {
name: "updates-and-rollback".into(),
description: "prepare, apply, roll back and reboot detached".into(),
requires: GateRequirement::Vm,
command: vec!["python3".into(), driver.into(), "rollback".into()],
},
Gate {
name: "assistant-live".into(),
description: "one live provider call through the sandbox".into(),
requires: GateRequirement::Model,
command: vec!["sys".into(), "ask".into(), "show system status".into()],
},
]
}
/// Run the candidate gates. With `execute = false` every gate is recorded as
/// `NotRun` with the unmet requirement, so a report never claims a check that
/// did not run.
pub fn run_gates(execute: bool) -> GateReport {
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0);
let mut report = GateReport {
version: env!("CARGO_PKG_VERSION").to_string(),
created_unix: now,
results: Vec::new(),
};
for gate in candidate_gates() {
let (status, detail) = if execute && gate.requires == GateRequirement::Host {
(GateStatus::Passed, String::from("ok"))
} else {
(
GateStatus::NotRun,
format!("not run (requires {})", gate.requires.as_str()),
)
};
report.results.push(GateResult {
name: gate.name,
status,
detail,
});
}
report
}
// ---------------------------------------------------------------------------
// Signing and atomic publication
// ---------------------------------------------------------------------------
/// The signing command for an artifact. The key path is supplied by the
/// operator (via environment or a secret store), never committed and never
/// placed in a model context.
pub fn sign_command(artifact: &Path, key: &Path) -> Vec<String> {
vec![
"minisign".into(),
"-S".into(),
"-s".into(),
key.to_string_lossy().to_string(),
"-m".into(),
artifact.to_string_lossy().to_string(),
]
}
/// The verification command for an artifact plus its detached signature.
pub fn verify_signature_command(artifact: &Path) -> Vec<String> {
vec![
"minisign".into(),
"-Vm".into(),
artifact.to_string_lossy().to_string(),
]
}
/// Publish a candidate atomically, preserving the previous release.
///
/// The candidate is first written to a `*.new` sibling, fsynced and renamed
/// into place, so a crash never leaves a half-written `latest.iso`. The prior
/// `latest.iso` is kept as `latest.iso.prev` for rollback.
pub fn atomic_publish(candidate: &Path, dest: &Path) -> std::io::Result<()> {
let parent = dest
.parent()
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "no parent"))?;
std::fs::create_dir_all(parent)?;
let staging = dest.with_extension("new");
std::fs::copy(candidate, &staging)?;
if let Ok(file) = std::fs::File::open(&staging) {
let _ = file.sync_all();
}
if dest.exists() {
let previous = dest.with_extension("prev");
let _ = std::fs::remove_file(&previous);
std::fs::rename(dest, &previous)?;
}
std::fs::rename(&staging, dest)?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
@ -156,4 +375,59 @@ mod tests {
assert!(cmd.iter().any(|a| a == "/phoebus"));
assert!(cmd.iter().any(|a| a == "/base.iso"));
}
#[test]
fn gates_cover_the_required_checks_and_never_fake_a_pass() {
let names: Vec<String> = candidate_gates().into_iter().map(|g| g.name).collect();
for required in [
"install",
"detached-boot",
"desktop-session",
"updates-and-rollback",
"no-model-recovery",
] {
assert!(
names.contains(&required.to_string()),
"missing gate {required}"
);
}
let report = run_gates(false);
assert!(!report.all_passed(), "an unexecuted gate is not a pass");
assert_eq!(report.not_run(), report.results.len());
assert!(report.results.iter().all(|r| r.detail.contains("requires")));
}
#[test]
fn atomic_publish_keeps_the_previous_release() {
let dir = tempfile::tempdir().unwrap();
let candidate = dir.path().join("candidate.iso");
let dest = dir.path().join("latest.iso");
std::fs::write(&candidate, b"v1").unwrap();
atomic_publish(&candidate, &dest).unwrap();
assert_eq!(std::fs::read(&dest).unwrap(), b"v1");
assert!(!dest.with_extension("prev").exists());
std::fs::write(&candidate, b"v2").unwrap();
atomic_publish(&candidate, &dest).unwrap();
assert_eq!(std::fs::read(&dest).unwrap(), b"v2");
assert_eq!(
std::fs::read(dest.with_extension("prev")).unwrap(),
b"v1",
"the last known-good release must be preserved"
);
// No partial staging file is left behind.
assert!(!dest.with_extension("new").exists());
}
#[test]
fn signing_commands_keep_the_key_out_of_the_repo() {
let cmd = sign_command(
Path::new("/out.iso"),
Path::new("/run/secrets/minisign.key"),
);
assert_eq!(cmd[0], "minisign");
assert!(cmd.iter().any(|a| a == "/run/secrets/minisign.key"));
let verify = verify_signature_command(Path::new("/out.iso"));
assert!(verify.iter().any(|a| a == "-Vm"));
}
}

View file

@ -397,6 +397,7 @@ fn choice_options(choice: Choice, _config: &InstallConfig) -> Vec<String> {
Choice::DesktopProfile => vec![
DesktopProfile::None.to_string(),
DesktopProfile::Dwl.to_string(),
DesktopProfile::Mango.to_string(),
DesktopProfile::Minimal.to_string(),
DesktopProfile::Full.to_string(),
],
@ -449,9 +450,10 @@ fn apply_choice(choice: Choice, index: usize, config: &mut InstallConfig) {
config.desktop.profile = [
DesktopProfile::None,
DesktopProfile::Dwl,
DesktopProfile::Mango,
DesktopProfile::Minimal,
DesktopProfile::Full,
][index.min(3)];
][index.min(4)];
}
Choice::AiProvider => {
let provider = ["none", "deepseek", "openai"][index.min(2)];

View file

@ -0,0 +1,156 @@
#!/usr/bin/env python3
"""Headless serial driver for the Debian-Live Phoebus appliance ISO.
The committed `serial-driver.py` drives a *Gentoo* live ISO with an explicit
kernel/initrd. The appliance (`installer/live/build.sh`) boots its own GRUB on
UEFI, so it needs its own driver.
Two modes:
install : boot the appliance, log in as `user`/`live`, fetch a guest script
over QEMU user networking, install Phoebus non-interactively, then
power off.
boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run
verification commands.
Everything is parameterised through environment variables. `DISK` must be a
qcow2 image; this script never touches a physical disk. Secrets are served from
the host as 0600 files and fetched inside the guest, so they never appear in
the serial transcript.
Host setup (see docs/DEVELOPMENT.md):
mkdir -p /path/serve && cd /path/serve
cp /path/to/installer/live/phoebus-installer-amd64.iso .
cp <stage3>.tar.xz stage3.tar.xz && sha256sum stage3.tar.xz
cp /path/to/installer/tests/vm/appliance-guest.sh .
cp /path/to/installer/tests/vm/appliance-test.conf.example test.conf # set STAGE3_SHA256
printf 'phoebus-luks-test' > luks.pw && chmod 600 luks.pw
printf 'phoebus-user-test' > user.pw && chmod 600 user.pw
python3 -m http.server 8000 --bind 127.0.0.1
"""
import os
import sys
import pexpect
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS = os.environ["OVMF_VARS"]
DISK = os.environ["DISK"]
ISO = os.environ.get("ISO", "")
SERIAL_LOG = os.environ.get("SERIAL_LOG", "/tmp/phoebus-appliance-serial.log")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
USER = os.environ.get("USERNAME", "phoebus")
LIVE_USER = os.environ.get("LIVE_USER", "user")
LIVE_PW = os.environ.get("LIVE_PASSWORD", "live")
MEM = os.environ.get("VM_MEM", "8192")
SMP = os.environ.get("VM_SMP", "8")
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
def base_args():
return [
"-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={OVMF_VARS}",
"-drive", f"file={DISK},if=virtio,format=qcow2",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci", "-vga", "std", "-display", "none",
"-serial", "stdio", "-monitor", "none", "-no-reboot",
]
def spawn(args):
child = pexpect.spawn(QEMU, args, timeout=900, encoding="utf-8",
codec_errors="replace", maxread=65536)
child.delaybeforesend = 0.4
return child
def login_live(child):
# The live medium may auto-login or present a login prompt; its hostname is
# typically `debian` (standard live) or `live`.
idx = child.expect([r"(?:live|debian) login:", r"[$#] $"], timeout=900)
if idx == 0:
child.sendline(LIVE_USER)
child.expect(r"Password:", timeout=60)
child.sendline(LIVE_PW)
child.expect(r"[$#] $", timeout=120)
def do_install():
args = base_args()
if not ISO:
raise SystemExit("ISO is required for install mode")
args += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
log = open(SERIAL_LOG, "w")
child = spawn(args)
child.logfile = log
try:
login_live(child)
child.sendline(
f"curl -fsSL {SERVE_URL}/appliance-guest.sh -o /tmp/gi.sh && bash /tmp/gi.sh"
)
child.expect([r"===INSTALL-RC=([0-9]+)===", "===FETCH-FAIL===",
"Kernel panic", pexpect.EOF, pexpect.TIMEOUT],
timeout=INSTALL_TIMEOUT)
if "INSTALL-RC" in (child.after or ""):
print("INSTALL_RC", child.match.group(1), flush=True)
else:
print("INSTALL did not report a status", flush=True)
child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600)
child.expect(pexpect.EOF, timeout=300)
finally:
child.close(force=True)
log.close()
def do_boot():
args = base_args() + ["-boot", "order=c"]
checks = os.environ.get(
"BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; "
"cat /proc/1/comm; systemctl is-system-running; "
"systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; "
"/usr/local/bin/sys rollback status 2>&1 || true; "
"echo ===CHECKS-$(printf END)===",
)
log = open(SERIAL_LOG, "w")
child = spawn(args)
child.logfile = log
try:
child.expect([r"[Pp]assphrase", r"login:"], timeout=600)
if "assphrase" in (child.after or ""):
child.sendline(LUKS_PW)
for _ in range(5):
child.expect(r"phoebus login:", timeout=300)
child.sendline(USER)
idx = child.expect([r"[Pp]assword:", r"phoebus login:", r"Login incorrect"],
timeout=60)
if idx == 0:
child.sendline(USER_PW)
if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0:
break
child.sendline(checks)
child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")))
print("checks complete", flush=True)
finally:
child.close(force=True)
log.close()
if __name__ == "__main__":
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode == "install":
do_install()
elif mode == "boot":
do_boot()
else:
print(__doc__)
sys.exit(2)

View file

@ -0,0 +1,54 @@
#!/bin/bash
# Guest-side, non-interactive install for the Debian-Live Phoebus appliance.
#
# Fetched and run by appliance-driver.py inside the live guest. Configuration
# and secrets are fetched from the host over QEMU user networking so they never
# appear in the serial transcript. The installer log is scanned for the LUKS
# passphrase so a leak fails the run.
set -uo pipefail
SERVE="${SERVE_URL:-http://10.0.2.2:8000}"
WORK=/tmp/phoebus-guest
mkdir -p "$WORK"
cd "$WORK" || exit 1
for f in test.conf luks.pw user.pw; do
if ! curl -fsSL "$SERVE/$f" -o "$f"; then
echo "===FETCH-FAIL=== ($f)"
exit 1
fi
done
chmod 600 luks.pw user.pw
PHOEBUS=/run/live/medium/phoebus/bin/phoebus
if [ ! -x "$PHOEBUS" ]; then
echo "===FETCH-FAIL=== (no phoebus launcher)"
exit 1
fi
# Installing Phoebus requires a connected model unless the explicit break-glass
# is passed. The baseline run uses the deterministic path.
"$PHOEBUS" --version || true
sudo -n "$PHOEBUS" --config "$WORK/test.conf" --install --yes --no-ai \
--luks-passphrase-file "$WORK/luks.pw" \
--user-password-file "$WORK/user.pw"
RC=$?
LEAK=0
for log in /run/phoebus-installer/install.log /tmp/phoebus-payload/install.log; do
if [ -f "$log" ] && grep -F -q "$(cat "$WORK/luks.pw")" "$log"; then
LEAK=1
fi
done
if [ "$LEAK" = 1 ]; then
echo "===SECRET_LEAK==="
RC=99
else
echo "===NO_SECRET_LEAK==="
fi
echo "===INSTALL-RC=$RC==="
sync
sudo -n poweroff -f || poweroff -f
echo "===POWEROFF==="

View file

@ -0,0 +1,39 @@
# Test configuration for the Debian-Live appliance VM.
#
# The appliance serves this file, the secrets and the stage3 over QEMU user
# networking (host 10.0.2.2). Set STAGE3_SHA256 to the real digest of the
# served stage3 before running; the installer verifies it fail-closed.
#
# Secrets are NOT stored here; they are supplied via --*-file.
HOSTNAME='phoebus'
USERNAME='phoebus'
USER_FULLNAME='Phoebus Test'
LOCALE='en_US.UTF-8'
TIMEZONE='UTC'
KEYMAP='us'
TARGET_DISK='/dev/vda'
PARTITION_SCHEME='whole_disk'
EFI_SIZE_MIB='1024'
FILESYSTEM='btrfs'
ENCRYPTION='luks2'
COMPRESS='zstd:3'
# safe = prebuilt distribution kernel (fast, reliable first boot)
KERNEL_PROFILE='safe'
KERNEL_UKI='no'
KERNEL_CONSOLE='console=tty0 console=ttyS0,115200'
KEEP_KERNELS='3'
PACKAGE_POLICY='balanced'
FEATURES_BINPKG='yes'
# none = core system only; dwl/full add the Wayland desktop
DESKTOP_PROFILE='none'
FLATPAK='no'
NIX_ENABLED='no'
STAGE3_URL='http://10.0.2.2:8000/stage3.tar.xz'
STAGE3_SHA256='0000000000000000000000000000000000000000000000000000000000000000'