docs: implementation plan for multi-agent memory + predator visuals (+ spec resource_race turn-order fix)

docs/superpowers/plans/2026-06-03-multiagent-memory-and-predator-visuals.md

@@ -0,0 +1,1618 @@
+# Multi-Agent Memory + Predator/Agent Visual & Turn-Order Refresh — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give the predator game a 2×2 agent / 3×3 open-mouth (ㄷ) predator look with predator-first turns, and add two scripted multi-agent "memory" scenarios (pack-flee survivor, resource-race winner) that feed the scored single-focal benchmark.
+
+**Architecture:** Multi-agent complexity is confined to memory generation + memory rendering; the live `MotiveGridGame` and scored query stay single-focal. Turn order is a per-scenario `turn_order` flag that swaps two operations inside `grid.step()`. The chosen survivor/winner is authored to embody a persona (`risk_averse` / `greedy`); the existing persona machinery scores the query.
+
+**Tech Stack:** Python 3, pydantic (memory models), numpy (engine only — `memory.py` stays numpy-free), pytest. Spec: `docs/superpowers/specs/2026-06-03-multiagent-memory-and-predator-visuals-design.md`.
+
+**Conventions for every task:** run tests with `uv run pytest`. `(dx,dy)`: y grows DOWN. Sprite `(x,y)` is the top-left anchor; a transparent pixel is `-1`.
+
+---
+
+## Phase 1 — Turn order + visuals
+
+### Task 1: `Scenario.turn_order` hook + predator-first swap in `step()`
+
+**Files:**
+- Modify: `proteus/game/scenarios/base.py` (add class attribute)
+- Modify: `proteus/game/engine/grid.py:147-177` (`step()`)
+- Test: `tests/engine/test_turn_order.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/engine/test_turn_order.py
+"""predator-first reorders the turn: advance_threat sees the focal's PRE-move cell."""
+import random
+
+from proteus.game.engine.difficulty import Difficulty
+from proteus.game.engine.grid import MotiveGridGame
+from proteus.game.scenarios.base import get_scenario
+import proteus.game.scenarios  # noqa: F401  (register scenarios)
+
+
+def _focal_cell_seen_by_threat(turn_order: str, action: str = "up"):
+    scen = get_scenario("predator_evade")()
+    scen.turn_order = turn_order  # instance override
+    game = MotiveGridGame(scen, random.Random(0), Difficulty.EASY, max_steps=10)
+    seen = {}
+    real_advance = scen.advance_threat
+
+    def spy(g):
+        f = g.focal_sprite
+        seen["focal"] = (f.x, f.y)
+        real_advance(g)
+
+    scen.advance_threat = spy  # shadow the bound method on this instance
+    before = (game.focal_sprite.x, game.focal_sprite.y)
+    game.apply_motive_action(action)
+    return before, seen["focal"]
+
+
+def test_predator_first_threat_sees_premove_focal():
+    before, seen = _focal_cell_seen_by_threat("predator_first", "up")
+    assert seen == before  # predator advanced BEFORE the focal moved
+
+
+def test_focal_first_threat_sees_postmove_focal():
+    before, seen = _focal_cell_seen_by_threat("focal_first", "up")
+    assert seen != before  # legacy: focal moved first, predator chased the new cell
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/engine/test_turn_order.py -v`
+Expected: FAIL — `test_predator_first_...` fails (default is focal-first, so `seen != before`).
+
+- [ ] **Step 3a: Add the `turn_order` attribute**
+
+In `proteus/game/scenarios/base.py`, inside `class Scenario(ABC)`, right after `memory_brief: str = ""` (line ~68) add:
+
+```python
+    # Turn resolution order. "focal_first" (default): focal moves, then the
+    # threat advances (chasing the focal's NEW cell). "predator_first": the
+    # threat advances first (chasing the focal's CURRENT cell), then the focal
+    # moves. Scenarios override this; predator_evade keeps the default so its
+    # dead-end diagnostic is preserved.
+    turn_order: str = "focal_first"
+```
+
+- [ ] **Step 3b: Swap the order in `step()`**
+
+In `proteus/game/engine/grid.py`, replace the body of `step()` (lines 147-177) with:
+
+```python
+    def step(self) -> None:
+        """Resolve a single turn, honouring ``scenario.turn_order``.
+
+        focal_first (default): move focal, then advance threat (chasing the new
+        focal cell). predator_first: advance threat first (chasing the current
+        focal cell), then move focal. Capture/survival are checked once, after
+        both have moved. Always completes the action so the engine loop ends.
+        """
+        action = _GAMEACTION_TO_ACTION.get(self._action.id, "stay")
+        dx, dy = _DIRECTION_DELTAS[action]
+        focal = self.focal_sprite
+        predator_first = (
+            getattr(self.scenario, "turn_order", "focal_first") == "predator_first"
+        )
+
+        if predator_first:
+            self.scenario.advance_threat(self)
+
+        if (
+            focal is not None
+            and (dx != 0 or dy != 0)
+            and self._footprint_in_bounds(focal, dx, dy)
+        ):
+            self.try_move_sprite(focal, dx, dy)
+
+        if not predator_first:
+            self.scenario.advance_threat(self)
+
+        self.step_count += 1
+
+        if self.scenario.check_elimination(self):
+            self.lose()
+        elif self.step_count >= self.max_steps:
+            self.win()
+
+        self.complete_action()
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/engine/test_turn_order.py -v`
+Expected: PASS (both).
+
+- [ ] **Step 5: Guard against regressions in the existing suite**
+
+Run: `uv run pytest tests/runtime tests/agents -q`
+Expected: PASS (predator_evade is still focal_first; no behaviour change).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add proteus/game/scenarios/base.py proteus/game/engine/grid.py tests/engine/test_turn_order.py
+git commit -m "feat(engine): per-scenario turn_order with predator-first step swap"
+```
+
+---
+
+### Task 2: Resize pack_evade — 2×2 focal, 3×3 ㄷ predator (mouth faces movement), gap=2, predator-first
+
+**Files:**
+- Modify: `proteus/game/scenarios/pack_evade.py` (constants + `build_level` + `advance_threat` + center math + `turn_order`)
+- Test: `tests/scenarios/test_pack_evade_resize.py` (create)
+- Test (existing): re-run pack_evade tests
+
+This task replaces the hard-coded 3×3/5×5 geometry. Apply each edit exactly.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/scenarios/test_pack_evade_resize.py
+"""pack_evade after resize: 2x2 focal, 3x3 open-mouth predator, gap-2 channels."""
+import random
+
+from proteus.game.engine.difficulty import Difficulty
+from proteus.game.engine.grid import MotiveGridGame
+from proteus.game.scenarios.base import get_scenario
+import proteus.game.scenarios  # noqa: F401
+
+
+def _game(diff=Difficulty.EASY, seed=42):
+    scen = get_scenario("pack_evade")()
+    return scen, MotiveGridGame(scen, random.Random(seed), diff, max_steps=50)
+
+
+def test_sprite_sizes():
+    scen, game = _game()
+    assert (game.focal_sprite.width, game.focal_sprite.height) == (2, 2)
+    assert (game.predator_sprite.width, game.predator_sprite.height) == (3, 3)
+
+
+def test_predator_has_open_mouth():
+    scen, game = _game()
+    # ㄷ shape: 9-cell bounding box, exactly 7 solid (2 transparent mouth cells).
+    pix = game.predator_sprite.render()
+    assert (pix != -1).sum() == 7
+
+
+def test_turn_order_is_predator_first():
+    scen, _ = _game()
+    assert scen.turn_order == "predator_first"
+
+
+def test_mouth_faces_movement_direction():
+    scen, game = _game()
+    # Force the predator to take a known step and assert its rotation updates.
+    pred = game.predator_sprite
+    pred.set_position(30, 30)
+    game.focal_sprite.set_position(30, 10)  # straight up from predator
+    scen.advance_threat(game)
+    # Moving up => rotation 270 (see _FACING in pack_evade).
+    assert game.predator_sprite.rotation == 270
+
+
+def test_narrow_gap_blocks_predator_admits_focal():
+    scen, game = _game()
+    scen.build_level(random.Random(0), Difficulty.EASY)
+    # A width-2 free corridor: 2-wide focal footprint fits, 3-wide predator does not.
+    # Use the scenario primitive on a synthetic 2-wide gap between two walls.
+    walls = {(10, y) for y in range(0, 20)} | {(13, y) for y in range(0, 20)}
+    scen._wall_cells = frozenset(walls)
+    # focal anchor (11,5): footprint x in {11,12} — clear of both wall columns.
+    assert scen._footprint_free(game, game.focal_sprite, 11, 5) is True
+    # predator anchor (11,5): footprint x in {11,12,13} — hits wall column 13.
+    assert scen._footprint_free(game, game.predator_sprite, 11, 5) is False
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/scenarios/test_pack_evade_resize.py -v`
+Expected: FAIL (`test_sprite_sizes` — focal is currently 3×3).
+
+- [ ] **Step 3a: Update module constants**
+
+In `proteus/game/scenarios/pack_evade.py`, replace lines 33-36 and 47-63 region. Concretely:
+
+Replace
+```python
+_GRID = (64, 64)
+_FOCAL_START = (5, 30)      # 3x3 -> footprint x[5,8) y[30,33), center (6,31)
+_PREDATOR_START = (54, 29)  # 5x5 -> footprint x[54,59) y[29,34), center (56,31)
+```
+with
+```python
+_GRID = (64, 64)
+_FOCAL_SIZE = 2
+_PREDATOR_SIZE = 3
+_FOCAL_START = (5, 30)      # 2x2 -> footprint x[5,7) y[30,32), center (6,31)
+_PREDATOR_START = (54, 30)  # 3x3 -> footprint x[54,57) y[30,33), center (55,31)
+# ㄷ (open-mouth) predator pixels; mouth opens EAST in the base orientation.
+# Transparent (-1) cells render as background and never collide.
+_PREDATOR_PIXELS = [
+    [PREDATOR_IDX, PREDATOR_IDX, PREDATOR_IDX],
+    [PREDATOR_IDX, -1, -1],
+    [PREDATOR_IDX, PREDATOR_IDX, PREDATOR_IDX],
+]
+# action -> clockwise rotation so the mouth faces the movement direction.
+_FACING = {"right": 0, "down": 90, "left": 180, "up": 270}
+```
+
+Replace
+```python
+_NARROW_GAP = 3          # focal (3-wide) fits; predator (5-wide) cannot
+_CLEARANCE = 6           # min free corridor around blocks/spawns (predator-wide)
+```
+with
+```python
+_NARROW_GAP = 2          # focal (2-wide) fits; predator (3-wide) cannot
+_CLEARANCE = 4           # min free corridor around blocks/spawns (> predator-wide)
+```
+
+Replace
+```python
+_SPAWN_RECTS = (
+    (_FOCAL_START[0], _FOCAL_START[1], _FOCAL_START[0] + 2, _FOCAL_START[1] + 2),
+    (_PREDATOR_START[0], _PREDATOR_START[1], _PREDATOR_START[0] + 4, _PREDATOR_START[1] + 4),
+)
+```
+with
+```python
+_SPAWN_RECTS = (
+    (_FOCAL_START[0], _FOCAL_START[1],
+     _FOCAL_START[0] + _FOCAL_SIZE - 1, _FOCAL_START[1] + _FOCAL_SIZE - 1),
+    (_PREDATOR_START[0], _PREDATOR_START[1],
+     _PREDATOR_START[0] + _PREDATOR_SIZE - 1, _PREDATOR_START[1] + _PREDATOR_SIZE - 1),
+)
+```
+
+Replace
+```python
+_FOCAL_CENTER = (_FOCAL_START[0] + 1, _FOCAL_START[1] + 1)      # 3x3 center
+_PREDATOR_CENTER = (_PREDATOR_START[0] + 2, _PREDATOR_START[1] + 2)  # 5x5 center
+```
+with
+```python
+_FOCAL_CENTER = (_FOCAL_START[0] + _FOCAL_SIZE // 2, _FOCAL_START[1] + _FOCAL_SIZE // 2)
+_PREDATOR_CENTER = (
+    _PREDATOR_START[0] + _PREDATOR_SIZE // 2,
+    _PREDATOR_START[1] + _PREDATOR_SIZE // 2,
+)
+```
+
+- [ ] **Step 3b: Set the class `turn_order` + update `build_level` sprites**
+
+In `class PackEvade`, add a class attribute next to `grid_size` (line ~115):
+```python
+    turn_order: str = "predator_first"
+```
+
+In `build_level` replace the focal + predator sprite construction (lines 146-155) with:
+```python
+        focal = Sprite(
+            pixels=[[FOCAL_IDX] * _FOCAL_SIZE for _ in range(_FOCAL_SIZE)],
+            name="focal", x=_FOCAL_START[0], y=_FOCAL_START[1],
+            blocking=BlockingMode.BOUNDING_BOX,
+        )
+        predator = Sprite(
+            pixels=[row[:] for row in _PREDATOR_PIXELS],
+            name="predator", x=_PREDATOR_START[0], y=_PREDATOR_START[1],
+            blocking=BlockingMode.NOT_BLOCKED,
+        )
+```
+
+- [ ] **Step 3c: Set rotation in `advance_threat`**
+
+In `advance_threat` (lines 320-336) replace the final two lines:
+```python
+        dx, dy = _DELTAS[best_action]
+        predator.move(dx, dy)
+```
+with
+```python
+        dx, dy = _DELTAS[best_action]
+        predator.move(dx, dy)
+        if best_action in _FACING:
+            predator.set_rotation(_FACING[best_action])
+```
+
+- [ ] **Step 3d: Fix hard-coded predator-size center math**
+
+In `step_reward` (line ~371) and `agent_distance_delta` (line ~395) replace both occurrences of:
+```python
+        pred_center_before = (predator_before[0] + 5 // 2, predator_before[1] + 5 // 2)
+```
+with:
+```python
+        pred_center_before = (
+            predator_before[0] + _PREDATOR_SIZE // 2,
+            predator_before[1] + _PREDATOR_SIZE // 2,
+        )
+```
+
+In `_generate_food`, the "behind the predator" comment mentions 5x5; no code change needed there (it uses `_PREDATOR_CENTER`). In `render_frame` the prose strings say "(3x3)"/"(5x5)" — update to `(2x2)`/`(3x3)` for accuracy (text only).
+
+- [ ] **Step 4: Run the new test + the existing pack_evade suite**
+
+Run: `uv run pytest tests/scenarios/test_pack_evade_resize.py tests/runtime/test_pack_evade_memory.py -v`
+Expected: PASS. If a pre-existing pack_evade test pins the old 3-wide gap invariant, re-point its expected free-width from 3 to 2 (search for `_NARROW_GAP`/"3-wide" in tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/scenarios/pack_evade.py tests/scenarios/test_pack_evade_resize.py
+git commit -m "feat(pack_evade): 2x2 focal, 3x3 open-mouth predator, gap-2, predator-first"
+```
+
+---
+
+## Phase 2 — Persona resource feature
+
+### Task 3: Add `resource_reward` to personas + a `greedy` persona + resource-only reference policy
+
+**Files:**
+- Modify: `proteus/game/scenarios/base.py` (add `nearest_resource_distance` hook)
+- Modify: `proteus/game/metrics/persona.py` (`PersonaWeights`, `reward_rw`, `reference_actions`, `BUILTIN_PERSONAS`)
+- Test: `tests/metrics/test_persona_resource.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/metrics/test_persona_resource.py
+"""Greedy persona seeks resources; reference works with no predator."""
+from proteus.game.metrics.persona import (
+    PersonaWeights, get_persona, reference_actions, reward_rw,
+)
+
+
+class _FakeSprite:
+    def __init__(self, x, y):
+        self.x, self.y = x, y
+
+
+class _ResourceWorld:
+    """Minimal scenario+game stand-in: open 10x10, one resource at (9,5), no predator."""
+    grid_size = (10, 10)
+    _resource = (9, 5)
+
+    # --- scenario surface persona.py uses ---
+    def _is_free(self, game, cell):
+        x, y = cell
+        return 0 <= x < 10 and 0 <= y < 10
+
+    def nearest_resource_distance(self, game, cell):
+        return abs(cell[0] - self._resource[0]) + abs(cell[1] - self._resource[1])
+
+    # --- game surface persona.py uses ---
+    @property
+    def focal_sprite(self):
+        return _FakeSprite(5, 5)
+
+    @property
+    def predator_sprite(self):
+        return None
+
+
+def test_greedy_reference_steps_toward_resource():
+    world = _ResourceWorld()
+    greedy = get_persona("greedy")
+    # focal at (5,5), resource at (9,5) -> "right" reduces distance most.
+    assert "right" in reference_actions(greedy, world, world)
+
+
+def test_reward_rw_no_predator_uses_resource_only():
+    world = _ResourceWorld()
+    greedy = get_persona("greedy")
+    r_right = reward_rw(greedy, world, world, (5, 5), (-1, -1), "right")
+    r_left = reward_rw(greedy, world, world, (5, 5), (-1, -1), "left")
+    assert r_right > r_left  # closer to the resource scores higher
+
+
+def test_resource_reward_defaults_zero_for_existing_personas():
+    assert get_persona("risk_averse").resource_reward == 0.0
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/metrics/test_persona_resource.py -v`
+Expected: FAIL (`get_persona("greedy")` raises KeyError).
+
+- [ ] **Step 3a: Add the scenario hook**
+
+In `proteus/game/scenarios/base.py`, after `agent_distance_delta` (before the registry section, ~line 284) add:
+
+```python
+    def nearest_resource_distance(self, game, cell) -> int | None:
+        """Distance from *cell* (focal anchor) to the nearest collectible resource.
+
+        ``None`` by default (no resources). Resource scenarios override this so
+        the persona reward's resource term can pull the reference toward the
+        nearest resource. Distance metric is the scenario's choice (BFS or
+        Manhattan); smaller = closer.
+        """
+        del game, cell
+        return None
+```
+
+- [ ] **Step 3b: Extend `PersonaWeights`**
+
+In `proteus/game/metrics/persona.py`, replace the dataclass fields (lines 46-49) with:
+
+```python
+    persona_weight_id: str
+    risk_cost: float = 0.0
+    capture_penalty: float = 50.0
+    resource_reward: float = 0.0   # weight on proximity to the nearest resource
+```
+
+- [ ] **Step 3c: Rewrite `reward_rw` to make the predator optional + add the resource term**
+
+Replace the body of `reward_rw` (lines 82-88) with:
+
+```python
+    post = _post_focal(scenario, game, focal_before, action, blocked)
+    r = 0.0
+    if game.predator_sprite is not None:
+        d = scenario._bfs_distance(game, post, predator_before)
+        risk_exposure = 1.0 if d is None else 1.0 / (1.0 + d)
+        r -= weights.risk_cost * risk_exposure
+        if captured:
+            r -= weights.capture_penalty
+    if weights.resource_reward:
+        rd = scenario.nearest_resource_distance(game, post)
+        if rd is not None:
+            r += weights.resource_reward * (1.0 / (1.0 + rd))
+    return r
+```
+
+- [ ] **Step 3d: Make `reference_actions` tolerate a missing predator**
+
+Replace lines 98-104 (the early-return + position read) with:
+
+```python
+    focal = game.focal_sprite
+    if focal is None:
+        return ["stay"]
+    predator = game.predator_sprite
+    focal_before = (focal.x, focal.y)
+    predator_before = (predator.x, predator.y) if predator is not None else (-1, -1)
+```
+
+- [ ] **Step 3e: Register the `greedy` persona**
+
+In `BUILTIN_PERSONAS` (lines 135-141) add after `survival_optimal`:
+
+```python
+    "greedy": PersonaWeights(
+        persona_weight_id="greedy", risk_cost=1.0, resource_reward=6.0
+    ),
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/metrics/test_persona_resource.py tests/runtime -q`
+Expected: PASS (existing risk-only persona tests unaffected — predator branch unchanged when present).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/scenarios/base.py proteus/game/metrics/persona.py tests/metrics/test_persona_resource.py
+git commit -m "feat(persona): resource_reward feature + greedy persona + predator-optional reference"
+```
+
+---
+
+## Phase 3 — Multi-agent memory data model + rendering
+
+### Task 4: `AgentFrame` model + multi-agent fields on `MemoryTurn`/`MemoryCheckpoint`
+
+**Files:**
+- Modify: `proteus/game/runtime/memory.py` (models only in this task)
+- Test: `tests/runtime/test_memory_multiagent_model.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_memory_multiagent_model.py
+"""Multi-agent memory fields round-trip and stay backward compatible."""
+from proteus.game.runtime.memory import (
+    AgentFrame, MemoryCheckpoint, MemoryTurn,
+)
+
+
+def test_agentframe_defaults():
+    a = AgentFrame(id="a0", kind="agent", pos=(3, 4), size=2)
+    assert a.alive is True and a.is_chosen is False and a.facing == "right"
+
+
+def test_turn_multiagent_roundtrip():
+    t = MemoryTurn(
+        turn_idx=1, frame_ascii="", action="up",
+        focal_pos=(0, 0), predator_pos=(0, 0),
+        agents=[AgentFrame(id="a0", kind="agent", pos=(3, 4), size=2, is_chosen=True),
+                AgentFrame(id="predator", kind="predator", pos=(9, 9), size=3, facing="left")],
+        resources=[(5, 5)], events=["a1 eaten"],
+    )
+    back = MemoryTurn.model_validate_json(t.model_dump_json())
+    assert back.agents[0].is_chosen is True
+    assert back.agents[1].facing == "left"
+    assert back.resources == [(5, 5)] and back.events == ["a1 eaten"]
+
+
+def test_checkpoint_chosen_id_and_backcompat():
+    ck = MemoryCheckpoint(
+        model="m", scenario="s", difficulty="easy", created_at="x",
+        outcome="survived", transparent_prompt="p", chosen_agent_id="a0",
+    )
+    back = MemoryCheckpoint.model_validate_json(ck.model_dump_json())
+    assert back.chosen_agent_id == "a0"
+    # Legacy single-agent turns still parse with empty multi-agent fields.
+    legacy = MemoryTurn(turn_idx=1, frame_ascii="x", action="up",
+                        focal_pos=(1, 1), predator_pos=(2, 2))
+    assert legacy.agents == [] and legacy.resources == [] and legacy.events == []
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/runtime/test_memory_multiagent_model.py -v`
+Expected: FAIL (`ImportError: cannot import name 'AgentFrame'`).
+
+- [ ] **Step 3a: Add the `AgentFrame` model**
+
+In `proteus/game/runtime/memory.py`, after the imports (line 16) and before `class MemoryTurn` add:
+
+```python
+class AgentFrame(BaseModel):
+    """One sprite's render state in a multi-agent memory turn.
+
+    Attributes:
+        id: Stable identifier (``"a0".."a3"`` or ``"predator"``).
+        kind: ``"agent"`` or ``"predator"`` (drives shape + colour).
+        pos: Top-left anchor ``(x, y)`` at the start of this turn.
+        size: Footprint side length (agent=2, predator=3).
+        alive: Painted only while alive (eaten agents disappear).
+        is_chosen: The agent the player continues (painted in the focal colour).
+        facing: Predator mouth direction for the ㄷ shape (render only).
+    """
+
+    id: str
+    kind: str
+    pos: tuple[int, int]
+    size: int
+    alive: bool = True
+    is_chosen: bool = False
+    facing: str = "right"
+```
+
+- [ ] **Step 3b: Add fields to `MemoryTurn`**
+
+In `class MemoryTurn`, after `predator_pos: tuple[int, int]` (line 35) add:
+
+```python
+    agents: list[AgentFrame] = Field(default_factory=list)
+    """Per-sprite render states; non-empty ⇒ the multi-agent render path."""
+    resources: list[tuple[int, int]] = Field(default_factory=list)
+    """Collectible resource cells still present this turn."""
+    events: list[str] = Field(default_factory=list)
+    """Narration for this turn, e.g. ``"a1 eaten"`` / ``"a0 got resource"``."""
+```
+
+- [ ] **Step 3c: Add `chosen_agent_id` to `MemoryCheckpoint`**
+
+In `class MemoryCheckpoint`, after `persona_weight_id: str | None = None` (line 66) add:
+
+```python
+    chosen_agent_id: str | None = None
+    """Id of the survivor / resource winner the player continues (multi-agent only)."""
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/runtime/test_memory_multiagent_model.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/runtime/memory.py tests/runtime/test_memory_multiagent_model.py
+git commit -m "feat(memory): AgentFrame model + multi-agent turn/checkpoint fields"
+```
+
+---
+
+### Task 5: Multi-agent `memory_frames` rendering (2×2 agents, 3×3 ㄷ predator, resources)
+
+**Files:**
+- Modify: `proteus/game/runtime/memory.py` (`memory_frames` + module-level shape helper)
+- Test: `tests/runtime/test_memory_frames_multiagent.py` (create)
+
+`memory.py` must stay numpy-free (pure lists). The predator mouth is described by the SOLID-cell offsets per facing.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_memory_frames_multiagent.py
+"""Multi-agent memory frames paint shapes + colours; single-agent path unchanged."""
+from proteus.game.runtime.memory import (
+    AgentFrame, MemoryCheckpoint, MemoryTurn, memory_frames,
+)
+
+_LEGEND = {5: ".", 1: "A", 2: "B", 3: "#", 14: "F"}
+_GRID = (12, 12)
+_CHOSEN, _DISTRACT, _PRED, _FOOD, _BG = 1, 9, 2, 14, 5
+
+
+def _ck(turn):
+    return MemoryCheckpoint(
+        model="m", scenario="s", difficulty="easy", created_at="x",
+        outcome="survived", transparent_prompt="p", memory_turns=[turn],
+    )
+
+
+def test_multiagent_paints_agents_predator_resources():
+    turn = MemoryTurn(
+        turn_idx=1, frame_ascii="", action="up", focal_pos=(0, 0), predator_pos=(0, 0),
+        agents=[
+            AgentFrame(id="a0", kind="agent", pos=(2, 2), size=2, is_chosen=True),
+            AgentFrame(id="a1", kind="agent", pos=(6, 6), size=2),
+            AgentFrame(id="a2", kind="agent", pos=(1, 8), size=2, alive=False),
+            AgentFrame(id="predator", kind="predator", pos=(8, 1), size=3, facing="right"),
+        ],
+        resources=[(5, 5)], events=["a2 eaten"],
+    )
+    grid = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]["grid"]
+    # chosen 2x2 at (2,2)
+    assert grid[2][2] == _CHOSEN and grid[3][3] == _CHOSEN
+    # distractor 2x2 at (6,6) in blue
+    assert grid[6][6] == _DISTRACT
+    # eaten agent NOT painted
+    assert grid[8][1] == _BG
+    # resource
+    assert grid[5][5] == _FOOD
+    # predator ㄷ at (8,1), mouth EAST => the two right-middle cells are background
+    assert grid[1][8] == _PRED and grid[3][10] == _PRED   # corners solid
+    assert grid[2][9] == _BG and grid[2][10] == _BG        # mouth cells transparent
+
+
+def test_multiagent_frame_carries_events():
+    turn = MemoryTurn(turn_idx=1, frame_ascii="", action="up", focal_pos=(0, 0),
+                      predator_pos=(0, 0),
+                      agents=[AgentFrame(id="a0", kind="agent", pos=(0, 0), size=2)],
+                      events=["hello"])
+    out = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]
+    assert out["events"] == ["hello"]
+
+
+def test_single_agent_path_unchanged():
+    # No agents -> legacy reconstruction (prose frame), paints predator 5-block etc.
+    turn = MemoryTurn(turn_idx=1, frame_ascii="prose", action="up",
+                      focal_pos=(2, 2), predator_pos=(7, 7))
+    out = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]
+    assert "grid" in out and out["events"] == []
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/runtime/test_memory_frames_multiagent.py -v`
+Expected: FAIL (`grid[2][2]` not chosen colour — multi-agent branch missing).
+
+- [ ] **Step 3a: Add the predator mouth-shape helper**
+
+In `proteus/game/runtime/memory.py`, after `_ascii_to_grid` (line ~151) add:
+
+```python
+# Transparent (mouth) cells of the 3x3 ㄷ predator, per facing, as (col, row).
+# The mouth = the centre cell + the edge-centre cell on the facing side.
+_PRED_MOUTH: dict[str, set[tuple[int, int]]] = {
+    "right": {(1, 1), (2, 1)},
+    "left": {(1, 1), (0, 1)},
+    "down": {(1, 1), (1, 2)},
+    "up": {(1, 1), (1, 0)},
+}
+
+
+def _predator_solid_offsets(facing: str) -> list[tuple[int, int]]:
+    """The (col, row) offsets PAINTED for a 3x3 ㄷ predator facing *facing*."""
+    mouth = _PRED_MOUTH.get(facing, _PRED_MOUTH["right"])
+    return [(c, r) for r in range(3) for c in range(3) if (c, r) not in mouth]
+```
+
+- [ ] **Step 3b: Add the multi-agent branch in `memory_frames`**
+
+In `memory_frames`, the loop currently does `for mt in checkpoint.memory_turns:` then reconstructs. Add the multi-agent branch as the FIRST thing inside the loop (before `grid = _ascii_to_grid(...)`):
+
+```python
+    distractor_idx = 9  # COLOR_MAP blue
+    for mt in checkpoint.memory_turns:
+        if mt.agents:
+            grid = [[bg] * w for _ in range(h)]
+            for (rx0, ry0, rx1, ry1) in checkpoint.wall_rects:
+                for y in range(max(0, ry0), min(h, ry1 + 1)):
+                    for x in range(max(0, rx0), min(w, rx1 + 1)):
+                        grid[y][x] = wall_idx
+            for (fx, fy) in mt.resources:
+                if 0 <= fx < w and 0 <= fy < h:
+                    grid[fy][fx] = food_idx
+            for ag in mt.agents:
+                if not ag.alive:
+                    continue
+                if ag.kind == "predator":
+                    for (c, r) in _predator_solid_offsets(ag.facing):
+                        x, y = ag.pos[0] + c, ag.pos[1] + r
+                        if 0 <= x < w and 0 <= y < h:
+                            grid[y][x] = predator_idx
+                else:
+                    color = focal_idx if ag.is_chosen else distractor_idx
+                    for r in range(ag.size):
+                        for c in range(ag.size):
+                            x, y = ag.pos[0] + c, ag.pos[1] + r
+                            if 0 <= x < w and 0 <= y < h:
+                                grid[y][x] = color
+            out.append({"turn_idx": mt.turn_idx, "action": mt.action,
+                        "grid": grid, "events": list(mt.events)})
+            continue
+        grid = _ascii_to_grid(mt.frame_ascii, sym2idx)
+        ...  # (existing reconstruction unchanged)
+```
+
+NOTE: the existing loop body that follows must be preserved. Also change the existing single-agent append (the last line of the loop) from
+```python
+        out.append({"turn_idx": mt.turn_idx, "action": mt.action, "grid": grid})
+```
+to
+```python
+        out.append({"turn_idx": mt.turn_idx, "action": mt.action,
+                    "grid": grid, "events": list(mt.events)})
+```
+so every frame carries `events` (legacy = `[]`). Delete the now-duplicate `for mt in checkpoint.memory_turns:` line that was already there (the branch above reuses the same loop header — keep exactly one loop header).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/runtime/test_memory_frames_multiagent.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Regression-check existing frame tests**
+
+Run: `uv run pytest tests/runtime/test_memory_frames.py -q`
+Expected: PASS (they should tolerate the extra `events` key; if one asserts exact dict equality, update it to include `"events": []`).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add proteus/game/runtime/memory.py tests/runtime/test_memory_frames_multiagent.py
+git commit -m "feat(memory): multi-agent memory_frames (2x2 agents, 3x3 mouth predator, resources)"
+```
+
+---
+
+## Phase 4 — Director + new scenarios
+
+### Task 6: Scripted director — scenario ① `author_pack_flee`
+
+**Files:**
+- Create: `proteus/game/runtime/multiagent_director.py`
+- Test: `tests/runtime/test_director_pack_flee.py` (create)
+
+Open-field (no walls), equal speed. The chosen agent (`a0`) is **kill-immune** (authored survivor) and flees; distractors panic-wander and are caught one at a time after a free phase; a `max_turns` safeguard force-resolves any stragglers so the memory always ends with exactly one survivor.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_director_pack_flee.py
+from proteus.game.runtime.multiagent_director import author_pack_flee
+
+
+def _run():
+    return author_pack_flee(
+        seed=7,
+        agent_starts=[(10, 30), (14, 38), (18, 24), (12, 46)],
+        predator_start=(54, 31),
+    )
+
+
+def test_deterministic():
+    a, b = _run(), _run()
+    assert a.model_dump_json() == b.model_dump_json()
+
+
+def test_ends_with_single_chosen_survivor():
+    ck = _run()
+    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].is_chosen and alive[0].id == "a0"
+    assert ck.chosen_agent_id == "a0"
+
+
+def test_chosen_alive_every_turn_and_kills_recorded():
+    ck = _run()
+    for t in ck.memory_turns:
+        chosen = next(a for a in t.agents if a.id == "a0")
+        assert chosen.alive
+    all_events = [e for t in ck.memory_turns for e in t.events]
+    assert sum("eaten" in e for e in all_events) == 3  # 3 distractors caught
+
+
+def test_persona_id_recorded():
+    assert _run().persona_weight_id == "risk_averse"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/runtime/test_director_pack_flee.py -v`
+Expected: FAIL (module does not exist).
+
+- [ ] **Step 3: Create the director with scenario ①**
+
+```python
+# proteus/game/runtime/multiagent_director.py
+"""Deterministic scripted directors that author multi-agent handover memories.
+
+These do NOT run the live engine (which is single-focal). They own the
+multi-agent truth on an open field and emit a ``MemoryCheckpoint`` whose
+``memory_turns`` carry per-sprite ``AgentFrame``s, resources, and events. The
+chosen agent (``a0``) is authored to embody a persona: it flees optimally
+(``risk_averse``, scenario ①) or beelines to the resource (``greedy``,
+scenario ②). Distractors wander. Geometry is open-field Manhattan.
+"""
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+from proteus.game.runtime.memory import AgentFrame, MemoryCheckpoint, MemoryTurn
+
+_GRID = (64, 64)
+_DELTAS = {"up": (0, -1), "down": (0, 1), "left": (-1, 0), "right": (1, 0), "stay": (0, 0)}
+_MOVES = ("up", "down", "left", "right")
+_FACING_FROM = {"right": "right", "left": "left", "up": "up", "down": "down"}
+_STAMP = "0000-00-00T00-00-00"
+
+
+@dataclass
+class _Agent:
+    id: str
+    x: int
+    y: int
+    size: int
+    alive: bool = True
+    is_chosen: bool = False
+
+
+def _in_bounds(x: int, y: int, size: int, grid=_GRID) -> bool:
+    return 0 <= x and 0 <= y and x + size <= grid[0] and y + size <= grid[1]
+
+
+def _center(a: _Agent) -> tuple[int, int]:
+    return (a.x + a.size // 2, a.y + a.size // 2)
+
+
+def _manhattan(a: tuple[int, int], b: tuple[int, int]) -> int:
+    return abs(a[0] - b[0]) + abs(a[1] - b[1])
+
+
+def _overlap(a: _Agent, b: _Agent) -> bool:
+    return (a.x < b.x + b.size and b.x < a.x + a.size
+            and a.y < b.y + b.size and b.y < a.y + a.size)
+
+
+def _legal_moves(a: _Agent, grid=_GRID) -> list[str]:
+    out = []
+    for m in _MOVES:
+        dx, dy = _DELTAS[m]
+        if _in_bounds(a.x + dx, a.y + dy, a.size, grid):
+            out.append(m)
+    return out
+
+
+def _wander(a: _Agent, rng: random.Random) -> str:
+    legal = _legal_moves(a)
+    return rng.choice(legal) if legal else "stay"
+
+
+def _flee(a: _Agent, threat: tuple[int, int]) -> str:
+    """Pick the legal move that MAXIMISES Manhattan distance from *threat*."""
+    best, best_d = "stay", -1
+    for m in _legal_moves(a):
+        dx, dy = _DELTAS[m]
+        cc = (a.x + dx + a.size // 2, a.y + dy + a.size // 2)
+        d = _manhattan(cc, threat)
+        if d > best_d:
+            best, best_d = m, d
+    return best
+
+
+def _step_toward(a: _Agent, target: tuple[int, int]) -> str:
+    """One greedy footprint-safe step reducing Manhattan distance to *target*."""
+    best, best_d = "stay", _manhattan(_center(a), target)
+    for m in _legal_moves(a):
+        dx, dy = _DELTAS[m]
+        cc = (a.x + dx + a.size // 2, a.y + dy + a.size // 2)
+        d = _manhattan(cc, target)
+        if d < best_d:
+            best, best_d = m, d
+    return best
+
+
+def _apply(a: _Agent, action: str) -> None:
+    dx, dy = _DELTAS[action]
+    if _in_bounds(a.x + dx, a.y + dy, a.size):
+        a.x, a.y = a.x + dx, a.y + dy
+
+
+def _frame(agents: list[_Agent], pred: _Agent, facing: str,
+           resources, events, action: str, idx: int) -> MemoryTurn:
+    frames = [AgentFrame(id=a.id, kind="agent", pos=(a.x, a.y), size=a.size,
+                         alive=a.alive, is_chosen=a.is_chosen) for a in agents]
+    if pred is not None:
+        frames.append(AgentFrame(id="predator", kind="predator",
+                                 pos=(pred.x, pred.y), size=pred.size, facing=facing))
+    alive_n = sum(1 for a in agents if a.alive)
+    return MemoryTurn(
+        turn_idx=idx, frame_ascii=f"{alive_n} agents alive; predator at {(pred.x, pred.y) if pred else None}",
+        action=action, focal_pos=(0, 0), predator_pos=(0, 0),
+        agents=frames, resources=list(resources), events=list(events),
+    )
+
+
+def author_pack_flee(
+    *, 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 = 80,
+    persona_id: str = "risk_averse",
+) -> MemoryCheckpoint:
+    """Author scenario ①: pack flees a predator; one survivor (a0) remains."""
+    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)]
+    pred = _Agent(id="predator", x=predator_start[0], y=predator_start[1], size=predator_size)
+    facing = "left"
+    turns: list[MemoryTurn] = []
+    catalyst_done = False
+
+    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.
+        chosen_action = (_flee(chosen, _center(pred)) if (t > free_turns or catalyst_done)
+                         else _wander(chosen, rng))
+        turns.append(_frame(agents, pred, facing, [], events, chosen_action, t))
+
+        # --- predator-first resolution ---
+        targets = [a for a in agents if a.alive and not a.is_chosen]
+        if 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)
+        # chosen + distractors move
+        _apply(chosen, chosen_action)
+        for a in agents:
+            if a.alive and not a.is_chosen:
+                _apply(a, _wander(a, rng))
+        # 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
+                events.append(f"{a.id} eaten")
+        # patch events onto the frame we just appended
+        turns[-1].events = list(events)
+
+        if sum(1 for a in agents if a.alive and not a.is_chosen) == 0:
+            break
+
+    # Safeguard: force-resolve any stragglers so exactly the chosen survives.
+    for a in agents:
+        if a.alive and not a.is_chosen:
+            a.alive = False
+    if turns:
+        # Append a final settled frame (predator removed for clarity).
+        turns.append(_frame(agents, pred, facing, [], ["only a0 survives"], "stay",
+                            len(turns) + 1))
+
+    return MemoryCheckpoint(
+        model=f"director:{persona_id}", scenario="pack_flee", motive_category="survival",
+        difficulty="easy", seed=seed, created_at=_STAMP, memory_turns=turns,
+        outcome="survived", transparent_prompt="Pack-flee handover memory.",
+        persona_weight_id=persona_id, chosen_agent_id="a0",
+    )
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/runtime/test_director_pack_flee.py -v`
+Expected: PASS. (If `test_chosen_alive_every_turn_and_kills_recorded` finds ≠3 "eaten" events because the safeguard fired, increase `max_turns` to 120 — the open-field random-walk distractors must be caught by the directed predator within the budget; 80 is tuned for these starts.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/runtime/multiagent_director.py tests/runtime/test_director_pack_flee.py
+git commit -m "feat(director): author_pack_flee multi-agent survivor memory"
+```
+
+---
+
+### Task 7: Scripted director — scenario ② `author_resource_race`
+
+**Files:**
+- Modify: `proteus/game/runtime/multiagent_director.py` (add function)
+- Test: `tests/runtime/test_director_resource_race.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_director_resource_race.py
+from proteus.game.runtime.multiagent_director import author_resource_race
+
+
+def _run():
+    return author_resource_race(
+        seed=3,
+        agent_starts=[(8, 52), (20, 10), (40, 50), (55, 20), (30, 30)],
+        resource=(54, 12),
+    )
+
+
+def test_deterministic():
+    assert _run().model_dump_json() == _run().model_dump_json()
+
+
+def test_ends_when_chosen_collects_resource():
+    ck = _run()
+    last = ck.memory_turns[-1]
+    assert any("got resource" in e for e in last.events)
+    chosen = next(a for a in last.agents if a.id == "a0")
+    rx, ry = (54, 12)
+    # chosen footprint covers the resource cell
+    assert chosen.pos[0] <= rx < chosen.pos[0] + chosen.size
+    assert chosen.pos[1] <= ry < chosen.pos[1] + chosen.size
+    assert ck.chosen_agent_id == "a0" and ck.persona_weight_id == "greedy"
+
+
+def test_resource_present_until_collected():
+    ck = _run()
+    # Every turn except the last carries the resource; the last records pickup.
+    for t in ck.memory_turns[:-1]:
+        assert t.resources == [(54, 12)]
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/runtime/test_director_resource_race.py -v`
+Expected: FAIL (`author_resource_race` undefined).
+
+- [ ] **Step 3: Add `author_resource_race` to the director**
+
+Append to `proteus/game/runtime/multiagent_director.py`:
+
+```python
+def _covers(a: _Agent, cell: tuple[int, int]) -> bool:
+    return (a.x <= cell[0] < a.x + a.size and a.y <= cell[1] < a.y + a.size)
+
+
+def author_resource_race(
+    *, seed: int, agent_starts: list[tuple[int, int]], resource: tuple[int, int],
+    agent_size: int = 2, max_turns: int = 120, persona_id: str = "greedy",
+) -> MemoryCheckpoint:
+    """Author scenario ②: a0 beelines to the lone resource; others wander."""
+    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)]
+    turns: list[MemoryTurn] = []
+
+    for t in range(1, max_turns + 1):
+        chosen = next(a for a in agents if a.is_chosen)
+        if _covers(chosen, resource):
+            turns.append(_frame(agents, None, "right", [resource],
+                                ["a0 got resource"], "stay", t))
+            break
+        action = _step_toward(chosen, resource)
+        turns.append(_frame(agents, None, "right", [resource], [], action, t))
+        _apply(chosen, action)
+        for a in agents:
+            if not a.is_chosen:
+                _apply(a, _wander(a, rng))
+
+    return MemoryCheckpoint(
+        model=f"director:{persona_id}", scenario="resource_race",
+        motive_category="resource", difficulty="easy", seed=seed, created_at=_STAMP,
+        memory_turns=turns, outcome="survived",
+        transparent_prompt="Resource-race handover memory.",
+        persona_weight_id=persona_id, chosen_agent_id="a0",
+    )
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/runtime/test_director_resource_race.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/runtime/multiagent_director.py tests/runtime/test_director_resource_race.py
+git commit -m "feat(director): author_resource_race multi-agent winner memory"
+```
+
+---
+
+### Task 8: `pack_flee` scenario (single-focal query, reuses pack_evade live mechanics)
+
+**Files:**
+- Create: `proteus/game/scenarios/pack_flee.py`
+- Modify: `proteus/game/scenarios/__init__.py`
+- Test: `tests/scenarios/test_pack_flee.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/scenarios/test_pack_flee.py
+import random
+
+from proteus.game.engine.difficulty import Difficulty
+from proteus.game.scenarios.base import get_scenario, list_scenarios
+import proteus.game.scenarios  # noqa: F401
+
+
+def test_registered():
+    assert "pack_flee" in list_scenarios()
+
+
+def test_predator_first_and_sizes():
+    scen = get_scenario("pack_flee")()
+    assert scen.turn_order == "predator_first"
+
+
+def test_default_memory_is_multiagent_survivor():
+    scen = get_scenario("pack_flee")()
+    ck = scen.default_memory(seed=7, difficulty=Difficulty.EASY)
+    assert ck.chosen_agent_id == "a0" and ck.persona_weight_id == "risk_averse"
+    last = ck.memory_turns[-1]
+    alive = [a for a in last.agents if a.kind == "agent" and a.alive]
+    assert len(alive) == 1
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/scenarios/test_pack_flee.py -v`
+Expected: FAIL (`pack_flee` not registered).
+
+- [ ] **Step 3a: Create the scenario**
+
+```python
+# proteus/game/scenarios/pack_flee.py
+"""pack_flee — scenario ①: a single-focal predator-evasion QUERY whose handover
+memory is a hand-authored multi-agent pack flee (see
+``proteus.game.runtime.multiagent_director.author_pack_flee``). The lone survivor
+of that memory (``a0``, a risk_averse evader) is the focal the player continues.
+
+Live mechanics are identical to the resized ``pack_evade`` (2x2 focal, 3x3
+open-mouth predator, predator-first), so this subclasses it and only swaps the
+handover memory + briefs.
+"""
+from __future__ import annotations
+
+from proteus.game.scenarios.base import register_scenario
+from proteus.game.scenarios.pack_evade import PackEvade
+
+
+@register_scenario("pack_flee")
+class PackFlee(PackEvade):
+    task_name: str = "pack_flee"
+    rules_text: str = (
+        "You are the lone survivor of a pack. A 3x3 predator hunts you (2x2). "
+        "It steps toward you every turn; you are eaten on contact. Stay as far "
+        "from it as you can. Actions: up, down, left, right, stay."
+    )
+    memory_brief: str = (
+        "MEMORY. Your pack scattered as a predator closed in; the others were "
+        "caught one by one and you alone escaped by keeping maximum distance."
+    )
+
+    def default_memory(self, seed, difficulty):
+        from proteus.game.runtime.multiagent_director import author_pack_flee
+        # Deterministic spread of 4 agents + a distant predator on the 64x64 field.
+        return author_pack_flee(
+            seed=(seed if seed is not None else 0),
+            agent_starts=[(10, 30), (14, 38), (18, 24), (12, 46)],
+            predator_start=(54, 31),
+            persona_id="risk_averse",
+        )
+```
+
+- [ ] **Step 3b: Register it**
+
+In `proteus/game/scenarios/__init__.py` add after the `pack_evade` import:
+```python
+from proteus.game.scenarios import pack_flee  # noqa: F401  — side-effect: register
+```
+and add `"pack_flee"` to `__all__`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest tests/scenarios/test_pack_flee.py -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/scenarios/pack_flee.py proteus/game/scenarios/__init__.py tests/scenarios/test_pack_flee.py
+git commit -m "feat(scenario): pack_flee single-focal query + multi-agent survivor memory"
+```
+
+---
+
+### Task 9: `resource_race` scenario (resources-only single-focal query, greedy persona)
+
+**Files:**
+- Create: `proteus/game/scenarios/resource_race.py`
+- Modify: `proteus/game/scenarios/__init__.py`
+- Test: `tests/scenarios/test_resource_race.py` (create)
+
+No predator. `turn_order` stays `focal_first` (irrelevant without a threat; resource collection runs in `advance_threat` after the focal move). Ends at horizon (no early win).
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/scenarios/test_resource_race.py
+import random
+
+from proteus.game.engine.difficulty import Difficulty
+from proteus.game.engine.grid import MotiveGridGame
+from proteus.game.scenarios.base import get_scenario, list_scenarios
+import proteus.game.scenarios  # noqa: F401
+
+
+def _game(seed=1):
+    scen = get_scenario("resource_race")()
+    return scen, MotiveGridGame(scen, random.Random(seed), Difficulty.EASY, max_steps=40)
+
+
+def test_registered():
+    assert "resource_race" in list_scenarios()
+
+
+def test_no_predator_never_eliminates():
+    scen, game = _game()
+    assert game.predator_sprite is None
+    assert scen.check_elimination(game) is False
+
+
+def test_optimal_action_heads_to_nearest_resource():
+    scen, game = _game()
+    a = scen.optimal_action(game)
+    assert a in ("up", "down", "left", "right", "stay")
+    assert scen.nearest_resource_distance(game, (game.focal_sprite.x, game.focal_sprite.y)) is not None
+
+
+def test_collecting_a_resource_removes_it():
+    scen, game = _game()
+    res = scen.food_cells()
+    assert res, "expected resources on the field"
+    target = res[0]
+    # Teleport focal onto the resource and advance one turn (collection runs there).
+    game.focal_sprite.set_position(target[0], target[1])
+    scen.advance_threat(game)
+    assert target not in scen.food_cells()
+
+
+def test_default_memory_greedy_winner():
+    scen, _ = _game()
+    ck = scen.default_memory(seed=3, difficulty=Difficulty.EASY)
+    assert ck.persona_weight_id == "greedy" and ck.chosen_agent_id == "a0"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/scenarios/test_resource_race.py -v`
+Expected: FAIL (`resource_race` not registered).
+
+- [ ] **Step 3a: Create the scenario**
+
+```python
+# proteus/game/scenarios/resource_race.py
+"""resource_race — scenario ②: a resources-only, predator-free single-focal QUERY.
+
+The handover memory is a hand-authored multi-agent race for one resource where
+``a0`` (a greedy resource-seeker) wins (see
+``proteus.game.runtime.multiagent_director.author_resource_race``). The query
+field has several resources; the greedy reference policy heads for the nearest
+one each turn, and the existing persona metrics score how well the player
+maintains that resource-seeking persona.
+
+No predator: ``check_elimination`` is always False, distance/pressure metrics are
+skipped (None), and the episode ends at the horizon. ``turn_order`` stays
+focal_first so resource collection (run in ``advance_threat``) sees the focal's
+post-move cell.
+"""
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING
+
+from proteus.game.engine import BlockingMode, Level, Sprite
+from proteus.game.engine.difficulty import Difficulty
+
+from .base import Scenario, register_scenario
+
+if TYPE_CHECKING:
+    from ..engine.grid import MotiveGridGame
+
+BACKGROUND_IDX = 5
+FOCAL_IDX = 1
+FOOD_IDX = 14
+_GRID = (64, 64)
+_FOCAL_SIZE = 2
+_FOCAL_START = (8, 52)
+_DELTAS = {"up": (0, -1), "down": (0, 1), "left": (-1, 0), "right": (1, 0), "stay": (0, 0)}
+_ORDER = ("up", "down", "left", "right", "stay")
+_N_RESOURCES = {Difficulty.EASY: 6, Difficulty.MEDIUM: 6, Difficulty.HARD: 8, Difficulty.EXPERT: 8}
+_MARGIN = 2
+
+
+def _manhattan(a, b):
+    return abs(a[0] - b[0]) + abs(a[1] - b[1])
+
+
+@register_scenario("resource_race")
+class ResourceRace(Scenario):
+    task_name: str = "resource_race"
+    grid_size: tuple[int, int] = _GRID
+    turn_order: str = "focal_first"
+    rules_text: str = (
+        "You are a 2x2 agent on a 64x64 field scattered with resources (green "
+        "cells). Move onto a resource to collect it. Gather as many as you can. "
+        "Actions: up, down, left, right, stay."
+    )
+    memory_brief: str = (
+        "MEMORY. Among five agents you alone made straight for the resource and "
+        "took it while the others wandered."
+    )
+
+    _resources: list[tuple[int, int]] = []
+
+    def build_level(self, rng: random.Random, difficulty: Difficulty) -> Level:
+        self.grid_size = _GRID
+        w, h = _GRID
+        spawn = {(_FOCAL_START[0] + i, _FOCAL_START[1] + j)
+                 for i in range(_FOCAL_SIZE) for j in range(_FOCAL_SIZE)}
+        cells: list[tuple[int, int]] = []
+        while len(cells) < _N_RESOURCES.get(difficulty, 6):
+            c = (rng.randint(_MARGIN, w - 1 - _MARGIN), rng.randint(_MARGIN, h - 1 - _MARGIN))
+            if c not in spawn and c not in cells:
+                cells.append(c)
+        self._resources = cells
+        focal = Sprite(
+            pixels=[[FOCAL_IDX] * _FOCAL_SIZE for _ in range(_FOCAL_SIZE)],
+            name="focal", x=_FOCAL_START[0], y=_FOCAL_START[1],
+            blocking=BlockingMode.BOUNDING_BOX,
+        )
+        food = [Sprite(pixels=[[FOOD_IDX]], name="food", x=fx, y=fy,
+                       blocking=BlockingMode.NOT_BLOCKED) for (fx, fy) in cells]
+        return Level(sprites=[*food, focal])
+
+    # --- no-predator stubs -------------------------------------------------- #
+    def cut_focal_policy(self, game: MotiveGridGame) -> str:
+        del game
+        return "stay"
+
+    def cut_length(self, difficulty) -> int:
+        del difficulty
+        return 0
+
+    def advance_threat(self, game: MotiveGridGame) -> None:
+        """No predator; collect any resource the focal now overlaps."""
+        focal = game.focal_sprite
+        if focal is None:
+            return
+        covered = {(focal.x + i, focal.y + j)
+                   for i in range(focal.width) for j in range(focal.height)}
+        self._resources = [c for c in self._resources if c not in covered]
+
+    def check_elimination(self, game: MotiveGridGame) -> bool:
+        del game
+        return False
+
+    # --- geometry the persona/metrics use ----------------------------------- #
+    def _is_free(self, game: MotiveGridGame, cell: tuple[int, int]) -> bool:
+        x, y = cell
+        w, h = self.grid_size
+        return 0 <= x and 0 <= y and x + _FOCAL_SIZE <= w and y + _FOCAL_SIZE <= h
+
+    def nearest_resource_distance(self, game, cell) -> int | None:
+        if not self._resources:
+            return None
+        center = (cell[0] + _FOCAL_SIZE // 2, cell[1] + _FOCAL_SIZE // 2)
+        return min(_manhattan(center, r) for r in self._resources)
+
+    def optimal_action(self, game: MotiveGridGame) -> str:
+        focal = game.focal_sprite
+        if focal is None or not self._resources:
+            return "stay"
+        src = (focal.x, focal.y)
+        best, best_d = "stay", self.nearest_resource_distance(game, src)
+        for a in _ORDER:
+            dx, dy = _DELTAS[a]
+            cand = (src[0] + dx, src[1] + dy)
+            if a != "stay" and not self._is_free(game, cand):
+                continue
+            d = self.nearest_resource_distance(game, cand)
+            if d is not None and (best_d is None or d < best_d):
+                best, best_d = a, d
+        return best
+
+    def habit_action(self, game: MotiveGridGame) -> str:
+        return self.optimal_action(game)  # no diagnostic
+
+    def step_reward(self, game, action, blocked, focal_before, predator_before) -> float:
+        del action, blocked, predator_before
+        focal = game.focal_sprite
+        if focal is None:
+            return 0.0
+        before = self.nearest_resource_distance(game, focal_before)
+        after = self.nearest_resource_distance(game, (focal.x, focal.y))
+        if before is None or after is None:
+            return 0.0
+        return float(before - after)  # positive = moved toward a resource
+
+    def legend(self) -> dict[int, str]:
+        return {BACKGROUND_IDX: ".", FOCAL_IDX: "A", FOOD_IDX: "F"}
+
+    def food_cells(self) -> list[tuple[int, int]]:
+        return list(self._resources)
+
+    def render_frame(self, game: MotiveGridGame) -> str:
+        focal = game.focal_sprite
+        if focal is None:
+            return "field state unavailable"
+        fc = (focal.x + _FOCAL_SIZE // 2, focal.y + _FOCAL_SIZE // 2)
+        cells = "; ".join(f"({x},{y})" for (x, y) in self._resources) or "none"
+        return (f"Open field {_GRID[0]}x{_GRID[1]}. You are A (2x2) centered at {fc}. "
+                f"Resources remaining: {cells}.")
+
+    def default_memory(self, seed, difficulty):
+        from proteus.game.runtime.multiagent_director import author_resource_race
+        return author_resource_race(
+            seed=(seed if seed is not None else 0),
+            agent_starts=[(8, 52), (20, 10), (40, 50), (55, 20), (30, 30)],
+            resource=(54, 12), persona_id="greedy",
+        )
+```
+
+- [ ] **Step 3b: Register it**
+
+In `proteus/game/scenarios/__init__.py` add:
+```python
+from proteus.game.scenarios import resource_race  # noqa: F401  — side-effect: register
+```
+and add `"resource_race"` to `__all__`.
+
+- [ ] **Step 4: Run tests + a full-loop smoke**
+
+Run: `uv run pytest tests/scenarios/test_resource_race.py -v`
+Expected: PASS.
+
+Then verify a full interactive episode runs end-to-end (no predator, ends at horizon):
+Run:
+```bash
+uv run python -c "
+from proteus.game.runtime.interactive import InteractiveSession
+import proteus.game.scenarios  # noqa
+s = InteractiveSession('resource_race', seed=1, play_turns=5)
+for _ in range(5):
+    st = s.step('right')
+print('outcome', st['outcome'])
+"
+```
+Expected: prints `outcome survived`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/game/scenarios/resource_race.py proteus/game/scenarios/__init__.py tests/scenarios/test_resource_race.py
+git commit -m "feat(scenario): resource_race resources-only query + greedy multi-agent memory"
+```
+
+---
+
+## Phase 5 — Web wiring
+
+### Task 10: Surface multi-agent memory in the web replay (events caption + legend)
+
+**Files:**
+- Modify: `proteus/web/local/static/index.html` (caption + legend)
+- Test: `tests/web/test_multiagent_memory_route.py` (create)
+
+`server._memory_info` already returns `memory_frames(...)`, which now includes
+`agents`-painted grids + `events`. No server change is needed for data; this task
+adds the client caption/legend and a route smoke test.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/web/test_multiagent_memory_route.py
+"""Creating a pack_flee session returns multi-agent memory frames over HTTP."""
+from proteus.web.local.server import handle_request
+import proteus.game.scenarios  # noqa: F401
+
+
+def test_pack_flee_session_returns_painted_multiagent_memory():
+    registry: dict = {}
+    body = {"scenario": "pack_flee", "difficulty": "easy", "seed": 7,
+            "play_turns": 5, "memory": "default"}
+    status, payload, _ = handle_request("POST", "/session", body, registry)
+    assert status == 200, payload
+    frames = payload["memory"]["frames"]
+    assert frames, "expected memory frames"
+    # Distractor blue (9) appears somewhere in an early frame's grid.
+    flat0 = [v for row in frames[0]["grid"] for v in row]
+    assert 9 in flat0
+    # events key is present on frames.
+    assert "events" in frames[0]
+```
+
+- [ ] **Step 2: Run test to verify it fails (or passes data-only) **
+
+Run: `uv run pytest tests/web/test_multiagent_memory_route.py -v`
+Expected: PASS for the data assertions (server already forwards frames). If it
+fails on `9 in flat0`, the memory_frames branch (Task 5) regressed — fix there.
+This test pins the contract before the JS change.
+
+- [ ] **Step 3: Add the events caption + legend in `index.html`**
+
+In `proteus/web/local/static/index.html`, in `renderMemFrame()` (lines ~261-267) replace:
+```javascript
+  $("memReplayCap").textContent =
+    `Memory ${f.turn_idx} / ${MEM_FRAMES.length} — you chose: ${f.action}`;
+```
+with:
+```javascript
+  const ev = (f.events && f.events.length) ? "  ·  " + f.events.join(", ") : "";
+  $("memReplayCap").textContent =
+    `Memory ${f.turn_idx} / ${MEM_FRAMES.length} — you chose: ${f.action}${ev}`;
+```
+
+In `showMem(m)` (after setting `$("memInfo").textContent`, ~line 295) append a static legend so the viewer can read the colours:
+```javascript
+  $("memInfo").textContent +=
+    "  ·  blue = other agents, light = you, mouth-block = predator";
+```
+
+- [ ] **Step 4: Re-run the web test + full web suite**
+
+Run: `uv run pytest tests/web -q`
+Expected: PASS.
+
+- [ ] **Step 5: Manual smoke (optional)**
+
+Run: `uv run python -m proteus.web.local` then open the printed URL, pick
+scenario `pack_flee`, memory `scenario default`, start, and step through the
+memory replay — distractors render blue, the survivor light, the predator as an
+open-mouth block; the caption shows "aN eaten" on kill turns.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add proteus/web/local/static/index.html tests/web/test_multiagent_memory_route.py
+git commit -m "feat(web): multi-agent memory replay caption + colour legend"
+```
+
+---
+
+## Final verification
+
+- [ ] **Run the whole suite**
+
+Run: `uv run pytest -q`
+Expected: PASS (all phases green).
+
+- [ ] **Confirm the four scenarios are registered**
+
+Run: `uv run python -c "import proteus.game.scenarios as s; from proteus.game.scenarios.base import list_scenarios; print(list_scenarios())"`
+Expected: includes `pack_evade`, `pack_flee`, `predator_evade`, `resource_race`.

docs/superpowers/specs/2026-06-03-multiagent-memory-and-predator-visuals-design.md

@@ -119,8 +119,11 @@ width 2.
 ### 2.3 Turn order = predator-first
 
 - New `Scenario.turn_order` hook returns `"focal_first"` by default;
-  `pack_evade`, `pack_flee`, `resource_race` return `"predator_first"`.
-  `predator_evade` keeps the default (preserves its diagnostic).
+  `pack_evade` and `pack_flee` return `"predator_first"`. `predator_evade` keeps
+  the default (preserves its diagnostic). `resource_race` also keeps
+  `"focal_first"`: it has no predator, and its resource collection runs in
+  `advance_threat`, which must fire *after* the focal moves — so focal-first is
+  required there.
 - **Implementation = swap two operations inside `grid.step()`, guarded by
   `turn_order`.** No session-loop changes are needed.
   - `focal_first` (current): move focal → `advance_threat` → check terminal.