feat(bundle): write environment and environment_universe artifacts from their artifact folders

[earakely-scale]

A bundle's artifacts/<name>/ folder whose artifact.toml declares type = "environment" or type = "environment_universe" is now written by agent-env run, as artifact environment put and artifact environment-universe put write them. Until now the run refused such a folder as one it can't write.

What an artifact folder holds

artifacts/crm-data/                 # an environment over the folder's one file
  artifact.toml                     # type = "environment"; environment_name = "crm"
  rows.json                         # written as <id>__file
artifacts/mail-data/artifact.toml   # type = "environment"; environment_name = "gmail"; file = "mail-rows"
artifacts/world/                    # a universe, laid out as `environment-universe get --output-dir` writes one
  artifact.toml                     # type = "environment_universe"; environment_artifacts = ["mail-data"]
  slack/data.json                   # an environment named slack: <id>__slack over <id>__slack__file
  metadata/manifest/manifest.json   # metadata key manifest: <id>__metadata__manifest

• environment. environment_name is required. The file it wraps is either the one file in its folder (description defaults to the file's name) or the file artifact file names: a bundle artifact, a store id, or { artifact = "…", version = n }.
• environment_universe. Each <environment_name>/ folder holds one environment's file, and each metadata/<key>/ folder one metadata file. environment_artifacts adds environments from the bundle or the store. Its environments are the folders', in name order, then the ones it names.
• Stored names. The keys the stored documents use (service_name, file_artifact_id, file_artifact_ref, service_artifact_refs, environment_artifact_refs, service_artifact_ids, metadata, metadata_refs) are refused, naming the key to write instead.
• Type aliases. A type alias configured for these types is written under the canonical type.

Checked before anything is written

• Unknown keys, a value of the wrong type, and file naming anything but a file artifact, or environment_artifacts anything but environment artifacts. These are typed refs, checked in the resolver for bundle artifacts and in the plan for store ones.
• An environment:
  • a folder with no file, or more than one;
  • a folder that holds a file while file names one;
  • file together with description.
• A universe:
  • no environments at all;
  • a file outside <environment_name>/ or metadata/<key>/, a folder holding anything but one file (empty included), or folders nested inside one;
  • a folder name holding __, opening or closing with a space, or giving an id validate_local_id refuses;
  • two environments of one name across its folders and environment_artifacts. A store environment's name is read at the version the plan read; bundle check, which reads no store, counts only the bundle's.
• Derived ids. The ids an environment's file and a universe's environments and metadata files are written under join the one-writer check, so one that clashes with, say, an image the bundle builds is refused.

Writing and reuse

• Each child file is written under a prefix of its own attempt (FileArtifact.put_attempt, now shared with file artifacts), so a write that fails partway never blocks the next.
• The ledger hashes the files each type's write reads from its folder (folder_walk), and now the versions of what any written document references, tasks and evals aside. So a universe is rewritten when an environment it names is, and an environment when its file is.
• A store ref named without a version is pinned at the version the plan read.
• Digests of everything written before are unchanged. ledger_digest_test pins nine digests recorded by v0.9.1278 across files, file universes, built images, envs, agents and tasks.

Round trip

A universe downloaded with environment-universe get --output-dir and dropped into a bundle as-is writes an equivalent universe. A unit test compares the canonical documents, setting aside ids, versions, timestamps, object URLs and file descriptions; environment order is name order. A real 9-environment, 42 MB universe was written in about a second and reused on the rerun; the only field that differed from the original was its legacy unpinned file_artifact_id.

Tests

• Unit: artifact_toml_test.py (both environment forms, store pins, universe composition, the round trip, refusals, a store-free check), plus toml_refs_test.py, materialize_test.py and ledger_digest_test.py.
• Slow tier: a new test writes two environments and a universe from a bundle and loads each into an MCP server env deployed through the gateway, checking the server serves the loaded data.
• By hand, with the CLI on local stores:
  • About 55 malformed layouts and tomls were each refused by --dry-run and by run, with the stores unchanged.
  • SIGINT, SIGTERM and SIGKILL mid-write each recovered on the next run.
  • Two concurrent runs serialized.
  • A 1,500-folder universe wrote in about 5 s and dry-runs in 1.5 s once written.

Not hot path: only the bundle path changes. The two artifact classes gain class variables and classmethods, and their models, schemas and dumps are unchanged.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no actionable new issue or outstanding previous finding remains.

Findings

1.  Shared universe loads are refused ▶

Fix with agent prompt

### Issue 1
src/agent_env/bundle/plan.py:485-489
When a task loads a bundle-written universe into one server, the new plan check rejects every environment with a different name. The server already loads its matching environment and skips the others. A universe containing `items` and `mail` can no longer load into the `items` server. Keep the matching-environment check without rejecting the extras.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

agent-env run can now write environment and environment-universe artifacts from bundle folders. The bundle planner checks their layouts and references, and the ledger tracks their source files and referenced versions.

• Environment folders can now write an environment around a file.
• Universe folders can now build a universe from files and references.

_{Reviews (3) · Last reviewed commit: "test(bundle): a universe composed every ..." · Reviewed by Greptile}

[greptile-apps]

Shared universe loads are refused

When a task loads a bundle-written universe into one server, the new plan check rejects every environment with a different name. The server already loads its matching environment and skips the others. A universe containing items and mail can no longer load into the items server. Keep the matching-environment check without rejecting the extras.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/bundle/plan.py
Line: 485-489

Comment:
**Shared universe loads are refused**

When a task loads a bundle-written universe into one server, the new plan check rejects every environment with a different name. The server already loads its matching environment and skips the others. A universe containing `items` and `mail` can no longer load into the `items` server. Keep the matching-environment check without rejecting the extras.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[earakely-scale]

Intended. A universe the bundle writes is data its author wrote for the env they load it into, so an environment there that matches no server is treated as a typo or a stray folder and refused before any write, for a single server as for a multi (a multi would otherwise skip it without a word). The skip-the-rest behavior is kept where it's legitimately used: a store universe shared across servers still loads into one server, taking its own environment (test_a_store_universe_loaded_into_one_server_gives_it_its_own_environment). A bundle that wants one server to take part of a universe can name that server's environment artifact instead.

[greptile-apps]

That makes sense, and the distinction is valid. _check_loaded_environments intentionally ensures every environment introduced by a bundle-written universe maps to a server in the task’s bundle environment, preventing typo or stray folders from being silently accepted. Store universes retain their shared-universe behavior, and tasks needing only one environment can reference that environment artifact directly.

I’m withdrawing this finding; no change is needed.