phoebus_os/docs/SYS.md
Phoebus be423597f2
Some checks are pending
ci / test (push) Waiting to run
fix(sys): cover every AI package lane in source review
2026-10-03 12:35:16 -07:00

686 lines
39 KiB
Markdown

# `sys` — the Phoebus system interface
`sys` is the typed, validated execution boundary shared by the desktop assistant
(`phoebus-assistant`) and the offline/deterministic administrator. Whatever the
assistant can do, a human can do by typing the same action; the assistant only
makes it easier. The AI path emits the same closed action schema, and the LLM
never holds privilege: every mutation is reviewed and authenticated by a human
through the privileged broker.
```sh
sys <phrase> # natural language / AI workflow (default)
sys please <phrase> # natural conversational alias (same AI workflow)
sys ask "<request>" # assistant proposes the same typed actions
sys --legacy <phrase> # explicit deterministic mode (no model interaction)
sys --legacy --action '<json>' # one typed action in deterministic legacy mode
sys --broker --action '<json>' # internal broker invocation for shared UI / bridge
sys --assistant-bridge # stdio JSON-RPC bridge for the desktop assistant
```
Run `sys --help` for the full list of flags. Mutating actions require root
(`sudo sys ...`). Without a model, AI workflows stop and print the actionable
deterministic legacy alternative (`sys install <pkg> --legacy --<source>`)
instead of silently falling back or switching sources.
### Terminal feedback
Interactive `sys` commands show the current phase on stderr: checking the
system, investigating with the connected model, validating real package
evidence, reviewing effects, applying each approved action, and verifying the
result. A command that takes more than a moment shows its operation label;
long steps repeat their current label and elapsed time every ten seconds.
Progress never includes command arguments, command output, or credentials.
Results remain on stdout. Broker JSON does not emit human progress. The
assistant's stdio protocol sends redacted progress JSON lines before the final
reply, keyed by request ID; its GUI displays these phases in the conversation
card. Informational model answers are wrapped as prose and
omit the approval digest when no action is proposed.
> [!NOTE]
> `--legacy` is the administrative flag for `sys` deterministic operations.
> `--no-ai` is an installer-only break-glass flag reserved exclusively for
> non-interactive ISO installations (`installer-rs/tests/ai_guidance.rs`).
## AI-first installation (`sys install`)
Natural language is the default interaction. Source flags alone constrain the
AI investigation to a specific package source without bypassing the model:
```sh
sys install firefox # AI investigates and recommends a package source
sys please install firefox # identical AI workflow
sys ask "install firefox" # identical AI workflow
sys install firefox --flatpak # AI workflow constrained to Flatpak
sys install firefox --portage # AI workflow constrained to Portage
sys install nodejs --nix # AI workflow constrained to Nix
sys install chatgpt desktop through nix # AI workflow constrained to Nix; descriptive name
sys install thunderbird --snap # AI workflow constrained to Snap
sys install MyTool --appimage # AI workflow constrained to AppImage
sys install app-misc/my-thing --ebuild # AI workflow constrained to custom ebuild
```
An install phrase ending in `through`, `via`, `using`, or `with` plus a package
lane is parsed as a lane choice, not as part of the application name. If the
model cannot produce a valid plan for a descriptive name, `sys` searches the
requested lane and suggests an exact package identifier when the catalogue
confirms one. It does not install a fallback without review.
Removal is also AI-first by default. The deterministic ownership discovery and
policy validation always run underneath; the connected model confirms the exact
discovered copy. An ambiguous multi-lane install still requires an explicit
source flag, and a model failure stops execution rather than silently removing
deterministically:
```sh
sys remove firefox # AI workflow: confirm target, then remove
sys remove firefox --flatpak # AI workflow constrained to Flatpak
sys remove firefox --legacy # deterministic removal, no model
sys remove firefox --legacy --flatpak # deterministic removal from Flatpak
```
### Deterministic administration (`--legacy`)
Deterministic operation must be explicitly selected with `--legacy`:
```sh
sys install firefox --legacy --flatpak # deterministic Flatpak workflow; no model interaction
sys install firefox --legacy --portage # deterministic Portage workflow; no model interaction
sys remove firefox --legacy # deterministic removal, no model interaction
sys history --legacy # deterministic history without model
sys undo --legacy # deterministic recovery without model
sys install firefox --legacy # REFUSED: requires an explicit package source flag
```
When `--legacy` is used with `install` but without an explicit source flag,
execution is refused and available package sources are displayed. `--legacy`
never contacts a model.
Direct JSON and action-file invocations (`--action` and `--action-file`) are
audited entry points: they fail closed unless invoked with `--legacy` (for
deterministic administrator usage) or `--broker` (for internal UI/bridge
calls).
One shared workflow (ADR 0013) is used by all installations:
```
identify -> evidence -> AI investigation -> proposed selection
-> deterministic validation + effects -> review -> approve -> execute
-> verify -> history
```
- **Unqualified** installation consults the connected model. The model may
request bounded, read-only evidence (`discover_candidates`,
`inspect_candidate`, `check_backend`, `inspect_installation`) and may ask one
bounded question about your intent. It returns a structured proposal naming a
real candidate id; the deterministic resolver independently confirms that
candidate against backend metadata, computes the effects, and binds approval
to a digest. A fabricated, stale, ambiguous or duplicating proposal is
rejected and returned to the model for a bounded revision.
- **Source flags without `--legacy`** constrain the AI investigation to the
specified backend, ensuring the model evaluates and explains candidates for
that source while preserving the full investigation, explanation, and
approval cycle.
- **Package source review** requires the model to inspect the exact candidate
before recommending a package from any lane, including ordinary Portage
source and binary packages. A vendor binary ebuild can appear in the
Portage source lane. `inspect_candidate` returns a structured
health report: source, integrity evidence, reported version and freshness
limits, isolation, and a `hold` or `review_required` status. The model must
explain uncertainty rather than declare a package safe or current. For
Flatpak, `sys` checks that the resolved app comes from its configured
`flathub` install remote, that the remote uses HTTPS, and that GPG
verification is enabled. It refuses an unverified remote and repeats the
check before execution; a changed version, remote, or verification state
invalidates approval. This Flatpak check also applies to direct typed
administrator actions. For all reviewed installs, the selected candidate
is inspected again and a changed version, source, or verification state
invalidates approval. Portage repository origin and Nix registry revision
are not currently established by this inspection and are labeled as such.
The plan shows these source health findings. A hash or
catalog entry alone does not authenticate an AppImage publisher, and this
review cannot prove that an upstream release is uncompromised.
- **General assistant plans** cannot use direct package install actions to
skip this source review. Package installs use the dedicated `sys install`
workflow. Typed administrator actions remain available through the audited
`--legacy` entry point.
- **Explicit backend flags with `--legacy`** bypass the model entirely, are
mutually exclusive, and never fall back to another lane. If the lane cannot
satisfy the request, the reason and alternatives are shown and nothing is
installed.
- **No model / Provider failure**: For an unqualified install without a model or
upon provider error, the operation halts cleanly. The deterministic candidate
selection and explicit `--legacy` commands are printed, and nothing is
installed. A provider failure is never permission to install through a lane
silently.
- Every install is recorded in the transaction log **before** it runs (an
interrupted run leaves an in-progress record) and verified afterwards
(package database, `flatpak list`, `snap list`, or the managed AppImage
record). A verification failure is a failed transaction. User data is
preserved by default on removal.
Read-only investigation is also directly available:
| Phrase / JSON | Typed action | Kind |
| --- | --- | --- |
| *(JSON only)* | `discover_candidates` | read |
| *(JSON only)* | `inspect_candidate` | read |
| *(JSON only)* | `check_backend` | read |
| *(JSON only)* | `inspect_installation` | read |
Example:
```sh
sys --action '{"action":"discover_candidates","query":"firefox","gui":true}'
sys --action '{"action":"check_backend","backend":"snap"}'
```
## Commands and typed actions
### Services (Portage/systemd ownership)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `inspect sshd` | `inspect_service` | read |
| `enable sshd` | `enable_service` | mutate |
| `disable sshd` | `disable_service` | mutate |
| `start sshd` | `start_service` | mutate |
| `stop sshd` | `stop_service` | mutate |
| `restart sshd` | `restart_service` | mutate |
### Packages (Portage)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `install vim` / `add vim` | `install_package` | mutate |
| `remove vim` / `uninstall vim` | `remove_package` | mutate |
| `build firefox from source` | `convert_to_source` | mutate (High risk, protective snapshot) |
| `build tuned kernel` | `build_tuned_kernel` | mutate (High risk, protective snapshot) |
| `search firefox` / `find firefox` | `search_packages` | read |
| `update` | `update_system` | mutate |
| `prepare updates` | `prepare_updates` | mutate |
| `what are you compiling` | `inspect_updates` | read |
| *(JSON only)* | `inspect_package` | read |
### Source selection (all lanes)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `choose firefox` | `choose_package` | read |
| `choose firefox via flatpak` | `choose_package` | read |
| `choose spotify as a gui sandboxed app` | `choose_package` | read |
| `prefer firefox via flatpak` | `set_package_preference` | mutate (personal) |
| `prefer firefox auto` | `set_package_preference` | mutate (personal) |
| *(JSON only)* `system_wide: true` | `set_package_preference` | mutate (privileged) |
`prefer ...` saves the invoking user's own preference; it needs no elevation and
is stored under the user's config directory. The system-wide default is the same
action with `"system_wide": true`, which requires the authenticated broker. At
resolution time the personal choice wins and system defaults fill anything the
user has not set.
`choose` resolves real backend metadata, applies the shared policy
(ADR 0006), and prints the selected lane, version, provenance, integrity,
sandbox level, sizes, update behaviour and the rejected alternatives. It never
installs anything and never fabricates a candidate.
### Flatpak
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `flatpak install org.chromium.Chromium` | `flatpak_install` | mutate |
| `flatpak remove org.chromium.Chromium` | `flatpak_remove` | mutate |
| `flatpak list` | `flatpak_list` | read |
### Nix (developer lane)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `nix prepare nodejs python312` | `nix_prepare` | mutate |
| `nix install cmatrix` | `nix_install` | mutate |
`sys install cmatrix --legacy --nix` installs into the shared Phoebus Nix
profile; its commands are on the graphical session's `PATH`. The Nix client's
default profile remains separate. Direct `nix profile install nixpkgs#cmatrix`
as a normal user uses the user's own profile, which is also on `PATH`.
`nix prepare` only realises packages for temporary `nix shell` use.
### Snap (`app-containers/snapd` through Portage)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `snap find notes` | `snap_find` | read |
| `snap info thunderbird` | `snap_info` | read |
| `snap install thunderbird [channel]` | `snap_install` | mutate |
| `snap remove thunderbird` | `snap_remove` | mutate |
| `snap list` | `snap_list` | read |
| `snap refresh [name]` | `snap_refresh` | mutate |
| `snap connections thunderbird` | `snap_connections` | read |
New Phoebus desktop installs include `snapd` and enable `snapd.socket`; systemd
starts the socket on boot. Snap application installs still receive their own
review and approval. Systems installed before this change, and minimal
installations, need a separate reviewed setup step:
```sh
sys install app-containers/snapd --legacy --portage
sys enable snapd.socket --legacy
sys start snapd.socket --legacy
sys install <app> --legacy --snap
```
Run these on the installed system, not on the live installer. The resolver
prints the setup commands when the daemon is missing. AppArmor availability
determines the confinement reported by `snap debug confinement`; a running
daemon alone does not imply strict confinement.
New installs include the scoped `sys-fs/squashfs-tools lzma lzo` USE settings
required by Gentoo's snapd ebuild. An existing installation made before that
setting was added may need the same line in
`/etc/portage/package.use/phoebus-snap` before the Portage step.
Confinement is detected (`strict`/`partial`/`none`); `--classic` is only used
when the typed action sets `"classic": true` and is shown in the review. The
plan notes that snapd also refreshes automatically.
### AppImage (opt-in; managed, not sandboxed)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `appimage import /path/App.AppImage` | `appimage_import` | mutate |
| *(JSON only)* | `appimage_acquire` | mutate |
| *(JSON only)* | `appimage_update` | mutate |
| `appimage remove name` | `appimage_remove` | mutate |
| `appimage info name` | `appimage_info` | read |
| `appimage list` | `appimage_list` | read |
Acquisition requires a pinned SHA-256 and a public URL without credentials,
query or fragment; a placeholder or mismatch is refused and
the download is discarded. Architecture is read from the ELF header without
executing the image. Managed files live in `/opt/phoebus/appimages`, where a
normal desktop account can launch them and read their inventory. Desktop
entries are installed, and user data is preserved
on removal unless `"purge_data": true`. AppImage provides **no application
sandbox** and is described as such.
Images imported by older builds into the private
`/var/lib/phoebus/appimages` directory must be re-imported by an administrator
from that original file; the current import writes the accessible path and
replaces its desktop entry. The old file is left in place for explicit cleanup.
### Custom ebuilds (Phoebus overlay)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `ebuilds` / `custom ebuilds` | `custom_ebuild_list` | read |
| *(JSON only)* | `custom_ebuild_prepare` | mutate |
| *(JSON only)* | `custom_ebuild_install` | mutate |
| *(JSON only)* | `custom_ebuild_remove` | mutate |
A custom ebuild is untrusted executable code. `custom_ebuild_prepare` writes it
to `/var/db/repos/phoebus` with a rationale and the SHA-256 of its exact
content; it does not build it. `custom_ebuild_install` requires that same
digest, regenerates the `Manifest` and builds through Portage with its sandbox
enabled. Editing the staged ebuild invalidates the approval.
### Package catalogue: search, inventory, information, updates, maintenance
These are AI-first like every other operation. Without `--legacy` the request
enters the connected model, which answers from **bounded, read-only evidence**
(search, inventory, information, update checks). A source flag
(`--portage`/`--flatpak`/`--nix`/`--snap`/`--appimage`/`--ebuild`) constrains the
AI workflow: lane-selectable queries are rewritten to that lane and an action
for any other lane is refused. `--legacy` runs the same typed action
deterministically with no model interaction.
Explicit AppImage **install** requests are a discovery-only exception: the
community catalog has no pinned artifact hash, so `sys` and the desktop
assistant show matching leads and the import/acquire requirements without
creating an install plan. A catalog match cannot be installed through
`sys install <name> --legacy --appimage` either.
Every result distinguishes three honest states per lane: **unavailable**
(tooling absent), **failed** (the tool ran and did not answer), and **empty**
(a successful query with no results). Package facts are never invented.
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `search firefox` / `find firefox` | `search_packages` | read |
| `list` / `list installed` / `list vim` | `list_packages` | read |
| `info firefox` | `package_info` | read |
| `updates` / `check updates` | `check_updates` | read |
| `apply updates` / `upgrade` | `apply_updates` | mutate |
| `depclean` / `autoremove` | `depclean` | mutate |
| `clean cache` / `clean distfiles` | `clean_cache` | mutate |
| `who owns /usr/bin/vim` | `package_owners` | read |
| `deps vim` | `package_dependencies` (reverse=false) | read |
| `rdeps vim` | `package_dependencies` (reverse=true) | read |
Deterministic forms:
On the desktop, launch **Phoebus Updates** or press Super+U. The update view
checks sources without a model, and **Review & Apply** opens the same
interactive `sudo sys apply updates --legacy` flow in Kitty. Portage compiles
and other package progress stay visible through completion. DankMaterialShell
is updated as a normal Portage package; the default DMS bar does not use its
separate updater widget.
```sh
sys search firefox --legacy # every source
sys search firefox --legacy --flatpak # one source
sys search firefox --legacy --appimage # managed images + community catalog leads
sys search chatgpt --legacy --overlays --portage # configured Portage + external GPO leads
sys list --legacy # installed inventory, all lanes
sys list vim --legacy --portage # inventory, source + text filter
sys info firefox --legacy # version/source/status/deps/size
sys updates --legacy # check only, no mutation
sys apply updates --legacy # apply, per-source outcome
sys depclean --legacy # Portage unused-dependency removal
sys clean cache --legacy --nix # Nix GC
sys who owns /usr/bin/vim --legacy # Portage file ownership
sys deps vim --legacy # forward dependencies
sys rdeps vim --legacy # reverse dependencies (equery)
```
Portage searches cover repositories configured on this machine. The optional
`--overlays` flag sends the search term to the unofficial GPO overlay index and
lists matching ebuild names as **external leads** below the local catalogue.
Those leads are not validated install candidates: review and sync a repository
first, and accept `~amd64` only for a specific package if needed. The external
lookup has an eight-second limit; a network failure leaves local results
available. `--overlays` is restricted to deterministic `search --legacy` and
cannot be combined with a non-Portage source flag.
AppImage searches include Phoebus-managed images and read-only leads from the
AppImage project's community catalog when online. Leads show a catalog page
when supplied, but the catalog does not provide a pinned artifact and hash.
They are labeled `catalog lead` and cannot be installed from a search result;
`appimage_acquire` still needs an independently reviewed HTTPS artifact URL and
SHA-256. An unavailable catalog is reported as a lookup failure, while managed
images remain visible. Alternate-root searches inspect only managed images.
During a terminal mutation, `sys` shows the package manager's output as it
arrives: Portage build and merge logs, Flatpak transaction progress, Snap
operations, Nix realisation, custom ebuild builds, and AppImage downloads.
Carriage-return progress updates are displayed as well as complete lines.
The current phase and slow-step heartbeat remain visible. Read-only queries
return a composed report; the broker and assistant protocols keep their
structured output.
- **Search** covers Portage (`emerge --search`), Flatpak remote search, the Snap
Store, Phoebus-managed AppImages plus online community catalog leads, Nix (`nix search`, when online) and staged
custom ebuilds. Entries show source, identity, version, description and
installed status where the backend provides them.
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
Phoebus-managed AppImages and the **packages of the active Nix profiles**
(parsed from each profile's `manifest.json`; historical generations and
realised store paths are reported separately, never as installed programs).
Custom ebuilds install through Portage and are listed once, under Portage.
- **Information** combines installed copies (VDB metadata: version, size,
repository, `DEPEND`/`RDEPEND`/`BDEPEND`) with resolved candidates and policy
metadata. When more than one real package matches, the report is marked
**ambiguous** and lists every match instead of guessing.
- **Updates** check every supported lane. Applying a Flatpak or Snap update
**executes exactly the reviewed transaction**: the plan binds the full Flatpak
ref (`app/…/arch/branch`, from `remote-ls`) plus the installed and remote
**full commits** (from `flatpak info`, since Flatpak's `commit` column is
abbreviated), or the snap name plus its old/new revisions and tracking
channel. Execution is pinned (`flatpak update --commit=<commit>`) and the
source is revalidated immediately before its mutation — including after an
earlier source has run — so a commit republished under an unchanged human
version, a newly appearing update, or a change in the active installation
aborts as stale. A source whose resolution failed is never re-discovered and
executed later. `flatpak` and `snap` both require backend prerequisites and
are refused explicitly when they cannot run. AppImage (pinned URL+SHA) and Nix
(project/declarative) are refused as a system-level transaction rather than
reported as updated. A source that was attempted and failed fails the whole
action while the report still shows the sources that succeeded. Background
**preparation** (`prepare updates`, `what are you compiling`) remains distinct
from **activation**.
- **Maintenance**: `depclean` records its removal set as **structured package
effects** (not only prose) from `emerge --pretend --depclean` at review time,
so a changed removal set is caught before execution; it refuses when the
selection cannot be established, and preserves config files and user data.
`clean cache` reviews each cleaner's real **non-destructive preview**
(`eclean-dist`/`eclean-pkg` delete by default, so the preview passes
`--pretend` with the same `--deep` selection as the destructive run;
`nix-store --gc`'s documented preview is `--print-dead`) and binds the item
set to approval; a cleaner that ran and failed propagates as a failed action
while partial successes are preserved, and an unavailable cleaner is reported
distinctly from one that found nothing. `package_owners` and
`package_dependencies` use the installed VDB metadata (forward dependencies
include already-satisfied and conditional/versioned dependencies, never the
requested package itself; reverse dependencies exclude only a genuine
self-reference where the *dependent* is the queried package) with
`qdepends`/`equery` as the tree fallback, and report an explicit unsupported
error when the tool is absent.
- **Rooting**: every catalogue, update-check and maintenance command is built
for the *intended target* — directly for `/`, or inside the target chroot for
an alternate root. Snap acts on the running daemon and is therefore reported
unavailable (and refused for mutation) for an alternate root rather than ever
touching the host.
- `sys inspect <service> --legacy` is unchanged: `inspect` always means service
inspection (use `info` for packages).
Read-only catalogue actions (`search_packages`, `list_packages`,
`package_info`, `check_updates`, `package_owners`, `package_dependencies`) need
no root and write no transaction. `apply_updates`, `depclean` and `clean_cache`
are mutating, require root, take a protective snapshot where available, and are
recorded.
### Snapshots and rollback
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `snapshot before update` | `create_snapshot` | mutate |
| `undo` / `rollback` | `undo` | mutate |
| `undo status` | `rollback_status` | read |
| `history` | `history` | read |
Portage, Flatpak, Snap, Nix profile, managed AppImage and custom ebuild package changes take
a protective coordinated root/var snapshot before mutation. `sys undo`
restores a chosen snapshot on the next boot; `/home` remains outside that
snapshot. Nix `prepare` only realises a development attribute and does not
install it into a persistent profile. Direct user-managed Nix profile changes and
snapd's automatic background refreshes are outside a `sys` transaction.
## Desktop assistant bridge (`sys --assistant-bridge`)
The desktop assistant GUI (`phoebus-assistant`) is a lightweight Quickshell QML
interface that delegates all logic to `sys --assistant-bridge`. The bridge runs
a stdio JSON-RPC server speaking newline-delimited JSON messages:
For work that takes time, the bridge emits zero or more intermediate
`{"id":17,"event":"progress","progress":{"label":"...","state":"started"}}`
messages before the final response with the same ID. A matching `completed`
or `failed` event closes each phase. Labels pass through the shared secret
redactor; command arguments, output, model messages, and credentials are not
sent to QML. The assistant displays the activity under the relevant request
or approved plan and retains it after completion. Callers must wait for a
final response rather than treating a progress event as the reply.
Malformed model JSON or typed investigation steps receive up to two bounded
correction requests. A third malformed reply returns an error; no action is
executed from that reply. Installation investigation also accepts a typed
`unavailable` result after read-only candidate discovery. If it cannot build a
validated plan, the desktop shows a read-only information card with AppImage
catalog guidance and no approval control. A catalog lead is never treated as
an installable candidate without a reviewed artifact URL and SHA-256.
- `handshake`: validates client identity and checks active AI model connectivity.
- `ask`: submits a conversational request (`install firefox`, `why is audio broken?`)
into the shared AI workflow, returning a reviewed plan card for install,
removal, general administration, or a follow-up confirmation. Every plan type
carries the same `plan_id`/`digest` review and approval state; information and
clarification replies carry no execution control. Removal is AI-first by
default.
- `execute`: executes exactly the referenced reviewed plan by plan ID and plan
digest. The privileged broker repeats the full validation.
- `legacy_install`: performs deterministic installation with an explicit backend.
- `legacy_execute`: executes typed actions deterministically.
- `clear_conversation`: deletes the persisted, minimized follow-up context.
- `updates`: queries the unified multi-source update system across Portage,
Flatpak, Snap, AppImage, and Nix.
- `proactive_alerts`, `proactive_snooze`, `proactive_dismiss`: interacts with the
quiet proactive system monitor.
- `get_preferences`, `set_preferences`: inspects and edits the invoking user's
package source profiles, project environment tool mappings, and
keep-existing-source pins. Personal preferences are stored 0600/0700 under the
user's own config (`~/.config/phoebus/package-preferences.toml`) without
elevation; system defaults stay root-owned. When the write runs elevated the
created paths are chowned to the initiating user, a non-root process acting
for a different user is refused, and symlinked path components are rejected.
A failed write is reported as an error, never as "saved".
- `history`, `undo`: queries transaction logs and initiates recovery.
Zero business logic lives in the GUI: equivalent CLI and GUI requests produce
identical validated plans given the same facts and preferences.
## Privileged execution boundary
A mutating plan is stored as a `PreparedPlan` in per-user storage
(`/run/user/<uid>/phoebus/plans`, mode 0700; a 0600 plan file; atomic write; a
128-bit unpredictable identifier). The plan is sealed with an integrity digest
over the reviewed fields, the target root and the initiating uid. That seal is
only a self-consistency check: the owner of the plan file can recompute it, so
it is never treated as authentication.
`execute_plan` validates the plan before elevation and again — authoritatively —
inside the privileged broker (`sys --broker --execute-plan <id> --plan-uid <uid>
--approval-digest <sha256> --root <root>`). The broker:
- **independently recomputes the canonical approval digest** from the exact
executable actions, candidate and reviewed material effects, and requires it
to equal both the digest stored in the plan and the independently supplied
`--approval-digest`. Retaining an approved digest while swapping an action and
resealing is therefore rejected for every plan kind (Install, LegacyInstall,
Removal, General, Undo) before any command runs;
- carries the digest the review card showed the user across authentication
independently of the plan file, so a replacement plan under the same
identifier is rejected even when it is resealed with a valid, self-consistent
checksum;
- rejects expired, modified, malformed, wrong-root or wrong-uid plans;
- derives the initiating identity from the authenticated caller context
(`PKEXEC_UID`), treating `--plan-uid` as untrusted input;
- revalidates the current package/removal state after authentication, and again
action-by-action at the execution boundary against the reviewed effects;
- anchors consumption in a **root-owned approval ledger**
(`/var/lib/phoebus/approvals`, 0700 / 0600, ADR 0014), keyed by a stable
approval identity (plan id, canonical digest, initiating uid, target root).
The key is claimed with `O_EXCL`, so at most one execution may run under
concurrent submissions; a retry is refused even after the user deletes every
file in their own plan directory; and editing only presentation fields
(summary, rationale, verification) and resealing cannot mint a fresh record.
A newly reviewed identical operation has a new plan id and is allowed. Each
claim records its owning process; terminal statuses are published atomically
once, are immutable, and recovery only marks an owner that is provably gone;
- treats the plan file and its contents as untrusted input, resolving storage
from the uid rather than an arbitrary path.
Authentication happens outside model context through Polkit (`pkexec`), never
passwordless sudo. Cancelling or refusing authentication performs no mutation
and consumes nothing: authentication precedes the ledger claim. A failed,
stale-plan, verification-failed or interrupted operation reaches a truthful
terminal status.
Each transaction records the outcome per action (`completed`, `failed`,
`unattempted`) plus the protective snapshot, so a partial execution is visible
and never reported as success.
## Transaction truthfulness
Every mutation is recorded as an in-progress transaction **before** it runs. On
action failure, verification failure, refusal or cancellation the same record is
finished with a truthful result (`failed: …` / `verify failed: …`); completed
steps and their protective snapshot are retained. A record that never reaches a
terminal result is an interrupted operation, and its consumed plan cannot be
replayed. A malformed broker reply is a protocol failure, never fabricated
success. History persistence failures are surfaced, not swallowed.
## Conversation privacy
Follow-up context is minimized before persistence: the raw request is never
stored, only structured context (kind, application, candidate, rationale), and
registered secrets are scrubbed with the active redactor. The history file is
0600 inside a 0700 directory, written atomically, bounded to ten turns, and can
be cleared (`clear_conversation`) so it no longer informs later follow-ups.
Redaction removes known secrets; it does not claim to detect arbitrary sensitive
text, which is why raw requests are not persisted.
## Acceptance matrix
The matrix below is the repeatable acceptance suite. `installer/tests/vm/sys-acceptance.sh`
runs the deterministic, legacy, and JSON acceptance cases inside a booted,
installed, detached VM and prints a machine-readable summary; it is safe to run
with no network and no model.
`sys-lane-operations.sh` exercises real Portage, Flatpak, AppImage and Nix
mutations; `sys-custom-ebuild-operations.sh` stages, builds and removes a
harmless package; `snap-guest.sh` covers Snap first use and refresh; and the
`appimage-rollback-*` fixtures verify a non-Portage change across a detached
rollback boot. All mutation fixtures require a validated disposable qcow2 VM.
| # | Case | Command | Expected |
| --- | --- | --- | --- |
| 1 | Identity | `sys --version` | prints the version, exit 0 |
| 2 | Read-only history (legacy) | `sys history --legacy` | state, exit 0, no mutation |
| 3 | Undo status (legacy) | `sys undo status --legacy` | idle rollback state, exit 0 |
| 4 | Non-root undo | `sys undo --legacy` (non-root) | requires root, exit nonzero |
| 5 | AppImage inventory (empty) | `sys --legacy appimage list` | "no managed AppImages", exit 0 |
| 6 | Ebuild inventory (empty) | `sys --legacy ebuilds` | "no custom ebuilds", exit 0 |
| 7 | Invalid natural operand | `sys --legacy -- install --color=n` | rejected, nonzero |
| 8 | Unknown phrase | `sys --legacy frobnicate` | rejected, nonzero, examples shown |
| 9 | Audited action without legacy/broker | `sys --action '{"action":"history"}'` | fail closed, requires `--legacy` or `--broker` |
| 10 | Legacy install without source | `sys install firefox --legacy` | refused: requires explicit source flag |
| 11 | JSON unknown action | `--legacy --action '{"action":"run_shell"}'` | fail closed, nonzero |
| 12 | JSON unknown field | `--legacy --action '{"action":"history","x":1}'` | fail closed, nonzero |
| 13 | Option-like operand (JSON) | `install_package atom="-C"` | rejected before any command |
| 14 | Invalid Snap name | `snap_install name="Bad Name"` | rejected, nonzero |
| 15 | Invalid AppImage hash | `appimage_acquire sha256="00"` | rejected, nonzero |
| 16 | Ebuild path traversal | `custom_ebuild_prepare atom="../../x"` | rejected, nonzero |
| 17 | System-wide policy as non-root | `set_package_preference system_wide:true` | refused: needs root |
| 17b | Personal preference as non-root | `set_package_preference` | saved to user config, no `/etc` write |
| 18 | Offline `sys ask` | `sys ask "<request>"` with no provider | deterministic fallback, nonzero |
| 19 | Choose with no lane | `sys --root / choose unused-xyz --legacy` | selection or clear failure, never invented |
| 20 | Conflicting backend flags | `sys install x --flatpak --nix` | rejected by CLI |
| 21 | Source flag without install | `sys --flatpak history --legacy` | rejected by CLI |
| 22 | Unqualified with no model | `sys install firefox` (no provider) | deterministic offer printed, nothing installed |
| 23 | Read-only investigation | `--legacy --action '{"action":"check_backend",...}'` | structured JSON evidence returned |
| 24 | Legacy unified search | `sys search firefox --legacy` | "Package catalogue", exit 0 |
| 25 | Legacy inventory | `sys list --legacy` | "Package catalogue", exit 0 |
| 26 | Legacy package information | `sys info bash --legacy` | "Package information", exit 0 |
| 27 | Legacy update check | `sys updates --legacy` | "Unified Update Overview", exit 0 |
| 28 | Legacy JSON search | `--legacy --action '{"action":"search_packages","query":"firefox"}'` | catalogue, exit 0 |
| 29 | Search without a model | `sys search firefox` (no provider) | nonzero; exact `sys search firefox --legacy` offered; nothing searched |
| 30 | Source flag constrains the AI | `sys search firefox --flatpak` (no provider) | nonzero; `... --legacy --flatpak` offered; not bypassed |
| 31 | Non-root depclean | `sys depclean --legacy` (non-root) | requires root, nonzero |
| 32 | Non-root apply updates | `sys apply updates --legacy` (non-root) | requires root, nonzero |
| 33 | Non-root cache cleanup | `sys clean cache --legacy` (non-root) | requires root, nonzero |
| 34 | Non-root source build | `sys --legacy --action '{"action":"convert_to_source","app":"firefox"}'` (non-root) | requires root, nonzero |
| 35 | Non-root tuned kernel | `sys build tuned kernel --legacy` (non-root) | requires root, nonzero |
| 36 | Brave source refusal (root, no mutation) | `--legacy --action '{"action":"convert_to_source","app":"brave"}'` (root) | nonzero, "no trustworthy source route"; refused before approval/commands |
| 37 | Unknown source refusal (root, no mutation) | `--legacy --action '{"action":"convert_to_source","app":"definitely-not-an-app-xyz"}'` (root) | nonzero, "no supported source build" |
### Mutating acceptance cases (disposable VM only)
When `SYS_ACCEPTANCE_MUTATE=1` is set in the disposable VM:
- `mutate-install`: `sys -y install app-misc/hello --legacy --portage` installs and verifies via `emerge -p`.
- `mutate-remove`: `sys -y remove app-misc/hello --legacy` uninstalls cleanly.
- `mutate-history`: `sys history --legacy` confirms both install and remove are logged.
The read-only and failure acceptance cases (37, including the
personal-preference case and the catalogue group) are exercised by the test
suite (`installer/tests/vm/sys-acceptance.sh`); the broker approval/replay
regression is covered by `phoebus-installer` unit tests. Host unit and
integration tests in `crates/phoebus-installer/tests/sys_cli.rs`,
`crates/phoebus-core/`, and `crates/phoebus-executor/` cover proposal validation,
digest matching, lane policy, cross-source removal, catalogue parsing, per-source
failures/ambiguity, the AI-default routing contract, and the source constraint.
## Security properties
- **No shell.** Every command is an argument vector through
`phoebus-executor::Exec`; there is no `sh -c` on any path.
- **Validated at the boundary.** Every action (manual, JSON, or AI) is
re-validated before a command is built; option-like operands are rejected.
- **Target-root isolation.** Alternate-root operations are chrooted; runtime
operations (services, Snap) refuse an alternate root.
- **Approval binding.** A resolved plan has a digest; a material change between
review and execution aborts. A custom ebuild binds approval to its content
digest.
- **Secrets** travel only through mode-0600 files/stdin and are redacted from
logs and history.