feat: add digest-pinned OCI image support

[lox]

Summary

• require digest-pinned sandbox.image.ref in policy compilation and capture image digest metadata
• add internal/imagemgr for OCI pull/extract/import, ext4 materialisation, XDG cache storage, and SQLite metadata
• integrate Firecracker launched runs with image-manager-resolved rootfs while preserving per-run copy lifecycle
• add cleanroom image pull|ls|rm|import CLI commands
• propagate image_ref and image_digest through run responses and execution stream events
• update docs/examples for new policy contract and runtime requirements
• rebase PR branch onto latest origin/main
• fix Firecracker/controlservice compile regressions introduced by API refactors (run_dir fallback wiring and stale host-passthrough references)
• set repo cleanroom.yaml to a reachable digest-pinned image ref
• add Firecracker adapter runtime-rootfs preparation that keeps imported OCI artifacts immutable while caching a derived runtime ext4 with injected /usr/local/bin/cleanroom-guest-agent and /sbin/cleanroom-init
• include guest-agent binary availability in doctor checks

Testing

• mise run test-full
• mise run install
• cleanroom policy validate
• cleanroom image pull docker.io/library/alpine@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659
• local smoke (ephemeral unix socket server):
  • CLEANROOM_HOST=unix:///tmp/cleanroom-rebase-smoke.sock cleanroom exec -c /tmp/cleanroom-adhoc --launch-seconds=20 -- echo runtime-injection-ok-after-rebase

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 18bf9fa033

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lox]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cad7045b92

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[catkins]

This looks great, and awesome that you could also lean on that go container registry pkg for some of the boring OCI things.

When this is in a more stable shape, having some kind of functional tests that run on an elastic stack on a on a real EC2 host with nested virtualisation enabled that test the whole process E2E would be a nice addition.

[lox]

Test summary from local validation on pr-23:

• Automated:

  • mise run test-full (runs go test ./...) -> PASS

• Build/install:

  • mise run install -> PASS

• Runtime checks (tmux):

  • Restarted cleanroom serve in tmux cleanroom:1 with updated binary.
  • Used tmux cleanroom:2 for ad-hoc CLI checks.

• Ad-hoc behavior verified:

  • cleanroom exec --host http://127.0.0.1:7777 ... requires explicit absolute -c/--chdir for remote endpoints (expected guardrail).
  • With prior policy image (ghcr.io/...@sha256:0123...), exec failed on image resolution with DENIED from GHCR (expected for placeholder/unreachable digest).
  • Pulled reachable public digest successfully:
    • cleanroom image pull docker.io/library/alpine@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659 -> PASS
  • Ran exec with a temp policy using that public digest; execution reached Firecracker launch path and failed at guest-agent readiness (firecracker exited before vsock guest agent became ready), which is expected for plain Alpine images without cleanroom guest init/agent.
  • cleanroom doctor --backend firecracker -> all checks PASS on this host.

• Config update included:

  • Updated cleanroom.yaml default image ref to the reachable public digest above.
  • cleanroom policy validate -> PASS