HANDOFF.md

# PROTEUS — Handoff

> Living handoff record. Updated at each checkpoint close. SSOT trio:
> `docs/superpowers/specs/2026-06-01-proteus-arena-slice-design.md` (immutable design) +
> the per-CP plan in `docs/superpowers/plans/` + this file.

**Last updated:** 2026-06-02 — two parallel slices shipped: **`pack_evade`** scenario (64×64 open-field
multi-cell evasion + persona weight-vector handover memory) and web **LLM spectating** (watch an LLM
play the color grid with live reasoning/analysis + pause/step; `SpectateSession` pinned to
`SessionRunner(VanillaAgent)` by a golden test; providers lazy-imported so offline import-safety holds).
Both built in isolated worktrees and merged clean. Before them: CP7/CP8 (LLM-generated memory pre-roll +
persona agentness eval) and Web interactive color-grid play; offline, headless. CP6 before that
(difficulty layouts + category eval + `compare`).

## Restructure (2026-06-02): game/web layout

The `proteus/` package was reorganised into a cleaner layout with **zero logic change** — 253 tests remain green. The top-level sub-packages are now: `game/` (engine, scenarios, agents, runtime, metrics, viz), `web/` (local server + arena skeleton), `shared/` (utilities), `cli/` (parser + per-command modules), and the unchanged `providers/`. Docs: design/SSOT at `docs/superpowers/specs/2026-06-02-proteus-game-web-restructure-design.md`; implementation plan at `docs/superpowers/plans/2026-06-02-proteus-game-web-restructure.md`.

| Old path / import | New path / import |
|---|---|
| `proteus/grid/game.py` | `proteus/game/engine/grid.py` |
| `proteus/grid/scenario.py` | `proteus/game/scenarios/base.py` |
| `proteus/grid/scenarios/<x>.py` | `proteus/game/scenarios/<x>.py` |
| `proteus/grid/difficulty.py` | `proteus/game/engine/difficulty.py` |
| `proteus/grid/ascii_view.py` | `proteus/game/engine/ascii_view.py` |
| `import proteus.grid` (registry side-effect) | `import proteus.game.scenarios` |
| `proteus/arc_grid/` / `proteus.arc_grid.*` | `proteus/game/engine/` / `proteus.game.engine.*` (vendored engine at `proteus/game/engine/arcengine/`) |
| `proteus/runtime/metrics.py` | `proteus/game/metrics/metrics.py` |
| `proteus/runtime/persona.py` | `proteus/game/metrics/persona.py` |
| `proteus/runtime/rollout.py` | `proteus/game/metrics/rollout.py` |
| `proteus/runtime/aggregate.py` | `proteus/game/metrics/aggregate.py` |
| `proteus/runtime/<other>.py` (session, _session_core, interactive, spectate, trace, io, memory, memory_gen, memory_policies) | `proteus/game/runtime/<x>.py` |
| `proteus/agents/<x>.py` | `proteus/game/agents/<x>.py` |
| `proteus/viz/<x>.py` / `proteus.viz` | `proteus/game/viz/<x>.py` |
| `proteus/web/server.py` | `proteus/web/local/server.py` |
| `proteus/web/static/index.html` | `proteus/web/local/static/index.html` |
| `import proteus.web.server` | `import proteus.web.local.server` |
| `python -m proteus.web` | `python -m proteus.web.local` (old command still works via a shim) |
| `proteus/cli.py` | `proteus/cli/` package (`cli/__init__.py`, `cli/parser.py`, `cli/commands/{run,play,memory,replay,compare,list_scenarios}.py`) |

## Done (CP0–CP3)

- **CP0** — `proteus` package skeleton + `pyproject.toml` (hatchling, pydantic/numpy/pyyaml,
  pytest config); `arc_grid` vendored **byte-for-byte** into `proteus/game/engine/arcengine/` (verified
  `diff -r` empty; firewall holds — zero `squid_game`/`proteus` cross-imports inside it).
- **CP1** — `grid` family ported with `squid_game.* → proteus.*` renames only: `difficulty`,
  `scenario` (ABC + registry), `game` (`MotiveGridGame`), `ascii_view`, `scenarios/predator_evade`.
  Registry self-populates on `import proteus.game.scenarios`. Acceptance gate locked: deterministic EASY
  handover (`focal (3,3) / predator (5,3)`) and the diagnostic invariant `optimal "up" ≠ habit "left"`.
- **CP2** — slim `Agent` ABC + frozen `ActResult`; `extract_action` parser; `VanillaAgent`
  (act + optional probe, reasoning via `parse_thinking_tags`); providers `base` +
  `thinking_utils` (pure ports) + new `FakeProvider` (scripted, offline).
- **CP3** — lean pydantic `TurnTrace`/`SessionTrace` (`outcome` is `Literal["survived","eliminated"]`);
  `compute_metrics`; `SessionRunner` orchestrator (Cut replay → handover → N-turn play →
  scored `SessionTrace`). Full offline end-to-end with JSON(L) round-trip.

## Done (CP4 — real-provider CLI; plan: `docs/superpowers/plans/2026-06-01-proteus-arena-cli.md`)

- **Provider factory** (`proteus/providers/factory.py`) — `make_provider("name:model")` +
  `available_providers()`. **Lazy** string registry `(module_path, class_name)`: importing
  `proteus.providers` or building a `FakeProvider` never imports an SDK (offline invariant holds).
  `fake:<model>` → offline `FakeProvider`; `partition(":")` so model ids with `:` (ollama) survive.
- **Cloud providers ported** (openai / anthropic_provider / gemini / ollama_cloud) by import-rename
  ONLY (`squid_game.* → proteus.*`); verified by file-text tests (SDKs not installed offline).
  Class names match the registry. local/mlx/cuda providers **not ported** (deferred — need a local
  server / Apple-silicon / CUDA; off the CP4 "one cheap model" gate).
- **JSONL trace I/O** (`proteus/game/runtime/io.py`) — `append_trace` / `read_traces` (one SessionTrace
  per line; creates parent dirs; skips blank lines).
- **CLI** (`proteus/cli/` package, `proteus/__main__.py`) — `run` / `list-scenarios` / `replay`.
  `run` validates `--model` (unknown → stderr+exit 2) AND `--scenario` (unknown → stderr+exit 2,
  before any session runs); `replay` prints per-turn action vs motive/habit + metrics. `python -m proteus`.

### Real-model smoke (CP4 acceptance gate — passed)

- **Model:** `ollama:gpt-oss:120b-cloud` (Ollama Cloud, native `/api/chat`). seed 42 / easy /
  play-turns 10 / probe on.
- **Outcome:** `survived | motive_reading_accuracy=70.0% | reactivity_index=75.0%`
  (survival_fraction 100%, first_divergence_turn 3). Real reasoning captured (3.9k–13.5k chars/turn).
  Confirms the full chain CLI→agent→OllamaCloudProvider→ollama.com and the lazy-imported port.
- **How it was run (repeatable):** `.venv` is kept **SDK-free**. A throwaway venv at
  `/tmp/proteus-smoke-venv` (only `pydantic numpy pyyaml httpx` — ollama needs just `httpx`) is run with
  `PYTHONPATH=<repo> /tmp/proteus-smoke-venv/bin/python -m proteus run --model ollama:gpt-oss:120b-cloud ...`.
  `runs/` and `.env` are gitignored (trace + key never committed).
- **Key gotcha (carry forward):** the `.env` `OLLAMA_API_KEY` value has a leading space + trailing
  extra tokens; the *real* key is the **first whitespace-delimited token** (57 chars). Passing the
  whole value → 401. The smoke extracts `... | awk '{print $1}'`. Cleaning the `.env` line (key only)
  would remove the need for that. `OLLAMA_API_KEY2` exists but is **not authorized** for use.

## Done (CP4.5 — per-turn LLM-response accounting; no separate plan, executed in-session)

Motivation: the smoke surfaced that token accounting and raw text were dropped (`thinking_tokens=0`
every turn, no `raw_text`). Fixed via TDD 3-gate, all ADDITIVE except the probe return-type change:

- **Act path** (`1c18fa9`): `ActResult` gains `input_tokens/output_tokens/thinking_tokens`;
  `VanillaAgent.act()` propagates them from `CompletionResult` with
  `thinking_tokens = result.thinking_tokens or <inline-think parser count>` (provider count preferred).
  `TurnTrace` gains `raw_text/input_tokens/output_tokens` (its `thinking_tokens` field is now populated);
  `SessionRunner.run()` wires them.
- **Probe path** (`f95852b`): new frozen `ProbeResult(answer, reasoning, raw_text, input/output/thinking
  tokens)`; `Agent.probe` returns it (was `str`); `TurnTrace` gains `probe_reasoning/probe_raw_text/
  probe_{input,output,thinking}_tokens`; `SessionRunner` wires them (`probe_a = probe.answer`).
  Probe `reasoning` falls back to `""` (not the answer — a probe answer is not its own reasoning).
  A regression test proves probe-side and act-side token fields are **not cross-wired** (probe=3, act=5).

## Done (CP5 — human play + trace visualization; plan: `docs/superpowers/plans/2026-06-01-proteus-arena-viz-humanplay.md`)

Executed task-by-task via subagent-driven-development (3-gate: implement → spec review → code-quality review). All offline/headless; no network, no display, no provider SDK added.

- **`HumanAgent`** (`proteus/game/agents/human.py`, Tasks 1–2) — implements the `Agent` ABC with **I/O
  injection** (`input_fn`/`output_fn`, resolved from `builtins` at construction so tests drive it
  headlessly). `act` parses canonical actions + WASD shortcuts (`w/a/s/d`), is case/whitespace-
  insensitive, re-prompts on invalid input; `probe` returns a typed `ProbeResult`; `name="human"`.
  Routed through the **unmodified** `SessionRunner`, so a human trace is schema- AND value-identical
  to an LLM trace under the same actions (only `model` differs). Locked by
  `tests/runtime/test_human_comparability.py` (Task 3, spec §10).
- **`proteus/game/viz/`** (Tasks 4–6) — `reconstruct.py` rebuilds pixel frames by **deterministically
  replaying** the trace through the real engine (`scenario, seed, difficulty` + recorded actions),
  with **double self-verify** (every Cut frame's ASCII == stored `cut_frames`; sprite positions before
  each turn == stored `focal_pos/predator_pos`) → raises `TraceReconstructionError` on any divergence.
  `terminal.py` renders truecolor (24-bit ANSI) block grids + a side panel (action/motive/habit/reward/
  tokens + reasoning excerpt, from the CP4.5 enrichment). `png.py` writes per-frame `frame_NNN.png` via
  matplotlib **Agg** (imported **lazily** inside `write_pngs`).
- **CLI** (Tasks 8–9) — `play` subcommand (human via stdin; **probe OFF by default**, opt-in `--probe`;
  optional `--out`) + `replay --visual/--png DIR/--fps` (text replay stays the **default**, CP4
  non-destructive; viz imported lazily only when a visual flag is set).
- **Offline import invariant made real** (Task 7, user-approved root-cause fix): `proteus/game/engine/arcengine/
  rendering.py`'s top-level `try: import matplotlib` was moved **lazily inside `render_frames`**, so
  importing the engine / `proteus.game.viz` no longer pulls matplotlib in ANY ordering. `tests/viz/
  test_import_safety.py` guards it. (This intentionally diverges from the untracked top-level `arc_grid/`
  vendored copy — that copy is not on the import path.)

### CP5 acceptance demo (passed)

- **Full suite:** `.venv/bin/python -m pytest -q` → **103 passed**, offline, no display.
- **Comparability:** human (`runs/cp5_human.jsonl`) and fake-LLM (`runs/cp5_llm.jsonl`) at seed 42 /
  play-turns 6, **both committing the same action** (CLI `fake:` emits `ACTION: stay`, so the human was
  driven with `stay` to match) → **identical** `cut_frames`, per-turn `action`, and `motive_action`
  answer keys (`['up','up']`); differ only in `model` (`human` vs `demo`). NOTE: the plan's demo drove
  the human with `up` vs a `stay`-playing fake LLM — that necessarily diverges (different actions →
  different world), so the demo was corrected to use a matching action; the comparability **invariant**
  itself (identical actions → identical trace) is unchanged and unit-tested.
- **Visual:** `replay --visual --fps 0` renders the truecolor grid + side panel; `replay --png
  runs/cp5_frames` wrote **5 non-zero** `frame_*.png` (cut_length 2 + 1 initial + 2 play turns).

## Done (CP6 — difficulty layouts + category eval + human-baseline harness; plan: `docs/superpowers/plans/2026-06-02-proteus-cp6-difficulty-eval-baseline.md`; design: `docs/superpowers/specs/2026-06-02-proteus-cp6-difficulty-eval-baseline-design.md`)

Executed task-by-task via subagent-driven-development (3-gate: implement → spec review → code-quality review). All offline/headless; no network, no display, no provider SDK added. **Full suite: 127 passed** (103 CP5 baseline + 24 CP6 additions).

- **Section A — difficulty layouts** (Tasks 1–3): `Scenario.build_level(rng, difficulty)` now takes the band; `record_focal_move`/`safety_distance` promoted to concrete defaults on the `Scenario` ABC (resolves a CP5 deferred item). `predator_evade` dispatches a **hand-authored per-difficulty layout table** (`_Layout` dataclass + `_LAYOUTS`): EASY 8×8 (byte-for-byte unchanged), MEDIUM 10×10, HARD 12×12 (L-trap), EXPERT 12×12 (forked corridor). `build_level` sets the **instance** attr `self.grid_size` so the camera/`within_bounds` size per-band. Golden test `tests/grid/test_difficulty_layouts.py` is the oracle: per band it locks determinism + the handover + the diagnostic invariant `optimal_action != habit_action` with `habit == "left"` blocked. Candidate coordinates satisfied the invariant with **no tuning** (all four bands: optimal=`up` ≠ habit=`left`). `rules_text` de-hard-coded ("8x8 grid" → "a grid") so it no longer lies on the larger bands.
- **Section B — category-specific eval** (Tasks 4–6): per-turn reward **ownership moved into the scenario**. New abstract `Scenario.step_reward(game, action, blocked, focal_before, predator_before)`; `SessionRunner._reward` + its 5 constants **deleted** (delegates now). predator_evade survival reward = BFS-distance gain measured against the predator's **pre-move** cell (away→positive `float(d_after − d_before)`, toward→negative, wall-hit→`−3.0`, terminal `−50/+50`), isolating the agent's own move from the chase. New `proteus/game/metrics/rollout.py` `optimal_rollout(...)` (engine-replay, same pattern as `game/viz/reconstruct`, imports `game.scenarios` only). `metrics.py` gains four additive keys: **`away_move_fraction`** (survival headline), `mean_step_reward`, `trajectory_agreement` (vs the optimal rollout, denominator = all played turns), `final_distance_gap`. Existing four metrics retained; `test_human_comparability`'s `set(h.metrics)==set(v.metrics)` still holds.
- **Section C — human-baseline harness** (Tasks 7–8): pure `proteus/game/metrics/aggregate.py` `aggregate_traces(traces) → {(model, difficulty): {"n", "metrics": means}}` (no I/O, union-of-keys robust). New CLI `proteus compare <trace.jsonl>… [--out summary.json]` (rc 2 not-found / rc 1 empty / rc 0, mirrors `replay`; JSON keys stringified `"model|difficulty"`).

### CP6 acceptance demo (passed)

- **Full suite:** `.venv/bin/python -m pytest -q` → **127 passed**, offline, no display.
- **Per-difficulty smoke:** `proteus run … --difficulty {easy,medium,hard,expert} --model fake:demo --seed 42 --play-turns 6 --no-probe` then `proteus compare …` → four `model=demo difficulty=<band> n=1` groups, each with the 8 metric means (incl. `away_move_fraction`/`trajectory_agreement`/`final_distance_gap`), summary written to `runs/cp6_summary.json`. Values differ by band (e.g. EXPERT `trajectory_agreement=66.67`, `survival_fraction=50.0` vs others `50.0`/`33.33`), confirming the layouts/metrics are genuinely band-sensitive.
- **Invariant acceptance:** all four bands print `optimal=up habit=left` with distinct grids `(8,8)/(10,10)/(12,12)/(12,12)` — `optimal != habit` everywhere.
- **Note:** the `fake:demo` provider plays a fixed non-optimal action (so `motive_reading_accuracy=0`); the smoke validates the deterministic pipeline + metric surfacing, not agent skill.

## Done (Web interactive play — color-grid browser arena; plan: `docs/superpowers/plans/2026-06-02-proteus-web-interactive-play.md`; design: `docs/superpowers/specs/2026-06-02-proteus-web-interactive-play-design.md`)

Executed task-by-task via subagent-driven-development (implement → spec review → code-quality review per task). The web slice alone was **149 passed** (127 CP6 baseline + 22 new web/runtime tests); after merging with the concurrent CP7/CP8 work the **combined suite is 193 passed**. Merge reconciliation: the `SessionRunner`→`_session_core` delegation refactor was kept as the basis and CP7 memory + CP8 persona were threaded through the shared helpers, so both `SessionRunner` and `InteractiveSession` (and thus web play) now emit CP8-rich traces from one source of truth.

- **Stdlib-only color-grid web play** — launch with `python -m proteus.web.local` (`--host`/`--port`, defaults to `127.0.0.1:8000`; `python -m proteus.web` still works via a shim). A single static `index.html` (vanilla JS, no build, no CDN) renders the engine's integer grids in color via `proteus.game.engine.rendering.COLOR_MAP`. **Zero new dependencies** — the `.venv` stays SDK-free/offline.
- **Shared session core** — extracted `SessionRunner`'s per-session mechanics into `proteus/game/runtime/_session_core.py` (pure refactor, no behavior change — the existing tests stayed green at the same count). Both `SessionRunner` and the new `InteractiveSession` build their traces from these same helpers.
- **`InteractiveSession`** (`proteus/game/runtime/interactive.py`) — a threadless, stepwise driver (`state()`/`step()`/`finish()`) that advances one turn per HTTP request. It is pinned to `SessionRunner(HumanAgent)` by a **golden equivalence test** (`tests/runtime/test_interactive_equivalence.py`) asserting full `model_dump()` equality for the same action sequence — the two paths cannot drift.
- **Fairness split** (carried from CP5) — the live `state` exposes only the color grid + available actions (no reward/optimal/habit), exactly what the LLM sees; the full per-turn disclosure (your action vs optimal vs habit, reward, 8 metrics) appears in `review` only once the game is over. Asserted in both the `InteractiveSession` and server tests.
- **Always-saved trace** — every finished game appends a `runs/web_<scenario>_<difficulty>.jsonl` line (override via the `/finish` `{out}` body) that is schema-identical to LLM/CLI traces. Verified end-to-end: a web-produced trace is accepted by both `proteus replay` and `proteus compare` (shows up as a `model=human` baseline group).
- **HTTP API** (stdlib `http.server`) — `GET /` (page), `GET /config`, `POST /session`, `GET /session/{id}`, `POST /session/{id}/act`, `POST /session/{id}/finish`; a pure socket-free `handle_request(...)` router (unit-tested without a socket) + in-memory registry; structured errors (400/404/409/500); offline import-safety guarded (`tests/web/test_import_safety.py`).

## Done (Web LLM spectating — watch an LLM play in color; plan: `docs/superpowers/plans/2026-06-02-proteus-web-spectate.md`; design: `docs/superpowers/specs/2026-06-02-proteus-web-spectate-design.md`)

Executed task-by-task via subagent-driven-development (TDD, commit-per-task). **Full suite: 202 passed** (193 baseline + 9 new spectate tests), offline, no display, no provider SDK added. A person can now **watch an LLM play the arena in the browser**: the color grid auto-advances turn by turn while a live panel shows the model's reasoning plus the per-turn optimal/habit/reward (rich disclosure — a spectator is not the scored subject), with **pause / step** controls.

- **`SpectateSession`** (`proteus/game/runtime/spectate.py`) — a threadless, **agent-driven** sibling of `InteractiveSession`. `state()`/`advance()`/`finish()` over the shared `_session_core`; the server (not a human) supplies each action by calling `agent.act(...)` once per HTTP request. It reads `default_memory` via `getattr(built, "default_memory", None)` (forward-compatible with pack_evade) and passes `memory=` to `build_observation`. It is pinned to `SessionRunner(VanillaAgent(same FakeProvider))` by a **golden equivalence test** (`tests/runtime/test_spectate_equivalence.py`) asserting full `model_dump()` equality — the spectate path cannot drift from the runner path.
- **HTTP API** — `POST /spectate`, `POST /spectate/{id}/next`, `POST /spectate/{id}/finish`, `GET /spectate/{id}`; `/config` now also returns `providers` + `default_model` (`fake:demo`). Providers/agents are **lazy-imported inside the create handler** (`available_providers` locally in `_config_payload`), so `import proteus.web.local.server` still pulls no provider SDK — the offline import-safety guard is extended and stays green. Structured errors: unknown model → 400, advance-after-done → 409, provider failure → 500 (no stack leak).
- **Frontend** (`proteus/web/local/static/index.html`) — a Play/Spectate mode toggle + model input; in spectate mode the human pad/keys go inert, a live analysis panel renders the model's reasoning + a per-turn table (turn/action/optimal/habit/reward/=opt?), and an auto-play loop drives `/next` with **Pause/Resume** and **Step**. On end it shows SURVIVED/ELIMINATED and the saved trace path.
- **Trace** — spectated runs save a `proteus compare`-compatible LLM-baseline trace (`runs/web_spectate_*.jsonl` by default) accepted by `proteus replay` / `proteus compare` as a `model=<provider model>` group (verified e2e with `fake:demo`).

## How to run

- Environment: `python` is **not** on PATH; a gitignored venv lives at `.venv` (Python 3.12,
  pydantic v2 / numpy / pyyaml / pytest **+ matplotlib** — the latter now required by the viz/png
  tests). **Full suite:** `.venv/bin/python -m pytest -q` → **148 passed**, no network, no display.
  Provider SDKs are NOT installed in `.venv` (keeps the offline invariant structural); matplotlib runs
  **Agg-only** (headless), so it does not break the offline/no-display invariant. Recreate `.venv` with:
  `uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python "pydantic>=2" "numpy>=1.26" "pyyaml>=6" "pytest>=8" "matplotlib>=3.8"`
- Human play (offline): `printf 'up\nup\n...' | .venv/bin/python -m proteus play --scenario
  predator_evade --seed 42 --play-turns 6 --out runs/h.jsonl` (live view is the same ASCII the LLM sees).
- Visual replay: `.venv/bin/python -m proteus replay runs/h.jsonl --visual --fps 0` (truecolor terminal)
  or `--png runs/frames` (per-frame PNGs). Plain `replay runs/h.jsonl` stays text-only.
- Web interactive play (offline, stdlib-only): `.venv/bin/python -m proteus.web.local` (`--host`/`--port`,
  defaults `127.0.0.1:8000`), then open the printed `http://127.0.0.1:8000/` — play the color grid in the
  browser; the finished game appends a schema-identical trace to `runs/web_<scenario>_<difficulty>.jsonl`
  (replayable/comparable with `proteus replay`/`compare`). Zero new dependencies.
- Offline CLI smoke: `.venv/bin/python -m proteus run --scenario predator_evade --model fake:demo
  --seed 42 --play-turns 5 --out runs/x.jsonl && .venv/bin/python -m proteus replay runs/x.jsonl`
- Difficulty bands: add `--difficulty {easy,medium,hard,expert}` to `run`/`play` (EASY is the default,
  byte-for-byte the CP0–CP5 world). Human-baseline compare: collect matched human (`play --out`) and LLM
  (`run --out`) traces, then `.venv/bin/python -m proteus compare h.jsonl llm.jsonl --out summary.json`
  → per-`(model, difficulty)` metric means + n (the `model` token is the part AFTER the colon, e.g.
  `fake:demo` → `demo`).
- Memory pre-roll (CP7): generate a checkpoint then reuse it —
  `.venv/bin/python -m proteus memory --scenario predator_evade --model fake:demo --seed 42 --memory-turns 8`
  writes `runs/memory/<model>/<stamp>.json`; `proteus run … --memory latest` (or `--memory generate` to do
  both in one shot, `--memory <path>` for a specific file, default `none`) injects it at the handover.
  `runs/memory/` is gitignored. Korean usage guide: `docs/USAGE-ko.md`.
- Real-model smoke: see the throwaway-venv recipe above (needs a provider SDK + key; never in `.venv`).

## Current state

A scored `SessionTrace` is produced offline (FakeProvider) AND against real cloud models via the CLI;
each turn persists full act + probe accounting to `runs/*.jsonl`. Single scenario only: `predator_evade`
(survival motive). **Human play and trace visualization now exist** (CP5): `proteus play` runs a human
through the same `SessionRunner` (comparable trace), and `proteus replay --visual/--png` renders any
trace as truecolor terminal frames or PNGs by deterministically replaying the engine. `proteus replay`
with no flags still prints TEXT (CP4 behavior preserved). `proteus/game/engine/arcengine/rendering.py` is now actively
reused (palette + ANSI + RGB helpers) and its matplotlib import is lazy.

**CP6 adds:** four genuinely distinct hand-authored difficulty layouts (EASY unchanged), scenario-owned
category-specific reward (`step_reward`; survival = reward for moving away from the predator), an
optimal-rollout trajectory metric (`game/metrics/rollout.py`) + four new metric keys, and a `proteus compare`
human-baseline aggregation CLI. Still a single scenario (`predator_evade`, survival motive) — the
`step_reward`/`safety_distance` ABC surface is now **open** for CP7 to plug new motive categories in
without touching `SessionRunner`.

## Done (CP7 — LLM-generated memory pre-roll; design: `docs/superpowers/specs/2026-06-02-proteus-cp7-memory-preroll-design.md`; plan: `docs/superpowers/plans/2026-06-02-proteus-cp7-memory-preroll.md`)

Executed inline (executing-plans, TDD, commit-per-task). **Full suite: 152 passed** (127 baseline + 25
CP7), offline/headless; no provider SDK added to `.venv`. The original "CP7 = new motive category" idea
was **renamed to CP8** when the user pivoted to this memory feature; curiosity/sociality stay deferred.

- **Stage 1 — `game/runtime/memory.py`** (pure pydantic + stdlib, no intra-runtime imports, like `trace.py`):
  `MemoryTurn`/`MemoryCheckpoint` models; `save_checkpoint`/`load_checkpoint` (single-file JSON at
  `runs/memory/<safe(model)>/<stamp>.json`); `latest_for_model` (lexical stamp = chronological);
  `render_memory_block` (pure observation renderer). Exported from `game/runtime/__init__`.
- **Stage 2 — `game/runtime/memory_gen.py`** (engine-coupled, like `game/metrics/rollout.py`): `generate_memory(scenario,
  agent, *, difficulty, seed, memory_turns, model_name, clock)` runs a **full-info self-play** episode
  (`max_steps=memory_turns`, no scripted Cut, no answer-key leakage), capturing frames/actions/reasoning
  → `MemoryCheckpoint`. Deterministic under an injected `clock`. New scenario-sourced `Scenario.memory_brief`
  (concrete attr default `""`); `predator_evade` sets a transparent brief (discloses the BFS chase). This
  resolves the **memory-prompt** half of the old "source prompts from Scenario" item; the
  `_PROBE_QUESTION`/`_ACTION_DIRECTIVE` predator-framing is still hard-coded (carried to CP8).
- **Stage 3 — hybrid handover** (`trace.py` + `session.py`): additive `SessionTrace.memory_ref: str | None`;
  `SessionRunner(..., memory=None, memory_ref=None)` prepends the memory block (+ `NOW — this run so far:`)
  to the **turn-1** observation only, **before** the unchanged scripted Cut. `step_reward`, answer keys,
  metrics, and `_session_core.py` untouched → diagnostic invariant + 127 preserved (pinned by
  `test_session_memory.py`: with/without memory the per-turn `motive_action`/`habit_action`/`is_diagnostic`
  and `metrics` are identical; only the turn-1 observation grows).
- **Stage 4 — CLI** (`proteus/cli/` package): `proteus memory` (generate+save a checkpoint) and `proteus run --memory
  MODE` where `MODE ∈ {none(default), generate, latest, <path>}` via a `_resolve_memory` helper. `--memory-turns`
  (default 10) and `--memory-root` (default `runs/memory`) on both. Exit codes mirror `run` (unknown
  model/scenario → 2; `latest` with no checkpoint → 2).

### CP7 acceptance smoke (passed)

- **Offline end-to-end:** `proteus memory … fake:demo` → `proteus run … --memory latest` → the turn-1
  observation carries the `MEMORY` block + `NOW` separator + scripted `Cut 1/2:` in order; `memory_ref` set.
- **Ollama (networked, manual):** `ollama:gpt-oss:120b-cloud`, seed 42 / easy. `proteus memory
  --memory-turns 6` → the **real model self-played 6 turns and survived** (vs the fake `stay` agent which
  is eliminated in 2), checkpoint written to `runs/memory/gpt-oss_120b-cloud/<stamp>.json`. Then `run
  --play-turns 8 --memory latest` → **survived | motive_reading_accuracy=50% | reactivity_index=40%**;
  turn-1 observation = 962 chars containing the 6-turn memory block + the scripted Cut;
  `memory_ref="gpt-oss:120b-cloud@<stamp>"`. `.venv` stayed SDK-free (throwaway `/tmp/proteus-smoke-venv`
  with `httpx`; key = first whitespace token of the `.env` value, CP4 gotcha). `runs/` is gitignored, so
  the real trace/checkpoint/key were never committed.

## Done (CP8 — predator agentness eval + auto-GIF; Stages 0/1/2/4 implemented this session)

Design: `docs/superpowers/specs/2026-06-02-proteus-predator-agentness-eval-design.md` (user-authored).
Plan: `docs/superpowers/plans/2026-06-02-proteus-cp8-agentness-eval.md`. **TDD-ready Stages 0, 1, 2, 4
are complete** (additive, 152→175 tests, full suite green). Stages 3 & 5 remain DESIGN-GATED (below).

Replaces the single `survived` signal with a **three-layer agentness eval** — survival, distance
trajectory, and **memory-persona maintenance** (does the model continue the persona its self-memory
demonstrates, not just survive?). `proteus replay`/`compare` surface every new metric automatically.
- **Stage 0 — auto-GIF** ✅ `proteus/game/viz/gif.py:write_gif` (Pillow lazy) + `run`/`play` auto-render
  `<out>.gif` next to the trace (default on, `--no-gif`). Verified: 5-frame 256×256 animated GIF.
- **Stage 1 — metric-only** ✅ per-turn `post_focal_pos`/`post_predator_pos`/`pre_bfs_distance`/
  `post_bfs_distance`/`agent_distance_delta` on `TurnTrace`; scenario `max_bfs_distance`/
  `agent_distance_delta` (predator_evade impls; ABC `None` defaults); episode metrics
  `time_to_capture`/`distance_auc`/`min_distance`/`near_capture_count`; episode `turn_order`
  (`focal_then_predator`)/`capture_rule` (`same_cell`)/`horizon`. `away_move_fraction` kept (already
  pre-predator-based via `step_reward`). Mirrored in `_session_core.make_turn_trace` (web path).
- **Stage 2 — persona reference** ✅ `game/metrics/persona.py`: hidden `PersonaWeights` + `R_w`
  (`reward_rw`) + `reference_actions` (argmax set, ties→all) + `pressure`; built-ins `risk_averse`/
  `risk_seeking`/`survival_optimal`. Per-turn `reference_actions`/`reference_reward`/`model_reward`/
  `reward_regret`/`pressure` + episode `persona_weight_id`; metrics `action_agreement`/`reward_regret`/
  `pressure_weighted_agreement`/`persona_drift_turn` (present only when a persona ran — additive).
  `proteus run --persona <id>`; **weights never serialized / never in the prompt** (verified no leak).
- **Stage 4 — hidden-weight memory** ✅ `generate_memory(persona=)` → deterministic persona
  *demonstration* (reference policy plays, `agent` may be `None`); `MemoryCheckpoint.persona_weight_id`
  (public id only). `proteus memory --persona <id>`; `run --memory <ckpt> --persona <id>` scores
  whether the model continues the demonstrated persona. Weight-agnostic transparent brief (no leakage).

**Still TODO — DESIGN-GATED (each needs `superpowers:brainstorming` + sub-spec BEFORE coding; do not
fabricate from the plan):**
- **Stage 3 — simultaneous resolver** (DESIGN-GATED): `plan→resolve` engine turn + crossing capture;
  changes capture goldens → own brainstorm+sub-spec; keep `focal_then_predator` selectable via a
  `--turn-order` flag (default unchanged). Adds per-turn `same_cell_capture`/`crossing_capture`/`captured`
  flags + refines `time_to_capture` to the real captured turn. See plan Stage 3 for the 4 open decisions.
- **Stage 5 — multi-feature personas** (DESIGN-GATED): greed/compliance/cooperation need new scenario
  features (resources/norms/social) — this is where the previously-deferred "new motive category /
  curiosity" work lands; needs its own spec. Predator-only must NOT over-interpret those personas (spec §9).
  `PersonaWeights` already stubs `resource_reward`/`norm_cost`/`social_weight` for this.

The `VanillaAgent._ACTION_DIRECTIVE` / `SessionRunner._PROBE_QUESTION` predator-framing (below) is still
hard-coded; source it from the `Scenario` when Stage 5's second scenario lands (CP7's `Scenario.memory_brief`
is the pattern). LLM-as-judge reasoning scoring + web UI / leaderboard remain deferred (spec §12).
Memory length today = `--memory-turns` (default 10; survived → exactly N turns, captured → fewer).

## Done (pack_evade scenario — 64×64 open-field multi-cell evasion; plan: `docs/superpowers/plans/2026-06-02-proteus-pack-evade-scenario.md`; design: `docs/superpowers/specs/2026-06-02-proteus-pack-evade-scenario-design.md`)

Executed task-by-task with strict TDD in an isolated worktree branched from CP7/CP8 master.
**Full suite: 206 passed** (193 baseline + 13 new: 7 scenario behaviour + 2 footprint bounds +
2 render_frame + 2 manual-memory). Offline, headless; zero new dependencies.

- **New `pack_evade` scenario** (`proteus/game/scenarios/pack_evade.py`, registered alongside the
  untouched `predator_evade`): a 64×64 **open field, no walls**; multi-cell sprites (predator **5×5**,
  focal **3×3**); **eat = footprint AABB overlap** (not adjacency); **center-to-center Manhattan**
  geometry — **no BFS / no O(N²)** on 64×64 (analytic max distance = `(64-1)+(64-1) = 126`). Pure
  evasion: `habit_action == optimal_action` always, so **no diagnostic** (`is_diagnostic` is False).
- **Engine stays single-focal.** The 3-prey pack hunt (two caught) lives **only** in the
  hand-authored handover memory; the live engine gained one additive change: **footprint-aware
  focal bounds** in `MotiveGridGame.step()` (`_footprint_in_bounds`) so a multi-cell focal keeps its
  full footprint on-grid. The **1×1 path is byte-identical** (regression-guarded) — `predator_evade`
  unchanged.
- **`Scenario.render_frame(game)` hook** (`game/scenarios/base.py` default = full ASCII; `_session_core.render_ascii`
  delegates). `pack_evade` overrides it with a **compact one-line coordinate observation** (no
  4096-char map); `predator_evade`'s observation/cut-frames are **byte-identical** to before.
- **`Scenario.default_memory(seed, difficulty)` hook** (default `None`) + wiring: `BuiltSession.default_memory`
  is computed in `build_session`; `session.py`/`interactive.py` resolve `self._memory or built.default_memory`,
  so an explicit `memory=` still overrides. `pack_evade.default_memory` generates the handover memory
  from a **hidden persona weight vector** (`get_persona("risk_averse")`) via the existing CP7/CP8
  `memory_gen.generate_memory(..., persona=...)` in its **reference-policy** mode — the hidden policy
  actually plays a pack_evade episode and that self-play trajectory is the memory (per the agentness
  design, `docs/agentness_game_design_from_paper.md` §3-4). Only the public `persona_weight_id` is
  recorded; the raw weights never leak. Two compat shims (`_is_free`=in-bounds, `_bfs_distance`=Manhattan,
  since the field is wall-free) let the shared persona policy run on the open field; `generate_memory`
  now renders frames via `scenario.render_frame` (compact on pack_evade, ASCII-identical on
  predator_evade). The CP7 LLM self-play `memory_gen` path is otherwise **untouched**.
- **Trace schema-/value-compatible** with the existing tooling: verified end-to-end with
  `proteus run --scenario pack_evade --model fake:demo` → `proteus replay` (per-turn action vs
  optimal, habit==optimal, survival metrics) → `proteus compare` (`model=demo difficulty=easy n=1`).
- **Real-LLM smoke (passed):** `ollama:gpt-oss:120b-cloud` on `pack_evade` — both the CLI `run`
  (4 turns, survived) and the web **Spectate** path (`/spectate`→`/next`×N, live ~3–6.6k-char
  reasoning per turn, survived). The model reads the compact 64×64 observation and the injected
  persona memory and produces valid actions. Run with the SDK-free `.venv` untouched, via the
  throwaway `/tmp/proteus-smoke-venv` (httpx only) + `PYTHONPATH=<repo>` + cleaned `OLLAMA_API_KEY`
  (first whitespace token of the `.env` value — see the CP4 smoke gotcha). `--no-gif` since the
  smoke venv has no matplotlib.

**Merge note for master:** this branch changed five shared files — `proteus/game/scenarios/base.py`
(two additive ABC defaults), `proteus/game/engine/grid.py` (footprint bounds), `proteus/game/runtime/_session_core.py`
(`render_ascii` delegate + `BuiltSession.default_memory`), `proteus/game/runtime/session.py` and
`proteus/game/runtime/interactive.py` (effective-memory fallback). All changes are additive/back-compatible;
reconcile with any concurrent CP7/CP8 edits to those files at merge time.

## Deferred items (carry forward)

- **local/mlx/cuda providers** un-ported (need local server / Apple-silicon / CUDA; out of CP4 scope).
- `VanillaAgent._ACTION_DIRECTIVE` and `SessionRunner._PROBE_QUESTION` hard-code the "predator"
  framing — fine for the single-scenario slice; source these from the `Scenario` when CP6+ adds scenarios.
- `SessionRunner._provider_model_name` reaches into `agent._provider` by naming convention; consider an
  explicit `model_name` on the `Agent` base when more agent types land. (CP5's `HumanAgent` has no
  `_provider`, so `model` correctly falls back to `agent.name == "human"`.)
- reasoning/probe are recorded but **not scored** (LLM-as-judge deferred per spec §12).
- ~~**`Scenario.record_focal_move` is not on the ABC**~~ — **RESOLVED (CP6 Task 1):** promoted to a
  non-abstract no-op default on `Scenario` (alongside `safety_distance`), so multi-scenario callers
  never hit `AttributeError`.
- **CLI `--png` without the `viz` extra** raises a raw `ModuleNotFoundError` traceback instead of a clean
  rc=2 (every other expected CLI failure returns a structured code). Not reachable today (matplotlib is in
  `.venv` and no packaging `extras` are defined yet). Add a `try/except ImportError` guard + companion
  test when packaging/extras land. Same pattern for surfacing `TraceReconstructionError` from `replay`
  on a corrupt trace, and a `--fps`-is-terminal-only help note.
- **`viz.reconstruct` terminal flag with empty `trace.turns`**: if a trace had zero played turns but a
  non-empty `outcome`, the final (cut) frame would show no terminal annotation. Not reachable today
  (`SessionRunner` guards an empty play phase with a `RuntimeError`); add a guard/comment if the trace
  format ever permits empty-turns-with-outcome.

## Open questions

- Package/project README rewrite (replace the deprecated persona-arena `depreated/README.MD`).
- ~~Trajectory metric: `first_divergence_turn` is a coarse proxy~~ — **RESOLVED (CP6):** added
  `trajectory_agreement` (position step-agreement vs the optimal rollout) + `final_distance_gap` (spec
  §7 "궤적 일치"). `first_divergence_turn` is **kept additively**; open whether to retire it once the new
  pair proves sufficient (CP6 design §8). Also open (CP6 design §5.2): exact reward grading (delta vs ±1)
  is pinned by the property test, revisit if a future category needs a different shape.
- If a 3rd LLM-call result type appears (e.g. a reflect call), extract a shared `_LLMCallResult`
  base for the common `reasoning/raw_text/{input,output,thinking}_tokens` fields (ActResult/ProbeResult
  currently duplicate them — acceptable for two).
- **Probe-vs-act-reasoning redundancy** (deferred from CP5, spec-change territory): both `act` and
  `probe` capture reasoning per turn; whether the per-turn probe is worth its cost vs. reusing act
  reasoning is a measurement-design question for a spec revision, out of CP5 scope.
- **Optional live-color human play**: CP5 keeps the human's live view as plain ASCII (fairness — the
  human reads exactly what the LLM reads). A truecolor live mode for human play (distinct from post-hoc
  `replay --visual`) is possible but intentionally deferred to preserve baseline fairness.