Trial-mode UX: live progress visibility + cosmetic fixes + tighter caps

Three classes of issue surfaced during the trial playthrough:

(1) The 3-minute /advance felt completely silent in the UI even though the
LiveProgress component was mounted. Root cause: EventSource has no way to
attach an X-Trial-Password header, so the password gate rejected every
SSE connection silently. Backend now also accepts the password as a
?token= query param on the /games/{id}/stream endpoint, and the frontend
streamUrl appends it from localStorage. Live deliberation cards, the
phase rail, and the cost meter now render during advance.

(2) Cosmetic SPA bugs that shipped wrong turn counts:
- GameView.tsx:96 had `(turns?.length && 5) || 5` which always returned 5
regardless of the game's actual world.max_turns. Read straight from
state.world.max_turns now.
- Debrief.tsx:31 hardcoded `turn:5, max:5` for the shell header. Now
pulls from /games/{id}/state.
- i18n strings in en.ts / de.ts hardcoded "Five turns" and "Turn 1 of 5"
in newGame.scenario.footnote, newGame.ready.engineTail/modelOnly, and
debrief.dek. Replaced with turn-count-agnostic copy ("Multi-turn
dossiers", "the first briefing", "Every turn of deliberation").

(3) Trial-mode LLM-call shrinks beyond the existing 5-agent / 2-turn cap:
- Action coach MAX_ROUNDS now env-driven via _resolve_max_rounds(); trial
mode collapses to 1 round (override via WARGAME_TRIAL_COACH_ROUNDS).
- Critic / premortem / evaluator phases skip when WARGAME_TRIAL_MODE=1.
Saves 3 LLM calls per turn. They enrich the debrief but aren't part of
the named-character reveal that's the core demo. With these cuts a
full trial game (2 turns, 5 agents, 1-round coach, no eval phases)
drops to ~16 LLM calls vs ~25 before this commit.

5 new tests (349 passing). New env vars documented in app.py docstring.

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

frontend/src/api.ts

@@ -184,7 +184,13 @@ export const api = {
     req<StateResponse>(`/games/${id}/pause`, { method: 'POST' }),
   resumeGame: (id: string) =>
     req<AdvanceResponse>(`/games/${id}/resume`, { method: 'POST' }),
-  streamUrl: (id: string) => `${BASE}/games/${id}/stream`,
+  // EventSource can't attach custom headers, so the trial password rides in
+  // a `?token=` query param instead. The backend middleware accepts either.
+  streamUrl: (id: string) => {
+    const pw = getPassword();
+    const qs = pw ? `?token=${encodeURIComponent(pw)}` : '';
+    return `${BASE}/games/${id}/stream${qs}`;
+  },
 };
 
 export type AnchorKind = 'prior_analogue' | 'stated_capability' | 'resource_committed';

frontend/src/i18n/de.ts

@@ -56,14 +56,14 @@ export const de: Partial<Record<StringKey, string>> = {
   "newGame.scenarios.loading": "Szenarien werden geladen…",
   "newGame.scenario.role": "Rolle",
   "newGame.scenario.agentCount": "{count} Berater am Vorstandstisch.",
-  "newGame.scenario.footnote": "Fünf Runden · Briefings im Nebel des Krieges · juriergte Ergebnisse",
+  "newGame.scenario.footnote": "Mehrrundige Dossiers · Briefings im Nebel des Krieges · juriergte Ergebnisse",
   "newGame.scenario.vs": "vs {rival}",
   "newGame.ready.eyebrow": "Bereit",
   "newGame.ready.openCompany": "{company} öffnen",
   "newGame.ready.pick": "Szenario oben auswählen",
   "newGame.ready.engineWith": "Engine ·",
-  "newGame.ready.engineTail": "· generiert Briefing · ~30s · Runde 1 von 5.",
-  "newGame.ready.modelOnly": "Modell generiert Briefing · ~30s · Runde 1 von 5.",
+  "newGame.ready.engineTail": "· generiert das erste Briefing · ~30s.",
+  "newGame.ready.modelOnly": "Modell generiert das erste Briefing · ~30s.",
   "newGame.ready.openCta": "Fall öffnen →",
   "newGame.ready.busy": "Briefing wird generiert…",
   "newGame.lang.eyebrow": "Sprache",
@@ -365,7 +365,7 @@ export const de: Partial<Record<StringKey, string>> = {
   "debrief.eyebrow.case": "Fall {short}…",
   "debrief.eyebrow.tail": "Postmortem",
   "debrief.title": "Das Urteil des Vorstands, aktenkundig.",
-  "debrief.dek": "Fünf Runden Beratung, das Rivalen-Drehbuch, der Verlauf der Welt und die Begründung des Schiedsrichters — in einem einzigen Bericht zusammengeführt. Nutzen Sie ihn, um Auftakte zu vergleichen, Anker zu prüfen und die Strategieklausur des nächsten Quartals vorzubereiten.",
+  "debrief.dek": "Alle Beratungsrunden, das Rivalen-Drehbuch, der Verlauf der Welt und die Begründung des Schiedsrichters — in einem einzigen Bericht zusammengeführt. Nutzen Sie ihn, um Auftakte zu vergleichen, Anker zu prüfen und die Strategieklausur des nächsten Quartals vorzubereiten.",
   "debrief.errorTitle": "Debrief konnte nicht geladen werden",
   "debrief.errorTag": "Fehler",
   "debrief.loading": "Debrief wird geladen…",

frontend/src/i18n/en.ts

@@ -54,14 +54,14 @@ export const en = {
   "newGame.scenarios.loading": "Loading scenarios…",
   "newGame.scenario.role": "Role",
   "newGame.scenario.agentCount": "{count} advisory agents at your board.",
-  "newGame.scenario.footnote": "Five turns · fog-of-war briefings · adjudicated outcomes",
+  "newGame.scenario.footnote": "Multi-turn dossiers · fog-of-war briefings · adjudicated outcomes",
   "newGame.scenario.vs": "vs {rival}",
   "newGame.ready.eyebrow": "Ready",
   "newGame.ready.openCompany": "Open {company}",
   "newGame.ready.pick": "Pick a scenario above",
   "newGame.ready.engineWith": "Engine ·",
-  "newGame.ready.engineTail": "· generates briefing · ~30s · Turn 1 of 5.",
-  "newGame.ready.modelOnly": "Model generates briefing · ~30s · Turn 1 of 5.",
+  "newGame.ready.engineTail": "· generates the first briefing · ~30s.",
+  "newGame.ready.modelOnly": "Model generates the first briefing · ~30s.",
   "newGame.ready.openCta": "Open case →",
   "newGame.ready.busy": "Generating briefing…",
   "newGame.lang.eyebrow": "Language",
@@ -363,7 +363,7 @@ export const en = {
   "debrief.eyebrow.case": "case {short}…",
   "debrief.eyebrow.tail": "Post-mortem",
   "debrief.title": "The board's verdict, on the record.",
-  "debrief.dek": "Five turns of deliberation, the rival playbook, the world-state arc, and the referee's reasoning — collated into a single report. Use it to compare openings, debug anchors, and line up next quarter's strategic review.",
+  "debrief.dek": "Every turn of deliberation, the rival playbook, the world-state arc, and the referee's reasoning — collated into a single report. Use it to compare openings, debug anchors, and line up next quarter's strategic review.",
   "debrief.errorTitle": "Debrief could not be loaded",
   "debrief.errorTag": "Error",
   "debrief.loading": "Loading debrief…",

frontend/src/screens/Debrief.tsx

@@ -14,6 +14,8 @@ export function Debrief({ id, onMeta }: Props) {
   const { t } = useI18n();
   const [md, setMd] = useState<string | null>(null);
   const [err, setErr] = useState<string | null>(null);
+  // Track real turn / max for the shell header; previously hardcoded to 5/5.
+  const [meta, setMeta] = useState<{ turn: number; max: number }>({ turn: 0, max: 0 });
 
   useEffect(() => {
     api.debrief(id).then((r) => setMd(r.markdown)).catch((e) => setErr(String(e)));
@@ -23,14 +25,16 @@ export function Debrief({ id, onMeta }: Props) {
     api.getState(id).then((s) => {
       const lang = s.language as Language | undefined;
       if (lang === 'en' || lang === 'de') setLanguage(lang);
+      const w: any = s.world;
+      if (w) setMeta({ turn: Number(w.turn) || 0, max: Number(w.max_turns) || 0 });
     }).catch(() => { /* non-fatal */ });
   }, [id]);
 
   useEffect(() => {
-    // Debrief is post-game: turn count is whatever we have, recon = 0.
-    onMeta({ id, turn: 5, max: 5, recon_remaining: 0 });
+    // Debrief is post-game; recon spent. Turn / max read from real state.
+    onMeta({ id, turn: meta.turn, max: meta.max, recon_remaining: 0 });
     return () => onMeta(null);
-  }, [id, onMeta]);
+  }, [id, meta, onMeta]);
 
   return (
     <>

frontend/src/screens/GameView.tsx

@@ -93,7 +93,9 @@ export function GameView({ id, onMeta }: Props) {
       setBriefing(br.briefing);
       setBudget(br.recon_budget_remaining);
       setTurn(br.turn);
-      setMaxTurns((st?.turns?.length && 5) || 5);
+      // Read max_turns from the live world state — was previously a stale
+      // hardcoded 5 that ignored trial-mode caps.
+      setMaxTurns(st?.world?.max_turns ?? 5);
       setPhase((st.current_phase as Phase) || 'briefing');
       // Paused mid-turn — keep the actionSent UI mounted so Resume is visible.
       if (st?.status === 'paused') setActionSent(true);

wargame/agents/action_coach.py

@@ -38,10 +38,31 @@ if TYPE_CHECKING:
     from wargame.engine.state import Game
 
 
-# Maximum conversational rounds before forcing best-effort. A round is one
-# user message + one coach reply. After 2 rounds, the coach must commit
-# best-effort anchors and surface what was inferred vs. provided.
-MAX_ROUNDS = 2
+import os as _os
+
+
+def _resolve_max_rounds() -> int:
+    """Conversational round cap before the coach must commit best-effort.
+
+    Trial mode collapses the coach to a single round (default 1) so a
+    leaked password can't drive the chatbot in a loop. Operators override
+    via WARGAME_TRIAL_COACH_ROUNDS. Outside trial mode the historical
+    behaviour (2 rounds) stands.
+    """
+    if _os.getenv("WARGAME_TRIAL_MODE", "").strip() in ("1", "true", "yes", "on"):
+        try:
+            return max(int(_os.getenv("WARGAME_TRIAL_COACH_ROUNDS", "1")), 1)
+        except ValueError:
+            return 1
+    return 2
+
+
+# Public constant kept for back-compat; readers should call
+# `_resolve_max_rounds()` directly. The constant is recomputed at import
+# time from env, which is fine for the single-process FastAPI server but
+# means tests that flip env via monkeypatch must call _resolve_max_rounds()
+# (or reload this module) to pick up the change.
+MAX_ROUNDS = _resolve_max_rounds()
 
 
 # ---------------------------------------------------------------------------
@@ -119,7 +140,7 @@ class ActionCoachSession(BaseModel):
         ge=0,
         description=(
             "Number of user-message / coach-reply rounds consumed so far. "
-            f"Capped at {MAX_ROUNDS}; round {MAX_ROUNDS + 1} forces ready."
+            f"Capped at {_resolve_max_rounds()}; round {_resolve_max_rounds() + 1} forces ready."
         ),
     )
     status: Literal["gathering", "ready", "committed"] = "gathering"
@@ -346,12 +367,12 @@ def advance_session(
         company_name=scenario.company_name,
         rival_name=scenario.rival_name,
         player_role=scenario.player_role,
-        max_rounds=str(MAX_ROUNDS),
+        max_rounds=str(_resolve_max_rounds()),
     )
     user = (
         f"## Game state\n\n"
         f"- Turn: **{game.world.turn} of {game.world.max_turns}**\n"
-        f"- Rounds used in this coach session: **{session.rounds_used} of {MAX_ROUNDS}**\n"
+        f"- Rounds used in this coach session: **{session.rounds_used} of {_resolve_max_rounds()}**\n"
         f"- Public narrative: {game.world.public_narrative or '_(none yet)_'}\n"
         f"- Media tone: {game.world.media_tone.value}\n\n"
         f"## Current briefing\n\n{_briefing_summary_for_coach(game)}\n\n"
@@ -377,9 +398,9 @@ def advance_session(
     )
 
     # Force a downgrade if the round budget is exhausted but the model still
-    # wants to ask another question. Round MAX_ROUNDS is the LAST allowed
+    # wants to ask another question. The last allowed round is _resolve_max_rounds().
     # round, so any 'asking' response on or after that round must commit.
-    if session.rounds_used >= MAX_ROUNDS and raw.status == "asking":
+    if session.rounds_used >= _resolve_max_rounds() and raw.status == "asking":
         raw = _force_best_effort(raw, transcript=transcript)
 
     # Belt-and-braces: if the model says 'ready' but didn't include a draft,

wargame/api/app.py

@@ -120,8 +120,16 @@ def create_app() -> FastAPI:
         # otherwise break CORS handshakes and HF Space healthchecks.
         elif request.method == "OPTIONS" or request.url.path == "/healthz":
             pass
-        elif request.headers.get("X-Trial-Password") != password:
-            return JSONResponse({"detail": "Unauthorized"}, status_code=401)
+        else:
+            # Browsers' EventSource API can't attach custom headers, so SSE
+            # endpoints accept the password as a `?token=` query param too.
+            # Anything else still requires the X-Trial-Password header.
+            supplied = (
+                request.headers.get("X-Trial-Password")
+                or request.query_params.get("token")
+            )
+            if supplied != password:
+                return JSONResponse({"detail": "Unauthorized"}, status_code=401)
         # Trial-mode: refuse expensive endpoints up front so a leaked
         # password can't drain the Azure budget through them.
         if _is_disabled(request.method, request.url.path):

wargame/engine/loop.py

@@ -13,8 +13,21 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import threading
 
+
+def _trial_mode_active() -> bool:
+    """Whether WARGAME_TRIAL_MODE is set in any of the truthy variants.
+
+    Used by both new_game (max_turns cap) and advance (skip eval phases)
+    to gate trial-mode-only shrinks. Cheap to call — re-reads env every
+    time so an operator change takes effect without a restart.
+    """
+    return os.getenv("WARGAME_TRIAL_MODE", "").strip() in (
+        "1", "true", "yes", "on",
+    )
+
 from wargame.agents import constraint_checker, rival_ceo
 from wargame.agents.base import begin_turn_usage, end_turn_usage, use_game_language
 from wargame.agents.registry import ScenarioConfig, load_scenario
@@ -145,10 +158,9 @@ def new_game(
     # can't drive a full 5-turn game (~80 LLM calls) in one click. Default
     # is 1 — a single decision plus debrief. Operators can override via
     # WARGAME_TRIAL_MAX_TURNS. No effect when WARGAME_TRIAL_MODE is unset.
-    import os as _os
-    if _os.getenv("WARGAME_TRIAL_MODE", "").strip() in ("1", "true", "yes", "on"):
+    if _trial_mode_active():
         try:
-            world.max_turns = max(int(_os.getenv("WARGAME_TRIAL_MAX_TURNS", "1")), 1)
+            world.max_turns = max(int(os.getenv("WARGAME_TRIAL_MAX_TURNS", "1")), 1)
         except ValueError:
             world.max_turns = 1
 
@@ -341,7 +353,11 @@ def advance(game: Game, *, generate_next_briefing: bool = True) -> Game:
                     )
                 _check_pause(game, current)
 
-                if not current.critic_assessments:
+                # Trial mode skips critic + premortem to cut ~2 LLM calls per
+                # turn. They enrich the debrief but aren't part of the core
+                # narrative reveal that matters for a quick demo.
+                _trial = _trial_mode_active()
+                if not _trial and not current.critic_assessments:
                     events.publish(
                         PhaseEventKind.PHASE_STARTED, label="critic"
                     )
@@ -351,7 +367,7 @@ def advance(game: Game, *, generate_next_briefing: bool = True) -> Game:
                     )
                 _check_pause(game, current)
 
-                if not current.pre_mortems:
+                if not _trial and not current.pre_mortems:
                     events.publish(
                         PhaseEventKind.PHASE_STARTED, label="premortem"
                     )
@@ -371,7 +387,8 @@ def advance(game: Game, *, generate_next_briefing: bool = True) -> Game:
                     )
                 _check_pause(game, current)
 
-                if not current.evaluator_scores and current.verdicts:
+                # Evaluator scores are also skipped in trial mode (1 LLM call).
+                if not _trial and not current.evaluator_scores and current.verdicts:
                     events.publish(
                         PhaseEventKind.PHASE_STARTED, label="evaluator"
                     )

wargame/tests/test_trial_safeguards.py

@@ -94,6 +94,52 @@ def test_trial_mode_keeps_core_loop_open(monkeypatch):
         assert r.status_code == 200, f"{path} should be reachable in trial mode"
 
 
+def test_sse_stream_accepts_token_query_param(monkeypatch, tmp_path):
+    """EventSource can't attach custom headers, so the SSE endpoint must
+    accept the password as `?token=...`. Header still works too."""
+    monkeypatch.setenv("WARGAME_TRIAL_PASSWORD", "letmein")
+    monkeypatch.setenv("WARGAME_GAMES_DIR", str(tmp_path))
+    app = _fresh_app(monkeypatch)
+    client = TestClient(app)
+    # No password -> 401
+    r = client.get("/games/nope/stream")
+    assert r.status_code == 401
+    # Header -> reaches the route, which 404s on unknown game
+    r = client.get("/games/nope/stream", headers={"X-Trial-Password": "letmein"})
+    assert r.status_code == 404
+    # Query param -> same as header
+    r = client.get("/games/nope/stream?token=letmein")
+    assert r.status_code == 404
+    # Wrong query param -> 401
+    r = client.get("/games/nope/stream?token=wrong")
+    assert r.status_code == 401
+
+
+def test_action_coach_max_rounds_in_trial_mode(monkeypatch):
+    monkeypatch.setenv("WARGAME_TRIAL_MODE", "1")
+    from wargame.agents import action_coach
+
+    importlib.reload(action_coach)
+    assert action_coach._resolve_max_rounds() == 1
+
+
+def test_action_coach_max_rounds_default(monkeypatch):
+    monkeypatch.delenv("WARGAME_TRIAL_MODE", raising=False)
+    from wargame.agents import action_coach
+
+    importlib.reload(action_coach)
+    assert action_coach._resolve_max_rounds() == 2
+
+
+def test_action_coach_max_rounds_overridable(monkeypatch):
+    monkeypatch.setenv("WARGAME_TRIAL_MODE", "1")
+    monkeypatch.setenv("WARGAME_TRIAL_COACH_ROUNDS", "3")
+    from wargame.agents import action_coach
+
+    importlib.reload(action_coach)
+    assert action_coach._resolve_max_rounds() == 3
+
+
 def test_password_gate_still_runs_in_trial_mode(monkeypatch):
     """Disabling endpoints must not bypass the password gate — otherwise a
     503 leaks the existence of those routes to unauthenticated callers."""