feat(cp3): guard cut-replay termination + cover survived/eliminated/cut-frame contracts

proteus/runtime/session.py

@@ -26,6 +26,8 @@ from proteus.runtime.metrics import compute_metrics
 from proteus.runtime.trace import SessionTrace, TurnTrace
 
 _ACTIONS = ["up", "down", "left", "right", "stay"]
+# Predator_evade-scoped for the current slice; spec defers scenario generalization.
+# A future multi-scenario runner should source this from the Scenario.
 _PROBE_QUESTION = (
     "Where is the predator, and which direction should you move to stay safe?"
 )
@@ -130,6 +132,12 @@ class SessionRunner:
             if self._game.eliminated or self._game.survived:
                 break
 
+        assert (
+            self._game.eliminated
+            or self._game.survived
+            or len(turns) == self._play_turns
+        ), "play loop exited without a terminal state or exhausting the budget"
+
         outcome = "eliminated" if self._game.eliminated else "survived"
         metrics = compute_metrics(
             turns,
@@ -166,8 +174,19 @@ class SessionRunner:
             self._game.apply_motive_action(action)
             self._scenario.record_focal_move(action)
             self._cut_frames.append(self._render())
+        # The Cut pre-roll must not end the game; if it does, the scenario's
+        # cut_focal_policy is buggy and any resulting trace would be corrupt.
+        if self._game.eliminated or self._game.survived:
+            raise RuntimeError(
+                f"Game terminated during Cut replay of '{self._scenario_name}'. "
+                "cut_focal_policy must not trigger elimination or survival."
+            )
 
     def _observation(self, turn_idx: int) -> str:
+        # Turn 1 replays the captured cut_frames so the agent sees the scripted
+        # history; turn 2+ render the live grid directly.  This is correct as
+        # long as rendering depends only on sprite state (true for all current
+        # scenarios).
         assert self._scenario is not None
         legend = self._scenario.legend()
         parts: list[str] = []
@@ -212,5 +231,7 @@ class SessionRunner:
         return frame_to_ascii(self._game.current_grid(), self._scenario.legend())
 
     def _provider_model_name(self) -> str:
+        # Relies on the agent exposing its provider as `_provider` (VanillaAgent's
+        # convention); unknown agent types fall back to agent.name.
         provider = getattr(self._agent, "_provider", None)
         return getattr(provider, "model_name", self._agent.name)

tests/runtime/test_session.py

@@ -63,3 +63,34 @@ def test_session_is_deterministic_for_same_inputs():
     # Same scripted agent + same seed -> identical realized trajectory.
     assert [t.focal_pos for t in t1.turns] == [t.focal_pos for t in t2.turns]
     assert t1.metrics == t2.metrics
+
+
+def test_short_budget_yields_survived_outcome():
+    # With a tiny budget the step count is exhausted (without capture) right
+    # after the played turns, so the engine fires `survived`.
+    agent = _agent(["ACTION: up"])
+    trace = SessionRunner(
+        "predator_evade", agent, seed=42, play_turns=1, use_probe=False,
+    ).run()
+    assert trace.outcome == "survived"
+    assert trace.turns[-1].reward == 50.0  # _REWARD_SURVIVED
+
+
+def test_eliminated_outcome_is_explicit_and_terminal():
+    # The habit player ("left") walks into the dead-end and is caught.
+    agent = _agent(["ACTION: left"])
+    trace = SessionRunner(
+        "predator_evade", agent, seed=42, play_turns=15, use_probe=False,
+    ).run()
+    assert trace.outcome == "eliminated"
+    assert len(trace.turns) <= 15           # stopped at/under budget
+    assert trace.turns[-1].reward == -50.0  # _REWARD_CAPTURED
+
+
+def test_cut_frames_count_matches_cut_length_plus_one():
+    agent = _agent(["ACTION: up"])
+    trace = SessionRunner(
+        "predator_evade", agent, seed=42, play_turns=5, use_probe=False,
+    ).run()
+    # EASY cut_length is 2 -> initial frame + 2 step frames = 3.
+    assert len(trace.cut_frames) == 3