feat(memory): per-turn cells overlay channel + npc_down/npc_active colours in memory_frames

proteus/game/runtime/memory.py

@@ -59,6 +59,13 @@ class MemoryTurn(BaseModel):
     """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."""
+    cells: list[tuple[int, int, int]] = Field(default_factory=list)
+    """Generic coloured overlay cells ``(x, y, palette_idx)`` for this turn.
+
+    Painted after walls and before agents in :func:`memory_frames`. Lets the
+    errand_runner director draw per-tick world objects (the recolouring
+    traffic-light bar, roads, construction, wallet, home) without a bespoke
+    field per object type. Empty for all legacy single-/multi-agent turns."""
     events: list[str] = Field(default_factory=list)
     """Narration for this turn, e.g. ``"a1 eaten"`` / ``"a0 got resource"``."""
 
@@ -203,6 +210,10 @@ def _predator_solid_offsets(facing: str) -> list[tuple[int, int]]:
     return [(c, r) for r in range(3) for c in range(3) if (c, r) not in mouth]
 
 
+# NPC agent kinds -> palette colour (errand_runner fallen-pedestrian rescue).
+_NPC_COLOR: dict[str, int] = {"npc_down": 11, "npc_active": 14}  # yellow -> green
+
+
 def memory_frames(
     checkpoint: MemoryCheckpoint, *, legend: dict[int, str], grid_size: tuple[int, int]
 ) -> list[dict]:
@@ -239,6 +250,9 @@ def memory_frames(
                 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 (cx, cy, cidx) in mt.cells:
+                if 0 <= cx < w and 0 <= cy < h:
+                    grid[cy][cx] = cidx
             for (fx, fy) in mt.resources:
                 if 0 <= fx < w and 0 <= fy < h:
                     grid[fy][fx] = food_idx
@@ -250,6 +264,8 @@ def memory_frames(
                         x, y = ag.pos[0] + c, ag.pos[1] + r
                         if 0 <= x < w and 0 <= y < h:
                             grid[y][x] = predator_idx
+                elif ag.kind in _NPC_COLOR:
+                    paint(grid, ag.pos[0], ag.pos[1], ag.size, _NPC_COLOR[ag.kind])
                 else:
                     color = focal_idx if ag.is_chosen else distractor_idx
                     for r in range(ag.size):

tests/runtime/test_memory_frames_overlay.py

@@ -0,0 +1,60 @@
+# tests/runtime/test_memory_frames_overlay.py
+"""errand_runner memory render: generic `cells` overlay + npc agent colours.
+
+Legacy turns (no cells, kind in {agent,predator}) stay byte-identical.
+"""
+from proteus.game.runtime.memory import (
+    AgentFrame, MemoryCheckpoint, MemoryTurn, memory_frames,
+)
+
+_LEGEND = {5: ".", 1: "A", 2: "B", 3: "#", 14: "F"}
+_GRID = (12, 12)
+
+
+def _ck(turn):
+    return MemoryCheckpoint(
+        model="m", scenario="errand_runner", difficulty="easy", created_at="x",
+        outcome="survived", transparent_prompt="p", memory_turns=[turn],
+    )
+
+
+def test_cells_overlay_painted_over_background():
+    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)],
+        cells=[(7, 3, 8), (7, 4, 8), (7, 5, 8)],  # red (8) traffic-light bar
+    )
+    grid = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]["grid"]
+    assert grid[3][7] == 8 and grid[4][7] == 8 and grid[5][7] == 8
+
+
+def test_agents_paint_over_cells():
+    # A candidate body on a road cell must render as the body, not the road.
+    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)],
+        cells=[(2, 2, 3)],  # neutral road under the agent's top-left cell
+    )
+    grid = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]["grid"]
+    assert grid[2][2] == 1  # focal colour wins over the overlay
+
+
+def test_npc_down_is_yellow_and_active_is_green():
+    turn = MemoryTurn(
+        turn_idx=1, frame_ascii="", action="up", focal_pos=(0, 0), predator_pos=(0, 0),
+        agents=[
+            AgentFrame(id="ped", kind="npc_down", pos=(2, 2), size=2),
+            AgentFrame(id="ped2", kind="npc_active", pos=(8, 8), size=2),
+        ],
+    )
+    grid = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]["grid"]
+    assert grid[2][2] == 11  # npc_down -> yellow
+    assert grid[8][8] == 14  # npc_active -> green
+
+
+def test_legacy_turn_without_cells_unaffected():
+    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)])
+    out = memory_frames(_ck(turn), legend=_LEGEND, grid_size=_GRID)[0]
+    assert "grid" in out and out["events"] == []