510 lines
27 KiB
Markdown
510 lines
27 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.
|
|
|
|
> [!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 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
|
|
```
|
|
|
|
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.
|
|
- **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 |
|
|
| `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 |
|
|
|
|
### Snap (opt-in; `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 |
|
|
|
|
Snap requires a ready `snapd` daemon. If it is absent, `snap_install` installs
|
|
`app-containers/snapd` through Portage and enables `snapd.socket` first.
|
|
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; a placeholder or mismatch is refused and
|
|
the download is discarded. Architecture is read from the ELF header without
|
|
executing the image. 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.
|
|
|
|
### 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. It never bypasses the model. `--legacy` runs the
|
|
same typed action deterministically with no model interaction.
|
|
|
|
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:
|
|
|
|
```sh
|
|
sys search firefox --legacy # every source
|
|
sys search firefox --legacy --flatpak # one source
|
|
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)
|
|
```
|
|
|
|
- **Search** covers Portage (`emerge --search`), Flatpak remote search, the Snap
|
|
Store, Phoebus-managed AppImages, 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 **Nix profiles**. Nix store paths are reported
|
|
separately as realised dependencies, never as installed programs. Custom
|
|
ebuilds install through Portage and are listed once, under Portage.
|
|
- **Information** combines installed copies (VDB metadata: version, size,
|
|
repository, `RDEPEND`) 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 updates reports a truthful
|
|
per-source outcome; AppImage (pinned URL+SHA) and Nix (project/declarative)
|
|
are explained as manual/project-specific and are never 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` previews its removal set with
|
|
`emerge --pretend --depclean` at review time and refuses when nothing is
|
|
selected; it preserves config files and user data. `clean cache` uses
|
|
`eclean-dist`/`eclean-pkg` (Portage) or `nix-store --gc` (Nix) and never
|
|
removes an installed package. `package_owners` and `package_dependencies`
|
|
require `app-portage/portage-utils`/`gentoolkit` and report an explicit
|
|
unsupported error when the tool is absent.
|
|
- `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 |
|
|
|
|
## 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:
|
|
|
|
- `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.
|
|
|
|
| # | 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 |
|
|
|
|
### 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 (33, 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.
|