feat(v1)!: move run info from trace to episode

[mikasenghaas]

Summary

Trace.run recorded which run (eval or train) a trace belonged to. But the episode is what a consumer actually dispatches, and an episode that produced no traces — cancelled, or a task that raised before reaching the env — had nowhere to record its run at all.

So the run moves up:

• Episode.run: RunInfo | None, consumer-stamped, on the unit that was dispatched.
• Episode.record_run(run, **info) sets the run and passes any extra info down to each trace, so a consumer stamps once instead of walking them.
• Trace.run and Trace.record_run are removed.

The field stays optional and unstamped by the library — verifiers doesn't own the notion of a run, consumers do. vf's own eval CLI now stamps at the episode level in all three places it used to loop over traces.

Breaking

• Trace.run is gone — read Episode.run. Traces persisted with a run field still load (records parse non-strict), but the value is dropped.
• Trace.record_run is gone — call Episode.record_run, which also forwards **info to the traces. A consumer holding only loose traces can set trace.info directly.
• A consumer that writes traces rather than episodes to disk no longer gets the run recorded in those rows, and should stamp what it needs into trace.info.

Verification

• uv run pytest tests/v1 -m "not e2e" green.
• ruff check / ruff format --check; ty reports nothing on the touched files.

🤖 Generated with Claude Code

Note

Move run metadata from Trace to Episode in eval runner

• Adds run: RunInfo | None and info: dict fields to Episode, with a record_run() method to set them, mirroring the API previously on Trace.
• Updates run_eval and run_eval_server in runner.py to call episode.record_run() once per episode instead of stamping each trace individually.
• Removes run field and record_run() method from Trace entirely.
• Risk: Breaking change — Trace serialization no longer includes a run field; any consumers reading run metadata from traces will need to read it from the parent Episode instead.

^{Macroscope summarized 1336d48.}

---

Note

Medium Risk
Schema and API break for anything reading Trace.run; persisted traces may drop the old run field on load, but eval output shape stays episode-based.

Overview
Breaking: Trace.run and Trace.record_run are removed. Consumers should use Episode.run and Episode.record_run, so trace-less episodes (cancelled or failed before agents run) can still record which eval/train run they belonged to.

Episode gains optional run, episode-level info, and record_run(run, **info) that sets the run and merges metadata on the episode once instead of on every trace.

The v1 eval runner stamps EvalRunInfo on the completed episode in all paths (local on_complete, env-server run_unit, and legacy run_group where each trace is wrapped with Episode.of then append_episode instead of per-trace append_trace).

^{Reviewed by Cursor Bugbot for commit 1336d48. Bugbot is set up for automated code reviews on this repo. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This is an explicitly marked breaking change (!) that relocates the run field and record_run() method from Trace to Episode, modifying the data model. Breaking schema/API changes warrant human review to assess downstream compatibility.

^{You can customize Macroscope's approvability policy. Learn more.}