phoebus_os/docs/adr/0015-agent-execution-boundaries.md
2026-10-12 04:27:15 -07:00

1.9 KiB

ADR 0015 — Explicit agent execution boundaries

Context

Implementation review found that material-effect digests omitted execution context, path checks preceded pathname I/O, and per-action PID locks did not serialize a complete transaction. Real negative testing also found that the systemd user model unit could read home files despite its configured properties.

Decision

Bind independent approval to a versioned execution envelope. Hold a persistent kernel flock through revalidation, mutation, verification and terminal recording. Use descriptor-relative no-follow target I/O and atomic file replacement. Pin application install identities with native backend mechanisms and verify the installed identity. Keep model transport output out of logs and funnel evidence through a minimized, redacted boundary. Bound process output and deadlines.

Use an explicit Bubblewrap filesystem/PID boundary for unprivileged model calls and developer agents. Developer workspace binds consume a pinned directory fd; synthetic home and clean environment are defaults. Never fall back unconfined. Systemd provides process/resource restrictions; root model calls use DynamicUser.

Consequences

Old staged plans require fresh review. Bubblewrap is required for normal-user model calls, and OSTree is shipped with Flatpak. Missing containment support fails closed. Developer home tools and credential state need future explicit, narrow grants. Backend dependency closures and repository snapshots are not claimed fully immutable. Fresh installer and remaining native acceptance are still required.

See implementation and evidence.

Status

Accepted, 2026-10-12. Implemented and regression tested; host negative isolation tests passed. Gentoo overlay acceptance passed 14/14 for sandbox denials, descriptor snapshots and Portage/Flatpak/Nix pins. Fresh installation and native Snap/drift/interrupted-worker acceptance remain pending.