Implement sourceosctl agent-machine CLI for cross-host Podman workspaces

[mdheller]

Context

We need the installable workstation/operator tool surface for the SourceOS Agent Machine pattern.

The product goal is a Docker Machine-style but Podman-first agent workspace that works across macOS, Windows, and Linux:

host OS -> Podman machine / Linux VM -> governed agent container -> mounted repo worktree -> agent shell / AgentPlane evidence.

sourceos-devtools already owns sourceosctl, Nix/devshell orchestration helpers, NLBoot helpers, agent sandbox/run helpers, fingerprint and proof bundle tools, and local-to-mesh registration helpers. This is the right implementation home for the local CLI surface.

Scope

Add a new sourceosctl agent-machine command group:

sourceosctl agent-machine doctor
sourceosctl agent-machine init --profile macos-podman --repo ~/dev/<repo>
sourceosctl agent-machine start
sourceosctl agent-machine shell --repo ~/dev/<repo>
sourceosctl agent-machine run --tool codex --repo ~/dev/<repo>
sourceosctl agent-machine run --tool claude-code --repo ~/dev/<repo>
sourceosctl agent-machine fingerprint
sourceosctl agent-machine evidence inspect <path>

Required behavior v0

• doctor is read-only and detects host OS, architecture, Podman CLI, Podman machine state, Git, Nix, and repo path readability.
• init creates or renders an AgentMachineProfile file, but does not mount secrets by default.
• start starts the named Podman machine if present; if absent, prints the exact recommended command rather than guessing destructive defaults.
• shell opens an interactive shell inside the agent container with only declared mounts.
• run invokes a named tool surface inside the container when that tool is enabled by the profile.
• fingerprint emits JSON using the forthcoming AgentMachineFingerprint schema.
• Every mutating command should support --dry-run.

Security constraints

• Do not mount $HOME wholesale.
• Do not mount SSH keys, cloud credentials, browser profiles, keychains, or token stores by default.
• Shared code folders must be explicit allowlisted paths.
• Secrets must be passed only through a future Secrets Door/Token Door abstraction.
• Evidence must include mount list, image digest, git ref, policy hash, and tool versions.

Cross-platform targets

• macOS Apple Silicon: Podman machine backed by Linux VM.
• Windows: Podman Desktop/Podman machine backed by WSL2 or Hyper-V provider.
• Linux: native rootless Podman first; Podman machine optional.

Acceptance criteria

• CLI help and tests added.
• make validate passes.
• No secrets or device-specific values committed.
• At least one macOS profile example and one Linux-native profile example are included.
• README command table updated.