docs(cp5): implementation plan — HumanAgent + viz (11 TDD tasks)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/superpowers/plans/2026-06-01-proteus-arena-viz-humanplay.md

@@ -0,0 +1,1373 @@
+# PROTEUS CP5 — Human Play + Trace Visualization 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:** Add `proteus play --human` (a stdin `HumanAgent` routed through the existing `SessionRunner`, producing a trace schema-identical to an LLM trace) and `proteus replay --visual/--png` (truecolor terminal + PNG visualization of any `SessionTrace`), all offline and headless-testable.
+
+**Architecture:** A new `HumanAgent` implements the existing `Agent` ABC with injected I/O so it is testable without a TTY; `SessionRunner` is reused verbatim. A new `proteus/viz/` package reconstructs pixel frames from a lean trace by deterministically replaying the world (`scenario, seed, difficulty` + recorded actions) through the real engine, with double self-verification (Cut-frame ASCII equality + per-turn position equality). Two renderers consume the reconstructed frames: a terminal compositor (truecolor block grid + side panel, reusing `arc_grid.rendering` helpers) and a matplotlib-Agg per-frame PNG writer.
+
+**Tech Stack:** Python 3.12, pydantic v2, numpy, argparse, matplotlib (Agg, `viz` extra), pytest. Run tests with `.venv/bin/python -m pytest` (note: `python` is NOT on PATH).
+
+**Spec:** `docs/superpowers/specs/2026-06-01-proteus-cp5-viz-humanplay-design.md` (CP5 sub-design) under the parent SSOT `docs/superpowers/specs/2026-06-01-proteus-arena-slice-design.md`.
+
+---
+
+## File Structure
+
+| File | Responsibility | Task |
+|------|----------------|------|
+| `proteus/agents/human.py` | `HumanAgent(Agent)` — stdin player, I/O-injected | 1, 2 |
+| `proteus/agents/__init__.py` | export `HumanAgent` | 1 |
+| `proteus/viz/__init__.py` | viz package public surface | 4, 5, 6 |
+| `proteus/viz/reconstruct.py` | trace → deterministic engine replay → `FrameStep[]` (+ self-verify) | 4 |
+| `proteus/viz/terminal.py` | `FrameStep[]` → truecolor grid + side panel (ANSI) | 5 |
+| `proteus/viz/png.py` | `FrameStep[]` → `frame_NNN.png` (matplotlib Agg) | 6 |
+| `proteus/cli.py` | `play` subcommand + `replay --visual/--png/--fps` | 8, 9 |
+| `tests/agents/test_human.py` | HumanAgent contract | 1, 2 |
+| `tests/runtime/test_human_comparability.py` | human trace ≡ LLM trace schema/answer-keys | 3 |
+| `tests/viz/test_reconstruct.py` | reconstruction + self-verify + corruption raise | 4 |
+| `tests/viz/test_terminal.py` | ANSI + panel fields + frame count | 5 |
+| `tests/viz/test_png.py` | per-frame file count + nonzero size | 6 |
+| `tests/cli/test_cli.py` | `play` + `replay --visual/--png` (extend existing) | 8, 9 |
+
+**Dependency direction (parent spec §3, invariant):** `viz` depends on `runtime.trace` (read), `grid` (engine rebuild), `arc_grid.rendering` (palette + ANSI helpers). `arc_grid` never imports `proteus.*`. `runtime/trace.py` imports nothing else. `SessionRunner` is NOT modified.
+
+---
+
+## Task 0: Environment prep — matplotlib in `.venv`
+
+The PNG path (Task 6) needs matplotlib; `.venv` currently has only pydantic/numpy/pyyaml/pytest. matplotlib Agg is offline (no network, no display), so it does not violate the SDK-free/offline invariant.
+
+- [ ] **Step 1: Install matplotlib into the existing venv**
+
+Run:
+```bash
+uv pip install --python .venv/bin/python "matplotlib>=3.8"
+```
+Expected: matplotlib (and its deps) install successfully.
+
+- [ ] **Step 2: Verify the headless import works**
+
+Run:
+```bash
+.venv/bin/python -c "import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt; print('agg ok')"
+```
+Expected: prints `agg ok` with no display/window.
+
+- [ ] **Step 3: Confirm the baseline suite still passes**
+
+Run:
+```bash
+.venv/bin/python -m pytest -q
+```
+Expected: `75 passed` (the pre-CP5 baseline), no network.
+
+No commit (environment-only change; `.venv` is gitignored).
+
+---
+
+## Task 1: HumanAgent — act path + reset + export
+
+**Files:**
+- Create: `proteus/agents/human.py`
+- Modify: `proteus/agents/__init__.py`
+- Test: `tests/agents/test_human.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/agents/test_human.py`:
+```python
+from proteus.agents import HumanAgent
+from proteus.agents.base import ActResult
+
+_ACTIONS = ["up", "down", "left", "right", "stay"]
+
+
+def _scripted(seq):
+    """Return an input_fn that yields the given strings in order."""
+    it = iter(seq)
+    return lambda prompt="": next(it)
+
+
+def test_act_parses_plain_action():
+    out = []
+    agent = HumanAgent(input_fn=_scripted(["up"]), output_fn=out.append)
+    result = agent.act("OBSERVATION", _ACTIONS, "SYSTEM")
+    assert isinstance(result, ActResult)
+    assert result.action == "up"
+    assert result.reasoning == ""
+    assert result.raw_text == "up"
+    assert result.input_tokens == 0
+    assert result.output_tokens == 0
+    assert result.thinking_tokens == 0
+    # The observation was shown to the human.
+    assert any("OBSERVATION" in line for line in out)
+
+
+def test_act_maps_wasd_shortcuts():
+    agent = HumanAgent(input_fn=_scripted(["w"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "up"
+    agent = HumanAgent(input_fn=_scripted(["a"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "left"
+    agent = HumanAgent(input_fn=_scripted(["s"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "down"
+    agent = HumanAgent(input_fn=_scripted(["d"]), output_fn=lambda s: None)
+    assert agent.act("o", _ACTIONS, "s").action == "right"
+
+
+def test_act_is_case_and_whitespace_insensitive():
+    agent = HumanAgent(input_fn=_scripted(["  UP  "]), output_fn=lambda s: None)
+    result = agent.act("o", _ACTIONS, "s")
+    assert result.action == "up"
+    assert result.raw_text == "UP"  # stripped, original casing preserved
+
+
+def test_act_reprompts_on_invalid_then_accepts():
+    out = []
+    agent = HumanAgent(input_fn=_scripted(["nope", "diagonal", "right"]), output_fn=out.append)
+    result = agent.act("o", _ACTIONS, "s")
+    assert result.action == "right"
+    # Two invalid inputs produced two guidance messages.
+    assert sum("invalid" in line for line in out) == 2
+
+
+def test_name_is_human():
+    assert HumanAgent().name == "human"
+
+
+def test_reset_is_noop():
+    assert HumanAgent().reset() is None
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/agents/test_human.py -q`
+Expected: FAIL with `ImportError: cannot import name 'HumanAgent'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `proteus/agents/human.py`:
+```python
+"""HumanAgent — a stdin-driven Agent so a person plays through the same SessionRunner.
+
+Routing a human through the identical SessionRunner makes the resulting
+SessionTrace schema-identical to an LLM trace, so the two compare directly
+(the human-baseline foundation, spec §10). The agent is I/O-injected
+(input_fn / output_fn) so human play is testable headlessly with a scripted
+input stream — no TTY, no network.
+
+Fairness note: the live view is the ASCII observation the LLM also sees; the
+truecolor / PNG renderers are reserved for post-hoc replay (proteus.viz), so a
+human baseline reads exactly what the model reads.
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import Callable, Optional
+
+from proteus.agents.base import Agent, ActResult, ProbeResult
+
+# Single-key shortcuts -> canonical action strings (WASD).
+_SHORTCUTS = {"w": "up", "a": "left", "s": "down", "d": "right"}
+
+
+class HumanAgent(Agent):
+    """An Agent driven by a person via injected input/output callables.
+
+    Args:
+        input_fn: Reads one line from the human (defaults to builtins.input,
+            resolved lazily so tests can monkeypatch builtins.input).
+        output_fn: Shows a line to the human (defaults to builtins.print).
+    """
+
+    def __init__(
+        self,
+        input_fn: Optional[Callable[[str], str]] = None,
+        output_fn: Optional[Callable[[str], None]] = None,
+    ) -> None:
+        # Resolve builtins at construction time (not as default-arg values, which
+        # would capture the pre-monkeypatch references at import time).
+        self._input = input_fn if input_fn is not None else builtins.input
+        self._output = output_fn if output_fn is not None else builtins.print
+
+    @property
+    def name(self) -> str:
+        return "human"
+
+    def act(
+        self,
+        observation: str,
+        available_actions: list[str],
+        system_prompt: str,
+    ) -> ActResult:
+        self._output(observation)
+        action, raw = self._read_action(available_actions)
+        return ActResult(action=action, reasoning="", raw_text=raw)
+
+    def probe(
+        self,
+        observation: str,
+        question: str,
+        system_prompt: str,
+    ) -> ProbeResult:
+        # Implemented in Task 2.
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        return None
+
+    def _read_action(self, available_actions: list[str]) -> tuple[str, str]:
+        """Prompt until a valid action is entered; return (action, raw_input)."""
+        valid = {a.lower() for a in available_actions}
+        prompt = f"action [{'/'.join(available_actions)} | wasd]> "
+        while True:
+            raw = self._input(prompt).strip()
+            token = raw.lower()
+            action = _SHORTCUTS.get(token, token)
+            if action in valid:
+                return action, raw
+            self._output(
+                f"invalid input {raw!r}; choose one of "
+                f"{', '.join(available_actions)} (or wasd)."
+            )
+```
+
+Modify `proteus/agents/__init__.py` to:
+```python
+"""proteus.agents — slim LLM agent abstraction (no forfeit/stake/risk)."""
+
+from proteus.agents.base import Agent, ActResult, ProbeResult
+from proteus.agents.human import HumanAgent
+from proteus.agents.vanilla import VanillaAgent
+
+__all__ = ["Agent", "ActResult", "ProbeResult", "HumanAgent", "VanillaAgent"]
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/agents/test_human.py -q`
+Expected: PASS (6 tests; `test_reset_is_noop` and `test_name_is_human` included). The probe test does not exist yet.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/agents/human.py proteus/agents/__init__.py tests/agents/test_human.py
+git commit -m "feat(cp5): HumanAgent act path + WASD parsing + reprompt (I/O-injected)"
+```
+
+---
+
+## Task 2: HumanAgent — probe path
+
+**Files:**
+- Modify: `proteus/agents/human.py` (replace the `probe` stub)
+- Test: `tests/agents/test_human.py` (add)
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/agents/test_human.py`:
+```python
+from proteus.agents.base import ProbeResult
+
+
+def test_probe_returns_typed_answer():
+    out = []
+    agent = HumanAgent(
+        input_fn=_scripted(["the predator is east; go up"]),
+        output_fn=out.append,
+    )
+    result = agent.probe("OBSERVATION", "Where is the predator?", "SYSTEM")
+    assert isinstance(result, ProbeResult)
+    assert result.answer == "the predator is east; go up"
+    assert result.reasoning == ""
+    assert result.raw_text == "the predator is east; go up"
+    assert result.input_tokens == 0
+    assert result.output_tokens == 0
+    assert result.thinking_tokens == 0
+    # Both the observation and the question were shown.
+    assert any("OBSERVATION" in line for line in out)
+    assert any("Where is the predator?" in line for line in out)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/agents/test_human.py::test_probe_returns_typed_answer -q`
+Expected: FAIL with `NotImplementedError`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `proteus/agents/human.py`, replace the `probe` method body:
+```python
+    def probe(
+        self,
+        observation: str,
+        question: str,
+        system_prompt: str,
+    ) -> ProbeResult:
+        self._output(observation)
+        self._output(question)
+        answer = self._input("probe> ").strip()
+        return ProbeResult(answer=answer, reasoning="", raw_text=answer)
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/agents/test_human.py -q`
+Expected: PASS (all HumanAgent tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/agents/human.py tests/agents/test_human.py
+git commit -m "feat(cp5): HumanAgent probe path returns typed ProbeResult"
+```
+
+---
+
+## Task 3: Comparability invariant — human trace ≡ LLM trace
+
+This task adds NO production code; it locks in the core spec §10 invariant: a human routed through `SessionRunner` yields a trace structurally identical to an LLM trace (same Cut, same per-turn answer keys, same metrics keys), differing only in `model`.
+
+**Files:**
+- Test: `tests/runtime/test_human_comparability.py`
+
+- [ ] **Step 1: Write the test**
+
+Create `tests/runtime/test_human_comparability.py`:
+```python
+from proteus.agents import HumanAgent, VanillaAgent
+from proteus.providers import FakeProvider
+from proteus.runtime.session import SessionRunner
+
+
+def _scripted(seq):
+    it = iter(seq)
+    return lambda prompt="": next(it)
+
+
+def test_human_and_llm_traces_share_schema_and_answer_keys():
+    # Both players commit "up" every turn under the same deterministic world,
+    # so cut frames and per-turn answer keys must be identical; only `model`
+    # differs. This is the human-baseline comparability foundation (spec §10).
+    human = HumanAgent(input_fn=_scripted(["up"] * 20), output_fn=lambda s: None)
+    h = SessionRunner(
+        "predator_evade", human, seed=42, play_turns=5, use_probe=False,
+    ).run()
+
+    llm = VanillaAgent(FakeProvider(["ACTION: up"]))
+    v = SessionRunner(
+        "predator_evade", llm, seed=42, play_turns=5, use_probe=False,
+    ).run()
+
+    assert h.cut_frames == v.cut_frames
+    assert [t.action for t in h.turns] == [t.action for t in v.turns]
+    assert [t.motive_action for t in h.turns] == [t.motive_action for t in v.turns]
+    assert [t.habit_action for t in h.turns] == [t.habit_action for t in v.turns]
+    assert h.outcome == v.outcome
+    assert set(h.metrics) == set(v.metrics)
+    assert h.model == "human"
+    assert v.model == "fake"
+```
+
+- [ ] **Step 2: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/runtime/test_human_comparability.py -q`
+Expected: PASS. (If it fails, the bug is real — investigate before proceeding; do NOT weaken the assertions.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/runtime/test_human_comparability.py
+git commit -m "test(cp5): lock human↔LLM trace comparability invariant (spec §10)"
+```
+
+---
+
+## Task 4: viz/reconstruct.py — deterministic frame reconstruction
+
+**Files:**
+- Create: `proteus/viz/__init__.py`
+- Create: `proteus/viz/reconstruct.py`
+- Test: `tests/viz/__init__.py` (empty), `tests/viz/test_reconstruct.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/viz/__init__.py` (empty file).
+
+Create `tests/viz/test_reconstruct.py`:
+```python
+import numpy as np
+import pytest
+
+from proteus.agents import VanillaAgent
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.scenario import get_scenario
+from proteus.providers import FakeProvider
+from proteus.runtime.session import SessionRunner
+from proteus.viz import FrameStep, TraceReconstructionError, reconstruct
+
+
+def _make_trace(seed=42, turns=5, action="ACTION: up"):
+    agent = VanillaAgent(FakeProvider([action]))
+    return SessionRunner(
+        "predator_evade", agent, seed=seed, play_turns=turns, use_probe=False,
+    ).run()
+
+
+def test_reconstruct_frame_count_matches_cut_plus_play():
+    trace = _make_trace()
+    steps = reconstruct(trace)
+    cut_len = get_scenario("predator_evade")().cut_length(Difficulty.EASY)
+    # initial Cut frame + cut_len Cut steps + one frame per played turn.
+    assert len(steps) == (cut_len + 1) + len(trace.turns)
+    assert all(isinstance(s, FrameStep) for s in steps)
+    assert isinstance(steps[0].frame, np.ndarray)
+
+
+def test_reconstruct_phases_and_terminal_flag():
+    trace = _make_trace()
+    steps = reconstruct(trace)
+    assert steps[0].meta.phase == "cut"
+    assert steps[-1].meta.phase == "play"
+    # The final frame carries the session outcome iff the game actually ended.
+    if trace.outcome in ("eliminated", "survived") and (
+        len(trace.turns) < 5 or trace.outcome == "survived"
+    ):
+        assert steps[-1].meta.terminal == trace.outcome
+
+
+def test_reconstruct_carries_turn_metadata():
+    trace = _make_trace()
+    steps = reconstruct(trace)
+    play = [s for s in steps if s.meta.phase == "play"]
+    assert len(play) == len(trace.turns)
+    first = play[0].meta
+    assert first.turn_idx == trace.turns[0].turn_idx
+    assert first.action == trace.turns[0].action
+    assert first.motive_action == trace.turns[0].motive_action
+    assert first.habit_action == trace.turns[0].habit_action
+
+
+def test_reconstruct_raises_on_corrupt_positions():
+    trace = _make_trace()
+    bad_turn = trace.turns[0].model_copy(update={"focal_pos": (99, 99)})
+    corrupt = trace.model_copy(update={"turns": [bad_turn] + list(trace.turns[1:])})
+    with pytest.raises(TraceReconstructionError):
+        reconstruct(corrupt)
+
+
+def test_reconstruct_raises_on_corrupt_cut_frame():
+    trace = _make_trace()
+    corrupt = trace.model_copy(
+        update={"cut_frames": ["GARBAGE"] + list(trace.cut_frames[1:])}
+    )
+    with pytest.raises(TraceReconstructionError):
+        reconstruct(corrupt)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_reconstruct.py -q`
+Expected: FAIL with `ModuleNotFoundError: No module named 'proteus.viz'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `proteus/viz/reconstruct.py`:
+```python
+"""Reconstruct a SessionTrace into a sequence of rendered frames.
+
+The trace stores ASCII + (focal_pos, predator_pos) per turn, not pixel frames
+(spec §7 keeps traces lean). But the world is fully deterministic from
+(scenario, seed, difficulty) + the recorded actions, so we rebuild the game and
+re-drive it, capturing the native palette grid at each step. Reconstruction is
+doubly self-verifying: every Cut frame's ASCII must equal the stored
+cut_frames, and the sprite positions BEFORE each played turn must equal the
+stored focal_pos / predator_pos. A mismatch means a corrupt or version-skewed
+trace and raises TraceReconstructionError immediately.
+
+The captured `frame` is the NATIVE-resolution palette grid (e.g. (8, 8) for an
+8x8 world) — small enough for terminal width, and upscaled on demand by the PNG
+renderer. This is the same array `ascii_view` consumes.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from proteus.grid.ascii_view import frame_to_ascii
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import get_scenario
+from proteus.runtime.trace import SessionTrace, TurnTrace
+
+
+class TraceReconstructionError(RuntimeError):
+    """Raised when a trace cannot be faithfully replayed (corrupt / version-skewed)."""
+
+
+@dataclass(frozen=True)
+class FrameMeta:
+    """Per-frame metadata shown alongside the rendered grid."""
+
+    phase: str  # "cut" or "play"
+    index: int  # step index within the whole sequence's phase (0-based for cut)
+    turn_idx: int = 0
+    action: str = ""
+    motive_action: str = ""
+    habit_action: str = ""
+    was_congruent: bool = False
+    is_diagnostic: bool = False
+    reward: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    thinking_tokens: int = 0
+    reasoning: str = ""
+    terminal: str = ""  # "" | "eliminated" | "survived" (set on the final frame)
+
+
+@dataclass(frozen=True)
+class FrameStep:
+    """A reconstructed frame plus its metadata."""
+
+    frame: np.ndarray  # native-resolution palette grid, shape (height, width)
+    meta: FrameMeta
+
+
+def reconstruct(trace: SessionTrace) -> list[FrameStep]:
+    """Replay a trace deterministically and return its frame sequence.
+
+    Raises:
+        TraceReconstructionError: if the rebuilt world diverges from the trace.
+    """
+    scenario = get_scenario(trace.scenario)()
+    difficulty = Difficulty(trace.difficulty)
+    rng = random.Random(trace.seed)
+    cut_length = scenario.cut_length(difficulty)
+    game = MotiveGridGame(
+        scenario, rng, difficulty, max_steps=cut_length + len(trace.turns),
+    )
+    legend = scenario.legend()
+
+    steps: list[FrameStep] = []
+
+    # --- Cut pre-roll (deterministic scripted policy). ---
+    steps.append(FrameStep(game.current_grid(), FrameMeta(phase="cut", index=0)))
+    _verify_cut(game, legend, trace, 0)
+    for i in range(cut_length):
+        action = scenario.cut_focal_policy(game)
+        game.apply_motive_action(action)
+        scenario.record_focal_move(action)
+        steps.append(
+            FrameStep(game.current_grid(), FrameMeta(phase="cut", index=i + 1))
+        )
+        _verify_cut(game, legend, trace, i + 1)
+
+    # --- Played turns (recorded actions). ---
+    last = trace.turns[-1] if trace.turns else None
+    for turn in trace.turns:
+        _verify_positions(game, turn)
+        game.apply_motive_action(turn.action)
+        scenario.record_focal_move(turn.action)
+        terminal = ""
+        if turn is last and (game.eliminated or game.survived):
+            terminal = trace.outcome
+        steps.append(
+            FrameStep(
+                game.current_grid(),
+                FrameMeta(
+                    phase="play",
+                    index=turn.turn_idx,
+                    turn_idx=turn.turn_idx,
+                    action=turn.action,
+                    motive_action=turn.motive_action,
+                    habit_action=turn.habit_action,
+                    was_congruent=turn.was_congruent,
+                    is_diagnostic=turn.is_diagnostic,
+                    reward=turn.reward,
+                    input_tokens=turn.input_tokens,
+                    output_tokens=turn.output_tokens,
+                    thinking_tokens=turn.thinking_tokens,
+                    reasoning=turn.reasoning,
+                    terminal=terminal,
+                ),
+            )
+        )
+    return steps
+
+
+def _verify_cut(
+    game: MotiveGridGame, legend: dict[int, str], trace: SessionTrace, idx: int
+) -> None:
+    if idx >= len(trace.cut_frames):
+        return
+    got = frame_to_ascii(game.current_grid(), legend)
+    if got != trace.cut_frames[idx]:
+        raise TraceReconstructionError(
+            f"Cut frame {idx} mismatch: reconstruction diverged from the trace "
+            "(corrupt or version-skewed scenario)."
+        )
+
+
+def _verify_positions(game: MotiveGridGame, turn: TurnTrace) -> None:
+    focal = game.focal_sprite
+    predator = game.predator_sprite
+    got_focal = (focal.x, focal.y) if focal else (-1, -1)
+    got_pred = (predator.x, predator.y) if predator else (-1, -1)
+    want_focal = tuple(turn.focal_pos)
+    want_pred = tuple(turn.predator_pos)
+    if got_focal != want_focal or got_pred != want_pred:
+        raise TraceReconstructionError(
+            f"Turn {turn.turn_idx} position mismatch: reconstructed "
+            f"focal={got_focal} predator={got_pred} vs trace "
+            f"focal={want_focal} predator={want_pred}."
+        )
+```
+
+Create `proteus/viz/__init__.py`:
+```python
+"""proteus.viz — human/debug visualization of a SessionTrace.
+
+Frames are reconstructed by deterministically replaying the trace through the
+real engine (reconstruct), then rendered to the terminal (truecolor + side
+panel) or to per-frame PNGs. matplotlib (the `viz` extra) is imported lazily by
+the PNG writer only, so importing this package stays offline-safe.
+"""
+
+from proteus.viz.reconstruct import (
+    FrameMeta,
+    FrameStep,
+    TraceReconstructionError,
+    reconstruct,
+)
+
+__all__ = [
+    "FrameMeta",
+    "FrameStep",
+    "TraceReconstructionError",
+    "reconstruct",
+]
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_reconstruct.py -q`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/viz/__init__.py proteus/viz/reconstruct.py tests/viz/__init__.py tests/viz/test_reconstruct.py
+git commit -m "feat(cp5): viz.reconstruct — deterministic frame replay with double self-verify"
+```
+
+---
+
+## Task 5: viz/terminal.py — truecolor grid + side panel
+
+**Files:**
+- Create: `proteus/viz/terminal.py`
+- Modify: `proteus/viz/__init__.py` (export `render_terminal`)
+- Test: `tests/viz/test_terminal.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/viz/test_terminal.py`:
+```python
+from proteus.agents import VanillaAgent
+from proteus.providers import FakeProvider
+from proteus.runtime.session import SessionRunner
+from proteus.viz import reconstruct, render_terminal
+
+
+def _steps():
+    agent = VanillaAgent(FakeProvider(["ACTION: up"]))
+    trace = SessionRunner(
+        "predator_evade", agent, seed=42, play_turns=4, use_probe=False,
+    ).run()
+    return reconstruct(trace), trace
+
+
+def test_render_terminal_emits_one_string_per_frame():
+    steps, _ = _steps()
+    buf = []
+    render_terminal(steps, fps=0, writer=buf.append, delay=0.0)
+    assert len(buf) == len(steps)
+
+
+def test_render_terminal_emits_truecolor_and_panel_fields():
+    steps, _ = _steps()
+    buf = []
+    render_terminal(steps, fps=0, writer=buf.append, delay=0.0)
+    joined = "\n".join(buf)
+    assert "\033[38;2;" in joined  # 24-bit truecolor escape
+    assert "action :" in joined
+    assert "motive :" in joined
+    assert "habit  :" in joined
+    assert "tokens :" in joined
+
+
+def test_render_terminal_does_not_sleep(monkeypatch):
+    steps, _ = _steps()
+    calls = []
+    monkeypatch.setattr("proteus.viz.terminal.time.sleep", lambda s: calls.append(s))
+    render_terminal(steps, fps=0, writer=lambda s: None, delay=0.0)
+    assert calls == []  # delay=0.0 -> never sleeps
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_terminal.py -q`
+Expected: FAIL with `ImportError: cannot import name 'render_terminal'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `proteus/viz/terminal.py`:
+```python
+"""Render reconstructed frames as truecolor terminal frames with a side panel.
+
+Reuses the vendored arc_grid palette (COLOR_MAP) and the rgb_to_ansi / hex_to_rgb
+helpers so the human-facing colors match the engine renderer. Each frame is drawn
+as 2-char colored blocks at native grid resolution (keeps it terminal-width) with
+a right-hand panel summarizing the turn — action / motive / habit / reward /
+tokens + a reasoning excerpt — built from the CP4.5 trace enrichment.
+
+Output goes through an injected writer so it can be captured in tests without a
+TTY; pass delay=0.0 (or fps=0) to disable inter-frame sleeping.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+from proteus.arc_grid.rendering import COLOR_MAP, hex_to_rgb, rgb_to_ansi
+from proteus.viz.reconstruct import FrameMeta, FrameStep
+
+_RESET = "\033[0m"
+_BLOCK = "██"
+_REASON_WIDTH = 60
+_REASON_MAX_LINES = 2
+
+
+def _reason_lines(reasoning: str) -> list[str]:
+    text = " ".join(reasoning.split())
+    if not text:
+        return []
+    chunks = [
+        text[i : i + _REASON_WIDTH] for i in range(0, len(text), _REASON_WIDTH)
+    ][:_REASON_MAX_LINES]
+    lines = [f"reason : {chunks[0]}"]
+    lines.extend(f"         {c}" for c in chunks[1:])
+    return lines
+
+
+def _panel_lines(meta: FrameMeta) -> list[str]:
+    if meta.phase == "cut":
+        return [f"Cut {meta.index}", "(scripted pre-roll)"]
+    head = f"Turn {meta.turn_idx}" + ("   [DIAGNOSTIC]" if meta.is_diagnostic else "")
+    mark = "✓ congruent" if meta.was_congruent else "✗ diverged"
+    lines = [
+        head,
+        f"action : {meta.action}    {mark}",
+        f"motive : {meta.motive_action}",
+        f"habit  : {meta.habit_action}",
+        f"reward : {meta.reward:+.1f}",
+        f"tokens : in{meta.input_tokens} out{meta.output_tokens} think{meta.thinking_tokens}",
+    ]
+    lines.extend(_reason_lines(meta.reasoning))
+    if meta.terminal:
+        lines.append(f">>> {meta.terminal.upper()}")
+    return lines
+
+
+def render_frame(step: FrameStep, color_map: Optional[dict[int, str]] = None) -> str:
+    """Return one frame as a multi-line truecolor string with its side panel."""
+    color_map = color_map or COLOR_MAP
+    grid = step.frame
+    height, width = grid.shape
+    panel = _panel_lines(step.meta)
+    lines: list[str] = []
+    for y in range(height):
+        parts = []
+        for x in range(width):
+            rgb = hex_to_rgb(color_map.get(int(grid[y, x]), "#000000FF"))
+            parts.append(f"{rgb_to_ansi(rgb)}{_BLOCK}{_RESET}")
+        row = "".join(parts)
+        side = panel[y] if y < len(panel) else ""
+        lines.append(f"{row}│ {side}" if side else f"{row}│")
+    pad = " " * (width * 2)
+    for k in range(height, len(panel)):
+        lines.append(f"{pad}│ {panel[k]}")
+    return "\n".join(lines)
+
+
+def render(
+    steps: list[FrameStep],
+    *,
+    fps: float = 4.0,
+    writer: Callable[[str], None] = print,
+    delay: Optional[float] = None,
+) -> None:
+    """Render each frame in order through `writer`, pacing with `fps`/`delay`."""
+    if delay is None:
+        delay = (1.0 / fps) if fps and fps > 0 else 0.0
+    for step in steps:
+        writer(render_frame(step))
+        if delay:
+            time.sleep(delay)
+```
+
+Modify `proteus/viz/__init__.py` to add the terminal export:
+```python
+from proteus.viz.reconstruct import (
+    FrameMeta,
+    FrameStep,
+    TraceReconstructionError,
+    reconstruct,
+)
+from proteus.viz.terminal import render as render_terminal
+
+__all__ = [
+    "FrameMeta",
+    "FrameStep",
+    "TraceReconstructionError",
+    "reconstruct",
+    "render_terminal",
+]
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_terminal.py -q`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/viz/terminal.py proteus/viz/__init__.py tests/viz/test_terminal.py
+git commit -m "feat(cp5): viz.terminal — truecolor block grid + CP4.5 side panel"
+```
+
+---
+
+## Task 6: viz/png.py — per-frame PNG (matplotlib Agg)
+
+**Files:**
+- Create: `proteus/viz/png.py`
+- Modify: `proteus/viz/__init__.py` (export `write_pngs`)
+- Test: `tests/viz/test_png.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/viz/test_png.py`:
+```python
+import pytest
+
+pytest.importorskip("matplotlib")  # PNG path needs the `viz` extra
+
+from proteus.agents import VanillaAgent
+from proteus.providers import FakeProvider
+from proteus.runtime.session import SessionRunner
+from proteus.viz import reconstruct, write_pngs
+
+
+def _steps():
+    agent = VanillaAgent(FakeProvider(["ACTION: up"]))
+    trace = SessionRunner(
+        "predator_evade", agent, seed=42, play_turns=4, use_probe=False,
+    ).run()
+    return reconstruct(trace)
+
+
+def test_write_pngs_one_nonempty_file_per_frame(tmp_path):
+    steps = _steps()
+    out_dir = tmp_path / "frames"
+    paths = write_pngs(steps, out_dir)
+    assert len(paths) == len(steps)
+    for p in paths:
+        assert p.exists()
+        assert p.stat().st_size > 0
+    # Files are zero-padded and ordered.
+    assert (out_dir / "frame_000.png").exists()
+
+
+def test_write_pngs_creates_missing_dir(tmp_path):
+    steps = _steps()
+    nested = tmp_path / "a" / "b" / "frames"
+    paths = write_pngs(steps, nested)
+    assert nested.is_dir()
+    assert len(paths) == len(steps)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_png.py -q`
+Expected: FAIL with `ImportError: cannot import name 'write_pngs'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `proteus/viz/png.py`:
+```python
+"""Write reconstructed frames as per-frame PNGs (headless, matplotlib Agg).
+
+Each frame is upscaled via the vendored frame_to_rgb_array and saved as
+frame_000.png, frame_001.png ... with a one-line title (turn + action). The rich
+side panel is a terminal feature; PNGs stay clean images with a label. matplotlib
+is the optional `viz` extra and is imported lazily so the offline core never
+needs it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from proteus.arc_grid.rendering import COLOR_MAP, frame_to_rgb_array
+from proteus.viz.reconstruct import FrameStep
+
+
+def _title(step: FrameStep) -> str:
+    meta = step.meta
+    if meta.phase == "cut":
+        return f"Cut {meta.index} (pre-roll)"
+    mark = "✓" if meta.was_congruent else "✗"
+    title = f"Turn {meta.turn_idx}: action={meta.action} {mark}"
+    if meta.terminal:
+        title += f"  [{meta.terminal}]"
+    return title
+
+
+def write_pngs(
+    steps: list[FrameStep],
+    out_dir: Union[str, Path],
+    *,
+    scale: int = 32,
+) -> list[Path]:
+    """Render every frame to `<out_dir>/frame_NNN.png`; return the paths in order."""
+    import matplotlib
+
+    matplotlib.use("Agg")  # headless: no window, no display required
+    import matplotlib.pyplot as plt
+
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    paths: list[Path] = []
+    for i, step in enumerate(steps):
+        rgb = frame_to_rgb_array(0, step.frame, scale, COLOR_MAP)
+        fig, ax = plt.subplots(figsize=(4.0, 4.4))
+        ax.imshow(rgb, interpolation="nearest")
+        ax.axis("off")
+        ax.set_title(_title(step), fontsize=9)
+        path = out_dir / f"frame_{i:03d}.png"
+        fig.savefig(path, dpi=100, bbox_inches="tight")
+        plt.close(fig)
+        paths.append(path)
+    return paths
+```
+
+Modify `proteus/viz/__init__.py` to add the PNG export:
+```python
+from proteus.viz.png import write_pngs
+from proteus.viz.reconstruct import (
+    FrameMeta,
+    FrameStep,
+    TraceReconstructionError,
+    reconstruct,
+)
+from proteus.viz.terminal import render as render_terminal
+
+__all__ = [
+    "FrameMeta",
+    "FrameStep",
+    "TraceReconstructionError",
+    "reconstruct",
+    "render_terminal",
+    "write_pngs",
+]
+```
+
+Note: `write_pngs` imports matplotlib lazily INSIDE the function, so `import proteus.viz` (and `__init__` importing `proteus.viz.png`) does NOT import matplotlib — only calling `write_pngs` does. The module-level `from proteus.viz.png import write_pngs` is safe because `png.py` has no top-level matplotlib import.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_png.py -q`
+Expected: PASS (2 tests). If matplotlib is missing, the file is skipped (importorskip) — but Task 0 installed it, so it should run.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/viz/png.py proteus/viz/__init__.py tests/viz/test_png.py
+git commit -m "feat(cp5): viz.png — per-frame titled PNGs via matplotlib Agg"
+```
+
+---
+
+## Task 7: viz package import-safety guard
+
+A tiny safety test: importing `proteus.viz` must NOT import matplotlib (offline invariant — matplotlib loads only when `write_pngs` is called).
+
+**Files:**
+- Test: `tests/viz/test_import_safety.py`
+
+- [ ] **Step 1: Write the test**
+
+Create `tests/viz/test_import_safety.py`:
+```python
+import sys
+
+
+def test_importing_viz_does_not_import_matplotlib():
+    # Drop any pre-loaded matplotlib so we observe a fresh import graph.
+    for name in list(sys.modules):
+        if name == "matplotlib" or name.startswith("matplotlib."):
+            del sys.modules[name]
+    for name in list(sys.modules):
+        if name == "proteus.viz" or name.startswith("proteus.viz."):
+            del sys.modules[name]
+
+    import proteus.viz  # noqa: F401
+
+    assert "matplotlib" not in sys.modules, (
+        "importing proteus.viz pulled in matplotlib; keep it lazy in write_pngs"
+    )
+```
+
+- [ ] **Step 2: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_import_safety.py -q`
+Expected: PASS. (If it FAILS, a top-level matplotlib import leaked into the viz package — move it back inside `write_pngs`.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/viz/test_import_safety.py
+git commit -m "test(cp5): guard viz package against eager matplotlib import"
+```
+
+---
+
+## Task 8: CLI — `play` subcommand
+
+**Files:**
+- Modify: `proteus/cli.py` (add `_cmd_play`, parser, import)
+- Test: `tests/cli/test_cli.py` (add)
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/cli/test_cli.py`:
+```python
+def test_play_human_writes_comparable_trace(tmp_path, monkeypatch, capsys):
+    # Feed scripted moves through builtins.input (HumanAgent resolves it lazily).
+    inputs = iter(["up"] * 20)
+    monkeypatch.setattr("builtins.input", lambda *a, **k: next(inputs))
+    out = tmp_path / "runs" / "human.jsonl"
+    rc = main([
+        "play",
+        "--scenario", "predator_evade",
+        "--seed", "42",
+        "--play-turns", "5",
+        "--out", str(out),
+    ])
+    assert rc == 0
+    traces = read_traces(out)
+    assert len(traces) == 1
+    assert traces[0].model == "human"
+    assert traces[0].scenario == "predator_evade"
+    # The run summary names the scenario.
+    assert "predator_evade" in capsys.readouterr().out
+
+
+def test_play_unknown_scenario_errors(capsys):
+    rc = main(["play", "--scenario", "nope", "--seed", "1", "--play-turns", "1"])
+    assert rc == 2
+    assert "Unknown scenario" in capsys.readouterr().err
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/cli/test_cli.py::test_play_human_writes_comparable_trace -q`
+Expected: FAIL — argparse exits because `play` is not a registered subcommand.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `proteus/cli.py`, add `HumanAgent` to the agents import near the top:
+```python
+from proteus.agents import HumanAgent, VanillaAgent
+```
+
+Add the command handler (place after `_cmd_run`):
+```python
+def _cmd_play(args: argparse.Namespace) -> int:
+    if args.scenario not in list_scenarios():
+        print(
+            f"Unknown scenario {args.scenario!r}. "
+            f"Available scenarios: {', '.join(list_scenarios())}.",
+            file=sys.stderr,
+        )
+        return 2
+    agent = HumanAgent()
+    runner = SessionRunner(
+        args.scenario,
+        agent,
+        difficulty=Difficulty(args.difficulty),
+        seed=args.seed,
+        play_turns=args.play_turns,
+        use_probe=args.probe,
+    )
+    trace = runner.run()
+    accuracy = trace.metrics["motive_reading_accuracy"]
+    print(
+        f"{trace.scenario} seed={trace.seed} {trace.difficulty} "
+        f"model={trace.model} -> {trace.outcome} "
+        f"| motive_reading_accuracy={accuracy:.1f}% "
+        f"| reactivity_index={trace.metrics['reactivity_index']:.1f}%"
+    )
+    if args.out:
+        written = append_trace(trace, args.out)
+        print(f"trace appended to {written}")
+    return 0
+```
+
+In `build_parser()`, add the `play` subparser (after the `run` subparser block):
+```python
+    play = sub.add_parser("play", help="play a session as a human via stdin")
+    play.add_argument("--scenario", default="predator_evade")
+    play.add_argument(
+        "--difficulty", default="easy", choices=[d.value for d in Difficulty]
+    )
+    play.add_argument("--seed", type=int, default=None)
+    play.add_argument("--play-turns", type=int, default=15, dest="play_turns")
+    play.add_argument(
+        "--probe",
+        action="store_true",
+        help="also ask the per-turn comprehension probe (default: off for humans)",
+    )
+    play.add_argument(
+        "--out", default=None, help="optional JSONL file to append the human trace to"
+    )
+    play.set_defaults(func=_cmd_play)
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/cli/test_cli.py -q`
+Expected: PASS (existing CLI tests + the two new `play` tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/cli.py tests/cli/test_cli.py
+git commit -m "feat(cp5): CLI 'play' subcommand — human session via stdin"
+```
+
+---
+
+## Task 9: CLI — `replay --visual / --png / --fps`
+
+**Files:**
+- Modify: `proteus/cli.py` (`_cmd_replay` + `replay` subparser)
+- Test: `tests/cli/test_cli.py` (add)
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/cli/test_cli.py`:
+```python
+def _write_fake_trace(tmp_path):
+    out = tmp_path / "r.jsonl"
+    main([
+        "run", "--scenario", "predator_evade", "--model", "fake:x",
+        "--seed", "42", "--play-turns", "4", "--no-probe", "--out", str(out),
+    ])
+    return out
+
+
+def test_replay_text_mode_unchanged(tmp_path, capsys):
+    out = _write_fake_trace(tmp_path)
+    capsys.readouterr()  # drain
+    rc = main(["replay", str(out)])
+    text = capsys.readouterr().out
+    assert rc == 0
+    assert "turn 1" in text  # legacy text behavior preserved
+
+
+def test_replay_visual_emits_truecolor(tmp_path, capsys):
+    out = _write_fake_trace(tmp_path)
+    capsys.readouterr()
+    rc = main(["replay", str(out), "--visual", "--fps", "0"])
+    text = capsys.readouterr().out
+    assert rc == 0
+    assert "\033[38;2;" in text  # truecolor escape present
+
+
+def test_replay_png_writes_frames(tmp_path, capsys):
+    import pytest
+
+    pytest.importorskip("matplotlib")
+    out = _write_fake_trace(tmp_path)
+    pdir = tmp_path / "png"
+    rc = main(["replay", str(out), "--png", str(pdir)])
+    assert rc == 0
+    frames = list(pdir.glob("frame_*.png"))
+    assert frames
+    assert all(p.stat().st_size > 0 for p in frames)
+    assert "PNG" in capsys.readouterr().out
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/cli/test_cli.py::test_replay_visual_emits_truecolor -q`
+Expected: FAIL — argparse rejects the unknown `--visual` flag.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `proteus/cli.py`, replace `_cmd_replay` with a version that branches to viz when `--visual`/`--png` is set (keep the existing text loop verbatim as the default branch):
+```python
+def _cmd_replay(args: argparse.Namespace) -> int:
+    try:
+        traces = read_traces(args.trace_file)
+    except FileNotFoundError:
+        print(f"trace file not found: {args.trace_file}", file=sys.stderr)
+        return 2
+    if not traces:
+        print(f"no traces in {args.trace_file}", file=sys.stderr)
+        return 1
+
+    if args.visual or args.png:
+        from proteus.viz import reconstruct, render_terminal, write_pngs
+
+        for trace in traces:
+            steps = reconstruct(trace)
+            if args.visual:
+                render_terminal(steps, fps=args.fps)
+            if args.png:
+                paths = write_pngs(steps, args.png)
+                print(f"wrote {len(paths)} PNG frames to {args.png}")
+        return 0
+
+    for trace in traces:
+        print(
+            f"=== {trace.scenario} seed={trace.seed} {trace.difficulty} "
+            f"model={trace.model} -> {trace.outcome} ==="
+        )
+        for turn in trace.turns:
+            tag = "congruent" if turn.was_congruent else "DIVERGED"
+            diag = " [diagnostic]" if turn.is_diagnostic else ""
+            print(
+                f"  turn {turn.turn_idx}: action={turn.action} "
+                f"motive={turn.motive_action} habit={turn.habit_action} "
+                f"{tag}{diag} reward={turn.reward}"
+            )
+        print(f"  metrics: {trace.metrics}")
+    return 0
+```
+
+In `build_parser()`, extend the `replay` subparser with the three flags (add after the existing `replay.add_argument("trace_file", ...)` line):
+```python
+    replay.add_argument(
+        "--visual", action="store_true", help="truecolor terminal replay"
+    )
+    replay.add_argument(
+        "--png", default=None, metavar="DIR",
+        help="also write per-frame PNGs to DIR (needs the 'viz' extra)",
+    )
+    replay.add_argument("--fps", type=float, default=4.0, help="replay frames/sec")
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/cli/test_cli.py -q`
+Expected: PASS (all CLI tests, including the three new replay tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/cli.py tests/cli/test_cli.py
+git commit -m "feat(cp5): CLI replay --visual/--png/--fps (text stays default)"
+```
+
+---
+
+## Task 10: Full-suite verification + acceptance demo
+
+This task runs the offline gate and the spec §11 acceptance demonstration (one human trace produced and compared against an LLM trace), then records results for the handoff.
+
+- [ ] **Step 1: Run the complete offline suite**
+
+Run:
+```bash
+.venv/bin/python -m pytest -q
+```
+Expected: ALL pass (the prior 75 + all CP5 additions), no network, no display window.
+
+- [ ] **Step 2: Generate an LLM (fake) trace and a human trace at the same seed**
+
+Run:
+```bash
+.venv/bin/python -m proteus run --scenario predator_evade --model fake:demo \
+  --seed 42 --play-turns 6 --no-probe --out runs/cp5_llm.jsonl
+printf 'up\nup\nup\nup\nup\nup\n' | .venv/bin/python -m proteus play \
+  --scenario predator_evade --seed 42 --play-turns 6 --out runs/cp5_human.jsonl
+```
+Expected: each command prints a summary line (`predator_evade seed=42 easy model=… -> … | motive_reading_accuracy=… | reactivity_index=…`) and appends one trace.
+
+- [ ] **Step 3: Verify the two traces are structurally comparable**
+
+Run:
+```bash
+.venv/bin/python -c "
+from proteus.runtime import read_traces
+h = read_traces('runs/cp5_human.jsonl')[0]
+l = read_traces('runs/cp5_llm.jsonl')[0]
+assert h.cut_frames == l.cut_frames, 'cut frames differ'
+assert [t.motive_action for t in h.turns] == [t.motive_action for t in l.turns], 'answer keys differ'
+assert h.model == 'human' and l.model == 'demo'
+print('OK comparable:', 'human', h.metrics.get('motive_reading_accuracy'), '| llm', l.metrics.get('motive_reading_accuracy'))
+"
+```
+Expected: prints `OK comparable: human <acc> | llm <acc>` with no assertion error.
+
+- [ ] **Step 4: Exercise the visual replay paths**
+
+Run:
+```bash
+.venv/bin/python -m proteus replay runs/cp5_human.jsonl --visual --fps 0
+.venv/bin/python -m proteus replay runs/cp5_human.jsonl --png runs/cp5_frames
+ls runs/cp5_frames/frame_000.png
+```
+Expected: the terminal shows a colored grid + side panel for each frame; `runs/cp5_frames/` contains `frame_000.png …`; the `ls` lists the first frame. (`runs/` is gitignored — these artifacts are not committed.)
+
+- [ ] **Step 5: Update HANDOFF.md (CP5 close) and the venv recreate command**
+
+Edit `HANDOFF.md`:
+- Move CP5 from "Next" to a new "Done (CP5)" section summarizing: `HumanAgent` (I/O-injected, same SessionRunner → comparable human trace), `proteus/viz/` (reconstruct + terminal + png), CLI `play` + `replay --visual/--png/--fps`, and the acceptance demo result from Step 3.
+- Update the `.venv` recreate command to append `"matplotlib>=3.8"` (now required by the viz/png tests).
+- Set "Next" to CP6 (difficulty layouts + metric refinement + human-baseline harness).
+- Under "Open questions", add the deferred **probe-vs-act-reasoning redundancy** review (spec change, out of CP5) and **optional live-color human play**.
+
+Then commit:
+```bash
+git add HANDOFF.md
+git commit -m "docs(cp5): handoff close — human play + trace viz shipped; CP6 next"
+```
+
+---
+
+## Self-Review (completed by plan author)
+
+**Spec coverage:**
+- §1 휴먼 플레이 → Tasks 1, 2, 3, 8. §1 시각화 → Tasks 4, 5, 6, 9.
+- §2 모듈 배치 (human.py, viz/reconstruct|terminal|png, cli) → Tasks 1–9. Dependency direction (viz leaf; SessionRunner untouched; arc_grid/trace unchanged) honored.
+- §3 HumanAgent (act/probe/reset, I/O injection, name="human", ASCII live view, Ctrl-C abort) → Tasks 1, 2 (Ctrl-C is the natural default — no quit action coded, as designed).
+- §4.1 reconstruct + double self-verify → Task 4. §4.2 terminal + side panel → Task 5. §4.3 png Agg titled → Task 6.
+- §5 CLI (play + replay flags) → Tasks 8, 9.
+- §6 tests (all offline/headless) → every task is TDD; matplotlib guarded by importorskip + Task 7 import-safety.
+- §7 invariants (offline, Agg-only-on-png, no SessionRunner edit) → Task 0 + Task 7 + Task 9 lazy import.
+- §8 완료 기준 → Task 10 (full suite + human/LLM comparison demo + visual/png).
+
+**Placeholder scan:** No TBD/TODO; every code step shows complete code; every command shows expected output.
+
+**Type consistency:** `FrameStep(frame, meta)` / `FrameMeta` fields are defined in Task 4 and consumed identically in Tasks 5 (`render_frame`/`_panel_lines`) and 6 (`_title`). `reconstruct`, `render_terminal` (exported alias of `terminal.render`), `write_pngs`, `TraceReconstructionError` names are consistent across `viz/__init__.py` and all consumers. `HumanAgent(input_fn, output_fn)` signature is consistent between Tasks 1/2 and the CLI default-construction in Task 8. `ActResult`/`ProbeResult` token fields default to 0 (verified against `agents/base.py`).