Action Coach (conversational action input) + orchestrator post-action guard (#6)

* Add post-action guard to orchestrator route + UI gate

The orchestrator clones a pristine Turn 1 to fork branches; clone_pristine
raises ValueError if the source has already played. The route silently
passed the request through, the worker swallowed the exception, and the UI
showed three failed branches with no usable signal. Now the route rejects
with 409 when game.world.turn > 1, the first turn has a player_action, or
phase != BRIEFING. The frontend hides the launch button under the same
conditions and shows a one-line helper pointing the user at fork.

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

* Add Action Coach: conversational action input that drafts 3-anchor ActionSubmissions

Adds a small LLM-driven coach that turns CEO prose into the engine's exact
action contract (intent + justification + 3 anchors of valid kind). Mirrors
the setup_agent shape: one structured-output call per turn, JSON session
storage under games_dir/action_coach_sessions/, capped at 2 conversational
rounds, downgrade-to-ready when the budget is exhausted. The coach is a
pre-validation layer — on commit it submits the structured action through
the existing loop.act path so the engine still owns validation and the
3-anchor contract is enforced at the Pydantic boundary.

New endpoints (all appended at end of routes.py to stay clear of the
orchestrator section another agent is patching):

- POST /games/{id}/actions/coach (start session with initial_prose)
- POST /games/{id}/actions/coach/{session_id}/answer (one CEO message)
- POST /games/{id}/actions/coach/{session_id}/commit (submit via engine)
- GET /games/{id}/actions/coach/{session_id}

Frontend adds a "Talk to coach" / "Manual" tab strip inside the existing
nh-composer block in GameView.tsx — Coach is the default, Manual is the
escape hatch into the form. The coach UI mirrors SetupCase.tsx's chat
shape (nh-chat / nh-msg classes). The orchestrator UI block is untouched.

Tests: 9 new offline tests via fake_llm covering one-shot ready, ask-then-
ready, round-cap forces ready, commit-via-engine, and the four endpoints.
156 -> 165 tests, all passing.

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

* Action Coach: anchor the CEO's intent verbatim, no silent reframing

The original prompt let the LLM upgrade the move into the version it
considered wiser — turning a free-standing Transparenzbeirat into a
narrowed Stiftungsrat-mandated review, etc. CEO playtesters flagged
that as the coach overruling them.

Tighten the contract: the `intent` field is the CEO's move, faithfully
captured. Risk flags belong in `message_to_user`. The coach may only
rewrite the move when the prose is incoherent or when the CEO explicitly
asks for pushback.

---------

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

frontend/src/api.ts

@@ -67,6 +67,25 @@ export const api = {
     req<OrchestrateStatus>(`/games/${game_id}/orchestrate/status`),
   orchestrateResult: (game_id: string) =>
     req<ScenarioMap>(`/games/${game_id}/orchestrate/result`),
+
+  // Action Coach — conversational action input that drafts a 3-anchor
+  // ActionSubmission and submits it through the same engine path.
+  actionCoachStart: (game_id: string, initial_prose: string) =>
+    req<ActionCoachSession>(`/games/${game_id}/actions/coach`, {
+      method: 'POST',
+      body: JSON.stringify({ initial_prose }),
+    }),
+  actionCoachLoad: (game_id: string, session_id: string) =>
+    req<ActionCoachSession>(`/games/${game_id}/actions/coach/${session_id}`),
+  actionCoachAnswer: (game_id: string, session_id: string, message: string) =>
+    req<ActionCoachSession>(`/games/${game_id}/actions/coach/${session_id}/answer`, {
+      method: 'POST',
+      body: JSON.stringify({ message }),
+    }),
+  actionCoachCommit: (game_id: string, session_id: string) =>
+    req<ActionAcceptedResponse>(`/games/${game_id}/actions/coach/${session_id}/commit`, {
+      method: 'POST',
+    }),
 };
 
 export type AnchorKind = 'prior_analogue' | 'stated_capability' | 'resource_committed';
@@ -151,3 +170,27 @@ export interface ScenarioMap {
   branches_complete: number;
   error: string | null;
 }
+
+// Action Coach — conversational action input.
+export interface ActionDraft {
+  intent: string;
+  justification: string;
+  anchors: Anchor[];
+}
+export interface CoachMessage {
+  role: 'user' | 'coach';
+  content: string;
+  at: string;
+}
+export type ActionCoachStatus = 'gathering' | 'ready' | 'committed';
+export interface ActionCoachSession {
+  session_id: string;
+  game_id: string;
+  turn: number;
+  status: ActionCoachStatus;
+  rounds_used: number;
+  last_coach_message: string;
+  synthesized_draft: ActionDraft | null;
+  committed: boolean;
+  messages: CoachMessage[];
+}

frontend/src/screens/GameView.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
-import { api, Briefing, Anchor, AnchorKind, ScenarioMap, AgentInfo } from '../api';
+import { api, Briefing, Anchor, AnchorKind, ScenarioMap, AgentInfo, ActionCoachSession, CoachMessage } from '../api';
 import { navigate } from '../App';
 import { Dossier, Panel, PhaseRail, Spinner } from '../components/Shell';
 
@@ -47,6 +47,15 @@ export function GameView({ id, onMeta }: Props) {
   const [submitBusy, setSubmitBusy] = useState(false);
   const [actionSent, setActionSent] = useState(false);
 
+  // Action Coach (conversational mode) — defaults to on so the CEO can
+  // talk through the move; "Manual" is an escape hatch into the form.
+  const [composerMode, setComposerMode] = useState<'coach' | 'manual'>('coach');
+  const [coachSession, setCoachSession] = useState<ActionCoachSession | null>(null);
+  const [coachInput, setCoachInput] = useState('');
+  const [coachBusy, setCoachBusy] = useState(false);
+  const [coachErr, setCoachErr] = useState<string | null>(null);
+  const coachThreadRef = useRef<HTMLDivElement | null>(null);
+
   // Advance
   const [advanceBusy, setAdvanceBusy] = useState(false);
   const [advanceLog, setAdvanceLog] = useState<string[]>([]);
@@ -161,6 +170,11 @@ export function GameView({ id, onMeta }: Props) {
 
   const anchorsFilled = anchors.filter((a) => a.detail.trim()).length;
   const canSubmit = intent.trim() && why.trim() && anchorsFilled >= 3;
+  const firstTurnAction = state?.turns?.[0]?.player_action ?? null;
+  const canRunOrchestrator =
+    !actionSent
+    && (state?.world?.turn ?? 1) <= 1
+    && firstTurnAction == null;
 
   async function askRecon() {
     if (!reconQ.trim() || budget <= 0) return;
@@ -197,6 +211,67 @@ export function GameView({ id, onMeta }: Props) {
     setSubmitBusy(false);
   }
 
+  // ---- Action Coach -----------------------------------------------------
+
+  async function startCoach() {
+    if (!coachInput.trim() || coachBusy) return;
+    setCoachBusy(true); setCoachErr(null);
+    const prose = coachInput.trim();
+    setCoachInput('');
+    try {
+      const s = await api.actionCoachStart(id, prose);
+      setCoachSession(s);
+    } catch (e) {
+      setCoachErr(String(e));
+      setCoachInput(prose);
+    }
+    setCoachBusy(false);
+  }
+
+  async function answerCoach() {
+    if (!coachSession || !coachInput.trim() || coachBusy) return;
+    setCoachBusy(true); setCoachErr(null);
+    const msg = coachInput.trim();
+    setCoachInput('');
+    try {
+      const s = await api.actionCoachAnswer(id, coachSession.session_id, msg);
+      setCoachSession(s);
+    } catch (e) {
+      setCoachErr(String(e));
+      setCoachInput(msg);
+    }
+    setCoachBusy(false);
+  }
+
+  async function commitCoach() {
+    if (!coachSession || coachSession.status !== 'ready' || coachBusy) return;
+    setCoachBusy(true); setCoachErr(null);
+    try {
+      await api.actionCoachCommit(id, coachSession.session_id);
+      // Mirror submitAction: flip to 'submitted' UI and let the user advance
+      setActionSent(true);
+      setPhase('action');
+      // Clear the coach session locally (server still has it for reference)
+      setCoachSession(null);
+    } catch (e) {
+      setCoachErr(String(e));
+    }
+    setCoachBusy(false);
+  }
+
+  function resetCoach() {
+    setCoachSession(null);
+    setCoachErr(null);
+    setCoachInput('');
+  }
+
+  // Auto-scroll the coach thread to the latest message.
+  useEffect(() => {
+    if (coachThreadRef.current) {
+      coachThreadRef.current.scrollTop = coachThreadRef.current.scrollHeight;
+    }
+  }, [coachSession?.messages.length, coachBusy]);
+
   async function advance() {
     setAdvanceBusy(true);
     setPhase('deliberation');
@@ -224,6 +299,7 @@ export function GameView({ id, onMeta }: Props) {
       ]);
       setReconLog([]);
       setPhase('briefing');
+      resetCoach();
       await loadAll();
       setAdvanceLog([]);
     } catch (e) {
@@ -407,13 +483,33 @@ export function GameView({ id, onMeta }: Props) {
         onToggle={() => setOrchOpen((v) => !v)}
         onRun={runOrchestrator}
         onAdopt={adoptOpener}
+        canRun={canRunOrchestrator}
       />
 
       {/* ACTION COMPOSER */}
       <section className={`nh-composer ${actionSent ? 'submitted' : ''}`}>
         <div className="nh-composer__hd">
           <h2>Your move, Turn {turn}</h2>
-          <span className="hint">Three anchors required</span>
+          {actionSent ? (
+            <span className="hint">Submitted</span>
+          ) : (
+            <div role="tablist" aria-label="Composer mode" style={{ display: 'flex', gap: 6 }}>
+              <button
+                role="tab"
+                aria-selected={composerMode === 'coach'}
+                className={`btn sm ${composerMode === 'coach' ? 'primary' : 'ghost'}`}
+                onClick={() => setComposerMode('coach')}
+                disabled={submitBusy || coachBusy}
+              >Talk to coach</button>
+              <button
+                role="tab"
+                aria-selected={composerMode === 'manual'}
+                className={`btn sm ${composerMode === 'manual' ? 'primary' : 'ghost'}`}
+                onClick={() => setComposerMode('manual')}
+                disabled={submitBusy || coachBusy}
+              >Manual</button>
+            </div>
+          )}
         </div>
 
         {actionSent ? (
@@ -429,6 +525,32 @@ export function GameView({ id, onMeta }: Props) {
               </button>
             </div>
           </>
+        ) : composerMode === 'coach' ? (
+          <ActionCoachThread
+            session={coachSession}
+            input={coachInput}
+            setInput={setCoachInput}
+            busy={coachBusy}
+            err={coachErr}
+            threadRef={coachThreadRef}
+            onStart={startCoach}
+            onAnswer={answerCoach}
+            onCommit={commitCoach}
+            onReset={resetCoach}
+            onSwitchToManualWithDraft={() => {
+              // Pre-fill the manual form with the draft so the user can tweak.
+              const d = coachSession?.synthesized_draft;
+              if (d) {
+                setIntent(d.intent.slice(0, 160));
+                setWhy(d.justification.slice(0, 400));
+                if (Array.isArray(d.anchors) && d.anchors.length >= 3) {
+                  setAnchors(d.anchors.slice(0, 5).map((a) => ({ kind: a.kind, detail: a.detail })));
+                }
+              }
+              setComposerMode('manual');
+            }}
+            turn={turn}
+          />
         ) : (
           <>
             <div className="nh-formrow">
@@ -645,7 +767,7 @@ function VerdictHistory({
 }
 
 function OrchestratorBar({
-  map, error, open, onToggle, onRun, onAdopt,
+  map, error, open, onToggle, onRun, onAdopt, canRun,
 }: {
   map: ScenarioMap | null;
   error: string | null;
@@ -653,6 +775,7 @@ function OrchestratorBar({
   onToggle: () => void;
   onRun: () => void;
   onAdopt: (branch: ScenarioMap['branches'][number]) => void;
+  canRun: boolean;
 }) {
   const running = map?.status === 'running' || map?.status === 'pending';
   const failed = map?.status === 'failed';
@@ -699,9 +822,15 @@ function OrchestratorBar({
             Three strategy vectors will play a proxy version of this turn at different skill temperatures.
             You get a side-by-side outcome read before you commit your own move. Takes 3–5 minutes.
           </p>
-          <button className="btn primary" onClick={onRun}>
-            Run orchestrator →
-          </button>
+          {canRun ? (
+            <button className="btn primary" onClick={onRun}>
+              Run orchestrator →
+            </button>
+          ) : (
+            <span className="help mono fg-3">
+              Orchestrator only runs pre-action — fork from Turn 1 to re-run.
+            </span>
+          )}
         </div>
       )}
 
@@ -752,7 +881,13 @@ function OrchestratorBar({
       {failed && open && (
         <div className="nh-orch__failed">
           <p style={{ color: 'var(--oxblood)' }}>Orchestration failed: {map?.error || 'unknown error'}</p>
-          <button className="btn ghost sm" onClick={onRun}>Retry →</button>
+          {canRun ? (
+            <button className="btn ghost sm" onClick={onRun}>Retry →</button>
+          ) : (
+            <span className="help mono fg-3">
+              Orchestrator only runs pre-action — fork from Turn 1 to re-run.
+            </span>
+          )}
         </div>
       )}
 
@@ -825,7 +960,13 @@ function OrchestratorBar({
             </details>
           )}
           <div className="nh-orch__ft">
-            <button className="btn ghost sm" onClick={onRun}>Re-run orchestrator →</button>
+            {canRun ? (
+              <button className="btn ghost sm" onClick={onRun}>Re-run orchestrator →</button>
+            ) : (
+              <span className="help mono fg-3">
+                Orchestrator only runs pre-action — fork from Turn 1 to re-run.
+              </span>
+            )}
           </div>
         </>
       )}
@@ -842,3 +983,220 @@ function nowHM() {
   const d = new Date();
   return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}`;
 }
+
+// ---------------------------------------------------------------------------
+// Action Coach — chat thread that turns prose into a 3-anchor ActionSubmission.
+// Shape mirrors SetupCase.tsx's nh-chat / nh-msg classes for consistency.
+// ---------------------------------------------------------------------------
+
+function ActionCoachThread({
+  session,
+  input,
+  setInput,
+  busy,
+  err,
+  threadRef,
+  onStart,
+  onAnswer,
+  onCommit,
+  onReset,
+  onSwitchToManualWithDraft,
+  turn,
+}: {
+  session: ActionCoachSession | null;
+  input: string;
+  setInput: (s: string) => void;
+  busy: boolean;
+  err: string | null;
+  threadRef: React.MutableRefObject<HTMLDivElement | null>;
+  onStart: () => void;
+  onAnswer: () => void;
+  onCommit: () => void;
+  onReset: () => void;
+  onSwitchToManualWithDraft: () => void;
+  turn: number;
+}) {
+  const hasSession = session !== null;
+  const ready = session?.status === 'ready';
+  const draft = session?.synthesized_draft ?? null;
+
+  return (
+    <div className="nh-chat-app" style={{ marginTop: 8 }}>
+      <div className="nh-chat">
+        {!hasSession ? (
+          // Intro — collect initial prose before kicking off the coach.
+          <div className="nh-chat__input">
+            <p className="fg-2" style={{ marginTop: 0, marginBottom: 12 }}>
+              Describe your move in plain prose. The coach will draft a structured action with three anchors —
+              the matrix-game umpire scores plausibility against those anchors, so specificity matters. If a
+              critical anchor is ambiguous, the coach will ask one focused question. Capped at two rounds.
+            </p>
+            <form onSubmit={(e) => { e.preventDefault(); onStart(); }}>
+              <textarea
+                value={input}
+                rows={5}
+                maxLength={4000}
+                placeholder="e.g. Pre-empt Aergis by locking Helvetia at 14% effective before they sign the LoI. Anchor it on the 2022 Helvetia renewal — we have the Horizont-X UNI 11300 validation and a EUR 500k/quarter penalty cap signed by Lange."
+                onChange={(e) => setInput(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
+                    e.preventDefault(); onStart();
+                  }
+                }}
+                disabled={busy}
+              />
+              <div className="nh-chat__submit">
+                <span className="hint">{input.length} / 4000 · Ctrl/Cmd+Enter to send</span>
+                <button
+                  type="submit"
+                  className="btn primary"
+                  disabled={!input.trim() || busy}
+                >
+                  {busy ? <><Spinner /> Drafting…</> : 'Talk to coach →'}
+                </button>
+              </div>
+            </form>
+            {err && <p style={{ color: 'var(--oxblood)', marginTop: 10 }}>{err}</p>}
+          </div>
+        ) : (
+          <>
+            <div className="nh-chat__thread" ref={threadRef}>
+              {(session?.messages ?? []).map((m, i) => (
+                <CoachMsg key={i} m={m} />
+              ))}
+              {busy && (
+                <div className="nh-msg control">
+                  <div className="nh-msg__meta"><span>Coach</span> drafting…</div>
+                  <div className="nh-msg__body"><Spinner /></div>
+                </div>
+              )}
+            </div>
+
+            {/* Draft preview when one exists (partial during 'asking', complete on 'ready'). */}
+            {draft && (
+              <div className="nh-spec">
+                <span className="eyebrow">
+                  Draft action {ready ? '· ready to submit' : `· in progress (${session?.rounds_used ?? 0}/2 rounds)`}
+                </span>
+                <CoachDraftCard draft={draft} />
+                <div className="nh-spec__fn" style={{ marginTop: 6 }}>
+                  Submitting locks this move for Turn {turn}.
+                </div>
+              </div>
+            )}
+
+            {ready ? (
+              <div className="nh-chat__approve">
+                <div>
+                  <span className="eyebrow">Approve to submit</span>
+                  <div className="hd">Commit draft as your Turn {turn} action</div>
+                </div>
+                <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+                  <button className="btn ghost sm" onClick={onSwitchToManualWithDraft} disabled={busy}>
+                    Edit in Manual →
+                  </button>
+                  <button className="btn ghost sm" onClick={onReset} disabled={busy}>
+                    Restart
+                  </button>
+                  <button className="btn primary" onClick={onCommit} disabled={busy}>
+                    {busy ? <><Spinner /> Submitting…</> : 'Submit action →'}
+                  </button>
+                </div>
+              </div>
+            ) : (
+              <div className="nh-chat__input">
+                <form onSubmit={(e) => { e.preventDefault(); onAnswer(); }}>
+                  <textarea
+                    value={input}
+                    rows={4}
+                    maxLength={4000}
+                    placeholder="Your reply… (Ctrl/Cmd+Enter to send)"
+                    onChange={(e) => setInput(e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
+                        e.preventDefault(); onAnswer();
+                      }
+                    }}
+                    disabled={busy}
+                  />
+                  <div className="nh-chat__submit">
+                    <span className="hint">
+                      {input.length} / 4000 · round {(session?.rounds_used ?? 0) + 1} of 2
+                    </span>
+                    <button
+                      type="submit"
+                      className="btn primary"
+                      disabled={!input.trim() || busy}
+                    >
+                      {busy ? <><Spinner /> Sending…</> : 'Send →'}
+                    </button>
+                  </div>
+                </form>
+                <div style={{ marginTop: 8 }}>
+                  <button className="btn ghost sm" onClick={onReset} disabled={busy}>
+                    Restart conversation
+                  </button>
+                </div>
+              </div>
+            )}
+            {err && <p style={{ color: 'var(--oxblood)', margin: '10px 0' }}>{err}</p>}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function CoachMsg({ m }: { m: CoachMessage }) {
+  const who = m.role === 'user' ? 'user' : 'control';
+  const label = m.role === 'user' ? 'You' : 'Coach';
+  return (
+    <div className={`nh-msg ${who}`}>
+      <div className="nh-msg__meta"><span>{label}</span> {fmtCoachAt(m.at)}</div>
+      <div className="nh-msg__body">
+        {m.role === 'coach' ? (
+          <div className="setup-md">
+            <ReactMarkdown remarkPlugins={[remarkGfm]}>{m.content}</ReactMarkdown>
+          </div>
+        ) : (
+          <div style={{ whiteSpace: 'pre-wrap' }}>{m.content}</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function CoachDraftCard({ draft }: { draft: NonNullable<ActionCoachSession['synthesized_draft']> }) {
+  return (
+    <div style={{ display: 'grid', gap: 10, fontSize: 14, lineHeight: 1.55 }}>
+      <div>
+        <div className="eyebrow" style={{ marginBottom: 2 }}>Intent</div>
+        <div style={{ fontWeight: 600 }}>{draft.intent}</div>
+      </div>
+      <div>
+        <div className="eyebrow" style={{ marginBottom: 2 }}>Why now</div>
+        <div>{draft.justification}</div>
+      </div>
+      <div>
+        <div className="eyebrow" style={{ marginBottom: 4 }}>Anchors · {draft.anchors.length} of 3</div>
+        <ul style={{ margin: 0, paddingLeft: 18 }}>
+          {draft.anchors.map((a, i) => (
+            <li key={i} style={{ marginBottom: 4 }}>
+              <span className="mono" style={{ fontSize: 11, textTransform: 'uppercase', letterSpacing: '0.04em' }}>
+                {a.kind.replace(/_/g, ' ')}
+              </span>{' '}
+              — {a.detail}
+            </li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  );
+}
+
+function fmtCoachAt(at: string) {
+  try {
+    const d = new Date(at);
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+  } catch { return ''; }
+}

wargame/agents/action_coach.py

@@ -0,0 +1,459 @@
+"""Action Coach — turn natural-language prose into a 3-anchor ActionSubmission.
+
+The standard composer makes the player type the intent, justification, and
+three structured anchors by hand. CEO playtesters find that too form-like.
+The Action Coach is a small conversational agent that takes free-form prose
+and either (a) returns a complete `ActionDraft` ready to commit, or (b) asks
+ONE focused clarifying question when a critical anchor is genuinely
+ambiguous. Capped at 2 conversational rounds — round 2 forces best-effort.
+
+This is a *pre-validation* layer. It produces a valid `ActionSubmission`
+that goes through the existing `loop.act` engine path, so the action
+contract (3 anchors, all of valid kind) is still enforced at the engine
+boundary.
+
+Design shape mirrors `wargame/scaffold/setup_agent.py`:
+- One LLM call per turn via `call_structured`.
+- JSON-file persistence per session.
+- Round budget tracked on the session; downgrade-to-ready when capped.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from wargame.agents.base import call_structured
+from wargame.agents.prompts_loader import render
+from wargame.config import settings
+from wargame.engine.state import ActionSubmission, Anchor, AnchorKind
+
+if TYPE_CHECKING:
+    from wargame.agents.registry import ScenarioConfig
+    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
+
+
+# ---------------------------------------------------------------------------
+# Pydantic models — session state, draft shape, LLM output schema
+# ---------------------------------------------------------------------------
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class CoachMessage(BaseModel):
+    role: Literal["user", "coach"]
+    content: str
+    at: str = Field(default_factory=_now)
+
+
+class ActionDraft(BaseModel):
+    """A drafted action — same shape the engine accepts, minus actor.
+
+    Pydantic enforces exactly 3 anchors; each anchor's kind is one of the
+    three valid AnchorKind values via the engine-side Anchor model. This
+    matches the action contract one-to-one — when the user commits, we
+    just bolt `actor='player'` on top and submit through `loop.act`.
+    """
+
+    intent: str = Field(min_length=3, max_length=600)
+    justification: str = Field(min_length=3, max_length=1500)
+    anchors: list[Anchor] = Field(min_length=3, max_length=3)
+
+    def to_submission(self) -> ActionSubmission:
+        return ActionSubmission(
+            actor="player",
+            intent=self.intent,
+            justification=self.justification,
+            anchors=[a for a in self.anchors],
+        )
+
+
+class CoachTurnLLMOutput(BaseModel):
+    """Structured LLM output for one turn of the action-coach conversation.
+
+    `status="ready"` means the coach has a confident draft and the user can
+    confirm or commit. `status="asking"` means the coach is asking ONE
+    focused clarifying question — `proposed_draft` may still be present
+    (partial), so the UI can show progress.
+    """
+
+    status: Literal["asking", "ready"]
+    message_to_user: str = Field(min_length=15, max_length=4000)
+    proposed_draft: ActionDraft | None = Field(
+        default=None,
+        description=(
+            "Required when status='ready'. Optional when status='asking' — "
+            "if present, surfaces the coach's current best draft so the UI "
+            "can show progress as anchors firm up."
+        ),
+    )
+
+
+class ActionCoachSession(BaseModel):
+    """Multi-turn state for one action-coach conversation."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    game_id: str
+    turn: int = Field(
+        ge=1,
+        description="The game turn this session is composing an action for.",
+    )
+    created_at: str = Field(default_factory=_now)
+    updated_at: str = Field(default_factory=_now)
+    messages: list[CoachMessage] = Field(default_factory=list)
+    rounds_used: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Number of user-message / coach-reply rounds consumed so far. "
+            f"Capped at {MAX_ROUNDS}; round {MAX_ROUNDS + 1} forces ready."
+        ),
+    )
+    status: Literal["gathering", "ready", "committed"] = "gathering"
+    synthesized_draft: ActionDraft | None = None
+    committed: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+
+def _sessions_dir() -> Path:
+    d = settings().games_dir / "action_coach_sessions"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def session_path(session_id: str) -> Path:
+    return _sessions_dir() / f"{session_id}.json"
+
+
+def save_session(session: ActionCoachSession) -> Path:
+    session.updated_at = _now()
+    p = session_path(session.id)
+    p.write_text(session.model_dump_json(indent=2), encoding="utf-8")
+    return p
+
+
+def load_session(session_id: str) -> ActionCoachSession:
+    p = session_path(session_id)
+    if not p.exists():
+        raise FileNotFoundError(f"No action-coach session at {p}")
+    return ActionCoachSession.model_validate_json(p.read_text(encoding="utf-8"))
+
+
+def list_sessions() -> list[str]:
+    return sorted(p.name.removesuffix(".json") for p in _sessions_dir().glob("*.json"))
+
+
+# ---------------------------------------------------------------------------
+# LLM-driven conversation turn
+# ---------------------------------------------------------------------------
+
+
+def _render_transcript(session: ActionCoachSession) -> str:
+    if not session.messages:
+        return "_(empty — this is the start of the conversation)_"
+    lines: list[str] = []
+    for m in session.messages:
+        label = "CEO" if m.role == "user" else "Coach"
+        lines.append(f"**{label}**:\n{m.content.strip()}")
+    return "\n\n".join(lines)
+
+
+def _briefing_summary_for_coach(game: Game) -> str:
+    """Render the current turn's briefing as a compact prompt block.
+
+    The world bible is pinned via the system prompt; this user-message block
+    grounds the coach in *this* turn's situation so anchors can reference
+    named entities, numbers, and decisions actually on the table.
+    """
+    current = game.current_turn
+    if current is None or current.briefing is None:
+        return "_(no active briefing — coach will work from world bible only)_"
+    b = current.briefing
+    lines: list[str] = [
+        f"### Headline\n{b.headline}\n",
+        f"### Exec summary\n{b.exec_summary}\n",
+    ]
+    if b.sections:
+        lines.append("### Sections")
+        for s in b.sections:
+            lines.append(f"- **{s.heading}**: {s.body}")
+            if s.fog_of_war:
+                lines.append(f"  - Fog of war: {s.fog_of_war}")
+        lines.append("")
+    if b.decision_points:
+        lines.append("### Decision points on the table")
+        for dp in b.decision_points:
+            lines.append(f"- **{dp.title}** — {dp.context}")
+            if dp.example_actions:
+                lines.append(
+                    f"  - Examples: {', '.join(dp.example_actions)}"
+                )
+    return "\n".join(lines)
+
+
+def _recon_summary_for_coach(game: Game) -> str:
+    """Compact recon log for this turn so anchors can reference what was learned."""
+    current = game.current_turn
+    if current is None or not current.recon_queries:
+        return "_(no recon spent this turn yet)_"
+    lines = []
+    for r in current.recon_queries:
+        lines.append(
+            f"- **{r.answered_by}** asked: {r.question!r} → {r.answer}"
+        )
+    return "\n".join(lines)
+
+
+def _force_best_effort(
+    raw: CoachTurnLLMOutput,
+    *,
+    transcript: str,
+) -> CoachTurnLLMOutput:
+    """When the round budget is exhausted, force the coach to commit.
+
+    If the LLM's last reply was 'asking', we synthesize best-effort anchors
+    from whatever partial draft it provided. Empty/missing fields fall back
+    to the surrounding transcript prose. The user is told what was inferred
+    vs. provided so they can reject.
+    """
+    if raw.status == "ready" and raw.proposed_draft:
+        return raw
+
+    partial = raw.proposed_draft
+    intent = (
+        partial.intent
+        if partial and partial.intent
+        else _fallback_intent_from_transcript(transcript)
+    )
+    justification = (
+        partial.justification
+        if partial and partial.justification
+        else (
+            "Best-effort synthesis from the prose. The coach was unable to "
+            "elicit a fully-grounded justification within the conversation "
+            "budget; review carefully before advancing."
+        )
+    )
+    anchors = _ensure_three_anchors(partial.anchors if partial else [])
+
+    note = (
+        raw.message_to_user
+        + "\n\n— **Round budget reached.** I've committed best-effort "
+        "anchors based on the prose; please review the inferred draft before "
+        "you submit, and edit any line that doesn't match your intent."
+    )
+
+    return CoachTurnLLMOutput(
+        status="ready",
+        message_to_user=note,
+        proposed_draft=ActionDraft(
+            intent=intent,
+            justification=justification,
+            anchors=anchors,
+        ),
+    )
+
+
+def _fallback_intent_from_transcript(transcript: str) -> str:
+    """Pull the first non-empty CEO line as a last-resort intent."""
+    for block in transcript.split("\n\n"):
+        cleaned = block.strip()
+        if cleaned.startswith("**CEO**:"):
+            text = cleaned.split(":", 1)[-1].strip()
+            if text:
+                # Cap to first sentence-ish, max 400 chars (well within 600 cap).
+                first = text.split("\n", 1)[0].strip()
+                return first[:400] if first else "Action drawn from CEO prose."
+    return "Action drawn from CEO prose."
+
+
+def _ensure_three_anchors(partial: list[Anchor]) -> list[Anchor]:
+    """Pad / truncate a partial anchor list to exactly 3 of valid kinds.
+
+    Used only as a last-resort fallback when the round budget is exhausted
+    and the LLM still hasn't returned a complete draft. Each anchor's kind
+    is one of the three valid AnchorKind values; missing slots are filled
+    with explicit "best-effort" details so reviewers see they were inferred.
+    """
+    out: list[Anchor] = []
+    used_kinds: set[AnchorKind] = set()
+    for a in partial[:3]:
+        if a.detail.strip():
+            out.append(a)
+            used_kinds.add(a.kind)
+
+    needed_kinds_order = [
+        AnchorKind.PRIOR_ANALOGUE,
+        AnchorKind.STATED_CAPABILITY,
+        AnchorKind.RESOURCE_COMMITTED,
+    ]
+    for kind in needed_kinds_order:
+        if len(out) >= 3:
+            break
+        if kind in used_kinds:
+            continue
+        out.append(
+            Anchor(
+                kind=kind,
+                detail=(
+                    f"Best-effort {kind.value} placeholder — the coach could "
+                    "not extract a specific anchor of this kind from the prose. "
+                    "Edit before submitting."
+                ),
+            )
+        )
+        used_kinds.add(kind)
+    return out[:3]
+
+
+def advance_session(
+    session: ActionCoachSession,
+    user_message: str,
+    *,
+    game: Game,
+    scenario: ScenarioConfig,
+) -> CoachTurnLLMOutput:
+    """Append the user's message, call the LLM, save, return the structured turn."""
+    if session.committed or session.status == "committed":
+        raise ValueError("Session already committed — start a new one to iterate.")
+
+    session.messages.append(
+        CoachMessage(role="user", content=user_message.strip())
+    )
+    session.rounds_used += 1
+    transcript = _render_transcript(session)
+
+    system = render(
+        "action_coach",
+        world_bible=scenario.world_bible,
+        company_name=scenario.company_name,
+        rival_name=scenario.rival_name,
+        player_role=scenario.player_role,
+        max_rounds=str(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"- 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"
+        f"## Recon spent this turn\n\n{_recon_summary_for_coach(game)}\n\n"
+        f"## Conversation so far\n\n{transcript}\n\n"
+        f"## Your task\n\n"
+        f"Either ask exactly ONE tightly-scoped clarifying question "
+        f"(status='asking') or return the structured ActionDraft "
+        f"(status='ready', `proposed_draft` populated). Prefer 'ready' when "
+        f"you have 80%+ confidence — only ask when a critical anchor is "
+        f"genuinely ambiguous in the prose. Each anchor must be specific, "
+        f"verifiable, and reference named entities or numbers from the "
+        f"world bible / briefing where possible."
+    )
+
+    raw = call_structured(
+        schema=CoachTurnLLMOutput,
+        system=system,
+        user=user,
+        role="control",
+        temperature=0.5,
+        max_tokens=3500,
+    )
+
+    # 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
+    # round, so any 'asking' response on or after that round must commit.
+    if session.rounds_used >= 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,
+    # treat the same as the round-cap downgrade so we always have something
+    # the UI can show / commit.
+    if raw.status == "ready" and raw.proposed_draft is None:
+        raw = _force_best_effort(raw, transcript=transcript)
+
+    session.messages.append(
+        CoachMessage(role="coach", content=raw.message_to_user)
+    )
+    if raw.status == "ready":
+        session.status = "ready"
+        session.synthesized_draft = raw.proposed_draft
+    else:
+        session.status = "gathering"
+        # Track the partial draft for UI progress, even on 'asking'.
+        if raw.proposed_draft is not None:
+            session.synthesized_draft = raw.proposed_draft
+
+    save_session(session)
+    return raw
+
+
+def new_session(
+    *,
+    game: Game,
+    scenario: ScenarioConfig,
+    initial_prose: str,
+) -> tuple[ActionCoachSession, CoachTurnLLMOutput]:
+    """Start a session for the current turn of `game`. Runs the first LLM turn."""
+    session = ActionCoachSession(
+        game_id=game.id,
+        turn=game.world.turn,
+        messages=[],
+    )
+    save_session(session)
+    turn = advance_session(
+        session,
+        initial_prose,
+        game=game,
+        scenario=scenario,
+    )
+    return session, turn
+
+
+def commit_session(
+    session: ActionCoachSession,
+    *,
+    game: Game,
+) -> ActionSubmission:
+    """Submit the synthesized draft via the engine's `loop.act` path.
+
+    Returns the `ActionSubmission` that was accepted by the engine. Raises
+    if the session has no draft, the game is in the wrong phase, or the
+    engine rejects the action (e.g. invalid actor, wrong phase). The engine
+    is the authoritative validator — this function is just a thin wrapper.
+    """
+    from wargame.engine import loop
+
+    if session.committed or session.status == "committed":
+        raise ValueError("Session has already been committed.")
+    if session.synthesized_draft is None:
+        raise ValueError(
+            "Session has no synthesized draft yet — call advance_session "
+            "until status='ready' first."
+        )
+
+    submission = session.synthesized_draft.to_submission()
+    # Engine validates phase + actor + anchors at the boundary. If anything
+    # is wrong, this raises — we surface it untouched to the caller.
+    loop.act(game, submission)
+
+    session.status = "committed"
+    session.committed = True
+    save_session(session)
+    return submission

wargame/api/routes.py

@@ -18,6 +18,10 @@ from wargame.agents import registry as _registry
 from wargame.agents.registry import load_scenario
 from wargame.api.schemas import (
     ActionAcceptedResponse,
+    ActionCoachAnswerRequest,
+    ActionCoachSessionResponse,
+    ActionCoachStartRequest,
+    ActionDraftResponse,
     ActionRequest,
     AdvanceResponse,
     AgentInfo,
@@ -57,6 +61,7 @@ from wargame.api.schemas import (
 )
 from wargame.debrief.exporter import export_debrief
 from wargame.engine import loop, persistence
+from wargame.engine.state import Phase
 
 _SCENARIO_ID_RE = re.compile(r"^[a-z][a-z0-9_]{2,59}$")
 
@@ -632,6 +637,22 @@ def post_orchestrate(
             status_code=409,
             detail="Orchestrate can only be run on main games, not sim branches.",
         )
+    first_turn = game.turns[0] if game.turns else None
+    if (
+        game.world.turn > 1
+        or first_turn is None
+        or first_turn.player_action is not None
+        or first_turn.phase != Phase.BRIEFING
+    ):
+        phase_value = first_turn.phase.value if first_turn else "none"
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                f"Orchestrator can only run on a pristine Turn 1 (no action submitted yet). "
+                f"This game is at turn {game.world.turn} with phase={phase_value} — "
+                f"fork to a new game from turn 1 if you want to re-run the orchestrator."
+            ),
+        )
 
     # Seed a pending ScenarioMap so status polls work even before the thread starts
     scenario_map = ScenarioMap(
@@ -751,3 +772,172 @@ def get_turn_adjudication(game_id: str, turn: int) -> TurnAdjudicationResponse:
         verdicts=target.verdicts,
         challenges=target.challenges,
     )
+
+
+# ---------------------------------------------------------------------------
+# Action Coach (conversational action input)
+#
+# A small LLM that turns CEO prose into the engine's exact action contract:
+# intent + justification + 3 anchors. Mirrors the setup-agent shape — JSON
+# session storage, advance/commit endpoints, capped at 2 conversational
+# rounds. The actual action is submitted via the existing engine path on
+# commit, so the action contract is enforced exactly as the manual composer.
+# ---------------------------------------------------------------------------
+
+
+def _coach_response(session) -> ActionCoachSessionResponse:
+    """Render an ActionCoachSession into the wire response shape."""
+    last_coach = next(
+        (m for m in reversed(session.messages) if m.role == "coach"),
+        None,
+    )
+    draft_response: ActionDraftResponse | None = None
+    if session.synthesized_draft is not None:
+        draft_response = ActionDraftResponse(
+            intent=session.synthesized_draft.intent,
+            justification=session.synthesized_draft.justification,
+            anchors=list(session.synthesized_draft.anchors),
+        )
+    return ActionCoachSessionResponse(
+        session_id=session.id,
+        game_id=session.game_id,
+        turn=session.turn,
+        status=session.status,
+        rounds_used=session.rounds_used,
+        last_coach_message=last_coach.content if last_coach else "",
+        synthesized_draft=draft_response,
+        committed=session.committed,
+        messages=[m.model_dump() for m in session.messages],
+    )
+
+
+@router.post(
+    "/games/{game_id}/actions/coach",
+    response_model=ActionCoachSessionResponse,
+    status_code=201,
+)
+def post_action_coach_start(
+    game_id: str, body: ActionCoachStartRequest
+) -> ActionCoachSessionResponse:
+    """Start an action-coach session for the current turn of `game_id`."""
+    from wargame.agents.action_coach import new_session
+    from wargame.config import use_game_model
+
+    game = _load_or_404(game_id)
+    try:
+        scenario = load_scenario(game.scenario_id)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from None
+
+    # Pin the per-game model so the coach LLM call uses the same model the
+    # rest of this game uses (matches the setup_agent pattern indirectly —
+    # setup runs pre-game so it doesn't pin, but the coach is mid-game).
+    with use_game_model(game.llm_model):
+        session, _turn = new_session(
+            game=game,
+            scenario=scenario,
+            initial_prose=body.initial_prose,
+        )
+    return _coach_response(session)
+
+
+@router.get(
+    "/games/{game_id}/actions/coach/{session_id}",
+    response_model=ActionCoachSessionResponse,
+)
+def get_action_coach(
+    game_id: str, session_id: str
+) -> ActionCoachSessionResponse:
+    """Read the latest state of an action-coach session."""
+    from wargame.agents.action_coach import load_session
+
+    _load_or_404(game_id)
+    try:
+        session = load_session(session_id)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from None
+    if session.game_id != game_id:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Coach session {session_id} does not belong to game {game_id}.",
+        )
+    return _coach_response(session)
+
+
+@router.post(
+    "/games/{game_id}/actions/coach/{session_id}/answer",
+    response_model=ActionCoachSessionResponse,
+)
+def post_action_coach_answer(
+    game_id: str,
+    session_id: str,
+    body: ActionCoachAnswerRequest,
+) -> ActionCoachSessionResponse:
+    """Submit one CEO message; the coach replies (asks one question or
+    returns a complete draft). Capped at 2 rounds — the coach forces a
+    best-effort draft on round 2."""
+    from wargame.agents.action_coach import advance_session, load_session
+    from wargame.config import use_game_model
+
+    game = _load_or_404(game_id)
+    try:
+        session = load_session(session_id)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from None
+    if session.game_id != game_id:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Coach session {session_id} does not belong to game {game_id}.",
+        )
+    try:
+        scenario = load_scenario(game.scenario_id)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from None
+    try:
+        with use_game_model(game.llm_model):
+            advance_session(
+                session,
+                body.message,
+                game=game,
+                scenario=scenario,
+            )
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e)) from None
+    return _coach_response(session)
+
+
+@router.post(
+    "/games/{game_id}/actions/coach/{session_id}/commit",
+    response_model=ActionAcceptedResponse,
+    status_code=202,
+)
+def post_action_coach_commit(
+    game_id: str, session_id: str
+) -> ActionAcceptedResponse:
+    """Commit the synthesized draft via the engine's `loop.act` path.
+
+    Returns the same response shape as `POST /games/{id}/actions` — the
+    coach is a builder, the engine is the validator. If the draft is
+    incomplete or the engine rejects the action, returns 409.
+    """
+    from wargame.agents.action_coach import commit_session, load_session
+
+    game = _load_or_404(game_id)
+    try:
+        session = load_session(session_id)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from None
+    if session.game_id != game_id:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Coach session {session_id} does not belong to game {game_id}.",
+        )
+    try:
+        submission = commit_session(session, game=game)
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e)) from None
+    return ActionAcceptedResponse(
+        game_id=game.id,
+        turn=game.world.turn,
+        action=submission,
+    )

wargame/api/schemas.py

@@ -356,3 +356,44 @@ class ModelInfo(BaseModel):
 class ModelsResponse(BaseModel):
     models: list[ModelInfo]
     default: str
+
+
+# ---------------------------------------------------------------------------
+# Action Coach (conversational action input → 3-anchor ActionSubmission)
+# ---------------------------------------------------------------------------
+
+
+class ActionCoachStartRequest(BaseModel):
+    initial_prose: str = Field(
+        min_length=3,
+        max_length=4000,
+        description=(
+            "The CEO's free-form description of the move they want to make. "
+            "The coach extracts intent + justification + 3 anchors from this."
+        ),
+    )
+
+
+class ActionCoachAnswerRequest(BaseModel):
+    message: str = Field(min_length=1, max_length=4000)
+
+
+class ActionDraftResponse(BaseModel):
+    """Mirror of the engine's `ActionDraft` for the wire — same shape the
+    coach assembles, the same shape the user-facing `ActionRequest` accepts."""
+
+    intent: str
+    justification: str
+    anchors: list[Anchor]
+
+
+class ActionCoachSessionResponse(BaseModel):
+    session_id: str
+    game_id: str
+    turn: int
+    status: str  # 'gathering' | 'ready' | 'committed'
+    rounds_used: int
+    last_coach_message: str
+    synthesized_draft: ActionDraftResponse | None = None
+    committed: bool = False
+    messages: list[dict]  # raw dicts for clients to render the chat thread

wargame/prompts/action_coach.md

@@ -0,0 +1,79 @@
+You are the **Action Coach** for a CEO playing a strategic war game. Your sole job is to take the CEO's natural-language description of a move and convert it into a properly structured action — exactly the shape the war-game engine adjudicates against.
+
+The CEO is playing as **{player_role}** at **{company_name}**, facing **{rival_name}** and the rest of the world. The full world bible (named entities, numbers, regulators, dates) follows below — every anchor you produce should reference those specifics rather than generic phrasing.
+
+## The action contract you must produce
+
+Every action carries:
+
+- **`intent`** — a single sentence describing the move *the CEO actually described*, framed as something the CEO would say across a board table. No hedging, no "we should consider…". One declarative move. **Anchor the move they described, not a safer or cleverer version of it.** You may tighten wording — turn "Do X-ish thing" into "Do X" — but you must not substitute a different move because you think theirs is exposed, naive, or politically risky. If you have concerns, raise them in `message_to_user`; the `intent` field is the CEO's move, faithfully captured.
+- **`justification`** — 1 to 3 sentences answering "why this move, why now", grounded in the CEO's framing. This is the strategic logic — what changes if the CEO acts vs. waits one turn. Specific, not slogan-y. Don't replace the CEO's reasoning with your own; expand and sharpen theirs.
+- **`anchors`** — exactly **THREE** anchors, one of each kind below. The matrix-game umpire (Control) scores plausibility against these; weak anchors get `no_effect` or `backfires`.
+
+### The three anchor kinds
+
+1. **`prior_analogue`** — A past case (yours or someone else's) where this move worked or a clearly comparable move worked. **Name** the case: company / situation / year, or a named regulator decision, or a documented playbook. "Sainsbury's 2022 pre-emptive buyback after a Czech-origin activist letter" beats "another company did this once".
+
+2. **`stated_capability`** — A capability the company has *already stated or demonstrated*. Reference the world bible's named systems, certifications, named team members, or documented track record. "Horizont-X validated under UNI 11300 (Jun 2024)" beats "we have engineering capability".
+
+3. **`resource_committed`** — Specific money, headcount, time, or contract authority being put behind this move. Numbers and names from the world bible where possible. "EUR 500k/quarter penalty cap, signed by Bettina Lange" beats "we'll dedicate resources".
+
+## Your two possible outputs each turn
+
+You always emit a `CoachTurnLLMOutput`. The fields:
+
+- **`status`**: either `"asking"` (one focused question) or `"ready"` (commit the draft).
+- **`message_to_user`**: 15–4000 chars, plain prose addressed to the CEO. When `asking`, this is your one question. When `ready`, this is a one-paragraph confirmation summarising what you drafted.
+- **`proposed_draft`**: required when `status="ready"`. When `status="asking"`, optional but recommended — populate the fields you DO know so the UI can show progress.
+
+### When to go `status="ready"`
+
+Prefer ready when ≥80% of the prose maps cleanly to the three anchors. Specifically, return ready when:
+
+- The intent is a single clear move you can paraphrase in one sentence.
+- For each of the three anchor kinds, you can extract a *specific, named* anchor from the prose, the world bible, or the briefing (e.g. cite a named regulator, named analyst, named account, a number, a date, or a named precedent).
+- The justification is implicit in the prose — even if the CEO didn't write "why now", you can lift the strategic frame from context.
+
+If the prose only loosely sketches the move and you'd be guessing on at least one anchor, ask. But ask **only one** question, and make it the one that unblocks all three anchors.
+
+### When to go `status="asking"`
+
+Use this exclusively when a critical anchor is genuinely ambiguous and the world bible doesn't disambiguate it. Examples of good questions:
+
+- "What prior analogue grounds this — the BBC Trust 2007 separation or the Schweizer Presserat? It changes the plausibility frame."
+- "Is the resource you're committing the EUR 200M revolver or new debt issuance? Anchor specificity changes the verdict."
+- "Are you naming a specific stakeholder to lead this — Bettina Lange the CFO, or someone else?"
+
+Do **not** ask:
+
+- Multi-part questions ("can you clarify A, B, and C…").
+- Strategic-direction questions ("are you sure this is wise?"). The coach's job is structuring, not second-guessing.
+- Questions whose answer is in the world bible. **Read it first.**
+- Questions that just rephrase the prose.
+
+You are budget-capped at **{max_rounds} rounds**. On round {max_rounds}, you MUST go `status="ready"` regardless. The system enforces this; if you try to ask a third question, your output gets rewritten as best-effort. So if you're going to ask, ask the *most unblocking* question first.
+
+## Reframing — don't
+
+The most common failure mode of an LLM in this seat is to silently *upgrade* the CEO's move into the version the LLM thinks is wiser. A free-standing oversight body becomes a "narrowed mandate"; a public counter-suit becomes a "measured statement"; a 90-day commitment becomes a "scoped 30-day pilot". **Do not do this.** The CEO chose the move. Your job is to anchor it, not to overrule it.
+
+If the move has a real exposure (litigation discoverability, regulatory tripwire, named opponent's likely framing), surface that in `message_to_user` as one short flag — e.g. *"Heads up: Hafenecker will read this as governance overreach. Confirm the framing or tell me to dial it back."* — and let the CEO decide. If they confirm, anchor the original. If they pull back, then re-anchor.
+
+The only times you may rewrite the move:
+
+1. The prose is genuinely incoherent (contradicts itself or the world bible's hard facts) — ask a clarifying question instead.
+2. The CEO explicitly asks you to "find a more defensible version" or "push back if this is naive". Default is anchor-the-intent.
+
+## Tone
+
+You're a sharp chief-of-staff drafting the move on behalf of the CEO. Direct, no preamble, no hedging. When you confirm a draft, name what you put in each anchor in one short sentence each so the CEO can spot mistakes fast.
+
+Do **not** lecture, coach the CEO on strategy, or pad responses with filler. The CEO is mid-game and time-constrained.
+
+## Pinned world bible
+
+The full world bible follows. Pull from it relentlessly when constructing anchors — named accounts, named regulators, named dates, real numbers. Specificity is the coach's only superpower.
+
+---
+
+{world_bible}

wargame/tests/conftest.py

@@ -428,6 +428,91 @@ def _fake_action_submission() -> dict[str, Any]:
     }
 
 
+def _fake_coach_turn(user: str) -> dict[str, Any]:
+    """Fake LLM turn for the Action Coach.
+
+    Mirrors the SetupAgentTurn dispatch shape: counts how many coach
+    messages already appeared in the transcript so multi-turn tests can
+    exercise the ask-then-ready path deterministically.
+
+    The user message includes the briefing + recon log + transcript. To
+    keep the trigger logic deterministic, scan ONLY the lines that
+    represent CEO turns in the transcript (`**CEO**:` blocks).
+    """
+    coach_replies = user.count("**Coach**:")
+    # Pull just the CEO transcript lines so trigger words inside the
+    # briefing or the world bible don't accidentally flip the response.
+    ceo_blocks: list[str] = []
+    for block in user.split("\n\n"):
+        cleaned = block.strip()
+        if cleaned.startswith("**CEO**:"):
+            ceo_blocks.append(cleaned[len("**CEO**:"):].strip().lower())
+    ceo_text = " ".join(ceo_blocks)
+    user_says_go = (
+        "looks right" in ceo_text
+        or " go " in f" {ceo_text} "
+        or "go." in ceo_text
+        or "go!" in ceo_text
+        or "approve" in ceo_text
+        or "commit it" in ceo_text
+        or "ship it" in ceo_text
+    )
+
+    ready_draft = {
+        "intent": "Lock Helvetia at 14% effective before Aergis signs an LoI.",
+        "justification": (
+            "Pre-empt Aergis's Italian sales push by closing the largest "
+            "renewal account first, removing a EUR 22M revenue risk and "
+            "anchoring the rest of the channel."
+        ),
+        "anchors": [
+            {
+                "kind": "prior_analogue",
+                "detail": (
+                    "Helvetia 2022 renewal — Norhard locked 16% effective on "
+                    "a 3-year auto-renew structure when KlimaPro was probing."
+                ),
+            },
+            {
+                "kind": "stated_capability",
+                "detail": (
+                    "Horizont-X system validated under UNI 11300 (Jun 2024); "
+                    "field service network already covers the Stuttgart plant."
+                ),
+            },
+            {
+                "kind": "resource_committed",
+                "detail": (
+                    "EUR 500k/quarter penalty cap signed by Bettina Lange the "
+                    "CFO; revolver capacity covers any shortfall."
+                ),
+            },
+        ],
+    }
+
+    if coach_replies >= 1 or user_says_go:
+        return {
+            "status": "ready",
+            "message_to_user": (
+                "I have a clean draft. Intent: lock Helvetia at 14%. "
+                "Justification: pre-empt Aergis. Anchors: 2022 Helvetia "
+                "renewal precedent / Horizont-X UNI 11300 validation / EUR "
+                "500k/quarter penalty cap signed by Lange. Ship it?"
+            ),
+            "proposed_draft": ready_draft,
+        }
+    return {
+        "status": "asking",
+        "message_to_user": (
+            "One question to ground the prior analogue: are you anchoring "
+            "this on the 2022 Helvetia renewal (16% effective, 3-year auto) "
+            "or the broader 2018 KlimaPro skirmish? Tell me which and I'll "
+            "draft the move."
+        ),
+        "proposed_draft": None,
+    }
+
+
 def _fake_scenario_map_synthesis() -> dict[str, Any]:
     return {
         "markdown": (
@@ -477,6 +562,8 @@ def _dispatch(schema_name: str, user: str) -> Any:
         return _fake_action_submission()
     if schema_name == "ScenarioMapSynthesis":
         return _fake_scenario_map_synthesis()
+    if schema_name == "CoachTurnLLMOutput":
+        return _fake_coach_turn(user)
     raise AssertionError(f"No fake canned for schema {schema_name!r}")
 
 
@@ -502,6 +589,7 @@ def fake_llm(monkeypatch: pytest.MonkeyPatch):
         "wargame.agents.control",
         "wargame.agents.role",
         "wargame.agents.rival_ceo",
+        "wargame.agents.action_coach",
         "wargame.scaffold.generator",
         "wargame.scaffold.setup_agent",
         "wargame.orchestrator.vectors",

wargame/tests/test_action_coach.py

@@ -0,0 +1,341 @@
+"""Tests for the Action Coach — conversational action input.
+
+The coach turns CEO prose into a structured 3-anchor `ActionSubmission`,
+either in one shot (status='ready') or after one focused clarification
+(status='asking' → 'ready'). After 2 rounds the coach must commit
+best-effort. On commit, the engine's `loop.act` validates and accepts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+from wargame.api.app import create_app
+
+
+# ---------------------------------------------------------------------------
+# Module-level happy paths (offline, fake LLM)
+# ---------------------------------------------------------------------------
+
+
+def test_one_shot_ready_when_prose_says_go(fake_llm) -> None:
+    """When the initial prose includes a 'go' / 'ready' signal, the fake
+    LLM returns status='ready' immediately and the coach has a draft."""
+    from wargame.agents.action_coach import new_session
+    from wargame.agents.registry import load_scenario
+    from wargame.engine import loop
+
+    game = loop.new_game("competitor_disruption")
+    scenario = load_scenario(game.scenario_id)
+
+    session, turn = new_session(
+        game=game,
+        scenario=scenario,
+        initial_prose=(
+            "Go pre-empt Aergis by locking Helvetia at 14% effective before "
+            "they sign an LoI. Use the 2022 Helvetia renewal as the precedent."
+        ),
+    )
+
+    assert session.status == "ready"
+    assert turn.status == "ready"
+    assert turn.proposed_draft is not None
+    assert len(turn.proposed_draft.anchors) == 3
+    kinds = {a.kind for a in turn.proposed_draft.anchors}
+    # The three valid anchor kinds, exactly.
+    assert len(kinds) == 3
+    assert session.synthesized_draft is not None
+    # Persistence: session is on disk
+    from wargame.agents.action_coach import load_session
+
+    reloaded = load_session(session.id)
+    assert reloaded.status == "ready"
+
+
+def test_ask_then_ready_path(fake_llm) -> None:
+    """First prose triggers a clarifying question; the second message flips
+    to ready with a populated draft."""
+    from wargame.agents.action_coach import advance_session, new_session
+    from wargame.agents.registry import load_scenario
+    from wargame.engine import loop
+
+    game = loop.new_game("competitor_disruption")
+    scenario = load_scenario(game.scenario_id)
+
+    # Round 1 — vague prose, no 'go' signal → coach asks one question
+    session, turn1 = new_session(
+        game=game,
+        scenario=scenario,
+        initial_prose=(
+            "I want to do something about Helvetia before the rival lands. "
+            "Lock them in somehow."
+        ),
+    )
+    assert turn1.status == "asking"
+    assert session.status == "gathering"
+    assert session.rounds_used == 1
+    # Coach asked exactly one question (15-4000 chars enforced by schema).
+    assert len(turn1.message_to_user) >= 15
+
+    # Round 2 — answer the question → coach goes ready
+    turn2 = advance_session(
+        session,
+        "Anchor it on the 2022 Helvetia renewal — 16% effective, 3-year auto.",
+        game=game,
+        scenario=scenario,
+    )
+    assert turn2.status == "ready"
+    assert turn2.proposed_draft is not None
+    assert len(turn2.proposed_draft.anchors) == 3
+    assert session.status == "ready"
+    assert session.rounds_used == 2
+
+
+def test_round_cap_forces_ready(monkeypatch, fake_llm) -> None:
+    """If the coach is still 'asking' on round MAX_ROUNDS, the session
+    forces a downgrade to 'ready' with best-effort anchors."""
+    from wargame.agents import action_coach
+    from wargame.agents.action_coach import (
+        MAX_ROUNDS,
+        advance_session,
+        new_session,
+    )
+    from wargame.agents.registry import load_scenario
+    from wargame.engine import loop
+    from wargame.engine.state import AnchorKind
+
+    # Patch call_structured at the action_coach module to ALWAYS return
+    # 'asking' — simulating an LLM that never closes out.
+    def always_asking(*, schema, system, user, role="agent", temperature=0.7, max_tokens=4000):
+        data = {
+            "status": "asking",
+            "message_to_user": (
+                "I still need one more clarification — which anchor "
+                "matters most for plausibility?"
+            ),
+            "proposed_draft": None,
+        }
+        return schema.model_validate(data)
+
+    monkeypatch.setattr(action_coach, "call_structured", always_asking)
+
+    game = loop.new_game("competitor_disruption")
+    scenario = load_scenario(game.scenario_id)
+
+    session, turn1 = new_session(
+        game=game,
+        scenario=scenario,
+        initial_prose="A vague move that doesn't specify any anchor.",
+    )
+    # Round 1 stays 'asking' (under the cap).
+    assert turn1.status == "asking"
+    assert session.rounds_used == 1
+    assert session.status == "gathering"
+
+    # Round MAX_ROUNDS — even though the LLM still wants to ask, the session
+    # forces a downgrade to 'ready' with best-effort anchors.
+    final = advance_session(
+        session,
+        "Just figure it out from context, please.",
+        game=game,
+        scenario=scenario,
+    )
+    assert session.rounds_used == MAX_ROUNDS
+    assert final.status == "ready"
+    assert session.status == "ready"
+    assert session.synthesized_draft is not None
+    # The forced draft has exactly 3 valid-kind anchors (Pydantic enforced).
+    assert len(session.synthesized_draft.anchors) == 3
+    valid_kinds = {AnchorKind.PRIOR_ANALOGUE, AnchorKind.STATED_CAPABILITY, AnchorKind.RESOURCE_COMMITTED}
+    assert {a.kind for a in session.synthesized_draft.anchors} == valid_kinds
+    # The user is told the budget was reached
+    assert "Round budget reached" in final.message_to_user
+
+
+def test_commit_submits_action_engine_accepts(fake_llm) -> None:
+    """Commit submits the synthesized ActionSubmission via `loop.act` and
+    the engine accepts it: turn flips to ACTION, player_action is set."""
+    from wargame.agents.action_coach import (
+        commit_session,
+        new_session,
+    )
+    from wargame.agents.registry import load_scenario
+    from wargame.engine import loop, persistence
+    from wargame.engine.state import Phase
+
+    game = loop.new_game("competitor_disruption")
+    scenario = load_scenario(game.scenario_id)
+
+    session, _turn = new_session(
+        game=game,
+        scenario=scenario,
+        initial_prose=(
+            "Go — lock Helvetia at 14% effective with the 2022 renewal precedent."
+        ),
+    )
+    assert session.status == "ready"
+
+    submission = commit_session(session, game=game)
+    assert submission.actor == "player"
+    assert len(submission.anchors) == 3
+    assert session.committed is True
+    assert session.status == "committed"
+
+    # Engine state confirms the action landed
+    assert game.current_turn is not None
+    assert game.current_turn.phase == Phase.ACTION
+    assert game.current_turn.player_action is not None
+    assert game.current_turn.player_action.intent == submission.intent
+
+    # Reloaded snapshot persists the committed action
+    reloaded = persistence.load(game.id)
+    assert reloaded.current_turn is not None
+    assert reloaded.current_turn.player_action is not None
+
+
+# ---------------------------------------------------------------------------
+# Engine-side guarantees
+# ---------------------------------------------------------------------------
+
+
+def test_committed_session_cannot_advance(fake_llm) -> None:
+    from wargame.agents.action_coach import (
+        advance_session,
+        commit_session,
+        new_session,
+    )
+    from wargame.agents.registry import load_scenario
+    from wargame.engine import loop
+
+    game = loop.new_game("competitor_disruption")
+    scenario = load_scenario(game.scenario_id)
+
+    session, _ = new_session(
+        game=game,
+        scenario=scenario,
+        initial_prose="Go and lock Helvetia at 14% with the 2022 precedent.",
+    )
+    commit_session(session, game=game)
+
+    with pytest.raises(ValueError, match="committed"):
+        advance_session(
+            session, "another message", game=game, scenario=scenario
+        )
+
+
+def test_commit_before_ready_raises(fake_llm) -> None:
+    """A session in 'gathering' has no draft yet; commit must raise."""
+    from wargame.agents.action_coach import commit_session, new_session
+    from wargame.agents.registry import load_scenario
+    from wargame.engine import loop
+
+    game = loop.new_game("competitor_disruption")
+    scenario = load_scenario(game.scenario_id)
+
+    session, turn = new_session(
+        game=game,
+        scenario=scenario,
+        initial_prose="A vague move with no signal at all.",
+    )
+    # Default fake LLM returns 'asking' on round 1 with no draft.
+    assert turn.status == "asking"
+    assert session.synthesized_draft is None
+    with pytest.raises(ValueError, match="no synthesized draft"):
+        commit_session(session, game=game)
+
+
+# ---------------------------------------------------------------------------
+# API contract
+# ---------------------------------------------------------------------------
+
+
+def test_api_action_coach_full_flow(fake_llm) -> None:
+    """Happy-path end-to-end via FastAPI: start → answer → commit → engine
+    accepts the action."""
+    client = TestClient(create_app())
+
+    # Create game
+    r = client.post("/games", json={"scenario_id": "competitor_disruption"})
+    assert r.status_code == 201
+    gid = r.json()["game_id"]
+
+    # Start coach session — vague prose triggers 'asking'
+    r = client.post(
+        f"/games/{gid}/actions/coach",
+        json={
+            "initial_prose": (
+                "I want to do something about Helvetia before Aergis lands."
+            )
+        },
+    )
+    assert r.status_code == 201, r.text
+    body = r.json()
+    sid = body["session_id"]
+    assert body["status"] == "gathering"
+    assert body["last_coach_message"]
+    assert body["synthesized_draft"] is None or body["synthesized_draft"]
+
+    # GET reflects current state
+    r = client.get(f"/games/{gid}/actions/coach/{sid}")
+    assert r.status_code == 200
+
+    # Answer with 'go' to trigger 'ready' on the fake
+    r = client.post(
+        f"/games/{gid}/actions/coach/{sid}/answer",
+        json={"message": "go — anchor it on the 2022 Helvetia renewal."},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "ready"
+    assert body["synthesized_draft"] is not None
+    assert len(body["synthesized_draft"]["anchors"]) == 3
+
+    # Commit → engine accepts → 202
+    r = client.post(f"/games/{gid}/actions/coach/{sid}/commit")
+    assert r.status_code == 202, r.text
+    body = r.json()
+    assert body["game_id"] == gid
+    assert body["action"]["actor"] == "player"
+    assert len(body["action"]["anchors"]) == 3
+
+    # Engine state shows the action committed
+    r = client.get(f"/games/{gid}/state")
+    assert r.status_code == 200
+    assert r.json()["current_phase"] == "action"
+
+
+def test_api_action_coach_unknown_session_returns_404(fake_llm) -> None:
+    client = TestClient(create_app())
+    r = client.post("/games", json={"scenario_id": "competitor_disruption"})
+    gid = r.json()["game_id"]
+
+    r = client.get(f"/games/{gid}/actions/coach/does_not_exist")
+    assert r.status_code == 404
+    r = client.post(
+        f"/games/{gid}/actions/coach/does_not_exist/answer",
+        json={"message": "hi"},
+    )
+    assert r.status_code == 404
+    r = client.post(f"/games/{gid}/actions/coach/does_not_exist/commit")
+    assert r.status_code == 404
+
+
+def test_api_action_coach_commit_before_ready_returns_409(fake_llm) -> None:
+    """A session that's still gathering has no draft; commit returns 409."""
+    client = TestClient(create_app())
+    r = client.post("/games", json={"scenario_id": "competitor_disruption"})
+    gid = r.json()["game_id"]
+
+    # Start with vague prose → 'asking'
+    r = client.post(
+        f"/games/{gid}/actions/coach",
+        json={"initial_prose": "Vague move, no specifics at all"},
+    )
+    sid = r.json()["session_id"]
+    assert r.json()["status"] == "gathering"
+
+    r = client.post(f"/games/{gid}/actions/coach/{sid}/commit")
+    assert r.status_code == 409

wargame/tests/test_api.py

@@ -140,6 +140,32 @@ def test_advance_before_action_returns_409(client: TestClient) -> None:
     assert r.status_code == 409
 
 
+def test_orchestrate_after_action_returns_409(client: TestClient) -> None:
+    # Regression: orchestrator only runs on a pristine Turn 1. Without this
+    # guard, clone_pristine ValueErrors get swallowed by the worker and the UI
+    # silently sees three failed branches.
+    r = client.post("/games", json={"scenario_id": "competitor_disruption"})
+    gid = r.json()["game_id"]
+    action_body = {
+        "intent": "Counter-price selectively",
+        "justification": "Defend EBIT while stabilizing installer channel.",
+        "anchors": [
+            {"kind": "prior_analogue", "detail": "2018 KlimaPro price skirmish"},
+            {"kind": "stated_capability", "detail": "Finance can model in 48h"},
+            {"kind": "resource_committed", "detail": "EUR 2M margin buffer"},
+        ],
+    }
+    r = client.post(f"/games/{gid}/actions", json=action_body)
+    assert r.status_code == 202
+    r = client.post(f"/games/{gid}/advance")
+    assert r.status_code == 200
+    r = client.post(
+        f"/games/{gid}/orchestrate", json={"branches": 3, "turns": 1}
+    )
+    assert r.status_code == 409
+    assert "pristine" in r.json()["detail"]
+
+
 def test_unknown_game_returns_404(client: TestClient) -> None:
     r = client.get("/games/does-not-exist/state")
     assert r.status_code == 404