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

40 lines
1.9 KiB
Markdown

# 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](../AGENTIC-HARDENING.md).
## 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.