[earakely-scale]

What

A bundle can name an image in a registry and keep its build context beside it:

image = { ref = "<registry>/<repo>:<tag>@sha256:<digest>", dockerfile = "Dockerfile" }

An image folder can also hold a Dockerfile beside the ref in its artifact.toml, which it used to refuse. A run pulls the image by its digest and never builds it. The context is there to read or rebuild, and a deploy builds from it only when it can't pull the image, as it already does for a published agent image.

agent-env bundle init can write images this way. --image-ref ID=REF (or image_refs= on import_task and import_eval) writes the stored image ID as the registry image REF, with the part of its stored context its Dockerfile reads beside it.

• Version pinning: it skips pinning the Dockerfile to the stored image's versions, since the run pulls the image, so the import never reads the stored tarball.
• No context: an image with no context, or one whose context can't be written, is written as the ref alone.
• Refusals: a ref that doesn't name its registry or pin a digest, or that names an image the import writes none of, fails the import.

The point is delivering a bundle the way Harbor is delivered: the export pushes each image to a private registry the recipient is granted, and the bundle names it by digest.

How

• Writing: put_ref with a context but no digest now pins through the registry, then records the name and the digest apart, the shape a published image has. Existing callers all pass a digest, so they're unchanged.
• Ledger: it covers the context's files, so editing the context rewrites the image. Rewriting keeps the earlier pin while the ref is the same.
• Reporting: the import lists such an image as "pulled as REF, its build context beside it". Its README says pulled images are pulled by digest, and names their registries among what a machine needs. The machine-needs bullets now sit inside that list instead of after the images paragraph.

Testing

• Unit tests cover resolve, the write, the ledger and pin reuse, the dry-run line, the import (with its refusals and the CLI), and an import followed by a run writing the image at the given digest without building it.
• End to end on local Docker 29, with the echo-mcp example and a local registry:2 standing in for the delivery registry:
  1. Ran it into the store and pushed its image.
  2. Ran bundle init --image-ref.
  3. Deleted the image from Docker.
  4. agent-env run from an empty state root pulled the image by its digest, built nothing, and the verifier passed.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; all four previous findings are addressed.

Summary

Adds registry-backed bundle images with optional build contexts and bundle init --image-ref.

• Registry image entries can keep their Dockerfile context beside them.
• bundle init can write stored images as digest-pinned registry references.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Stored image] --> B{Supplied image ref?}
  B -->|Yes| C[Write digest-pinned ref]
  C --> D{Context writable?}
  D -->|Yes| E[Keep context beside ref]
  D -->|No| F[Keep ref alone]
  E --> G[Run uses registry image]
  F --> G
  B -->|No| H[Existing import behavior]

Loading

_{Reviews (2) · Last reviewed commit: "fix(bundle): leave a Dockerfile a pulled..." · Reviewed by Greptile}