Gate local-agent persistence behind Nix activation preflight

[mdheller]

Context

Canonical spec: SourceOS-Linux/sourceos-spec specs/local-agent-runtime.md.

The node-commander incident showed that Nix activation can reproducibly install an operationally unsafe service if preflight is not part of activation. A Nix-generated wrapper was installed behind launchd before Podman machine/socket/auth conditions were safe.

Required boot/activation behavior

Nix activation for local agents must run in this order:

1. Evaluate local-agent declaration.
2. Generate wrapper.
3. Lint wrapper.
4. Generate launchd plist or systemd unit.
5. Lint service definition.
6. Run preflight.
7. Install only if preflight passes.
8. Enable only if install succeeds.
9. Start only if enable succeeds.
10. Emit status.

If preflight fails, activation must stage the service but must not enable persistence unless explicitly requested.

Deliverables

• Add activation guard hooks for SourceOS local agents.
• Add stage-only mode for failed preflight.
• Add clear status output for staged, installed, enabled, and running states.
• Add policy checks preventing direct /Library/LaunchAgents root-owned user agents, /tmp logs, and unbounded KeepAlive=true.

Acceptance criteria

• A missing/stopped Podman machine prevents active service installation.
• Noninteractive credential-helper failure prevents service enablement.
• Failed preflight creates a staged artifact and clear remediation output.
• Activation never leaves a half-enabled respawn loop.

[mdheller]

Upstream devtools tranche 1 is now implemented enough for boot integration planning.

Relevant implemented surfaces in SourceOS-Linux/sourceos-devtools:

• sourceos-agent direct entrypoint.
• Registry-backed declarations under sourceosctl/local_agents/*.json.
• sourceosctl/local_agents/registry.py loader.
• sourceosctl/commands/local_agent_registry_cli.py adapter.
• Guarded stage, install, start, stop, restart, quarantine, uninstall flows.
• Read-only JSON output for list, preflight, doctor, status.
• Registry validator and backend template validator wired into make validate.
• Systemd user and Quadlet backend templates.

Boot integration should now consume the devtools contract instead of reinventing local-agent activation logic.

Recommended next boot-side implementation:

1. Call sourceos-agent preflight <agent> --json during activation.
2. If preflight has failures, run sourceos-agent stage <agent> --execute --policy-ok but do not enable/start.
3. If preflight passes, run install/start through guarded devtools surfaces.
4. Record activation evidence and resulting local-agent status.
5. Refuse any direct launchd/systemd persistence path that bypasses devtools.