Add Podman machine/image/container lifecycle contract for local agents

[mdheller]

Context

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

The node-commander repair showed that Podman machine state, socket reachability, local image provenance, authfile selection, and container lifecycle must be first-class platform concepts.

Deliverables

• Add Podman machine preflight library.
• Detect machine missing, stopped, or socket-refusing states.
• Detect local image presence and image ID.
• Enforce local runtime image tags such as localhost/sourceos/<agent>:<tag> or localhost/socioprophet/<agent>:<tag>.
• Support explicit empty authfile runtime mode.
• Detect stale host credential-helper risk.
• Detect container states including Stopping, Removing, Exited, Created, and Running.
• Emit machine-readable and human-readable diagnostics.

Acceptance criteria

• node-commander style failure is diagnosed as Podman socket unavailable, not as generic launch failure.
• Local image run can bypass ambient Google credential helpers using explicit authfile.
• Runtime refuses direct remote registry image unless service auth is declared.
• Stopping containers are detected and remediated or reported clearly.

[mdheller]

Upstream devtools tranche 1 has landed the local-agent control surface that agent-machine should consume.

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

• sourceos-agent preflight/status/doctor <agent> with Podman machine/socket/image/container/auth checks.
• Registry declarations under sourceosctl/local_agents/*.json.
• sourceosctl/local_agents/templates/quadlet.container.tmpl for Podman-backed Linux agents.
• Explicit empty authfile runtime mode in the generated launcher.
• Container-state checks that detect Stopping / Removing as warnings.
• Unsafe persistence scanner and registry/template validators.

Recommended agent-machine next step:

1. Align machine/image/container lifecycle terminology to the devtools registry fields.
2. Provide stronger Podman-machine remediation helpers for stopped/refusing sockets.
3. Emit structured machine and container status that can feed sourceos-agent --json output.
4. Add fixture transcripts for machine stopped, socket refused, image missing, image present, and container stopping.
5. Treat local image tagging/provenance as part of agent-machine image lifecycle.