Env & Episode Lifecycle
Five nested scopes, five signals — who owns env / episode / run lifecycle and how the layers connect
An evaluation run nests like rings: a job holds a suite, a suite holds episodes, an episode holds iterations. Each ring has a single owner — the env panel owns the heavy operations (build the env, choose the episode), graph nodes own the light ones (revive an episode, advance it), and the executor stitches the rings together with broadcast signals. This page is the ownership-and-timing map. The loop rings themselves are Loop Control; what the signals reset is State Containers; the panel contract is Env Panels.
1. The five scopes
Every lifecycle operation belongs to exactly one ring; the recurring failure mode is an operation drifting to a neighbouring ring's owner (§5).
| Scope | Owner | Key operations |
|---|---|---|
| Job (cross-session) | JobScheduler | admission (VRAM / exclusive-GPU), subprocess spawn, finalisation, orphan reaping (POST /api/eval/v2/start). |
| Suite / process | Env manager singleton, driven by the env panel | initialize() (build config, create env, reset to first episode), shutdown() — never a graph node. |
| Episode placement | Env panel | field cascade dataset → split → episode_index → set_episode; emits the episode_reset request. |
| Episode liveness | reset node | pre-loop band, fires once: idempotent ensure-live (habitat re-arms a finished episode; others read metadata — §6). |
| In-episode advance | step_* nodes + loop control | sim mutation, terminated/truncated emission; loop end seeds the after-loop band via final_*. |
On top of the two innermost rings the executor lays its own banding: run_start → pre-loop band (entry nodes, reset) → loop (observe_* → reason → step_*) → after-loop band (evaluate, fed once by the loop iterOut's final_* edges). The banding mechanics are Graph Executor; the loop's stop/final side is Loop Control §6.
2. The five signals
Signals are the only mechanism that crosses scope boundaries: the bus (broadcast_signal → each container's on_signal) is the only lifecycle channel state containers respond to (State Containers §6). There are five canonical ones:
| Signal | Emitter — when | Clears (lifetime) |
|---|---|---|
run_start | executor — before any node fires | run |
run_end | executor — at teardown (clean and error paths) | — |
step_start | executor at the iterIn boundary — opens each iteration (payload carries scope_id) | step (on the matching boundary) |
step_end | executor at the iterOut boundary — closes each iteration (payload carries scope_id) | step |
episode_reset | env panel, via the env-panel router — on a committed episode change | episode |
final_* is not a signal. The iterOut final side (final_<name> / final_stop) is a set of edge handles that route values to the after-loop band once at termination — it never goes through broadcast_signal. It seeds evaluate by ordinary dataflow, not by the signal bus. (Loop Control §6.)
3. Who owns each transition
| Transition | Owner | Mechanism |
|---|---|---|
| build / tear down the env | env panel + manager | initialize() / shutdown() (suite scope) — never a node |
| choose the episode | env panel | field cascade → set_episode, returns episode_reset intent |
| revive the episode | reset node | pre-loop, idempotent ensure-live |
| advance the episode | step_* node + loop | sim mutation; terminated → iterOut.stop |
| run / step signals | executor | run_start/run_end/step_start/step_end broadcast at the band boundaries |
| the verdict | evaluate node | after-loop band, fed once by final_* |
4. Two driving modes
Interactive (canvas). The user opens the env panel; the field cascade initialises the manager and places an episode. Pressing Play returns a side_effect the frontend acts on (the panel only requests — Env Panels §6); the executor then runs run_start → pre-loop reset (re-armed if the previous run finished the episode) → loop → after-loop evaluate. Re-running without touching the panel replays the same episode — placement is sticky, liveness is re-armed by reset.
Batch eval. The job is admitted by the JobScheduler and runs as a backend subprocess. Per episode the runner drives the same panel programmatically — on_field_change("episode_index", i) then on_action("play") — each env family keeping its own cascade shape. At worker_count > 1, env_panel_overrides map panel names to per-worker proxies so each worker's nodes and panel resolve to the same env instance.
One asymmetry between the modes. The control plane is symmetric on placement — batch chooses episodes through the panel exactly as a user would — but not on the episode_reset signal. The panel's signal side-effect is only forwarded to broadcast_signal on the interactive canvas API path; in batch the runner reads the panel's return for episode metadata and step_budget but does not re-broadcast episode_reset. Batch gets per-episode isolation a different way: a fresh LoopRunner (and thus fresh containers) is built per episode, so lifetime="episode" state is clean by construction.
5. Invariants (the contract)
- Suite init/teardown is panel/manager-owned — never a graph node. Per-episode
closeis forbidden (SIMPLER: SAPIEN GC-ordering segfault; mirror upstream's no-close pattern). - Placement is panel-owned — nodes never choose which episode runs; the batch runner chooses through the panel, not around it.
- Liveness is reset-owned —
resetis an idempotent ensure-live in the pre-loop band. It revives, never chooses. observe_*is a pure read — no lifecycle action, ever. A finished episode observed again returns the terminal frame.step_*is the only in-episode state advance, and emits control signals only (reward/terminated/truncated/info— never an observation).evaluatefires once, in the after-loop band, fed by the iterOut final side. Per-step telemetry ridesstep.infointo viewers; the verdict never comes from an in-loop evaluate.- Method-side state clears via signals only —
run_startforlifetime="run",episode_resetforlifetime="episode". No node manually wipes containers at lifecycle boundaries. - One control plane (for placement) — anything batch does to place an env, a user can do through the panel, and vice versa. New lifecycle abilities go into the panel or the engine's signals, not into ad-hoc node behaviour.
6. Known seams
Every lifecycle bug to date sat on a boundary between scopes, not inside one. The watch-list:
| Seam | What happened / can happen | Status |
|---|---|---|
| placement ↔ liveness | an early auto-reset inside habitat's observe_* left episode rollover homeless, later a metric-pollution hazard (a post-loop observe re-fire could roll into a new episode under evaluate) | resolved 2026-06-11 — rollover moved to reset |
| advance ↔ run accounting | a node returning {"error": …} instead of its declared port dict makes the engine silently complete the episode with step_count=0 (routing checks src_handle in result) — cost 11/100 episodes in a smartway-ce run | open (engine) |
| loop ↔ after-loop band | a post-loop node fed by a loop-body node resolves that input to None on the final re-fire (collapsed explore-eqa SR 0.43→0) — which is exactly why the after-loop band purity rule now bars body→band edges | structural rule — Loop Control §9 |
| liveness, per-env | only habitat's reset implements the re-arm today; the other MDP envs (MP3D's is a pure metadata read) were never audited against the ensure-live wording — a dead-episode canvas re-run may hang on them | open (audit pending) |
7. Related pages
- Nodeset Env Panels — the panel API: fields, actions, side-effects, server-mode bridge.
- State Containers — lifetimes and the signal bus.
- Loop Control System — two-sided iterIn/iterOut, stop port, final side.
- Graph Executor — pre/in/after-loop banding, entry-node seeding, after-loop drain.
- Batch Eval System — BatchEvalRunner, EnvWorkerPool, per-worker routing.