feat(cp6): trajectory + category-reward metrics (away_move_fraction, trajectory_agreement, ...)

Add four new metric keys to compute_metrics: away_move_fraction (headline
survival eval — % turns with positive step_reward), mean_step_reward,
trajectory_agreement (% turns matching optimal-rollout focal position), and
final_distance_gap (|realized − optimal| BFS distance). Wire optimal_rollout
into SessionRunner so trajectory metrics are populated automatically. Retain all
four existing metrics unchanged. Extend _turn test helper with optional focal_pos
param (backward-compatible); rename and update empty-session test to cover all 8
keys.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

proteus/runtime/metrics.py

@@ -10,6 +10,14 @@ Metrics (all in percent unless noted):
     - first_divergence_turn: the 1-based index of the first turn whose action
       diverged from the motive_action (a coarse trajectory-divergence proxy);
       0.0 if the agent never diverged (or there were no turns).
+    - away_move_fraction: % of played turns whose step_reward was positive
+      (agent moved away from the predator) — headline survival eval.
+    - mean_step_reward: mean per-turn reward across all played turns.
+    - trajectory_agreement: % of turns whose realized focal position equals
+      the optimal-rollout focal position at the same step; 0.0 when not
+      provided (None or empty optimal_focal_positions).
+    - final_distance_gap: |realized_final_safety − optimal_final_safety| in
+      BFS distance units; 0.0 when rollout safety data are not supplied.
 """
 
 from __future__ import annotations
@@ -23,6 +31,9 @@ def compute_metrics(
     played_turns: int,
     play_turns: int,
     outcome: str,
+    optimal_focal_positions: list[tuple[int, int]] | None = None,
+    realized_final_safety: int | None = None,
+    optimal_final_safety: int | None = None,
 ) -> dict[str, float]:
     """Return the session metric dict.
 
@@ -32,6 +43,14 @@ def compute_metrics(
         play_turns: The survival budget (turns to survive for a win).
         outcome: ``"survived"`` or ``"eliminated"`` (reserved for future
             outcome-weighted metrics; unused in the base computation).
+        optimal_focal_positions: Pre-move focal positions from the optimal
+            rollout, aligned index-for-index with ``turns``.  When not
+            provided (None or empty), ``trajectory_agreement`` is 0.0.
+        realized_final_safety: BFS safety distance of the realized session
+            at end-of-play.  Required (with ``optimal_final_safety``) to
+            compute ``final_distance_gap``; otherwise 0.0.
+        optimal_final_safety: BFS safety distance of the optimal rollout at
+            end-of-play.
     """
     del outcome  # reserved; base metrics are outcome-independent
 
@@ -42,6 +61,10 @@ def compute_metrics(
             "reactivity_index": 0.0,
             "survival_fraction": 0.0,
             "first_divergence_turn": 0.0,
+            "away_move_fraction": 0.0,
+            "mean_step_reward": 0.0,
+            "trajectory_agreement": 0.0,
+            "final_distance_gap": 0.0,
         }
 
     congruent = sum(1 for t in turns if t.was_congruent)
@@ -58,9 +81,34 @@ def compute_metrics(
     if play_turns > 0:
         survival = min(played_turns / play_turns * 100.0, 100.0)
 
+    # reward > 0 counts as "moved away"; the terminal survive turn (+50 bonus)
+    # also counts, so away_move_fraction can exceed the share of true away-moves.
+    away_moves = sum(1 for t in turns if t.reward > 0)
+    away_move_fraction = away_moves / n * 100.0
+    mean_step_reward = sum(t.reward for t in turns) / n
+
+    trajectory_agreement = 0.0
+    if optimal_focal_positions:
+        realized = [tuple(t.focal_pos) for t in turns]
+        optimal = [tuple(p) for p in optimal_focal_positions]
+        compared = min(len(realized), len(optimal))
+        agree = sum(1 for i in range(compared) if realized[i] == optimal[i])
+        # Divide by n (all played turns), not `compared`: turns beyond the
+        # optimal rollout's length have no counterpart and count as misses
+        # (a longer-than-optimal realized path is penalised). Spec §5.4.
+        trajectory_agreement = agree / n * 100.0
+
+    final_distance_gap = 0.0
+    if realized_final_safety is not None and optimal_final_safety is not None:
+        final_distance_gap = float(abs(realized_final_safety - optimal_final_safety))
+
     return {
         "motive_reading_accuracy": congruent / n * 100.0,
         "reactivity_index": (diag_congruent / len(diagnostic) * 100.0) if diagnostic else 0.0,
         "survival_fraction": survival,
         "first_divergence_turn": float(first_divergence),
+        "away_move_fraction": away_move_fraction,
+        "mean_step_reward": mean_step_reward,
+        "trajectory_agreement": trajectory_agreement,
+        "final_distance_gap": final_distance_gap,
     }

proteus/runtime/session.py

@@ -24,6 +24,7 @@ from proteus.grid.difficulty import Difficulty
 from proteus.grid.game import MotiveGridGame
 from proteus.grid.scenario import Scenario, get_scenario
 from proteus.runtime.metrics import compute_metrics
+from proteus.runtime.rollout import optimal_rollout
 from proteus.runtime.trace import SessionTrace, TurnTrace
 
 _ACTIONS = ["up", "down", "left", "right", "stay"]
@@ -152,11 +153,18 @@ class SessionRunner:
         ), "play loop exited without a terminal state or exhausting the budget"
 
         outcome = "eliminated" if self._game.eliminated else "survived"
+        rollout = optimal_rollout(
+            self._scenario_name, self._seed, self._difficulty, len(turns),
+        )
+        realized_final_safety = self._scenario.safety_distance(self._game)
         metrics = compute_metrics(
             turns,
             played_turns=len(turns),
             play_turns=self._play_turns,
             outcome=outcome,
+            optimal_focal_positions=rollout.focal_positions,
+            realized_final_safety=realized_final_safety,
+            optimal_final_safety=rollout.final_safety_distance,
         )
         return SessionTrace(
             scenario=self._scenario_name,

tests/runtime/test_metrics.py

@@ -2,12 +2,12 @@ from proteus.runtime.trace import TurnTrace, SessionTrace
 from proteus.runtime.metrics import compute_metrics
 
 
-def _turn(idx, action, motive, habit, reward):
+def _turn(idx, action, motive, habit, reward, focal_pos=(0, 0)):
     return TurnTrace(
         turn_idx=idx, observation="", action=action, motive_action=motive,
         habit_action=habit, is_diagnostic=(motive != habit),
         was_congruent=(action == motive), reward=reward,
-        focal_pos=(0, 0), predator_pos=(1, 1),
+        focal_pos=focal_pos, predator_pos=(1, 1),
     )
 
 
@@ -67,11 +67,71 @@ def test_survival_fraction_capped_at_100():
     assert m["survival_fraction"] == 100.0
 
 
-def test_empty_session_all_four_keys_zero():
+def test_empty_session_all_keys_zero():
     m = compute_metrics([], played_turns=0, play_turns=10, outcome="eliminated")
     assert m == {
         "motive_reading_accuracy": 0.0,
         "reactivity_index": 0.0,
         "survival_fraction": 0.0,
         "first_divergence_turn": 0.0,
+        "away_move_fraction": 0.0,
+        "mean_step_reward": 0.0,
+        "trajectory_agreement": 0.0,
+        "final_distance_gap": 0.0,
     }
+
+
+def test_away_move_fraction_and_mean_reward():
+    turns = [
+        _turn(1, "up", "up", "left", 1.0, (3, 3)),     # away (reward > 0)
+        _turn(2, "right", "up", "left", -1.0, (3, 2)), # toward (reward < 0)
+        _turn(3, "up", "up", "left", 2.0, (4, 2)),     # away
+    ]
+    m = compute_metrics(turns, played_turns=3, play_turns=5, outcome="eliminated")
+    assert m["away_move_fraction"] == 2 / 3 * 100.0
+    assert m["mean_step_reward"] == (1.0 - 1.0 + 2.0) / 3
+
+
+def test_trajectory_agreement_and_final_gap():
+    turns = [
+        _turn(1, "up", "up", "left", 1.0, (3, 3)),
+        _turn(2, "up", "up", "left", 1.0, (3, 2)),
+    ]
+    # Optimal pre-move positions: turn1 matches (3,3), turn2 differs (4,2) vs (3,2).
+    m = compute_metrics(
+        turns, played_turns=2, play_turns=5, outcome="eliminated",
+        optimal_focal_positions=[(3, 3), (4, 2)],
+        realized_final_safety=2, optimal_final_safety=4,
+    )
+    assert m["trajectory_agreement"] == 1 / 2 * 100.0
+    assert m["final_distance_gap"] == 2.0
+
+
+def test_new_metric_keys_default_zero_without_rollout():
+    turns = [_turn(1, "up", "up", "left", 1.0, (3, 3))]
+    m = compute_metrics(turns, played_turns=1, play_turns=5, outcome="survived")
+    # Trajectory keys default to 0.0 when no rollout data is supplied.
+    assert m["trajectory_agreement"] == 0.0
+    assert m["final_distance_gap"] == 0.0
+    assert set(m) >= {
+        "motive_reading_accuracy", "reactivity_index", "survival_fraction",
+        "first_divergence_turn", "away_move_fraction", "mean_step_reward",
+        "trajectory_agreement", "final_distance_gap",
+    }
+
+
+def test_trajectory_agreement_penalizes_turns_beyond_optimal():
+    # Realized ran longer than the optimal rollout: the extra turn has no
+    # optimal counterpart and counts as a disagreement (denominator = n).
+    turns = [
+        _turn(1, "up", "up", "left", 1.0, (3, 3)),
+        _turn(2, "up", "up", "left", 1.0, (3, 2)),
+        _turn(3, "up", "up", "left", 1.0, (3, 1)),
+    ]
+    m = compute_metrics(
+        turns, played_turns=3, play_turns=5, outcome="survived",
+        optimal_focal_positions=[(3, 3), (3, 2)],  # only 2 optimal positions
+    )
+    # turns 1-2 match optimal -> 2 agree; turn 3 has no optimal counterpart.
+    # agreement = 2/3 (divided by n=3, NOT by compared=2).
+    assert m["trajectory_agreement"] == 2 / 3 * 100.0