feat(bundle): run --dry-run, another bundle's entities by @local id, bare depends_on ids

[earakely-scale]

Three changes to how a bundle is checked before anything is written, one commit each:

1. depends_on takes a bare step id. ["load"] means [{"task_step_id": "load"}].
2. agent-env run --dry-run makes every check the run makes before its first task and writes nothing.
3. A bundle can name another bundle's entities by their @local/… id.

A bare step id in depends_on

"depends_on": ["load", {"task_step_id": "box"}]

• TaskStepDependency.from_dict takes either form, and reads the object form exactly as before, so every stored task that loaded still loads; only a bare entry must be a string. The new dependencies() reads a whole depends_on, and refuses a lone string, which would otherwise be read as a list of its characters.

• Steps are still stored in the object form, so every stored task and every reader of to_dict() is unchanged.

• Task._validate_dag now separates the two ways a dependency can be wrong: a step that comes later (still "forward refs are not allowed"), and an id that names no step in the task.

• The bundle resolver reads depends_on through the same parser. A malformed one used to show up only as "…which this step doesn't depend on"; now it is reported with its cause:

  tasks/t.json: step 'run': depends_on is a list of step ids, not 'cli'
  tasks/t.json: step 'run': depends_on 'clii' names no step in this task
  

agent-env run --dry-run

$ agent-env run triage --dry-run      # after a newer @local/~/other/solver-image was stored
Dry run: nothing is written or run.
agents/solver: v2 (artifact @local/~/other/solver-image has a new version in the store (v1 → v2))
tasks/t.json: v1, unchanged

Store refs:
  artifact @local/~/other/solver-image v2, the latest
  artifact @local/~/other/greeting v2, the latest
Would run:
  tasks/t.json v1
Dry run: nothing is written or run.

• One flow. It is materialize(plan, dry_run=True): the same refusals, ledger checks and preflights as a run, without the lock, the writers or Task.put / Eval.put. Each write is reported at the version it would reuse or the store's next one. dry_run_bundle() returns the same to Python as a DryRun.
• Needs are hashed from the walk. Ledger.check(write, versions) hashes the versions the walk passes in for what an env or agent needs, instead of reading the ledger as it stands. So a need that would be written anew rewrites its dependent in the prediction, as it does in the run. Versions are still hashed as strings, so rows a run already recorded stay reused, and no ledger scheme bump is needed.
• Steps it can't preflight. A step that reads what the run would write first (for example run_code over a changed artifact) can't be preflighted against the store. The dry run lists those whose type has its own preflight, under Not preflighted. Steps over reused writes are preflighted as in a run.
• Exit status. 0 for a valid plan, whatever it would write; 1 for a problem the run would stop at. --sandbox is checked; --model and --keep change nothing it shows.
• Known limits. It takes no lock (as run --help says), so another run writing the same ids can change the answer first, and it doesn't see what another bundle's pending run would write. It reads the configured stores the way a run does, so a read can create an empty default local store.

Another bundle's entities by their @local id

# agents/solver/agent.toml
image = "@local/~/other/solver-image"

• An explicit @local/… id outside the bundle is checked against the @local namespace's store, like any store id. Until now it was refused as not supported yet.
• An unpinned one takes the latest version at plan time: an agent is written with that version, and written again, with the reason shown, once a newer version is stored under that id. Tasks and evals stay bare, as for any store ref.
• An id under the bundle's own root that the bundle doesn't write is still refused without a read, since it is most likely left over from a rename.
• Planning such a read with namespace routing off raises, as materializing already does.
• An eval naming another bundle's task is refused as a store task, with the existing agent-env task run hint.

Docs

The README now points to the docs site and keeps only the plugin contract, so this PR changes no README text; the user-facing docs for bare depends_on, --dry-run and cross-bundle references go to the docs site separately.

Testing

• Unit tier (make unit-test): 5,684 passed, 13 skipped, with main merged in. Each of the three feature commits also passes on its own: 5,649, 5,665 and 5,671.
• tst/integration/cli/run_bundle_test.py, which runs agent-env run on hello: 7 passed.
• End to end: one bundle's agent names another bundle's image, and its task names another bundle's artifact with a bare depends_on.
  • Every dry run, from Python and from the CLI, predicted exactly what the run that followed wrote, including the rewrite after a newer image version was stored under the other bundle's root.
  • The state directory was byte-identical after each dry run.
  • hello with bare depends_on scores 1, stores its steps in the object form, and a rerun reuses both writes.

🤖 Generated with Claude Code

Confidence Score: 5/5

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

Findings

1.  Bad dependency crashes bundle checks ▶

Fix with agent prompt

### Issue 1
src/agent_env/task_step/task_step.py:26-27
A step with `depends_on: [{"task_step_id": ["load"]}]` now gets past `TaskStepDependency.from_dict`. The resolver then tries to look up that list in a set and raises `TypeError`. Bundle checks and dry runs crash instead of explaining the bad dependency. Reject object-form IDs that are not strings.

```suggestion
        if isinstance(data, dict) and isinstance(data.get("task_step_id"), str):
            return cls(task_step_id=data["task_step_id"])
```

---

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

Summary

Bundle runs can now be previewed with --dry-run, and bundles can read entities from another bundle using @local IDs. Task steps also accept bare IDs in depends_on, while keeping the stored format the same.

• Dry runs show predicted writes and tasks without running or writing them.
• Cross-bundle references are checked against the local namespace store.
• Bare dependency IDs work alongside the existing object form.

_{Reviews (5) · Last reviewed commit: "refactor(bundle): simpler ledger walk an..."}

[greptile-apps]

Bad dependency crashes bundle checks

A step with depends_on: [{"task_step_id": ["load"]}] now gets past TaskStepDependency.from_dict. The resolver then tries to look up that list in a set and raises TypeError. Bundle checks and dry runs crash instead of explaining the bad dependency. Reject object-form IDs that are not strings.

Suggested change

	if isinstance(data, dict) and "task_step_id" in data:
	return cls(task_step_id=data["task_step_id"])
	if isinstance(data, dict) and isinstance(data.get("task_step_id"), str):
	return cls(task_step_id=data["task_step_id"])

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/task_step/task_step.py
Line: 26-27

Comment:
**Bad dependency crashes bundle checks**

A step with `depends_on: [{"task_step_id": ["load"]}]` now gets past `TaskStepDependency.from_dict`. The resolver then tries to look up that list in a set and raises `TypeError`. Bundle checks and dry runs crash instead of explaining the bad dependency. Reject object-form IDs that are not strings.

```suggestion
        if isinstance(data, dict) and isinstance(data.get("task_step_id"), str):
            return cls(task_step_id=data["task_step_id"])
```

---

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

[earakely-scale]

Fixed in the resolver instead (next commit): a bundle's depends_on that names a step by anything but its id is now reported as a problem, not a crash. The object form stays lenient in TaskStepDependency on purpose, so every stored task that loads today keeps loading.

[greptile-apps]

That resolution is valid. Keeping TaskStepDependency.from_dict lenient preserves compatibility for already-stored tasks, while _depends_on now validates the bundle’s raw depends_on before dependency IDs are used. Malformed entries and non-string task_step_id values therefore become bundle problems instead of reaching an unhashable lookup. The added resolver tests cover the list-valued object form and confirm it reports the cause alongside the missing dependency edge, so no further change to TaskStepDependency.from_dict is needed.