phoebus_os/docs/SYS.md
Phoebus 12f365e38f
Some checks failed
ci / test (push) Has been cancelled
feat(sys): compare install sources and review alternatives
2026-10-03 17:13:35 -07:00

41 KiB

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.

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:

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:

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:

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 first receive a read-only search across the configured Portage, Flatpak, Snap, AppImage, Nix and staged-ebuild catalogues. Each source reports actual matches, no matches, an unavailable backend, or a failed lookup; catalog results are leads rather than verified artifacts. For a multiword name, an empty lane also searches the first term and labels those broader results. The model compares these findings before recommending a source. The desktop Assistant shows the source results alongside the recommended plan. Selecting a different result re-resolves the exact displayed package ID and prepares a new source-specific plan for approval; it never executes directly. A changed ID is refused. AppImage catalog leads have no direct install button because acquisition requires a pinned artifact URL and SHA-256. Source-constrained requests only investigate the selected lane. 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:

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:

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.

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 overlay review app-misc/chatgpt-desktop    # inspect listed repos and current ebuilds
sys overlay enable app-misc/chatgpt-desktop gentoo-zh # stage, review, approve, register
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. sys overlay review category/package follows each GPO lead to Gentoo's repository registry, then inspects the live Git repository name, commit, exact ebuild SHA-256, amd64 keywords, and package Manifest. It presents only options that pass these checks. The registry explicitly calls many repositories unofficial and experimental; listing and hashes do not prove publisher trust. sys overlay enable category/package repository repeats discovery and stages an exact revision-bound plan. After approval, the broker rechecks the registry, commit and ebuild, clones the repository, masks every package in it except the selected atom, adds a package-scoped ~amd64 allowance when needed, and registers it with auto-sync = yes. A normal emerge --sync refreshes the repository; sys updates still checks the last synced metadata. Installing or updating the package itself requires a separate reviewed Portage plan. If the source changes between review and execution, the broker refuses the stale plan. Only the running system (/) supports this external review and registration.

In the desktop Assistant, pasting a https://gpo.zugaina.org/category/package link checks that exact atom against configured Portage sources. If absent, it shows eligible overlay options with their source, revision and ebuild digest. Selecting one stages its registration plan; it never installs the package from the GPO listing. The same broker handles the Assistant approval and CLI plan.

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.