# Lios Plugin Contract
Managed Lios plugins are separate `lios-*` executables, not dynamically loaded
shared libraries. A standalone plugin crash cannot corrupt Lios's memory.
## Built-in LiosBar component
Lios 0.1.81 additionally embeds an exact, reviewed LiosBar widget snapshot.
`Ctrl+Shift+T` opens this integrated workspace without installing or launching
a plugin executable. Its static Rust code shares Lios's process and is not a
sandbox. Provenance and licenses are in `src/liosbar/`.
The component owns only layout, bounded labels, stable IDs, and selection.
Lios owns each complete terminal widget, process, settings, clipboard guard,
and close confirmation. Actions are scoped to each session; hidden terminals
cannot change the active title or complete stale paste requests. Pending
startup is canceled on removal, and exited output is retained until closed.
The managed standalone plugin described below is still a separate option.
Disabling it does not disable the built-in workspace, and its install/enable
state does not grant the component any additional authority.
## Preferences behavior
The `Plugins` card distinguishes three independent facts:
- managed: a binary and Cargo receipt exist in Lios's versioned plugin root and
pass ownership, permission, type, and pinned-identity checks;
- enabled: Lios may present and launch that plugin;
- running: a separately launched process may continue until it exits.
Enabling an absent plugin is an explicit install request. Lios invokes Cargo
directly with an argv equivalent to:
```text
cargo install --root "$XDG_DATA_HOME/lios/plugins/lios-bar-0.1.7" --locked --force --registry crates-io --version =0.1.7 lios-bar
```
No shell command string is built. The catalog supplies the crate name,
executable name, and exact version; user input cannot replace those fields.
Standard output is silenced. Standard error is continuously drained without
blocking Cargo, but Lios retains only a 32 KiB tail and shows at most 180
sanitized characters after a failure, so compiler output cannot grow memory
without limit or inject terminal control sequences into the GUI.
Cargo and its compiler children run in a dedicated process group. The install
button becomes `Cancel` while they run, closing the plugin UI also cancels the
operation, and a 30-minute safety deadline stops an abandoned build. Cancel and
timeout request graceful termination first, then kill the process group after a
five-second grace period if Cargo has not exited. Completion, cancellation, and
timeout callbacks share a generation guard so only the current install may
change its controls or configuration.
`XDG_DATA_HOME` falls back to `$HOME/.local/share`. Lios never discovers plugin
binaries through `PATH`; install, repair, detection, and launch all use that
fixed app-owned root.
After Cargo returns success, Lios requires the managed root, `bin` directory,
executable, and `.crates2.json` receipt to be real user-owned filesystem objects
rather than symlinks. They must reject group/world writes; the executable and
receipt must not be hard-linked; and the receipt is capped at 1 MiB. Its metadata
must match all of:
- curated crate name;
- exact curated version;
- registry source rather than a local path;
- expected executable name, with no second package claiming that binary.
A same-named or unsafe binary is shown as unmanaged and cannot be launched
through Lios until `Repair` installs the pinned registry release. Cargo's receipt
is an identity/provenance check, not a cryptographic signature of a locally built
binary; the managed-root checks prevent unrelated `PATH` entries from being
mistaken for official plugins.
Disabling changes only `[plugins]` in the Lios config. It never runs
`cargo uninstall`, removes files, deletes plugin data, or terminates a process
that the user already launched. No plugin is installed, repaired, updated, or
launched in the background.
## Configuration
Plugin enablement is stored atomically with user-only config permissions:
```toml
[plugins]
lios_bar = true
```
Malformed non-boolean values fail configuration validation. Unknown
lowercase plugin keys are preserved so a newer Lios release can add catalog
entries without an older release deleting their state.
## Adding an official plugin
A catalog entry must remain a compile-time constant and include a unique
lowercase config key, crates.io package name, executable name, exact reviewed
version, display name, description, and a bounded safe launch contract.
Before catalog inclusion, the plugin must:
- be published under `MIT OR Apache-2.0` with both canonical license files and
explicit Trevor Knott/Knott Dynamics attribution;
- publish a locked crate containing its README and security documentation;
- accept `--version` and `--help` without side effects;
- avoid listening sockets, telemetry, credentials, and automatic downloads
unless those capabilities are the plugin's clearly documented purpose;
- pass formatting, strict Clippy, tests, package verification, and an install
smoke test from the exact public artifact.
Plugins needing destinations, credentials, terminal byte streams, or service
lifecycles require a purpose-built UI and threat model. They must not reuse the
standalone launch contract merely to appear in the catalog.