Expose local-agent status, logs, repair, and quarantine ergonomics

[mdheller]

Context

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

The node-commander incident showed that local agents need an operator-facing surface. Users should not have to inspect launchd plists, Nix store wrappers, Podman sockets, and credential-helper configs manually.

Deliverables

Add SourceOS shell affordances for:

• sourceos-agent status <name>
• sourceos-agent logs <name>
• sourceos-agent doctor <name>
• sourceos-agent repair <name>
• sourceos-agent quarantine <name>
• sourceos doctor local-runtime

UX requirements

Status output should show:

• service scope and backend
• installed plist/unit path
• launchd/systemd state
• PID and run/restart count
• runtime backend
• Podman machine and socket state
• container state
• image ID/tag/provenance
• auth mode
• log paths
• warnings and recommended action

Acceptance criteria

• A user can understand why a local agent is running without reading Nix store paths.
• Suspicious persistence patterns are explained in plain language.
• Repair/quarantine paths are surfaced as copy-paste-safe commands.

[mdheller]

Upstream devtools tranche 1 has landed the local-agent operator surface this shell issue should consume.

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

• sourceos-agent list/preflight/doctor/status/logs.
• Guarded stage/install/start/stop/restart/quarantine/uninstall.
• sourceosctl local-agent ... routing.
• sourceosctl doctor local-runtime routing.
• Read-only JSON output for list, preflight, doctor, and status.
• Registry-backed declarations under sourceosctl/local_agents/*.json.

Recommended shell next step:

1. Build concise operator views over sourceos-agent status <agent> --json.
2. Add log tailing / warning summary for local agents.
3. Surface unsafe conditions: legacy system plist, disabled override, Podman socket failure, missing local image, auth-helper risk, and container Stopping.
4. Provide copy-paste-safe repair/quarantine commands, but keep destructive actions behind explicit confirmation.