Completion Agent (linxira-completion-agent)
Why it exists
The installer deliberately defers some software: it needs a network, needs extra
licence acceptance, or the provider behind it is not implemented yet. Those items must
not disappear silently — you need to see what is left, why, and what installing it would
change. linxira-completion-agent is the screen that lays out the software explicitly
deferred in the installer receipt.
It binds the recorded catalog to that receipt and shows source, size, licence, repository impact and deferability per item. It accepts no package names, commands, URLs or repository definitions.
Responsibility boundaries
It owns: reading the explicitly deferred entries from the installer receipt, presenting source and licence information, collecting explicit confirmation for sensitive items, and recording the deferred or completed state.
It does not own:
- Install decisions. Which items may install, through which source and whether acceptance is required comes from the catalog and the receipt.
- Package transactions. Installing is not done here; it is handed to Components.
- The installer's job. Reviewed official Arch applications and components must be installed into the Calamares target before first boot; a receipt that defers such an item to Completion is rejected.
The delegated transaction: when something is executable, the agent writes the
receipt items as a selection document and hands it to the
Components plan → confirm → apply chain, with pkexec elevating
apply; receipts are written by the backend under
/var/lib/linxira/components/receipts.
The agent never escalates by itself: it runs as a normal user, only reads the
catalog and the installer receipt, only writes its own state file, and never calls
sudo, runs pacman or writes backend receipts.
How to use
linxira-completion-agent # from the application menu or a terminal
linxira-completion-agent --autostart # what the first-login entry runs
The table has six columns: software, source, size, licence, repository change and state.
State is either Ready or Deferred. Items with proprietary licences or an opt-in
requirement add a confirmation checkbox that must be ticked individually.
Two actions:
- Defer records the whole plan as deferred and closes the window.
- Complete ready items is enabled only when the network is available (checked via
nmcli), at least one item is ready, and every sensitive item is ticked. It writes a selection document to a temporary directory, runslinxira-components planandconfirm, thenpkexecrunsapply.
Inputs are fixed: /usr/share/linxira/catalog/catalog-v3.json and
/var/lib/linxira/installer-selection.json. If either is a symlink, the receipt schema
is unsupported, the catalog changed after the receipt was written, or the
classifications disagree, the program prints the reason and exits with status 2.
State lives in ${XDG_STATE_HOME:-$HOME/.local/state}/linxira/completion/state.json and
records the catalog and receipt SHA-256 values. With --autostart, a previous status of
complete or deferred exits immediately, and already succeeded items are not shown
again.
When root is needed
Not at all. The agent runs as your normal user and only reads the catalog and receipt.
If something is applied, pkexec requests Polkit authorization. The agent never
elevates on its own and accepts no root commands.
Known limitations
- The current implementation is a review and defer surface. Every deferred entry is
classified
Deferred(the executable flag is always false), so Complete ready items is never enabled. Theplan/confirm/applypath exists but no item reaches it today. - Only leaves listed in the receipt's
pendingItemsare shown; installed or unselected items never appear. - Operation leaves wait for their dedicated system action. AUR, Flatpak, Conda, proprietary and review-channel items each wait for their provider and review contract.
- Only Catalog v3 and the
org.linxira.installer.selection-receipt.v1receipt are accepted; a receipt that does not classify every selected item exactly once is rejected. - It does not install reviewed official Arch applications or components; that belongs to the installer, and deferring them is treated as an error.
Further reading
Receipt/catalog binding rules, item classification and the state file format are in the
linxira-completion-agent
repository. The transaction shape is described under Components.