feat(director): predator_chase memory — longer pre-kill preroll + wider, varied agent roaming

proteus/game/runtime/multiagent_director.py

@@ -64,6 +64,35 @@ def _wander(a: _Agent, rng: random.Random) -> str:
     return rng.choice(legal) if legal else "stay"
 
 
+@dataclass
+class _RoamState:
+    """Persistent per-agent heading for exploratory roaming."""
+    heading: str
+    ttl: int  # steps remaining before the heading is re-rolled
+
+
+def _roam(a: _Agent, rng: random.Random, state: _RoamState,
+          run_min: int = 6, run_max: int = 12) -> str:
+    """Exploratory roam: follow a persistent, seeded per-agent heading for a
+    run of steps, then re-roll it. Headings persist (unlike :func:`_wander`'s
+    fresh uniform draw each turn), so each agent travels far in a distinct
+    direction and the pack covers a much wider area. Fully deterministic given
+    *rng*. The agent stays NON-predator-aware (heading ignores the predator).
+
+    Re-rolls when the run expires OR the current heading is blocked (boundary
+    or another agent), choosing a fresh legal-ish heading and resetting the run.
+    """
+    legal = _legal_moves(a)
+    if not legal:
+        return "stay"
+    # Re-roll on expiry or when the committed heading is no longer in-bounds.
+    if state.ttl <= 0 or state.heading not in legal:
+        state.heading = rng.choice(legal)
+        state.ttl = rng.randint(run_min, run_max)
+    state.ttl -= 1
+    return state.heading
+
+
 def _flee(a: _Agent, threat: tuple[int, int]) -> str:
     """Pick the legal move that MAXIMISES Manhattan distance from *threat*."""
     best, best_d = "stay", -1
@@ -128,11 +157,26 @@ def _frame(agents: list[_Agent], pred: _Agent, facing: str,
 
 def author_predator_chase(
     *, seed: int, agent_starts: list[tuple[int, int]], predator_start: tuple[int, int],
-    agent_size: int = 2, predator_size: int = 3, free_turns: int = 8,
-    max_turns: int = 160,  # >80 plan default: seed=7 distractors are all caught by genuine contact at ~turn 124; smaller budgets trip the safeguard
+    agent_size: int = 2, predator_size: int = 3, free_turns: int = 24,
+    predator_grace: int = 24,  # predator roams (does not pursue) for this many turns, delaying the first kill
+    max_turns: int = 260,  # grace + wider roaming lengthen the episode; seed=7 catches all 3 distractors by genuine contact well within this budget
     persona_id: str = "risk_averse",
 ) -> MemoryCheckpoint:
-    """Author scenario ①: pack flees a predator; one survivor (a0) remains."""
+    """Author scenario ①: pack flees a predator; one survivor (a0) remains.
+
+    Pre-kill design (two levers):
+
+    * **Longer preroll.** The predator holds back during a *grace* period
+      (``predator_grace`` turns): instead of pursuing it merely roams, so the
+      first genuine catch lands much later. ``free_turns`` (a0's pre-flee
+      free-roam window) is widened to match.
+    * **Wider, more varied roaming.** During the pre-catalyst phase every agent
+      (distractors, and a0 in its free window) uses :func:`_roam` — a persistent
+      seeded per-agent heading — instead of a uniform random walk, so the pack
+      travels far in distinct directions and covers a wider area. Distractors
+      stay NON-predator-aware (they never flee), preserving the "caught by
+      genuine contact" contract.
+    """
     rng = random.Random(seed)
     agents = [_Agent(id=f"a{i}", x=p[0], y=p[1], size=agent_size, is_chosen=(i == 0))
               for i, p in enumerate(agent_starts)]
@@ -140,28 +184,40 @@ def author_predator_chase(
     facing = "left"
     turns: list[MemoryTurn] = []
     catalyst_done = False
+    # Per-agent + predator roam headings (seeded; ttl=0 forces a first roll).
+    roam: dict[str, _RoamState] = {a.id: _RoamState(heading="stay", ttl=0) for a in agents}
+    roam["predator"] = _RoamState(heading="stay", ttl=0)
 
     for t in range(1, max_turns + 1):
         events: list[str] = []
         chosen = next(a for a in agents if a.is_chosen)
         # Record the PRE-move frame; the stored action is the chosen agent's.
+        # a0 flees once the catalyst fires or its free window ends; otherwise it
+        # roams widely (exploratory heading) rather than fleeing.
         chosen_action = (_flee(chosen, _center(pred)) if (t > free_turns or catalyst_done)
-                         else _wander(chosen, rng))
+                         else _roam(chosen, rng, roam[chosen.id]))
         turns.append(_frame(agents, pred, facing, [], events, chosen_action, t))
 
         # --- predator-first resolution ---
+        # During the grace window the predator roams (no pursuit), so distractors
+        # are not yet hunted; afterwards it chases the nearest distractor.
         targets = [a for a in agents if a.alive and not a.is_chosen]
-        if targets:
+        pursuing = (t > predator_grace or catalyst_done)
+        if pursuing and targets:
             nearest = min(targets, key=lambda a: _manhattan(_center(pred), _center(a)))
             move = _step_toward(pred, _center(nearest))
-            if move != "stay":
-                facing = _FACING_FROM[move]
-            _apply(pred, move)
+        else:
+            move = _roam(pred, rng, roam["predator"])
+        if move != "stay":
+            facing = _FACING_FROM[move]
+        _apply(pred, move)
         # chosen + distractors move (agent-agent collision avoidance; predator exempt)
         _apply_safe(chosen, chosen_action, agents)
         for a in agents:
             if a.alive and not a.is_chosen:
-                _apply_safe(a, _wander(a, rng), agents)
+                # Wider, varied pre-kill roam; distractors stay non-predator-aware.
+                a_action = _roam(a, rng, roam[a.id]) if not catalyst_done else _wander(a, rng)
+                _apply_safe(a, a_action, agents)
         # kills (distractors only; chosen is the authored survivor)
         for a in agents:
             if a.alive and not a.is_chosen and _overlap(pred, a):

tests/runtime/test_predator_chase_memory.py

@@ -0,0 +1,86 @@
+# tests/runtime/test_predator_chase_memory.py
+"""Redesigned predator_chase memory: longer pre-kill preroll + wider, more
+varied pre-kill roaming.
+
+Baseline (pre-redesign, seed 7):
+  - first "eaten" event at turn_idx 71
+  - max distractor Manhattan displacement from start during the pre-kill phase
+    was only 12 cells (uniform random walk drifts back near the start).
+
+These tests pin measurable improvements:
+  - the first kill must land meaningfully later (preroll floor),
+  - distractors must travel noticeably farther from their starts before the
+    first kill (wider action radius).
+
+Hard invariants (a0 survivor, 3 genuine eaten, determinism) are asserted in
+test_director_predator_chase.py and reinforced here as guardrails.
+"""
+from proteus.game.runtime.multiagent_director import author_predator_chase
+
+_STARTS = [(10, 30), (14, 38), (18, 24), (12, 46)]
+_PRED = (54, 31)
+
+# Justified thresholds vs baseline (seed 7):
+#   first-eat baseline = 71 -> require >= 100 (the redesign lands it at 104,
+#     +33 turns / ~1.46x later; the floor sits a few turns below the achieved
+#     value because first-eat is non-monotonic in the grace/roam interaction).
+#   max pre-kill distractor displacement baseline = 12 -> require >= 20
+#     (the persistent-heading roam achieves 40, vs the random walk's 12).
+_FIRST_EAT_FLOOR = 100
+_SPREAD_FLOOR = 20
+
+
+def _run():
+    return author_predator_chase(seed=7, agent_starts=_STARTS, predator_start=_PRED)
+
+
+def _first_eat_turn(ck):
+    for t in ck.memory_turns:
+        for e in t.events:
+            if "eaten" in e:
+                return t.turn_idx
+    return None
+
+
+def test_first_kill_happens_later():
+    """First genuine 'eaten' event must occur at a clearly later turn."""
+    first = _first_eat_turn(_run())
+    assert first is not None, "expected at least one 'eaten' event"
+    assert first >= _FIRST_EAT_FLOOR, (
+        f"first eat at turn {first}, want >= {_FIRST_EAT_FLOOR}"
+    )
+
+
+def test_distractors_roam_wider_before_first_kill():
+    """Max distractor displacement from start during the pre-kill phase must
+    clearly exceed the uniform-random-walk baseline."""
+    ck = _run()
+    first = _first_eat_turn(ck)
+    assert first is not None
+    starts = {f"a{i}": p for i, p in enumerate(_STARTS) if i != 0}
+    max_disp = 0
+    for t in ck.memory_turns:
+        if t.turn_idx >= first:
+            break
+        for a in t.agents:
+            if a.id in starts:
+                s = starts[a.id]
+                d = abs(a.pos[0] - s[0]) + abs(a.pos[1] - s[1])
+                max_disp = max(max_disp, d)
+    assert max_disp >= _SPREAD_FLOOR, (
+        f"max pre-kill distractor displacement {max_disp}, want >= {_SPREAD_FLOOR}"
+    )
+
+
+def test_guardrails_survivor_and_three_genuine_eaten():
+    """a0 is the sole survivor, alive every turn, and exactly 3 distractors are
+    eaten by GENUINE predator contact (not the silent end safeguard)."""
+    ck = _run()
+    for t in ck.memory_turns:
+        chosen = next(a for a in t.agents if a.id == "a0")
+        assert chosen.alive
+    eaten = [e for t in ck.memory_turns for e in t.events if "eaten" in e]
+    assert len(eaten) == 3, f"expected 3 genuine eaten events, got {eaten}"
+    last = ck.memory_turns[-1]
+    alive = [a for a in last.agents if a.kind == "agent" and a.alive]
+    assert len(alive) == 1 and alive[0].id == "a0"