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.

[mdheller]

Status (2026-07-18): The helper causal receipts (PR #26) provide the receipt infrastructure. The specific operator-facing agent ergonomics surface described here — sourceos-agent status/logs/doctor/repair/quarantine commands with structured UX output showing service scope, backend, Podman machine state, container state, image provenance, auth mode, and copy-paste-safe remediation paths — has not shipped. This is a future sprint item, coordinated with sourceos-devtools#20 (agent runtime CLI).

[mdheller]

Implemented in PR #30 (feat/shell-ergonomics-stubs, now merged into main).

Issue #9 is addressed by:

• scripts/sourceosctl: operator CLI with explain surfaces, state-integrity status, lifecycle status
• schemas/host-runtime-lifecycle.schema.json: typed JSON Schema 2020-12 for all 13 lifecycle states
• docs/adr-035-examples.md: EngineManifest + BoundaryTransition + FaultEnvelope fixtures for shell-adjacent engines

All commands verified working (lifecycle status, state-integrity status --json, all explain surfaces).