docs(plan): web LLM spectating — 7-task TDD implementation plan

docs/superpowers/plans/2026-06-02-proteus-web-spectate.md

@@ -0,0 +1,753 @@
+# PROTEUS Web LLM Spectating 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:** Let a person watch an LLM play the arena in the browser (color grid + live reasoning/analysis), auto-advancing turn by turn with pause/step, always saving a `proteus compare`-compatible LLM trace.
+
+**Architecture:** A new threadless `SpectateSession` (agent-driven sibling of `InteractiveSession`) advances exactly one LLM turn per HTTP request via the shared `_session_core`, and is pinned to `SessionRunner(VanillaAgent(...))` by a golden equivalence test. The stdlib `http.server` gains `/spectate*` routes; providers are **lazy-imported inside the create handler** so the offline import-safety invariant holds. The browser auto-loops `POST /spectate/{id}/next` (pause/step), showing each turn's grid + reasoning + optimal/habit/reward (rich disclosure — a spectator is not the scored subject).
+
+**Tech Stack:** Python 3.12 stdlib (`http.server`) + existing providers/agents + pydantic v2. Vanilla HTML/JS (no build, no CDN). **Zero new dependencies** (providers already exist; lazy-imported — `.venv` import surface unchanged).
+
+**Reference spec:** `docs/superpowers/specs/2026-06-02-proteus-web-spectate-design.md`
+
+**Run tests with:** `.venv/bin/python -m pytest -q` (`python` is NOT on PATH; use the venv).
+
+**IMPORTANT — isolation & parallelism:** Execute in an **isolated git worktree** (superpowers:using-git-worktrees) branched from current `master`. This plan's writable files (`proteus/runtime/spectate.py`, `proteus/web/server.py`, `proteus/web/static/index.html`, new spectate tests) are **disjoint** from the `pack_evade` plan's writable files (grid + runtime-core), so the two can be implemented in parallel on separate branches and merged without cross-conflict. `SpectateSession` reads `default_memory` via `getattr(..., None)` so it works whether or not pack_evade has merged yet.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `proteus/runtime/spectate.py` | **Create.** `SpectateSession`: agent-driven `state()`/`advance()`/`finish()` over `_session_core`; rich (non-fair) live disclosure. |
+| `proteus/web/server.py` | **Modify.** `/spectate`, `/spectate/{id}/next`, `/spectate/{id}` (GET), `/spectate/{id}/finish`; `/config` += providers/default_model; providers lazy-imported in the create handler. |
+| `proteus/web/static/index.html` | **Modify.** Mode toggle (Play / Spectate), model input, analysis panel, auto-play/pause/step. |
+| `tests/runtime/test_spectate.py` | **Create.** advance / rich live disclosure / finish / advance-after-done (FakeProvider, offline). |
+| `tests/runtime/test_spectate_equivalence.py` | **Create.** Golden: `SpectateSession` trace == `SessionRunner(VanillaAgent(same FakeProvider))`. |
+| `tests/web/test_spectate_routes.py` | **Create.** `/spectate` + `/next` + `/finish` + errors (fake:demo, no socket). |
+| `tests/web/test_import_safety.py` | **Modify.** Extend the existing guard: spectate additions still pull no provider SDK at import. |
+
+---
+
+## Task 1: `SpectateSession` — agent-driven stepwise driver
+
+**Files:**
+- Create: `proteus/runtime/spectate.py`
+- Test: `tests/runtime/test_spectate.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_spectate.py
+"""Unit tests for SpectateSession (agent-driven, stepwise, rich disclosure)."""
+from __future__ import annotations
+
+import pytest
+
+import proteus.grid  # noqa: F401
+from proteus.agents.vanilla import VanillaAgent
+from proteus.grid.difficulty import Difficulty
+from proteus.providers.fake import FakeProvider
+from proteus.runtime._session_core import SessionFinishedError
+from proteus.runtime.spectate import SpectateSession
+
+
+def _agent(n=10):
+    return VanillaAgent(FakeProvider(responses=["ACTION: stay"] * n, model_name="demo"))
+
+
+def _new(play_turns=5):
+    return SpectateSession(
+        "predator_evade", agent=_agent(), model_name="fake:demo",
+        difficulty=Difficulty.EASY, seed=42, play_turns=play_turns, use_probe=False,
+    )
+
+
+def test_initial_state_is_cut_intro_int_grid():
+    s = _new()
+    st = s.state()
+    assert st["phase"] == "cut_intro"
+    assert st["turn_idx"] == 0
+    assert isinstance(st["grid"][0][0], int)
+    assert st["turns_so_far"] == []
+
+
+def test_advance_runs_one_llm_turn_with_rich_disclosure():
+    s = _new()
+    st = s.advance()
+    assert st["turn_idx"] == 1
+    last = st["turns_so_far"][-1]
+    # rich: optimal/habit/reward/reasoning ARE exposed live (spectator, not scored).
+    for k in ("action", "motive_action", "habit_action", "reward",
+              "is_diagnostic", "was_congruent", "reasoning"):
+        assert k in last
+
+
+def test_advance_to_budget_then_done_and_finish():
+    s = _new(play_turns=2)
+    while s.state()["outcome"] is None:
+        s.advance()
+    st = s.state()
+    assert st["phase"] == "done" and st["outcome"] in ("survived", "eliminated")
+    trace = s.finish()
+    assert trace.model == "fake:demo" and trace.scenario == "predator_evade"
+
+
+def test_advance_after_done_raises():
+    s = _new(play_turns=1)
+    s.advance()
+    with pytest.raises(SessionFinishedError):
+        s.advance()
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/runtime/test_spectate.py -q`
+Expected: FAIL — `ModuleNotFoundError: proteus.runtime.spectate`.
+
+- [ ] **Step 3: Write the implementation**
+
+```python
+# proteus/runtime/spectate.py
+"""SpectateSession — a threadless, agent-driven driver for watching an LLM play.
+
+Sibling of InteractiveSession, but the server (not a human) supplies each action
+by calling the agent once per HTTP request. Built on the same ``_session_core``
+helpers, so its trace matches SessionRunner for the same agent (pinned by
+tests/runtime/test_spectate_equivalence.py).
+
+Disclosure: a spectator is NOT the scored subject, so ``state()`` exposes the per
+turn answer keys (optimal/habit), reward, and the model's reasoning LIVE. (The
+model itself still only ever receives the observation passed to ``agent.act``.)
+"""
+from __future__ import annotations
+
+from proteus.agents.base import Agent
+from proteus.grid.difficulty import Difficulty
+from proteus.runtime import _session_core as core
+from proteus.runtime.trace import SessionTrace, TurnTrace
+
+
+class SpectateSession:
+    def __init__(
+        self,
+        scenario_name: str,
+        *,
+        agent: Agent,
+        model_name: str,
+        difficulty: Difficulty = Difficulty.EASY,
+        seed: int | None = None,
+        play_turns: int = 15,
+        use_probe: bool = False,
+        motive_category: str = "survival",
+    ) -> None:
+        self._scenario_name = scenario_name
+        self._agent = agent
+        self._model_name = model_name
+        self._difficulty = difficulty
+        self._seed = seed
+        self._play_turns = play_turns
+        self._use_probe = use_probe
+        self._motive_category = motive_category
+
+        built = core.build_session(scenario_name, seed, difficulty, play_turns)
+        self._scenario = built.scenario
+        self._game = built.game
+        self._cut_frames = built.cut_frames
+        self._cut_grids = built.cut_grids
+        # Forward-compatible with pack_evade's default_memory (absent -> None).
+        self._memory = getattr(built, "default_memory", None)
+        self._system_prompt = self._scenario.rules_text + core._HANDOVER_FRAMING
+        self._turns: list[TurnTrace] = []
+        self._trace: SessionTrace | None = None
+
+    def _is_done(self) -> bool:
+        return (
+            self._game.eliminated
+            or self._game.survived
+            or len(self._turns) >= self._play_turns
+        )
+
+    def state(self) -> dict:
+        done = self._is_done()
+        played = len(self._turns)
+        phase = "done" if done else ("cut_intro" if played == 0 else "play")
+        st: dict = {
+            "phase": phase,
+            "turn_idx": played,
+            "play_turns": self._play_turns,
+            "model": self._model_name,
+            "grid": core.grid_to_list(self._game.current_grid()),
+            "legend": {str(k): v for k, v in self._scenario.legend().items()},
+            "actions": list(core._ACTIONS),
+            "outcome": None,
+            "cut_frames": self._cut_grids if played == 0 else None,
+            # RICH disclosure (spectator): per-turn answer keys + reward + reasoning.
+            "turns_so_far": [
+                {
+                    "turn_idx": t.turn_idx,
+                    "action": t.action,
+                    "motive_action": t.motive_action,
+                    "habit_action": t.habit_action,
+                    "reward": t.reward,
+                    "is_diagnostic": t.is_diagnostic,
+                    "was_congruent": t.was_congruent,
+                    "reasoning": t.reasoning,
+                }
+                for t in self._turns
+            ],
+            "review": None,
+        }
+        if done:
+            trace = self.finish()
+            st["outcome"] = trace.outcome
+            st["review"] = {"outcome": trace.outcome, "metrics": trace.metrics}
+        return st
+
+    def advance(self) -> dict:
+        if self._is_done():
+            raise core.SessionFinishedError("session already finished")
+        turn_idx = len(self._turns) + 1
+        observation = core.build_observation(
+            self._scenario, self._game, self._cut_frames, turn_idx,
+            memory=self._memory,
+        )
+        result = self._agent.act(observation, list(core._ACTIONS), self._system_prompt)
+        self._turns.append(core.make_turn_trace(
+            self._scenario, self._game,
+            turn_idx=turn_idx, observation=observation,
+            action=result.action, reasoning=result.reasoning, raw_text=result.raw_text,
+            input_tokens=result.input_tokens, output_tokens=result.output_tokens,
+            thinking_tokens=result.thinking_tokens,
+        ))
+        return self.state()
+
+    def finish(self) -> SessionTrace:
+        if self._trace is not None:
+            return self._trace
+        self._trace = core.finalize(
+            self._scenario_name, self._scenario, self._game,
+            seed=self._seed, difficulty=self._difficulty,
+            play_turns=self._play_turns, turns=self._turns,
+            cut_frames=self._cut_frames, motive_category=self._motive_category,
+            model=self._model_name,
+        )
+        return self._trace
+```
+
+NOTE: `core.build_observation(..., memory=...)` is the CP7-merged signature already on
+`master`. If `build_observation` in this tree does not yet accept `memory`, drop the
+`memory=self._memory` kwarg (predator_evade does not use it); the pack_evade plan
+adds/relies on it.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/runtime/test_spectate.py -q`
+Expected: PASS (4 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/runtime/spectate.py tests/runtime/test_spectate.py
+git commit -m "feat(spectate): SpectateSession — agent-driven stepwise LLM driver"
+```
+
+---
+
+## Task 2: Golden equivalence — SpectateSession == SessionRunner(VanillaAgent)
+
+**Files:**
+- Test: `tests/runtime/test_spectate_equivalence.py`
+
+- [ ] **Step 1: Write the test**
+
+```python
+# tests/runtime/test_spectate_equivalence.py
+"""Golden: the same scripted FakeProvider produces an identical SessionTrace
+whether driven through SpectateSession (one advance per turn) or SessionRunner +
+VanillaAgent (batch). Pins the spectate path to the runner path."""
+from __future__ import annotations
+
+import proteus.grid  # noqa: F401
+from proteus.agents.vanilla import VanillaAgent
+from proteus.grid.difficulty import Difficulty
+from proteus.providers.fake import FakeProvider
+from proteus.runtime.session import SessionRunner
+from proteus.runtime.spectate import SpectateSession
+
+RESPONSES = ["ACTION: up", "ACTION: up", "ACTION: left",
+             "ACTION: stay", "ACTION: right", "ACTION: up"]
+
+
+def _agent():
+    return VanillaAgent(FakeProvider(responses=list(RESPONSES), model_name="demo"))
+
+
+def test_spectate_matches_session_runner():
+    runner = SessionRunner(
+        "predator_evade", _agent(), difficulty=Difficulty.EASY, seed=42,
+        play_turns=len(RESPONSES), use_probe=False,
+    )
+    batch_trace = runner.run()
+
+    sess = SpectateSession(
+        "predator_evade", agent=_agent(), model_name="demo",
+        difficulty=Difficulty.EASY, seed=42, play_turns=len(RESPONSES), use_probe=False,
+    )
+    while sess.state()["outcome"] is None:
+        sess.advance()
+    watch_trace = sess.finish()
+
+    assert watch_trace.model == batch_trace.model == "demo"
+    assert watch_trace.model_dump() == batch_trace.model_dump()
+```
+
+- [ ] **Step 2: Run the test**
+
+Run: `.venv/bin/python -m pytest tests/runtime/test_spectate_equivalence.py -q`
+Expected: PASS (1 passed). If a field differs, the spectate path diverges from the
+runner — fix `spectate.py` (system_prompt, memory resolution, finalize args) until the
+`model_dump()` is byte-identical. Do not weaken the assert.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/runtime/test_spectate_equivalence.py
+git commit -m "test(spectate): golden — SpectateSession trace == SessionRunner(VanillaAgent)"
+```
+
+---
+
+## Task 3: Server routes (`/spectate*`) + provider config
+
+**Files:**
+- Modify: `proteus/web/server.py`
+- Test: `tests/web/test_spectate_routes.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/web/test_spectate_routes.py
+"""Route-level tests for spectating (offline via fake:demo, no socket)."""
+from __future__ import annotations
+
+import proteus.grid  # noqa: F401
+from proteus.web import server
+
+
+def _reg():
+    return {}
+
+
+def test_config_lists_providers_and_default_model():
+    _, payload, _ = server.handle_request("GET", "/config", None, _reg())
+    assert "fake" in payload["providers"]
+    assert payload["default_model"] == "fake:demo"
+
+
+def test_spectate_create_next_finish(tmp_path):
+    reg = _reg()
+    status, created, _ = server.handle_request(
+        "POST", "/spectate",
+        {"scenario": "predator_evade", "difficulty": "easy", "seed": 42,
+         "play_turns": 3, "model": "fake:demo", "probe": False}, reg)
+    assert status == 200
+    sid = created["session_id"]
+    assert created["state"]["phase"] == "cut_intro"
+
+    # advance to terminal
+    last = None
+    for _ in range(3):
+        status, payload, _ = server.handle_request(
+            "POST", f"/spectate/{sid}/next", None, reg)
+        assert status == 200
+        last = payload["state"]
+        if last["outcome"] is not None:
+            break
+    assert last["turns_so_far"]  # rich disclosure present
+
+    out = tmp_path / "spectate.jsonl"
+    status, payload, _ = server.handle_request(
+        "POST", f"/spectate/{sid}/finish", {"out": str(out)}, reg)
+    assert status == 200 and out.exists()
+    assert payload["trace_path"] == str(out) and "survival_fraction" in payload["metrics"]
+
+
+def test_unknown_model_is_400():
+    status, payload, _ = server.handle_request(
+        "POST", "/spectate",
+        {"scenario": "predator_evade", "difficulty": "easy", "seed": 1,
+         "play_turns": 3, "model": "nope:x", "probe": False}, _reg())
+    assert status == 400 and "error" in payload
+
+
+def test_next_after_done_is_409():
+    reg = _reg()
+    _, created, _ = server.handle_request(
+        "POST", "/spectate",
+        {"scenario": "predator_evade", "difficulty": "easy", "seed": 42,
+         "play_turns": 1, "model": "fake:demo", "probe": False}, reg)
+    sid = created["session_id"]
+    server.handle_request("POST", f"/spectate/{sid}/next", None, reg)  # exhausts budget
+    status, payload, _ = server.handle_request("POST", f"/spectate/{sid}/next", None, reg)
+    assert status == 409 and "error" in payload
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/web/test_spectate_routes.py -q`
+Expected: FAIL — `/config` lacks `providers`; `/spectate` route returns 404.
+
+- [ ] **Step 3: Modify `proteus/web/server.py`**
+
+Add lazy imports + the spectate handlers (providers/agents imported INSIDE the create
+handler to keep the offline import-safety invariant). Extend `_config_payload`, and add
+routes to `handle_request`.
+
+Add these handler functions (above `handle_request`):
+
+```python
+def _create_spectate(body: dict, registry: dict) -> Response:
+    # Lazy imports keep `import proteus.web.server` free of provider SDKs.
+    from proteus.agents.vanilla import VanillaAgent
+    from proteus.providers import make_provider
+    from proteus.runtime.spectate import SpectateSession
+    try:
+        scenario = body["scenario"]
+        difficulty = Difficulty(body.get("difficulty", "easy"))
+        seed = body.get("seed", _DEFAULT_SEED)
+        seed = None if seed in ("", None) else int(seed)
+        play_turns = int(body.get("play_turns", 10))
+        model = body.get("model", "fake:demo")
+        probe = bool(body.get("probe", False))
+    except (KeyError, ValueError) as exc:
+        return _err(400, f"bad spectate params: {exc}")
+    if scenario not in list_scenarios():
+        return _err(400, f"unknown scenario {scenario!r}")
+    try:
+        provider = make_provider(model)
+    except ValueError as exc:
+        return _err(400, str(exc))
+    agent = VanillaAgent(provider)
+    session = SpectateSession(
+        scenario, agent=agent, model_name=provider.model_name,
+        difficulty=difficulty, seed=seed, play_turns=play_turns, use_probe=probe,
+    )
+    sid = uuid.uuid4().hex
+    registry[sid] = session
+    return 200, {"session_id": sid, "state": session.state()}, _JSON
+
+
+def _spectate_next(sid: str, registry: dict) -> Response:
+    session = registry.get(sid)
+    if session is None:
+        return _err(404, f"unknown session {sid!r}")
+    try:
+        state = session.advance()
+    except core.SessionFinishedError:
+        return _err(409, "session already finished")
+    except Exception as exc:  # provider failure (missing key / network): no stack leak
+        return _err(500, f"agent step failed: {exc}")
+    return 200, {"state": state}, _JSON
+
+
+def _spectate_finish(sid: str, body: dict, registry: dict) -> Response:
+    session = registry.get(sid)
+    if session is None:
+        return _err(404, f"unknown session {sid!r}")
+    try:
+        trace = session.finish()
+    except core.SessionNotFinishedError:
+        return _err(409, "session not finished")
+    out = (body or {}).get("out") or f"runs/web_spectate_{trace.scenario}_{trace.difficulty}.jsonl"
+    written = append_trace(trace, out)
+    return 200, {"trace_path": str(written), "metrics": trace.metrics}, _JSON
+```
+
+Extend `_config_payload` to add providers + default model:
+
+```python
+def _config_payload() -> dict:
+    from proteus.providers import available_providers  # local: keep module import light
+    return {
+        "scenarios": list_scenarios(),
+        "difficulties": [d.value for d in Difficulty],
+        "color_map": {str(k): v for k, v in COLOR_MAP.items()},
+        "default_seed": _DEFAULT_SEED,
+        "providers": available_providers(),
+        "default_model": "fake:demo",
+    }
+```
+
+Add the routes in `handle_request` (after the `/session/` block, before the final 404):
+
+```python
+    if method == "POST" and path == "/spectate":
+        return _create_spectate(body or {}, registry)
+    if path.startswith("/spectate/"):
+        rest = path[len("/spectate/"):]
+        if method == "POST" and rest.endswith("/next"):
+            return _spectate_next(rest[: -len("/next")], registry)
+        if method == "POST" and rest.endswith("/finish"):
+            return _spectate_finish(rest[: -len("/finish")], body or {}, registry)
+        if method == "GET":
+            session = registry.get(rest)
+            if session is None:
+                return _err(404, f"unknown session {rest!r}")
+            return 200, {"state": session.state()}, _JSON
+```
+
+(`available_providers` / `make_provider` are imported **locally** so the top-level
+`import proteus.web.server` still pulls no provider SDK — Task 6 guards this.)
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/web/test_spectate_routes.py -q`
+Expected: PASS (5 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/web/server.py tests/web/test_spectate_routes.py
+git commit -m "feat(spectate): /spectate routes + provider config (lazy-imported)"
+```
+
+---
+
+## Task 4: Frontend — spectate mode (toggle, analysis panel, auto-play/pause/step)
+
+**Files:**
+- Modify: `proteus/web/static/index.html`
+
+- [ ] **Step 1: Add a mode toggle + model input to the start screen**
+
+In the start-screen `.row` (after the `probe` checkbox `<div>`), add:
+
+```html
+      <div><label>mode</label><select id="mode">
+        <option value="play">Play (human)</option>
+        <option value="spectate">Spectate (LLM)</option>
+      </select></div>
+      <div id="modelWrap" class="hidden"><label>model</label>
+        <input id="model" value="fake:demo" style="width:140px"></div>
+```
+
+- [ ] **Step 2: Add a spectate analysis panel to the play screen**
+
+After the `#grid` div inside `#play`, add:
+
+```html
+    <div id="analysis" class="hidden">
+      <div id="thinking" style="color:var(--muted)"></div>
+      <div id="reasoning" style="white-space:pre-wrap;margin:8px 0"></div>
+      <table id="turnlog"><tr><th>turn</th><th>action</th><th>optimal</th>
+        <th>habit</th><th>reward</th><th>=opt?</th></tr></table>
+      <p style="text-align:center;margin-top:10px">
+        <button id="pauseBtn">Pause</button>
+        <button id="stepBtn">Step</button></p>
+    </div>
+```
+
+- [ ] **Step 3: Add the spectate JS (append inside the existing `<script>`)**
+
+```javascript
+let SPECT = false, PAUSED = false;
+
+function showModelInput() {
+  $("modelWrap").classList.toggle("hidden", $("mode").value !== "spectate");
+}
+
+function appendTurn(t) {
+  const tr = document.createElement("tr");
+  if (t.is_diagnostic) tr.className = "diag";
+  tr.innerHTML = `<td>${t.turn_idx}</td><td>${t.action}</td><td>${t.motive_action}</td>`
+    + `<td>${t.habit_action}</td><td>${t.reward.toFixed(1)}</td>`
+    + `<td>${t.was_congruent ? '✓':'✗'}</td>`;
+  $("turnlog").appendChild(tr);
+}
+
+function showSpectateState(st) {
+  $("turnInfo").textContent = `Turn ${st.turn_idx} / ${st.play_turns}`;
+  drawGrid(st.grid);
+  const last = st.turns_so_far[st.turns_so_far.length - 1];
+  if (last) { $("reasoning").textContent = last.reasoning || ""; appendTurn(last); }
+}
+
+async function spectateLoop() {
+  while (SPECT && !PAUSED) {
+    $("thinking").textContent = "thinking…";
+    const {status, data} = await jpost(`/spectate/${SID}/next`, {});
+    $("thinking").textContent = "";
+    if (status === 409) break;
+    if (status !== 200) { $("thinking").textContent = data.error || "error"; SPECT = false; break; }
+    showSpectateState(data.state);
+    if (data.state.outcome) {
+      const fin = await jpost(`/spectate/${SID}/finish`, {});
+      if (fin.status === 200) $("savedPath").textContent = "trace saved: " + fin.data.trace_path;
+      $("play").classList.add("hidden"); $("end").classList.remove("hidden");
+      const o = $("outcome");
+      o.textContent = data.state.outcome === "survived" ? "SURVIVED" : "ELIMINATED";
+      o.className = "outcome " + (data.state.outcome === "survived" ? "win" : "lose");
+      SPECT = false; break;
+    }
+  }
+}
+
+async function startSpectate(body) {
+  const {status, data} = await jpost("/spectate", body);
+  if (status !== 200) { alert(data.error || "failed to start"); return; }
+  SID = data.session_id; SPECT = true; PAUSED = false;
+  $("turnlog").querySelectorAll("tr:not(:first-child)").forEach(r => r.remove());
+  $("start").classList.add("hidden"); $("end").classList.add("hidden");
+  $("play").classList.remove("hidden"); $("analysis").classList.remove("hidden"); $("pad")?.classList?.add?.("hidden");
+  $("meta").textContent = `${body.scenario} · ${body.difficulty} · ${body.model}`;
+  const st = data.state;
+  if (st.cut_frames) await animateCut(st.cut_frames);
+  drawGrid(st.grid);
+  spectateLoop();
+}
+```
+
+- [ ] **Step 4: Wire the controls in `startGame`/`init`**
+
+In `init()`, add:
+
+```javascript
+  $("mode").addEventListener("change", showModelInput);
+  $("pauseBtn").addEventListener("click", () => {
+    PAUSED = !PAUSED; $("pauseBtn").textContent = PAUSED ? "Resume" : "Pause";
+    if (!PAUSED) spectateLoop();
+  });
+  $("stepBtn").addEventListener("click", async () => {
+    if (!SPECT) return;
+    const {status, data} = await jpost(`/spectate/${SID}/next`, {});
+    if (status === 200) { showSpectateState(data.state);
+      if (data.state.outcome) { await jpost(`/spectate/${SID}/finish`, {}); SPECT = false; } }
+  });
+```
+
+In `startGame()`, branch on mode at the top:
+
+```javascript
+  if ($("mode").value === "spectate") {
+    return startSpectate({
+      scenario: $("scenario").value, difficulty: $("difficulty").value,
+      seed: Number($("seed").value), play_turns: Number($("turns").value),
+      model: $("model").value, probe: $("probe").checked,
+    });
+  }
+  // ... existing human-play body unchanged ...
+```
+
+Also hide the human direction pad in spectate mode (give the `.pad` div `id="pad"` if it
+has none, or guard the `.pad` listeners with `if (SPECT) return;` inside `act`).
+
+- [ ] **Step 5: Verify the server byte test still passes + manual check**
+
+Run: `.venv/bin/python -m pytest tests/web/test_server.py::test_root_serves_html_bytes -q`
+Expected: PASS.
+Manual: `.venv/bin/python -m proteus.web --port 8124`, open `http://127.0.0.1:8124/`,
+pick **Spectate (LLM)**, model `fake:demo` → grid auto-advances with the analysis table
++ pause/step working → on end, SURVIVED/ELIMINATED + "trace saved". Stop with Ctrl-C.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add proteus/web/static/index.html
+git commit -m "feat(spectate): frontend — mode toggle + live analysis + auto-play/pause/step"
+```
+
+---
+
+## Task 5: End-to-end + full suite
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Full suite**
+
+Run: `.venv/bin/python -m pytest -q`
+Expected: PASS — all existing + new spectate tests, zero failures.
+
+- [ ] **Step 2: End-to-end — a spectated (fake) trace is replayable + comparable**
+
+```bash
+.venv/bin/python -m proteus.web --port 8124 & SRV=$!; sleep 1.5
+SID=$(curl -s -X POST http://127.0.0.1:8124/spectate -H 'Content-Type: application/json' \
+  -d '{"scenario":"predator_evade","difficulty":"easy","seed":42,"play_turns":3,"model":"fake:demo","probe":false}' \
+  | .venv/bin/python -c "import sys,json;print(json.load(sys.stdin)['session_id'])")
+for i in 1 2 3; do curl -s -X POST http://127.0.0.1:8124/spectate/$SID/next >/dev/null; done
+curl -s -X POST http://127.0.0.1:8124/spectate/$SID/finish \
+  -H 'Content-Type: application/json' -d '{"out":"runs/spectate_e2e.jsonl"}'; echo
+kill $SRV
+.venv/bin/python -m proteus replay runs/spectate_e2e.jsonl
+.venv/bin/python -m proteus compare runs/spectate_e2e.jsonl
+rm -f runs/spectate_e2e.jsonl
+```
+Expected: `/finish` returns `{trace_path, metrics}`; `replay`/`compare` accept the
+trace as a `model=fake` group.
+
+---
+
+## Task 6: Offline import-safety still holds
+
+**Files:**
+- Modify: `tests/web/test_import_safety.py`
+
+- [ ] **Step 1: Extend the guard**
+
+Append to the existing test body (after the current asserts) — re-clearing and
+re-importing already happens; just confirm the spectate additions did not pull an SDK:
+
+```python
+    # spectate routes import providers LAZILY (inside the handler), so a plain
+    # import of the web layer must still pull no provider SDK.
+    import proteus.web.server  # noqa: F401  (re-exercised after the clear above)
+    for sdk in ("openai", "anthropic", "google", "ollama"):
+        assert sdk not in sys.modules
+```
+
+- [ ] **Step 2: Run it**
+
+Run: `.venv/bin/python -m pytest tests/web/test_import_safety.py -q`
+Expected: PASS (1 passed).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/web/test_import_safety.py
+git commit -m "test(spectate): offline import-safety still holds (providers lazy)"
+```
+
+---
+
+## Task 7: Update HANDOFF.md
+
+**Files:**
+- Modify: `HANDOFF.md`
+
+- [ ] **Step 1: Add a "Done (Web LLM spectating)" section**
+
+Summarize: watch an LLM play in the browser (color grid + live reasoning/analysis,
+auto-play with pause/step); `SpectateSession` (agent-driven, `_session_core`-shared)
+pinned to `SessionRunner(VanillaAgent)` by a golden test; real providers + `fake:demo`
+fallback, **lazy-imported** (offline import-safety preserved); spectated runs save a
+`runs/web_spectate_*.jsonl` LLM-baseline trace accepted by `proteus replay`/`compare`.
+Update the full-suite count.
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add HANDOFF.md
+git commit -m "docs(spectate): handoff — watch an LLM play in color shipped"
+```
+
+---
+
+## Self-Review notes (already reconciled)
+
+- **Spec coverage:** §3 components → Tasks 1,3,4; §4 SpectateSession → Task 1; §5 golden → Task 2; §6 API → Task 3; §7 frontend → Task 4; §8 trace → Tasks 3,5; §9 testing → Tasks 1,2,3,5,6; §10 acceptance → Task 5.
+- **Parallel-safe vs pack_evade:** writable files here (`spectate.py`, `web/server.py`, `web/static/index.html`, spectate tests) are disjoint from pack_evade's (grid + runtime-core). `SpectateSession` reads `default_memory` via `getattr(..., None)` and passes `memory=` only if `build_observation` accepts it, so it builds and tests green whether pack_evade has merged or not.
+- **Offline invariant:** providers/agents imported only inside `_create_spectate` (and `available_providers` locally in `_config_payload`); Task 6 guards that `import proteus.web.server` pulls no SDK.
+- **Type consistency:** `SpectateSession(agent=, model_name=)`; `advance()`/`state()`/`finish()` mirror the `_session_core` calls used by `InteractiveSession`/`SessionRunner`; `state()["turns_so_far"]` keys match the frontend `appendTurn`/`showSpectateState` reads; route handler names (`_create_spectate`/`_spectate_next`/`_spectate_finish`) match their `handle_request` dispatch.
+```