feat(director): predator_chase pack scatters (all survivors flee) after the first kill

proteus/game/runtime/multiagent_director.py

@@ -159,7 +159,8 @@ 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 = 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
+    panic_turns: int = 14,  # after EACH kill all survivors flee for this many turns (the visible scatter), then resume roaming
+    max_turns: int = 400,  # grace + wider roaming + panic bursts lengthen the episode; seed=7 catches all 3 distractors by genuine contact within this budget
     persona_id: str = "risk_averse",
 ) -> MemoryCheckpoint:
     """Author scenario ①: pack flees a predator; one survivor (a0) remains.
@@ -176,6 +177,18 @@ def author_predator_chase(
       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.
+
+    Post-kill SCATTER (panic burst). Once a distractor is eaten the whole pack
+    scatters: for ``panic_turns`` turns AFTER each kill every surviving
+    distractor flees the predator (maximising Manhattan distance), exactly like
+    the chosen a0. This reproduces "when one agent is eaten, the whole pack
+    moves away from the predator". The burst is finite: because the predator and
+    the agents move at EQUAL speed, perfectly-fleeing distractors run to opposite
+    field corners and deadlock — they can never be cornered. So after the burst
+    expires the surviving distractors resume the (non-predator-aware) roam, which
+    lets the predator close in and genuinely catch the next one; that next catch
+    re-arms the burst, scattering the remaining survivors again. a0 (``is_chosen``,
+    never killed) flees permanently once the catalyst fires.
     """
     rng = random.Random(seed)
     agents = [_Agent(id=f"a{i}", x=p[0], y=p[1], size=agent_size, is_chosen=(i == 0))
@@ -184,6 +197,7 @@ def author_predator_chase(
     facing = "left"
     turns: list[MemoryTurn] = []
     catalyst_done = False
+    panic_ttl = 0  # >0 => survivors are mid-scatter (flee); re-armed on each kill
     # 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)
@@ -215,14 +229,22 @@ def author_predator_chase(
         _apply_safe(chosen, chosen_action, agents)
         for a in agents:
             if a.alive and not a.is_chosen:
-                # 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)
+                # While a panic burst is active every surviving distractor FLEES
+                # the predator (the scatter); otherwise it uses the wider, varied
+                # roam (non-predator-aware) so the predator can close in for the
+                # next genuine catch. Pre-catalyst there is never a burst, so this
+                # is the original wide roam.
+                a_action = (_flee(a, _center(pred)) if panic_ttl > 0
+                            else _roam(a, rng, roam[a.id]))
                 _apply_safe(a, a_action, agents)
+        if panic_ttl > 0:
+            panic_ttl -= 1
         # kills (distractors only; chosen is the authored survivor)
         for a in agents:
             if a.alive and not a.is_chosen and _overlap(pred, a):
                 a.alive = False
                 catalyst_done = True
+                panic_ttl = panic_turns  # (re-)arm the scatter burst on every kill
                 events.append(f"{a.id} eaten")
         # patch events onto the frame we just appended
         turns[-1].events = list(events)

tests/runtime/test_predator_chase_memory.py

@@ -72,6 +72,95 @@ def test_distractors_roam_wider_before_first_kill():
     )
 
 
+def _pred_center(turn):
+    for a in turn.agents:
+        if a.kind == "predator":
+            return (a.pos[0] + a.size // 2, a.pos[1] + a.size // 2)
+    return None
+
+
+def _agent_center(a):
+    return (a.pos[0] + a.size // 2, a.pos[1] + a.size // 2)
+
+
+# Window (in turns) right after the first kill over which the pack must visibly
+# move AWAY from the predator. Kept short so edge-cornering of one agent cannot
+# make the assertion vacuous or fragile.
+_SCATTER_WINDOW = 6
+# One-step slack: agent-agent collision (the no-overlap invariant) can block a
+# survivor's optimal flee move for a single transition, costing at most ~2 cells
+# of Manhattan distance before it recovers. We allow that much and no more.
+# Measured separation between the two regimes for seed 7:
+#   roaming (pre-change): nearest survivor is steadily approached, min distance
+#     drops by 6 over the window  -> exceeds the slack -> FAILS.
+#   fleeing (post-change): the pack holds the predator off, min distance drops
+#     by at most 2 (one blocked step) then holds -> within slack -> PASSES.
+_BLOCK_SLACK = 2
+
+
+def _min_survivor_dist(turn, ids):
+    """Minimum Manhattan distance from any alive distractor in *ids* to the
+    predator on *turn*, or None if no predator / none of *ids* alive."""
+    pred = _pred_center(turn)
+    if pred is None:
+        return None
+    dists = [
+        abs(_agent_center(a)[0] - pred[0]) + abs(_agent_center(a)[1] - pred[1])
+        for a in turn.agents
+        if a.kind == "agent" and a.id in ids and a.alive
+    ]
+    return min(dists) if dists else None
+
+
+def test_pack_scatters_after_first_kill():
+    """After the FIRST 'eaten' event the whole pack scatters and FLEES, so the
+    predator cannot keep closing the gap: the MINIMUM surviving-distractor
+    distance to the predator never drops more than one blocked step below its
+    value at the kill turn across the short window right after the kill.
+
+    Pre-change the survivors keep roaming (predator-unaware), so the predator
+    steadily corners the nearest one and the minimum distance collapses well
+    past the slack -> this assertion FAILS. With the scatter change every
+    survivor flees, the pack holds the predator off, and the minimum distance is
+    maintained -> it PASSES."""
+    ck = _run()
+    first = _first_eat_turn(ck)
+    assert first is not None
+    by_turn = {t.turn_idx: t for t in ck.memory_turns}
+
+    # The kill-turn frame is recorded PRE-move, so the agent being eaten is still
+    # alive in it. Restrict to the genuine SURVIVORS (alive non-chosen distractors
+    # that are NOT named in any 'eaten' event on the kill turn) so the baseline
+    # reflects the pack that must flee, not the agent about to die.
+    kill_turn = by_turn[first]
+    eaten_now = {e.split()[0] for e in kill_turn.events if "eaten" in e}
+    survivor_ids = {
+        a.id for a in kill_turn.agents
+        if a.kind == "agent" and a.id != "a0" and a.alive and a.id not in eaten_now
+    }
+    assert survivor_ids, "expected surviving distractors at the first-kill turn"
+
+    kill_min = _min_survivor_dist(kill_turn, survivor_ids)
+    assert kill_min is not None
+    floor = kill_min - _BLOCK_SLACK
+
+    checked = 0
+    for off in range(1, _SCATTER_WINDOW + 1):
+        t = by_turn.get(first + off)
+        if t is None:
+            break
+        m = _min_survivor_dist(t, survivor_ids)
+        if m is None:  # final settled frame (predator removed) or no survivors
+            break
+        checked += 1
+        assert m >= floor, (
+            f"nearest survivor closed on the predator after the kill: "
+            f"min distance {m} at turn {t.turn_idx} < floor {floor} "
+            f"(kill-turn min {kill_min} - slack {_BLOCK_SLACK}); the pack did not flee"
+        )
+    assert checked >= 3, f"scatter window too short to be meaningful ({checked} frames)"
+
+
 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)."""