[earakely-scale]

Why

A bundle folder runs locally (agent-env run) but nothing writes it where a service runs tasks. agent-env bundle register writes a folder into the configured stores under registry ids, so whatever runs the stores' tasks runs what the folder ran: the hub and its workers, agent-env task run, an eval at scale.

What it does

agent-env bundle register FOLDER [--task NAME]… [--eval NAME]… [--prefix P] [--dry-run] [--yes]

It plans the bundle as a run does, reusing parse, resolve, plan and materialize, then translates each @local id the plan writes into a registry id:

• Entries: <prefix><name>, with the name lowercased and every character an id can't hold made -. The prefix defaults to the folder's name plus a dash. Two entries that land on one id are refused.
• Derived ids keep their suffix after the base's registry id (echo-echo__env_image). A task's outputs take <task id>-<name>.
• A shipped agent named by its alias (claude-code) is registered under the alias when the store lacks it, with its published image pulled by digest. A step that leaves its agent unset stays unset, so whatever runs the task gives its own default; the planner gains default_agents=False for this.

Each task and eval is written naming the version of each entity it references. That is the version register wrote or reused for the bundle's own entities, and the version the plan read for a store's. A registered version never changes meaning, and a new env version gives the tasks naming it new versions too. A field that takes no version is listed as floating in the dry run.

Images. Each image the bundle builds is built here for linux/amd64 with Docker and pushed to the configured image store under the tag src-<sources>. A push the registry already serves is skipped. The image is registered by digest with its build context beside it. An image published for its sources (a shipped agent, the mail example) is registered as published, and nothing is built.

Ledger. A ledger in the target store's bundle_registrations collection makes a rerun write only what changed. Each row names the bundle by its git remote, without credentials, plus its path in the repo (or folder:<path> outside git), and records the commit, whether the folder was dirty, and the agent-env version. The Ledger class gains a collection, reference pinning and row fields, so RegistrationLedger is a small subclass.

Refused before anything is written:

• an @local id left in a document;
• a store reference the store lacks.

An id the store already holds takes the bundle's next version, whoever wrote the store's latest.

For a store other than this machine's (anything but the local SQLite store), also refused:

• a credential written out;
• an env var set to an env: or secret: reference, since nothing resolves one in a step's env vars, so the run would get the reference itself;
• a URL only this machine reaches (file:, loopback). Writing to such a store asks for confirmation first, unless --yes.

Concurrency. Two registrations of a bundle on one machine wait for each other on the run's per-id locks, then the second reuses what the first wrote. Two on different machines aren't serialized by those locks, so the registration ledger holds each write to the version its check found next.

This uses expecting_version in the document store: inside it, a put of that id that names no version takes exactly the held version through insert_next, in both VersionedEntityStore.put and ArtifactStore.put_document. A registration that loses a race raises ConcurrentModificationError instead of writing v2, and a rerun reuses what the winner wrote. A write that raises also leaves no pending ledger row.

Repository names. An image's repository is its id with __ made -, because ECR refuses two separators in a row and a derived id holds __.

Not in this PR

• Registering an imported folder back to its source ids. That PR uses feat(bundle): record what an import wrote, so registering the folder back can tell an edit #353's record: unedited folders write nothing, and dropped user-scoped fields are re-grafted.
• An installed bundle's env, which a task names by its alias, is refused before anything is written: no store env may start on an installed env alias's id. An installed agent named by its alias is registered under the alias.
• The agentenvhub-sdk wrapper (project ids, hub task defaults, the prod path).

Verification

Unit tests: tst/unit/bundle/register_test.py, 32 tests, covering:

• ids, slugs and collisions, and --prefix;
• pins for bundle and store refs, and eval pins;
• the ledger: reruns, an edit re-versioning only what it reaches, rows in the target store, and remotes without credentials;
• an id the store already holds taking the bundle's next version, whoever wrote it;
• outputs, the unset default agent, a shipped agent under its alias, and a pushed image;
• the @local leftover, credential, env-var reference and loopback refusals;
• the CLI's dry run, confirm, --yes and nothing-to-write;
• a failed write, a lost race, a refused installed env, and a registration resumed after being killed between a write and its ledger row;
• a step that names no version taking the latest even where another step pins one;
• push_context_image pushing once.

The full unit tier passes: 10,903.

e2e and chaos on an agent-environments-admin VM, against open-source stores: MongoDB 7, SeaweedFS (S3) and registry:2 with TLS and basic auth.

• echo-mcp registered with its image built and pushed to the registry. The record holds a digest and the S3 context, and the task pins the env and check at v1.
• mail-mcp registered with its published GHCR image, building nothing.
• Each registered task ran from those stores alone with agent-env task run on the local provider, score 1.0. Infra envs were put with env service-db/gateway put.
• A rerun wrote nothing. An edited check re-versioned only the check and the task, and the new task ran, score 1.0.
• A second clone of the repo is the same bundle, with nothing to write. (A copy outside git was refused until --prefix by an ownership check this PR has since dropped.)
• No secret text in any results: the Mongo, S3 and registry passwords, and the token in the git remote.

Chaos cases, each followed by a rerun and a check of every id's versions:

Case	Result
killed (kill -9) during the image push	rerun completes, every id at v1
killed just after its first write	rerun reuses it, every id at v1
4 registrations at once, one machine	serialized by the locks, every id at v1
2 at once as from two machines (own state dirs)	one writes everything at v1, the other fails with ConcurrentModificationError, rerun has nothing to write
registry stopped mid-push	fails, rerun completes
Mongo down	fails on connect, nothing written, rerun completes
S3 down during upload	fails, rerun completes

Before the strict writes, the two-machines case wrote every id at v1 and v2.

Default local stores, with no config: echo-mcp registered into SQLite, the local object store and the local registry, then ran, score 1.0.

Dev stage (agentenvhub-sdk 0.35.5, --stage dev): run from a laptop, because the dev cluster isn't reachable from the admin VM.

• mail-mcp registered into agent_env_dev and its dev bucket, and ran on a Modal VM, score 1.0.
• echo-mcp built and pushed to the dev ECR registry, at agent-env/agent-images-dev/fd3965-e2e-echo-echo-env_image, then ran on a Modal VM, score 1.0.
• A rerun wrote nothing. (An id another bundle registered was refused, by the ownership check since dropped.)

These ids stay in dev, since entities are append-only: 8 entities under fd3965-e2e-, their bundle_registrations rows, and one ECR repository.

🤖 Generated with Claude Code

Confidence Score: 5/5

The reviewed changes appear safe to merge, with no new blocking issues found.

Summary

Adds agent-env bundle register to write bundle entities into configured stores, pin task and eval references, push built images, and reuse unchanged versions.

• Bundle folders can be registered in configured stores under registry IDs.
• Registered tasks keep the versions they were written against.
• Bundle-built images are pushed to the configured image store.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Bundle folder] --> B[Parse, resolve, and plan]
  B --> C[Translate local ids]
  C --> D[Check references and shared-store restrictions]
  D --> E[Check registration ledger]
  E --> F[Reuse unchanged versions]
  E --> G[Build and push required images]
  G --> H[Write entities at expected versions]
  H --> I[Write pinned tasks and evals]
  I --> J[Record completed writes]

Loading

_{Reviews (10) · Last reviewed commit: "refactor(bundle): drop the ownership che..." · Reviewed by Greptile}

[earakely-scale]

@greptileai review

[greptile-apps]

Comments Outside Diff

These findings could not be posted inline.

•  Unchanged tasks gain extra versions src/agent_env/bundle/ledger.py:150 ▶

  Registering an unchanged task that names a missing shipped agent, such as claude-code, writes another task version on the next registration. The first registration records the agent in inputs["needs"]. Once the alias exists in the store, the second records the same id and version in inputs["store_refs"].

  Those different hashes rewrite the task and any eval that pins it, despite unchanged content. Compare the final pinned references consistently across both paths.