Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=counsel_env
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,231 @@
 ---
 title: Counsel Env
-emoji: 🏢
-colorFrom: green
-colorTo: gray
+emoji: "⚖️"
+colorFrom: indigo
+colorTo: yellow
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - rl
+  - multi-agent
+  - theory-of-mind
+  - adversarial-dialogue
+  - procgen
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Cross-Examination Arena
+
+We built a courtroom where an LLM learns to catch lies.
+
+Counsel-Env trains an agent to act like a sharper trial lawyer: make a deterministic witness commit to a claim, then present the exhibit that proves the claim false. It is built for OpenEnv and GRPO-style post-training on multi-agent, partially observable dialogue.
+
+> Baseline behavior: vague questions, early evidence, zero reward.
+>
+> Target behavior: trigger sealed claim, present matching exhibit, surface contradiction.
+
+![Held-out baseline reward comparison](../assets/plots/baseline_vs_oracle.svg)
+
+```mermaid
+flowchart LR
+  A[Procgen Case Generator] --> B[Deterministic Witness]
+  B --> C[Agent Tools]
+  C --> D[Transcript + State Tracker]
+  D --> E[Weighted Reward Rubric]
+  E --> F[GRPO Training Loop]
+```
+
+## Environment Design
+
+Each episode is a procedurally generated case with:
+
+- a public case brief
+- deterministic witness story
+- hidden contradiction objects
+- evidence exhibits with descriptions visible to the agent
+- a 15-question budget
+- replayable seeds for before/after evaluation
+
+A contradiction is surfaced only when both steps happen in order:
+
+1. The agent asks a trigger question and the witness gives a sealed claim.
+2. The agent presents the matching disprover exhibit.
+
+The witness is deterministic by design. That keeps reward verification fast, cheap, reproducible, and non-LLM-judged.
+
+## Actions
+
+| Tool | Field | Purpose |
+| --- | --- | --- |
+| `ask_question` | `text` | Ask the witness a question. |
+| `present_evidence` | `exhibit_id` | Present an exhibit from `available_evidence`. |
+| `make_objection` | `reason` | Currently penalized unless an objection window exists. |
+| `rest_case` | none | End the episode and receive final reward. |
+
+## Reward
+
+Primary reward remains binary per contradiction:
+
+```text
+primary_reward = contradictions_surfaced / contradictions_total
+```
+
+Auxiliary shaping reduces sparsity while staying secondary:
+
+```text
+auxiliary =
+  +0.2 * contradictions_triggered
+  +0.1 * trigger_keyword_questions
+  +0.1 * correctly_timed_evidence
+  -0.05 * duplicate_or_irrelevant_questions
+  -0.05 * blind_evidence
+  -0.1 * inadmissible_actions
+
+total_reward = 0.8 * primary_reward + 0.2 * auxiliary
+```
+
+Diagnostics log primary, auxiliary, and total reward separately.
+
+## Reward-Hacking Audit
+
+The local evaluator compares four baselines:
+
+| Agent | Avg Reward | Primary Reward | Trigger Rate | Surface Rate |
+| --- | ---: | ---: | ---: | ---: |
+| random | 0.000 | 0.000 | 0.000 | 0.000 |
+| keyword_spam | 0.073 | 0.000 | 0.678 | 0.000 |
+| present_all | 0.000 | 0.000 | 0.000 | 0.000 |
+| scripted_oracle | 0.902 | 0.950 | 0.950 | 0.950 |
+
+This shows the obvious hacks do not get primary reward: keyword spam can trigger claims, and present-all can burn exhibits, but neither surfaces contradictions.
+
+![Reward-hacking audit metrics](../assets/plots/rubric_breakdown.svg)
+
+## Demo Walkthrough
+
+The fastest way to understand the environment is the same-seed demo:
+
+```text
+assets/demo/demo_case.md
+assets/transcripts/before_after_pairs.md
+```
+
+In the demo case, the random baseline presents timestamped surveillance evidence before the witness has committed to a false time, so the witness gives no useful reaction. The successful strategy first asks about time, gets the witness to claim the assault happened at the wrong hour, then presents the timestamped footage.
+
+That sequence is the capability we want training to amplify.
+
+## Curriculum
+
+`generate_case()` supports:
+
+- `difficulty="easy"`: 1 contradiction, obvious trigger language
+- `difficulty="medium"`: 2 contradictions, overlapping trigger language
+- `difficulty="hard"`: 3+ contradictions, distractor evidence
+- `curriculum_stage` and custom sampling distributions
+
+## Local Validation
+
+From the repo root:
+
+```bash
+python pre_hf_validate.py
+python -m pytest -p no:cacheprovider -q
+```
+
+Latest local result:
+
+```text
+20 passed
+```
+
+The preflight also checks local FastAPI + WebSocket reset/step/state, Docker-style imports, notebook credit guards, rollout diagnostics, and held-out evaluation artifacts.
+
+## Diagnostics
+
+Generate a no-credit local diagnostic sample:
+
+```bash
+python -m counsel_env.server.diagnostics
+```
+
+Generate held-out baseline artifacts:
+
+```bash
+python scripts/run_local_eval.py --episodes 30 --output-dir assets
+```
+
+Outputs:
+
+- `assets/heldout_eval.jsonl`
+- `assets/heldout_eval_summary.json`
+- `assets/plots/baseline_vs_oracle.svg`
+- `assets/plots/rubric_breakdown.svg`
+- `assets/transcripts/before_after_pairs.md`
+- `assets/demo/demo_case.md`
+- `assets/demo/video_script.md`
+- `assets/demo/blog_draft.md`
+
+## Training
+
+The notebook is at:
+
+```text
+counsel_env/notebooks/train_counsel.ipynb
+```
+
+It is credit-safe by default:
+
+- `RUN_TRAINING=0`
+- `push_to_hub=False`
+- `report_to="none"`
+
+GRPO exploration settings:
+
+- `num_generations=6`
+- `temperature=0.8`
+- `top_p=0.95`
+- `max_completion_length=1024`
+
+Tiny approved dry-run mode:
+
+```bash
+RUN_TRAINING=1 COUNSEL_MODEL=Qwen/Qwen3-0.6B COUNSEL_MAX_STEPS=5 COUNSEL_DATASET_SIZE=12
+```
+
+Before running remote training, approve the spend. Estimated costs:
+
+- A10G dry run: about `$0.50`
+- Full A100 GRPO run: about `$6-$10`
+
+## Run Server Locally
+
+```bash
+uvicorn counsel_env.server.app:app --host 0.0.0.0 --port 8000
+```
+
+Client example:
+
+```python
+from counsel_env import CounselAction, CounselEnv
+
+with CounselEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset(curriculum_stage="easy")
+    print(result.observation.case_brief)
+
+    result = client.step(CounselAction(tool="ask_question", text="Where were you that night?"))
+    print(result.observation.witness_response)
+```
+
+## Limitations
+
+- The witness is rule-based, intentionally, so reward is verifiable and cheap.
+- Cases are template-generated rather than open-domain.
+- The environment models adversarial questioning mechanics, not full legal procedure.
+
+Future work: self-play witness training, civil deposition templates, jurisdiction-specific admissibility rules, and trained-vs-baseline model ablations after the first GRPO run.
+
+## Status
+
+Local environment validation is complete. Hugging Face Space deployment, real GRPO training, trained-model reward curves, and public video/blog publishing still require approval and compute.

__init__.py

@@ -0,0 +1,17 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Counsel Env Environment."""
+
+from .client import CounselEnv
+from .models import CounselAction, CounselObservation, CounselState
+
+__all__ = [
+    "CounselAction",
+    "CounselObservation",
+    "CounselState",
+    "CounselEnv",
+]

client.py

@@ -0,0 +1,119 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Counsel Env Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import CounselAction, CounselObservation, CounselState
+
+
+class CounselEnv(
+    EnvClient[CounselAction, CounselObservation, CounselState]
+):
+    """
+    Client for the Counsel Env Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with CounselEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(CounselAction(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = CounselEnv.from_docker_image("counsel_env-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(CounselAction(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: CounselAction) -> Dict:
+        """
+        Convert CounselAction to JSON payload for step message.
+
+        Args:
+            action: CounselAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "tool": action.tool,
+            "text": action.text,
+            "exhibit_id": action.exhibit_id,
+            "reason": action.reason,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[CounselObservation]:
+        """
+        Parse server response into StepResult[CounselObservation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with CounselObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = CounselObservation(
+            witness_response=obs_data.get("witness_response", ""),
+            available_evidence=obs_data.get("available_evidence", []),
+            evidence_descriptions=obs_data.get("evidence_descriptions", {}),
+            questions_remaining=obs_data.get("questions_remaining", 0),
+            transcript_tail=obs_data.get("transcript_tail", ""),
+            case_brief=obs_data.get("case_brief", ""),
+            case_id=obs_data.get("case_id", ""),
+            difficulty=obs_data.get("difficulty", ""),
+            done=obs_data.get("done", payload.get("done", False)),
+            reward=obs_data.get("reward", payload.get("reward", 0.0)),
+            reward_components=obs_data.get("reward_components", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=observation.reward,
+            done=observation.done,
+        )
+
+    def _parse_state(self, payload: Dict) -> CounselState:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        data = payload.get("data", payload)
+        return CounselState(
+            case_id=data.get("case_id", ""),
+            difficulty=data.get("difficulty", ""),
+            contradictions_total=data.get("contradictions_total", 0),
+            contradictions_triggered=data.get("contradictions_triggered", 0),
+            contradictions_surfaced=data.get("contradictions_surfaced", 0),
+            questions_used=data.get("questions_used", 0),
+            action_count=data.get("action_count", data.get("step_count", 0)),
+            duplicate_question_count=data.get("duplicate_question_count", 0),
+            irrelevant_question_count=data.get("irrelevant_question_count", 0),
+            inadmissible_count=data.get("inadmissible_count", 0),
+            evidence_timing_successes=data.get("evidence_timing_successes", 0),
+            step_count=data.get("step_count", data.get("action_count", 0)),
+        )

evaluation.py

@@ -0,0 +1,337 @@
+"""Local held-out evaluation and artifact generation for Counsel-Env."""
+
+import argparse
+import csv
+import json
+import random
+from pathlib import Path
+from statistics import mean
+from typing import Callable, Dict, Iterable, List
+
+from counsel_env.models import CounselAction
+from counsel_env.server.counsel_env_environment import CounselEnvironment
+
+
+AgentPolicy = Callable[[CounselEnvironment, random.Random], None]
+
+
+def random_agent(env: CounselEnvironment, rng: random.Random) -> None:
+    """Low-information baseline."""
+    for _ in range(8):
+        if env.done:
+            break
+        if rng.random() < 0.7:
+            env.step(CounselAction(tool="ask_question", text=f"Can you explain detail {rng.randint(1, 999)}?"))
+        else:
+            env.step(CounselAction(tool="present_evidence", exhibit_id=rng.choice(list(env.case["evidence"].keys()))))
+    if not env.done:
+        env.step(CounselAction(tool="rest_case"))
+
+
+def keyword_spam_agent(env: CounselEnvironment, rng: random.Random) -> None:
+    """Reward-hacking probe: asks trigger-like terms but does not reason about exhibits."""
+    questions = [
+        "Where were you?",
+        "What was your motive?",
+        "Did you know the victim?",
+        "What happened and why?",
+        "Were you at the location?",
+    ]
+    for question in questions:
+        if env.done:
+            break
+        env.step(CounselAction(tool="ask_question", text=question))
+    if not env.done:
+        env.step(CounselAction(tool="rest_case"))
+
+
+def present_all_agent(env: CounselEnvironment, rng: random.Random) -> None:
+    """Reward-hacking probe: blindly presents every exhibit."""
+    for exhibit_id in list(env.case["evidence"].keys()):
+        if env.done:
+            break
+        env.step(CounselAction(tool="present_evidence", exhibit_id=exhibit_id))
+    if not env.done:
+        env.step(CounselAction(tool="rest_case"))
+
+
+def oracle_scripted_agent(env: CounselEnvironment, rng: random.Random) -> None:
+    """Upper-bound scripted strategy using hidden contradiction metadata."""
+    for contradiction in env.witness.contradictions:
+        if env.done:
+            break
+        env.step(CounselAction(tool="ask_question", text=f"{contradiction.trigger_keywords[0]}?"))
+        if env.done:
+            break
+        env.step(CounselAction(tool="present_evidence", exhibit_id=contradiction.disprover_evidence_id))
+    if not env.done:
+        env.step(CounselAction(tool="rest_case"))
+
+
+AGENTS: Dict[str, AgentPolicy] = {
+    "random": random_agent,
+    "keyword_spam": keyword_spam_agent,
+    "present_all": present_all_agent,
+    "scripted_oracle": oracle_scripted_agent,
+}
+
+
+def make_eval_seeds(count: int = 30, start: int = 20260425) -> List[int]:
+    return list(range(start, start + count))
+
+
+def evaluate_agent(
+    name: str,
+    policy: AgentPolicy,
+    seeds: Iterable[int],
+    curriculum_stage: str = "mixed",
+    transcript_limit: int = 3,
+) -> tuple[List[dict], List[str]]:
+    rows: List[dict] = []
+    markdown_samples: List[str] = []
+
+    for index, seed in enumerate(seeds):
+        agent_offset = sum(ord(ch) for ch in name)
+        rng = random.Random(seed + agent_offset)
+        env = CounselEnvironment()
+        obs = env.reset(seed=seed, curriculum_stage=curriculum_stage, episode_id=f"{name}_{seed}")
+        assert obs.case_id == env.case["case_id"]
+        policy(env, rng)
+        if not env.done:
+            env.step(CounselAction(tool="rest_case"))
+
+        components = env._calculate_reward_components()
+        row = {
+            "agent": name,
+            "seed": seed,
+            "case_id": env.case["case_id"],
+            "difficulty": env.case["difficulty"],
+            "reward": components["total_reward"],
+            "primary_reward": components["primary_reward"],
+            "auxiliary_reward": components["auxiliary_reward_raw"],
+            "contradictions_total": int(components["contradictions_total"]),
+            "contradictions_triggered": int(components["contradictions_triggered"]),
+            "contradictions_surfaced": int(components["contradictions_surfaced"]),
+            "questions_used": env.questions_used,
+            "evidence_presented": env.evidence_presented_count,
+            "evidence_timing_successes": int(components["evidence_timing_successes"]),
+            "blind_evidence_count": int(components["blind_evidence_count"]),
+            "useless_questions_ratio": components["useless_questions_ratio"],
+            "avg_question_length": components["avg_question_length"],
+        }
+        rows.append(row)
+
+        if index < transcript_limit:
+            markdown_samples.append(f"# Agent: {name}\n\n" + env.export_transcript_markdown())
+
+    return rows, markdown_samples
+
+
+def summarize(rows: List[dict]) -> List[dict]:
+    summaries: List[dict] = []
+    for agent in sorted({row["agent"] for row in rows}):
+        agent_rows = [row for row in rows if row["agent"] == agent]
+        summaries.append(
+            {
+                "agent": agent,
+                "episodes": len(agent_rows),
+                "avg_reward": mean(row["reward"] for row in agent_rows),
+                "avg_primary_reward": mean(row["primary_reward"] for row in agent_rows),
+                "avg_trigger_rate": mean(
+                    row["contradictions_triggered"] / max(1, row["contradictions_total"])
+                    for row in agent_rows
+                ),
+                "avg_surface_rate": mean(
+                    row["contradictions_surfaced"] / max(1, row["contradictions_total"])
+                    for row in agent_rows
+                ),
+                "avg_evidence_timing": mean(row["evidence_timing_successes"] for row in agent_rows),
+                "avg_useless_ratio": mean(row["useless_questions_ratio"] for row in agent_rows),
+            }
+        )
+    return summaries
+
+
+def write_jsonl(path: Path, rows: Iterable[dict]) -> None:
+    with path.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, sort_keys=True) + "\n")
+
+
+def write_csv(path: Path, rows: List[dict]) -> None:
+    if not rows:
+        return
+    with path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(rows[0].keys()))
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def write_plots(plot_dir: Path, summaries: List[dict]) -> None:
+    try:
+        import matplotlib.pyplot as plt
+    except Exception:
+        write_csv(plot_dir / "summary_for_plots.csv", summaries)
+        write_svg_bar_chart(
+            plot_dir / "baseline_vs_oracle.svg",
+            summaries,
+            metric="avg_reward",
+            title="Held-out evaluation reward by baseline",
+        )
+        write_svg_multi_metric(plot_dir / "rubric_breakdown.svg", summaries)
+        return
+
+    agents = [row["agent"] for row in summaries]
+    rewards = [row["avg_reward"] for row in summaries]
+    primary = [row["avg_primary_reward"] for row in summaries]
+    surface = [row["avg_surface_rate"] for row in summaries]
+    trigger = [row["avg_trigger_rate"] for row in summaries]
+    useless = [row["avg_useless_ratio"] for row in summaries]
+
+    plt.figure(figsize=(8, 4.5))
+    plt.bar(agents, rewards, color=["#777777", "#ba5a31", "#4c78a8", "#2f855a"][: len(agents)])
+    plt.ylabel("average reward")
+    plt.xlabel("agent")
+    plt.title("Held-out evaluation reward by baseline")
+    plt.xticks(rotation=20, ha="right")
+    plt.tight_layout()
+    plt.savefig(plot_dir / "baseline_vs_oracle.png", dpi=180)
+    plt.close()
+
+    x = range(len(agents))
+    plt.figure(figsize=(8, 4.5))
+    plt.plot(x, primary, marker="o", label="primary reward")
+    plt.plot(x, trigger, marker="o", label="trigger rate")
+    plt.plot(x, surface, marker="o", label="surface rate")
+    plt.plot(x, useless, marker="o", label="useless question ratio")
+    plt.xticks(list(x), agents, rotation=20, ha="right")
+    plt.ylabel("rate")
+    plt.xlabel("agent")
+    plt.title("Reward-hacking audit metrics")
+    plt.legend()
+    plt.tight_layout()
+    plt.savefig(plot_dir / "rubric_breakdown.png", dpi=180)
+    plt.close()
+
+
+def write_svg_bar_chart(path: Path, summaries: List[dict], metric: str, title: str) -> None:
+    width, height = 840, 460
+    margin_left, margin_bottom, margin_top = 80, 90, 60
+    chart_w = width - margin_left - 40
+    chart_h = height - margin_top - margin_bottom
+    max_value = max(1.0, max(row[metric] for row in summaries))
+    bar_gap = 24
+    bar_w = (chart_w - bar_gap * (len(summaries) - 1)) / max(1, len(summaries))
+    colors = ["#777777", "#ba5a31", "#4c78a8", "#2f855a"]
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">',
+        '<rect width="100%" height="100%" fill="white"/>',
+        f'<text x="{width/2}" y="32" text-anchor="middle" font-family="Arial" font-size="20">{title}</text>',
+        f'<line x1="{margin_left}" y1="{height-margin_bottom}" x2="{width-30}" y2="{height-margin_bottom}" stroke="#333"/>',
+        f'<line x1="{margin_left}" y1="{margin_top}" x2="{margin_left}" y2="{height-margin_bottom}" stroke="#333"/>',
+    ]
+    for idx, row in enumerate(summaries):
+        value = row[metric]
+        x = margin_left + idx * (bar_w + bar_gap)
+        bar_h = chart_h * value / max_value
+        y = height - margin_bottom - bar_h
+        parts.append(f'<rect x="{x:.1f}" y="{y:.1f}" width="{bar_w:.1f}" height="{bar_h:.1f}" fill="{colors[idx % len(colors)]}"/>')
+        parts.append(f'<text x="{x + bar_w/2:.1f}" y="{y - 8:.1f}" text-anchor="middle" font-family="Arial" font-size="13">{value:.3f}</text>')
+        parts.append(f'<text x="{x + bar_w/2:.1f}" y="{height - 54}" text-anchor="middle" font-family="Arial" font-size="12">{row["agent"]}</text>')
+    parts.append(f'<text x="22" y="{margin_top + chart_h/2}" transform="rotate(-90 22,{margin_top + chart_h/2})" font-family="Arial" font-size="13">average reward</text>')
+    parts.append("</svg>")
+    path.write_text("\n".join(parts), encoding="utf-8")
+
+
+def write_svg_multi_metric(path: Path, summaries: List[dict]) -> None:
+    width, height = 880, 500
+    margin_left, margin_bottom, margin_top = 80, 100, 60
+    chart_w = width - margin_left - 50
+    chart_h = height - margin_top - margin_bottom
+    metrics = [
+        ("avg_primary_reward", "primary", "#2f855a"),
+        ("avg_trigger_rate", "trigger", "#4c78a8"),
+        ("avg_surface_rate", "surface", "#805ad5"),
+        ("avg_useless_ratio", "useless", "#ba5a31"),
+    ]
+    agents = [row["agent"] for row in summaries]
+    x_step = chart_w / max(1, len(agents) - 1)
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">',
+        '<rect width="100%" height="100%" fill="white"/>',
+        f'<text x="{width/2}" y="32" text-anchor="middle" font-family="Arial" font-size="20">Reward-hacking audit metrics</text>',
+        f'<line x1="{margin_left}" y1="{height-margin_bottom}" x2="{width-30}" y2="{height-margin_bottom}" stroke="#333"/>',
+        f'<line x1="{margin_left}" y1="{margin_top}" x2="{margin_left}" y2="{height-margin_bottom}" stroke="#333"/>',
+    ]
+    for value in [0.0, 0.25, 0.5, 0.75, 1.0]:
+        y = height - margin_bottom - chart_h * value
+        parts.append(f'<line x1="{margin_left}" y1="{y:.1f}" x2="{width-30}" y2="{y:.1f}" stroke="#ddd"/>')
+        parts.append(f'<text x="{margin_left-10}" y="{y+4:.1f}" text-anchor="end" font-family="Arial" font-size="11">{value:.2f}</text>')
+    for metric, label, color in metrics:
+        points = []
+        for idx, row in enumerate(summaries):
+            x = margin_left + idx * x_step
+            y = height - margin_bottom - chart_h * max(0.0, min(1.0, row[metric]))
+            points.append((x, y))
+        path_data = " ".join(f"{x:.1f},{y:.1f}" for x, y in points)
+        parts.append(f'<polyline points="{path_data}" fill="none" stroke="{color}" stroke-width="3"/>')
+        for x, y in points:
+            parts.append(f'<circle cx="{x:.1f}" cy="{y:.1f}" r="4" fill="{color}"/>')
+        lx = width - 180
+        ly = margin_top + 22 * metrics.index((metric, label, color))
+        parts.append(f'<rect x="{lx}" y="{ly-10}" width="12" height="12" fill="{color}"/>')
+        parts.append(f'<text x="{lx+18}" y="{ly}" font-family="Arial" font-size="13">{label}</text>')
+    for idx, agent in enumerate(agents):
+        x = margin_left + idx * x_step
+        parts.append(f'<text x="{x:.1f}" y="{height-62}" text-anchor="middle" font-family="Arial" font-size="12">{agent}</text>')
+    parts.append("</svg>")
+    path.write_text("\n".join(parts), encoding="utf-8")
+
+
+def write_before_after_pairs(path: Path, transcript_by_agent: Dict[str, List[str]]) -> None:
+    sections = ["# Before / After Transcript Samples", ""]
+    for agent in ["random", "keyword_spam", "present_all", "scripted_oracle"]:
+        samples = transcript_by_agent.get(agent, [])
+        if samples:
+            sections.append(samples[0])
+            sections.append("")
+    path.write_text("\n".join(sections), encoding="utf-8")
+
+
+def run_evaluation(output_dir: str | Path = "assets", episodes: int = 30) -> dict:
+    output = Path(output_dir)
+    plot_dir = output / "plots"
+    transcript_dir = output / "transcripts"
+    output.mkdir(exist_ok=True)
+    plot_dir.mkdir(parents=True, exist_ok=True)
+    transcript_dir.mkdir(parents=True, exist_ok=True)
+
+    seeds = make_eval_seeds(episodes)
+    all_rows: List[dict] = []
+    transcript_by_agent: Dict[str, List[str]] = {}
+    for agent, policy in AGENTS.items():
+        rows, markdown_samples = evaluate_agent(agent, policy, seeds)
+        all_rows.extend(rows)
+        transcript_by_agent[agent] = markdown_samples
+
+    summaries = summarize(all_rows)
+    write_jsonl(output / "heldout_eval.jsonl", all_rows)
+    write_csv(output / "heldout_eval_summary.csv", summaries)
+    (output / "heldout_eval_summary.json").write_text(json.dumps(summaries, indent=2), encoding="utf-8")
+    write_plots(plot_dir, summaries)
+    write_before_after_pairs(transcript_dir / "before_after_pairs.md", transcript_by_agent)
+    return {"rows": all_rows, "summaries": summaries}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output-dir", default="assets")
+    parser.add_argument("--episodes", type=int, default=30)
+    args = parser.parse_args()
+    result = run_evaluation(args.output_dir, args.episodes)
+    print(json.dumps(result["summaries"], indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

models.py

@@ -0,0 +1,38 @@
+from typing import Dict, List, Optional
+
+from pydantic import Field
+
+from openenv.core import Action, Observation, State
+
+
+class CounselAction(Action):
+    tool: str = Field(description="Action tool: ask_question, present_evidence, make_objection, or rest_case")
+    text: Optional[str] = Field(default=None, description="Question text for ask_question")
+    exhibit_id: Optional[str] = Field(default=None, description="Evidence id for present_evidence")
+    reason: Optional[str] = Field(default=None, description="Objection reason for make_objection")
+
+
+class CounselObservation(Observation):
+    witness_response: str = ""
+    available_evidence: List[str] = Field(default_factory=list)
+    evidence_descriptions: Dict[str, str] = Field(default_factory=dict)
+    questions_remaining: int = 0
+    transcript_tail: str = ""
+    case_brief: str = ""
+    case_id: str = ""
+    difficulty: str = ""
+    reward_components: Dict[str, float] = Field(default_factory=dict)
+
+
+class CounselState(State):
+    case_id: str = ""
+    difficulty: str = ""
+    contradictions_total: int = 0
+    contradictions_triggered: int = 0
+    contradictions_surfaced: int = 0
+    questions_used: int = 0
+    action_count: int = 0
+    duplicate_question_count: int = 0
+    irrelevant_question_count: int = 0
+    inadmissible_count: int = 0
+    evidence_timing_successes: int = 0

notebooks/train_counsel.ipynb

@@ -0,0 +1,327 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Cross-Examination Arena GRPO Training\n",
+        "\n",
+        "Credit-safe training notebook for Counsel-Env. Hugging Face GPU usage is disabled by default. Before running a remote training job, confirm the spend: a short A10G dry run is roughly $0.50, and a 90 minute A100 GRPO run is roughly $6-$10 depending on queue/runtime.\n",
+        "\n",
+        "This notebook uses OpenEnv's `environment_factory` pattern, curriculum stages, shaped rewards from the environment, and rollout diagnostics saved to `rollout_debug.jsonl`."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Optional installs for Colab/HF Jobs. Keep commented until you approve credit/network usage.\n",
+        "# !pip install -U 'trl[vllm]' unsloth openenv-core datasets transformers accelerate matplotlib\n",
+        "# !pip install -e .\n",
+        "\n",
+        "import json\n",
+        "import os\n",
+        "import random\n",
+        "import re\n",
+        "from pathlib import Path\n",
+        "from typing import Any, Dict, List\n",
+        "\n",
+        "import numpy as np\n",
+        "from datasets import Dataset\n",
+        "from trl import GRPOConfig, GRPOTrainer\n",
+        "\n",
+        "from counsel_env import CounselEnv\n",
+        "from counsel_env.models import CounselAction\n",
+        "\n",
+        "MODEL = os.getenv('COUNSEL_MODEL', 'Qwen/Qwen3-1.7B')\n",
+        "ENV_URL = os.getenv('COUNSEL_ENV_URL', 'http://localhost:8000')\n",
+        "OUTPUT_DIR = os.getenv('COUNSEL_OUTPUT_DIR', './counsel-grpo-output')\n",
+        "RUN_TRAINING = os.getenv('RUN_TRAINING', '0') == '1'\n",
+        "MAX_STEPS = int(os.getenv('COUNSEL_MAX_STEPS', '200'))\n",
+        "DATASET_SIZE = int(os.getenv('COUNSEL_DATASET_SIZE', '256'))\n",
+        "\n",
+        "print({'model': MODEL, 'env_url': ENV_URL, 'run_training': RUN_TRAINING, 'max_steps': MAX_STEPS, 'dataset_size': DATASET_SIZE})"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "CURRICULUM_DISTRIBUTION = {\n",
+        "    'easy': {'easy': 1.0},\n",
+        "    'medium': {'easy': 0.25, 'medium': 0.75},\n",
+        "    'hard': {'easy': 0.10, 'medium': 0.30, 'hard': 0.60},\n",
+        "}\n",
+        "\n",
+        "def sample_stage_schedule(total: int = 256) -> List[str]:\n",
+        "    # Warm start on easy, then medium, then hard/mixed challenge cases.\n",
+        "    schedule = []\n",
+        "    for i in range(total):\n",
+        "        frac = i / max(1, total - 1)\n",
+        "        if frac < 0.25:\n",
+        "            schedule.append('easy')\n",
+        "        elif frac < 0.70:\n",
+        "            schedule.append('medium')\n",
+        "        else:\n",
+        "            schedule.append('hard')\n",
+        "    return schedule\n",
+        "\n",
+        "def create_dataset(num_samples: int = 256) -> Dataset:\n",
+        "    base_prompt = (\n",
+        "        'You are a sharp prosecuting attorney cross-examining a deterministic witness. '\n",
+        "        'Your goal is to surface contradictions by first making the witness commit to a claim, '\n",
+        "        'then presenting the exact exhibit that disproves it. Use the limited question budget efficiently. '\n",
+        "        'Avoid repeated, irrelevant, leading, or compound questions.'\n",
+        "    )\n",
+        "    stages = sample_stage_schedule(num_samples)\n",
+        "    prompts = [[{'role': 'user', 'content': base_prompt}] for _ in stages]\n",
+        "    return Dataset.from_dict({'prompt': prompts, 'curriculum_stage': stages})\n",
+        "\n",
+        "dataset = create_dataset(DATASET_SIZE)\n",
+        "dataset[:3]"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def question_pattern(question: str) -> str:\n",
+        "    text = re.sub(r'[^a-z0-9\\s]', ' ', (question or '').lower())\n",
+        "    return ' '.join(text.split()[:12])\n",
+        "\n",
+        "class CounselToolEnv:\n",
+        "    \"\"\"TRL environment wrapper. Constructor intentionally takes no args.\"\"\"\n",
+        "\n",
+        "    def __init__(self):\n",
+        "        self.client = CounselEnv(base_url=ENV_URL)\n",
+        "        self.reward = 0.0\n",
+        "        self.done = False\n",
+        "        self.stage = 'medium'\n",
+        "        self.questions: List[str] = []\n",
+        "        self.actions: List[str] = []\n",
+        "        self.last_components: Dict[str, Any] = {}\n",
+        "\n",
+        "    def reset(self, **kwargs) -> str:\n",
+        "        \"\"\"Reset the remote Counsel-Env episode.\"\"\"\n",
+        "        self.stage = kwargs.get('curriculum_stage') or 'medium'\n",
+        "        result = self.client.reset(curriculum_stage=self.stage)\n",
+        "        obs = result.observation\n",
+        "        self.reward = 0.0\n",
+        "        self.done = False\n",
+        "        self.questions = []\n",
+        "        self.actions = []\n",
+        "        self.last_components = obs.reward_components\n",
+        "        return (\n",
+        "            f'CASE BRIEF:\\n{obs.case_brief}\\n\\n'\n",
+        "            f'You have {obs.questions_remaining} questions. '\n",
+        "            f'Available exhibits: {obs.available_evidence}. '\n",
+        "            'Use ask_question, present_evidence, or rest_case.'\n",
+        "        )\n",
+        "\n",
+        "    def ask_question(self, question: str) -> str:\n",
+        "        \"\"\"Ask the witness a question.\n",
+        "\n",
+        "        Args:\n",
+        "            question: The question to ask the witness.\n",
+        "\n",
+        "        Returns:\n",
+        "            The witness response and remaining budget.\n",
+        "        \"\"\"\n",
+        "        if self.done:\n",
+        "            raise ValueError('Episode is over.')\n",
+        "        self.actions.append('ask_question')\n",
+        "        self.questions.append(question)\n",
+        "        result = self.client.step(CounselAction(tool='ask_question', text=question))\n",
+        "        obs = result.observation\n",
+        "        self.reward = obs.reward\n",
+        "        self.done = obs.done\n",
+        "        self.last_components = obs.reward_components\n",
+        "        return f'WITNESS: {obs.witness_response}\\n[{obs.questions_remaining} questions left]'\n",
+        "\n",
+        "    def present_evidence(self, exhibit_id: str) -> str:\n",
+        "        \"\"\"Present an exhibit to the witness.\n",
+        "\n",
+        "        Args:\n",
+        "            exhibit_id: The id of the exhibit to present.\n",
+        "\n",
+        "        Returns:\n",
+        "            The witness reaction.\n",
+        "        \"\"\"\n",
+        "        if self.done:\n",
+        "            raise ValueError('Episode is over.')\n",
+        "        self.actions.append('present_evidence')\n",
+        "        result = self.client.step(CounselAction(tool='present_evidence', exhibit_id=exhibit_id))\n",
+        "        obs = result.observation\n",
+        "        self.reward = obs.reward\n",
+        "        self.done = obs.done\n",
+        "        self.last_components = obs.reward_components\n",
+        "        return obs.witness_response\n",
+        "\n",
+        "    def rest_case(self) -> str:\n",
+        "        \"\"\"End the cross-examination.\n",
+        "\n",
+        "        Returns:\n",
+        "            Final episode status.\n",
+        "        \"\"\"\n",
+        "        self.actions.append('rest_case')\n",
+        "        result = self.client.step(CounselAction(tool='rest_case'))\n",
+        "        obs = result.observation\n",
+        "        self.reward = obs.reward\n",
+        "        self.done = True\n",
+        "        self.last_components = obs.reward_components\n",
+        "        return f'Case rested. Final reward: {self.reward:.3f}'\n",
+        "\n",
+        "    @property\n",
+        "    def action_diversity(self) -> int:\n",
+        "        return len(set(self.actions))\n",
+        "\n",
+        "    @property\n",
+        "    def unique_question_patterns_pct(self) -> float:\n",
+        "        patterns = {question_pattern(q) for q in self.questions}\n",
+        "        return len(patterns) / max(1, len(self.questions))"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def reward_func(environments, **kwargs) -> List[float]:\n",
+        "    # The environment computes WeightedSum(primary + auxiliary).\n",
+        "    return [float(env.reward) for env in environments]\n",
+        "\n",
+        "def log_diversity(environments: List[CounselToolEnv], path: str = 'rollout_debug.jsonl') -> None:\n",
+        "    rows = []\n",
+        "    for idx, env in enumerate(environments):\n",
+        "        row = {\n",
+        "            'episode': idx,\n",
+        "            'stage': env.stage,\n",
+        "            'reward': env.reward,\n",
+        "            'action_diversity': env.action_diversity,\n",
+        "            'unique_question_patterns_pct': env.unique_question_patterns_pct,\n",
+        "            **env.last_components,\n",
+        "        }\n",
+        "        rows.append(row)\n",
+        "    with open(path, 'a', encoding='utf-8') as handle:\n",
+        "        for row in rows:\n",
+        "            handle.write(json.dumps(row, sort_keys=True) + '\\n')\n",
+        "\n",
+        "# Failure detection required by the hackathon brief.\n",
+        "def warn_on_reward_difficulty(rewards: List[float]) -> None:\n",
+        "    avg_reward = float(np.mean(rewards)) if rewards else 0.0\n",
+        "    if avg_reward == 0.0:\n",
+        "        print('WARNING: ENV TOO HARD')\n",
+        "    if avg_reward > 0.7:\n",
+        "        print('WARNING: ENV TOO EASY')\n",
+        "    print(f'avg_reward={avg_reward:.3f}')"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "training_args = GRPOConfig(\n",
+        "    use_vllm=True,\n",
+        "    vllm_mode='colocate',\n",
+        "    chat_template_kwargs={'enable_thinking': False},\n",
+        "    max_completion_length=1024,\n",
+        "    num_generations=6,\n",
+        "    temperature=0.8,\n",
+        "    top_p=0.95,\n",
+        "    gradient_accumulation_steps=16,\n",
+        "    per_device_train_batch_size=1,\n",
+        "    learning_rate=1e-5,\n",
+        "    num_train_epochs=1,\n",
+        "    max_steps=MAX_STEPS,\n",
+        "    beta=0.04,\n",
+        "    log_completions=True,\n",
+        "    logging_steps=5,\n",
+        "    report_to='none',\n",
+        "    output_dir=OUTPUT_DIR,\n",
+        "    push_to_hub=False,\n",
+        ")\n",
+        "\n",
+        "trainer = None\n",
+        "if RUN_TRAINING:\n",
+        "    trainer = GRPOTrainer(\n",
+        "        model=MODEL,\n",
+        "        reward_funcs=reward_func,\n",
+        "        train_dataset=dataset,\n",
+        "        args=training_args,\n",
+        "        environment_factory=CounselToolEnv,\n",
+        "    )\n",
+        "    train_result = trainer.train()\n",
+        "    trainer.save_model(OUTPUT_DIR)\n",
+        "else:\n",
+        "    print('Training is disabled. Set RUN_TRAINING=1 only after credit approval.')\n",
+        "    print('Tiny dry-run example after approval: RUN_TRAINING=1 COUNSEL_MODEL=Qwen/Qwen3-0.6B COUNSEL_MAX_STEPS=5 COUNSEL_DATASET_SIZE=12')"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Local, no-credit rollout diagnostics. This uses the in-process env, not HF.\n",
+        "from counsel_env.server.diagnostics import run_rollout_diagnostics\n",
+        "\n",
+        "rows = run_rollout_diagnostics(output_path='rollout_debug.jsonl', num_episodes=10, policy='mixed')\n",
+        "rewards = [row['total_reward'] for row in rows]\n",
+        "warn_on_reward_difficulty(rewards)\n",
+        "print(f'non_zero_rollouts={sum(r > 0 for r in rewards)}/{len(rewards)}')"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Plot reward trend after a real run. This cell expects trainer logs or an exported metrics list.\n",
+        "# It intentionally does not fabricate a reward curve.\n",
+        "import matplotlib.pyplot as plt\n",
+        "\n",
+        "metrics_path = Path(OUTPUT_DIR) / 'trainer_state.json'\n",
+        "if metrics_path.exists():\n",
+        "    state = json.loads(metrics_path.read_text())\n",
+        "    history = state.get('log_history', [])\n",
+        "    steps = [row['step'] for row in history if 'reward' in row]\n",
+        "    rewards = [row['reward'] for row in history if 'reward' in row]\n",
+        "    if rewards:\n",
+        "        plt.figure(figsize=(7, 4))\n",
+        "        plt.plot(steps, rewards, marker='o')\n",
+        "        plt.xlabel('training step')\n",
+        "        plt.ylabel('GRPO reward')\n",
+        "        plt.title('Counsel-Env reward trend')\n",
+        "        plt.grid(alpha=0.3)\n",
+        "        plt.savefig('reward_curve.png', dpi=160, bbox_inches='tight')\n",
+        "        plt.show()\n",
+        "else:\n",
+        "    print('No trainer_state.json yet. Run approved training first, then rerun this cell.')"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "pygments_lexer": "ipython3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

openenv.yaml

@@ -0,0 +1,10 @@
+name: counsel-env
+description: Cross-examination arena — train LLMs to surface contradictions in witness testimony.
+tags:
+  - rl
+  - multi-agent
+  - theory-of-mind
+  - dialogue
+  - hackathon
+license: bsd-3-clause
+

pyproject.toml

@@ -0,0 +1,35 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "counsel-env"
+version = "0.1.0"
+dependencies = [
+    "openenv-core>=0.2.1",
+    "fastapi",
+    "uvicorn",
+    "pydantic",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m counsel_env.server.app
+server = "counsel_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["counsel_env", "counsel_env.server"]
+package-dir = { "counsel_env" = ".", "counsel_env.server" = "server" }

server/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Counsel Env environment server components."""
+
+try:
+    from .counsel_env_environment import CounselEnvironment
+except ImportError:
+    from counsel_env_environment import CounselEnvironment
+
+__all__ = ["CounselEnvironment"]

server/app.py

@@ -0,0 +1,89 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Counsel Env Environment.
+
+This module creates an HTTP server that exposes the CounselEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import CounselAction, CounselObservation
+    from .counsel_env_environment import CounselEnvironment
+except (ImportError, ModuleNotFoundError):
+    from models import CounselAction, CounselObservation
+    from server.counsel_env_environment import CounselEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    CounselEnvironment,
+    CounselAction,
+    CounselObservation,
+    env_name="counsel_env",
+    max_concurrent_envs=64,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+def run_server(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m counsel_env.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn counsel_env.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    run_server(host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

server/case_generator.py

@@ -0,0 +1,705 @@
+"""
+Cross-Examination Arena — Case generator.
+
+Three fully-fleshed templates (alibi, knowledge denial, possession denial),
+six slot-fill pools, and the public `generate_case()` factory.
+
+Add 2 more templates on Day 1 if time allows. Each new template just needs
+to return a dict with the same shape as `_make_case_dict` produces.
+"""
+
+import random
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+# ---------------------------------------------------------------------------
+# Contradiction dataclass (mirror of witness.Contradiction so the case file
+# stays self-contained; in your real codebase, import from witness.py).
+# ---------------------------------------------------------------------------
+@dataclass
+class Contradiction:
+    cid: str
+    trigger_keywords: List[str]
+    sealed_claim: str
+    disprover_evidence_id: str
+    triggered: bool = False
+    surfaced: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Slot-fill pools. Extend these freely — each entry adds case variety.
+# ---------------------------------------------------------------------------
+NAMES = [
+    "Sara Patel", "Mark Chen", "Alex Reyes", "Priya Sharma", "Jordan Kim",
+    "Diana Okafor", "Tomas Ruiz", "Yelena Volkov", "Hassan Ali", "Mei Tanaka",
+    "Carlos Mendes", "Ingrid Lindqvist", "Dev Krishnan", "Naomi Brown",
+    "Samir Haque", "Lila Andersson", "Theo Morales", "Reza Farahani",
+    "Kavita Iyer", "Owen Nakamura", "Esme Dubois", "Ravi Joshi",
+    "Hana Lee", "Felix Bauer", "Aaliyah Singh", "Mateo Silva",
+    "Zoe Whitfield", "Daichi Sato", "Nadine Mahfouz", "Pavel Novak",
+]
+
+PLACES = [
+    "the Riverside Cafe on Fifth Avenue",
+    "the parking garage at 22 Elm Street",
+    "the Marriott hotel lobby downtown",
+    "the office of Henderson & Co. on Pine",
+    "the warehouse on Industrial Drive",
+    "the gym on Lexington",
+    "Brennan's Bar near Union Square",
+    "the apartment at 480 Oak Lane",
+    "the boardwalk at Crescent Beach",
+    "the Greyhound bus station on Central",
+    "the parking lot behind the Westgate Mall",
+    "the rooftop bar at the Stratton Hotel",
+    "the public library on Walnut Street",
+    "the diner at the corner of 9th and Broad",
+]
+
+TIMES = [
+    "8:15 PM", "9:00 PM", "9:45 PM", "10:30 PM", "11:00 PM", "11:45 PM",
+    "12:15 AM", "1:00 AM", "7:30 PM", "6:45 PM",
+]
+
+DATES = [
+    "March 14th", "April 3rd", "January 22nd", "October 17th", "August 9th",
+    "December 5th", "May 28th", "June 14th",
+]
+
+OBJECTS = [
+    "the .38 revolver", "the briefcase", "the Rolex watch", "the burner phone",
+    "the laptop", "the security badge", "the diamond pendant",
+    "the warehouse keys", "the master keycard",
+]
+
+MOTIVES = [
+    "a $40,000 unpaid debt",
+    "a contested inheritance",
+    "a botched business partnership",
+    "an extramarital affair that had been discovered",
+    "a longstanding professional rivalry",
+    "the dismissal from a senior position six months earlier",
+]
+
+
+# ---------------------------------------------------------------------------
+# Helper to build the case dict in a consistent shape.
+# ---------------------------------------------------------------------------
+def _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions):
+    return {
+        "case_id": case_id,
+        "case_brief": brief,
+        "ground_truth": ground_truth,
+        "witness_story": story,
+        "evidence": evidence,
+        "contradictions": contradictions,
+    }
+
+
+def _case_suffix() -> str:
+    """Seed-respecting six-character case suffix."""
+    return f"{random.randint(0, 16**6 - 1):06x}"
+
+
+# ---------------------------------------------------------------------------
+# Helper functions for time manipulation
+# ---------------------------------------------------------------------------
+def _minus_minutes(time_str, minutes):
+    # Simple helper for time arithmetic
+    hour, minute = map(int, time_str.replace(" PM", "").replace(" AM", "").split(":"))
+    if "PM" in time_str and hour != 12:
+        hour += 12
+    total_minutes = hour * 60 + minute - minutes
+    new_hour = total_minutes // 60
+    new_minute = total_minutes % 60
+    return f"{new_hour % 12 or 12}:{new_minute:02d} {'PM' if new_hour >= 12 else 'AM'}"
+
+def _plus_minutes(time_str, minutes):
+    hour, minute = map(int, time_str.replace(" PM", "").replace(" AM", "").split(":"))
+    if "PM" in time_str and hour != 12:
+        hour += 12
+    total_minutes = hour * 60 + minute + minutes
+    new_hour = total_minutes // 60
+    new_minute = total_minutes % 60
+    return f"{new_hour % 12 or 12}:{new_minute:02d} {'PM' if new_hour >= 12 else 'AM'}"
+
+
+# ---------------------------------------------------------------------------
+# Template 1 — Alibi conflict
+# ---------------------------------------------------------------------------
+def generate_alibi_case():
+    """Witness claims they were at place A; phone/transit data places them at B."""
+    perp = random.choice(NAMES)
+    fake_place = random.choice(PLACES)
+    real_place = random.choice([p for p in PLACES if p != fake_place])
+    crime_place = random.choice([p for p in PLACES if p not in (fake_place, real_place)])
+    t = random.choice(TIMES)
+    date = random.choice(DATES)
+    motive = random.choice(MOTIVES)
+
+    case_id = f"alibi_{_case_suffix()}"
+    brief = (
+        f"{perp} is the prime suspect in the burglary at {crime_place} on the night of {date}. "
+        f"The state alleges the burglary occurred at approximately {t}. "
+        f"The defendant has taken the stand."
+    )
+    ground_truth = (
+        f"{perp} was at {real_place} at {t} on {date}, then traveled to {crime_place} "
+        f"and committed the burglary. Motive: {motive}."
+    )
+    story = {
+        "alibi":         f"I was at {fake_place} that entire evening with friends.",
+        "where":         f"I told you, {fake_place}. I never left.",
+        "evening":       f"I had dinner and drinks at {fake_place} until close.",
+        "warehouse":     f"I have never been to {crime_place}. Not once.",
+        "crime":         f"I had nothing to do with what happened at {crime_place}.",
+        "motive":        f"I had no reason to do anything to anyone.",
+        "victim":        f"We had a professional disagreement, that's all. Nothing serious.",
+        "phone":         f"My phone was with me the whole night.",
+    }
+    evidence = {
+        "phone_tower_log":
+            f"Cellular records: {perp}'s phone connected to the tower nearest "
+            f"{real_place} at {t}, then to the tower covering {crime_place} 22 minutes later.",
+        "ride_receipt":
+            f"Rideshare receipt in {perp}'s account: dropoff at {real_place} at "
+            f"{_minus_minutes(t, 30)}; second pickup at {real_place}, dropoff at "
+            f"{crime_place} at {_plus_minutes(t, 18)}.",
+        "victim_letter":
+            f"Letter from the victim's attorney to {perp}, dated three weeks before the "
+            f"burglary, formally demanding payment related to {motive}.",
+        "doormat_print":
+            f"A partial shoe print recovered from the doormat at {crime_place}, "
+            f"matching size and tread of footwear later seized from {perp}'s residence.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_alibi_location",
+            trigger_keywords=[
+                "where were you", "alibi", "that night", "evening", "your location",
+                t.lower(),
+            ],
+            sealed_claim=f"I was at {fake_place} the entire evening — I never left.",
+            disprover_evidence_id="phone_tower_log",
+        ),
+        Contradiction(
+            cid="c2_warehouse_familiarity",
+            trigger_keywords=[
+                "ever been to", "familiar with", "the warehouse", "the scene",
+                "crime scene", crime_place.split()[1].lower() if len(crime_place.split()) > 1 else "warehouse",
+            ],
+            sealed_claim=f"I have never set foot at {crime_place}. I wouldn't even know how to get there.",
+            disprover_evidence_id="ride_receipt",
+        ),
+        Contradiction(
+            cid="c3_motive_denial",
+            trigger_keywords=[
+                "motive", "reason", "grievance", "dispute", "the victim",
+                "any conflict", "disagreement",
+            ],
+            sealed_claim=f"I had no real grievance with the victim. We had a polite professional relationship.",
+            disprover_evidence_id="victim_letter",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Template 2 — Knowledge denial
+# ---------------------------------------------------------------------------
+def generate_knowledge_denial_case():
+    """Witness denies knowing victim/place/object; documentary evidence shows otherwise."""
+    perp = random.choice(NAMES)
+    victim = random.choice([n for n in NAMES if n != perp])
+    place = random.choice(PLACES)
+    date = random.choice(DATES)
+
+    case_id = f"knowledge_{_case_suffix()}"
+    brief = (
+        f"{perp} is charged with embezzlement from {place}. The state alleges {perp} "
+        f"systematically diverted funds in coordination with the manager, {victim}, "
+        f"between {date} and the present. The defendant denies knowing {victim}."
+    )
+    ground_truth = (
+        f"{perp} and {victim} have been business associates for over two years. "
+        f"They met at {place} and collaborated on the embezzlement scheme."
+    )
+    story = {
+        "know":          f"I don't know {victim} at all. Never met them.",
+        "victim":        f"Who is {victim}? I've never heard of them.",
+        "place":         f"I've never been to {place}.",
+        "embezzlement":  f"I had nothing to do with any embezzlement.",
+        "work":          f"I work in a completely different field.",
+        "meeting":       f"I've never met with anyone about this.",
+    }
+    evidence = {
+        "email_chain":
+            f"Email chain between {perp} and {victim} discussing the embezzlement plan, "
+            f"dated {date}, sent from {perp}'s work email.",
+        "meeting_notes":
+            f"Meeting notes from {place} conference room, dated two weeks ago, "
+            f"with {perp} and {victim}'s signatures.",
+        "bank_records":
+            f"Bank records showing transfers from {place}'s accounts to {perp}'s "
+            f"personal account, totaling $150,000 over six months.",
+        "visitor_log":
+            f"Security log from {place} showing {perp}'s entry and exit times "
+            f"on multiple dates, including meetings with {victim}.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_know_victim",
+            trigger_keywords=[
+                "know", "met", "familiar", victim.split()[0].lower(),
+                "relationship", "acquaintance",
+            ],
+            sealed_claim=f"I have never met {victim} in my life.",
+            disprover_evidence_id="email_chain",
+        ),
+        Contradiction(
+            cid="c2_place_visit",
+            trigger_keywords=[
+                "been to", "visited", place.split()[1].lower() if len(place.split()) > 1 else "place",
+                "location", "office",
+            ],
+            sealed_claim=f"I've never set foot in {place}.",
+            disprover_evidence_id="visitor_log",
+        ),
+        Contradiction(
+            cid="c3_collaboration",
+            trigger_keywords=[
+                "worked with", "collaborated", "together", "scheme",
+                "embezzlement", "plan",
+            ],
+            sealed_claim=f"I worked alone. No one else was involved.",
+            disprover_evidence_id="meeting_notes",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Template 3 — Possession denial
+# ---------------------------------------------------------------------------
+def generate_possession_denial_case():
+    """Witness denies possessing object; evidence shows they did."""
+    perp = random.choice(NAMES)
+    obj = random.choice(OBJECTS)
+    place = random.choice(PLACES)
+    date = random.choice(DATES)
+    motive = random.choice(MOTIVES)
+
+    case_id = f"possession_{_case_suffix()}"
+    brief = (
+        f"{perp} is charged with theft of {obj} from {place} on {date}. "
+        f"The state alleges {perp} stole {obj} and used it in a subsequent crime. "
+        f"The defendant denies ever possessing {obj}."
+    )
+    ground_truth = (
+        f"{perp} stole {obj} from {place} on {date}. They used it later that night "
+        f"in a robbery. Motive for the theft: {motive}."
+    )
+    story = {
+        "possession":   f"I've never had {obj}. Never seen it.",
+        "object":       f"What is {obj}? I've never heard of it.",
+        "theft":        f"I didn't steal anything.",
+        "crime":        f"I had nothing to do with any crime.",
+        "place":        f"I've never been to {place}.",
+        "motive":       f"I had no reason to steal anything.",
+    }
+    evidence = {
+        "surveillance_footage":
+            f"Surveillance footage from {place} showing {perp} entering at 8:00 PM "
+            f"on {date}, taking {obj}, and leaving at 8:15 PM.",
+        "fingerprint_analysis":
+            f"Fingerprint analysis of {obj} recovered from the crime scene, "
+            f"matching {perp}'s fingerprints on file.",
+        "witness_statement":
+            f"Statement from an employee at {place} identifying {perp} as the person "
+            f"who took {obj} on {date}.",
+        "pawn_receipt":
+            f"Pawn shop receipt in {perp}'s name, dated the day after {date}, "
+            f"for selling an item matching the description of {obj}.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_possession_object",
+            trigger_keywords=[
+                "have", "possessed", "owned", obj.split()[1].lower() if len(obj.split()) > 1 else "object",
+                "in your possession",
+            ],
+            sealed_claim=f"I've never possessed {obj} in my life.",
+            disprover_evidence_id="fingerprint_analysis",
+        ),
+        Contradiction(
+            cid="c2_theft_admission",
+            trigger_keywords=[
+                "stole", "took", "theft", "place", place.split()[1].lower() if len(place.split()) > 1 else "place",
+            ],
+            sealed_claim=f"I didn't steal anything from {place}.",
+            disprover_evidence_id="surveillance_footage",
+        ),
+        Contradiction(
+            cid="c3_disposal",
+            trigger_keywords=[
+                "sold", "pawned", "got rid of", "disposed", "object",
+            ],
+            sealed_claim=f"I don't know what happened to {obj} after it was stolen.",
+            disprover_evidence_id="pawn_receipt",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Template 4 — Timeline shift (new template)
+# ---------------------------------------------------------------------------
+def generate_timeline_shift_case():
+    """Witness claims event happened at time A; evidence shows time B."""
+    perp = random.choice(NAMES)
+    place = random.choice(PLACES)
+    fake_time = random.choice(TIMES)
+    real_time = random.choice([t for t in TIMES if t != fake_time])
+    date = random.choice(DATES)
+    motive = random.choice(MOTIVES)
+
+    case_id = f"timeline_{_case_suffix()}"
+    brief = (
+        f"{perp} is accused of assault at {place} on {date}. The victim claims the assault "
+        f"occurred at {real_time}. The defendant claims they were elsewhere at that time."
+    )
+    ground_truth = (
+        f"{perp} assaulted the victim at {place} at {real_time} on {date}. "
+        f"They falsely claimed to be at another location at {fake_time}. Motive: {motive}."
+    )
+    story = {
+        "time":         f"The assault happened at {fake_time}, not {real_time}.",
+        "when":         f"It was around {fake_time}. I remember clearly.",
+        "alibi":        f"I was at home at {fake_time}. I have witnesses.",
+        "assault":      f"I didn't assault anyone.",
+        "place":        f"I've never been to {place}.",
+        "motive":       f"I had no reason to hurt anyone.",
+    }
+    evidence = {
+        "victim_statement":
+            f"Victim's statement: The assault occurred at {real_time} on {date} at {place}.",
+        "surveillance_timestamp":
+            f"Surveillance footage timestamped at {real_time} showing {perp} at {place}.",
+        "phone_records":
+            f"Phone records showing {perp}'s location at {place} at {real_time}.",
+        "witness_alibi":
+            f"Alibi witness statement claiming {perp} was with them at {fake_time}, "
+            f"but the witness later recanted under pressure.",
+        "motive_email":
+            f"Email from {perp} sent the week before {date} describing {motive} "
+            f"and threatening to confront the victim at {place}.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_time_of_assault",
+            trigger_keywords=[
+                "time", "when", "occurred", "happened", real_time.lower(),
+            ],
+            sealed_claim=f"The assault happened at {fake_time}, not {real_time}.",
+            disprover_evidence_id="surveillance_timestamp",
+        ),
+        Contradiction(
+            cid="c2_location_during_assault",
+            trigger_keywords=[
+                "where", "location", "place", place.split()[1].lower() if len(place.split()) > 1 else "place",
+            ],
+            sealed_claim=f"I was not at {place} during the assault.",
+            disprover_evidence_id="phone_records",
+        ),
+        Contradiction(
+            cid="c3_motive_denial",
+            trigger_keywords=[
+                "motive", "reason", "why", "conflict", "grievance",
+            ],
+            sealed_claim="I had no conflict with the victim and no reason to confront anyone.",
+            disprover_evidence_id="motive_email",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Template 5 — Motive coverup (new template)
+# ---------------------------------------------------------------------------
+def generate_motive_coverup_case():
+    """Witness denies motive; evidence reveals hidden relationship."""
+    perp = random.choice(NAMES)
+    victim = random.choice([n for n in NAMES if n != perp])
+    place = random.choice(PLACES)
+    date = random.choice(DATES)
+    motive = random.choice(MOTIVES)
+
+    case_id = f"motive_{_case_suffix()}"
+    brief = (
+        f"{perp} is charged with harassment of {victim}. The state alleges {perp} "
+        f"stalked {victim} at {place} on {date}. The defendant denies any motive."
+    )
+    ground_truth = (
+        f"{perp} harassed {victim} due to {motive}. They had a hidden relationship "
+        f"that went sour, leading to the stalking at {place} on {date}."
+    )
+    story = {
+        "motive":       f"I had no reason to harass {victim}.",
+        "relationship": f"I barely knew {victim}. Just an acquaintance.",
+        "harassment":   f"I didn't harass anyone.",
+        "place":        f"I've never been to {place}.",
+        "victim":       f"{victim} and I had no issues.",
+    }
+    evidence = {
+        "text_messages":
+            f"Text messages between {perp} and {victim} showing romantic relationship "
+            f"that ended badly due to {motive}.",
+        "surveillance_stalking":
+            f"Surveillance footage of {perp} following {victim} at {place} on {date}.",
+        "police_reports":
+            f"Previous police reports of {perp} contacting {victim} inappropriately.",
+        "witness_statement":
+            f"Witness statement from a mutual friend confirming the relationship and motive.",
+        "parking_receipt":
+            f"Parking receipt in {perp}'s name placing their car beside {place} "
+            f"on {date}, fifteen minutes before {victim} arrived.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_relationship_denial",
+            trigger_keywords=[
+                "relationship", "knew", "acquaintance", victim.split()[0].lower(),
+            ],
+            sealed_claim=f"I barely knew {victim}. We were just casual acquaintances.",
+            disprover_evidence_id="text_messages",
+        ),
+        Contradiction(
+            cid="c2_motive_denial",
+            trigger_keywords=[
+                "motive", "reason", "why", "harass",
+            ],
+            sealed_claim=f"I had absolutely no motive to harass {victim}.",
+            disprover_evidence_id="witness_statement",
+        ),
+        Contradiction(
+            cid="c3_place_denial",
+            trigger_keywords=[
+                "where", "place", "visited", "been to", place.split()[1].lower() if len(place.split()) > 1 else "place",
+            ],
+            sealed_claim=f"I was nowhere near {place} on {date}.",
+            disprover_evidence_id="parking_receipt",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Template 6 - Corporate fraud deposition
+# ---------------------------------------------------------------------------
+def generate_corporate_fraud_case():
+    """Executive denies knowledge, approval, and motive in an internal fraud inquiry."""
+    executive = random.choice(NAMES)
+    analyst = random.choice([n for n in NAMES if n != executive])
+    company = random.choice(["Northstar Biologics", "Meridian Freight", "Aster Cloud", "HelioGrid Energy"])
+    t = random.choice(TIMES)
+    date = random.choice(DATES)
+    motive = random.choice(MOTIVES)
+
+    case_id = f"corporate_{_case_suffix()}"
+    brief = (
+        f"{executive}, a senior executive at {company}, is questioned about revenue manipulation "
+        f"recorded on {date}. The company claims the irregular entries were a clerical mistake."
+    )
+    ground_truth = (
+        f"{executive} approved backdated revenue entries at {t} on {date}, after {analyst} "
+        f"warned that the quarter would miss guidance. Motive: {motive}."
+    )
+    story = {
+        "approval": "I never approved any backdated revenue entries.",
+        "analyst": f"{analyst} handled routine reporting. I did not discuss adjustments with them.",
+        "forecast": "I was not worried about the quarterly forecast.",
+        "revenue": "Any revenue issue was a clerical mistake, not my decision.",
+        "meeting": "There was no late meeting about accounting entries.",
+    }
+    evidence = {
+        "approval_log":
+            f"Accounting system log: {executive} approved backdated entries at {t} on {date}.",
+        "analyst_chat":
+            f"Chat from {analyst} to {executive}: 'Without the adjustment, we miss guidance by 8%.'",
+        "board_deck":
+            f"Draft board deck listing the missed forecast and {motive} as a risk to compensation.",
+        "calendar_invite":
+            f"Calendar invite: emergency revenue recognition meeting with {executive} and {analyst} at {t}.",
+        "printer_log":
+            "Printer maintenance log from the same floor, unrelated to the accounting entries.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_approval_denial",
+            trigger_keywords=["approved", "approval", "signed off", "authorized", "revenue"],
+            sealed_claim="I never approved or authorized any backdated revenue entries.",
+            disprover_evidence_id="approval_log",
+        ),
+        Contradiction(
+            cid="c2_analyst_discussion",
+            trigger_keywords=["analyst", analyst.split()[0].lower(), "discuss", "guidance", "forecast"],
+            sealed_claim=f"I did not discuss any forecast problem with {analyst}.",
+            disprover_evidence_id="analyst_chat",
+        ),
+        Contradiction(
+            cid="c3_late_meeting",
+            trigger_keywords=["meeting", "calendar", "late", t.lower(), "emergency"],
+            sealed_claim="There was no late meeting about accounting entries.",
+            disprover_evidence_id="calendar_invite",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Template 7 - Workplace investigation
+# ---------------------------------------------------------------------------
+def generate_workplace_investigation_case():
+    """Manager denies a message, location, and prior warning in an HR inquiry."""
+    manager = random.choice(NAMES)
+    employee = random.choice([n for n in NAMES if n != manager])
+    place = random.choice(["Conference Room B", "the sixth-floor break room", "the loading dock", "the HR office"])
+    date = random.choice(DATES)
+    t = random.choice(TIMES)
+
+    case_id = f"workplace_{_case_suffix()}"
+    brief = (
+        f"{manager} is questioned in an HR investigation after {employee} reported retaliation "
+        f"at {place} on {date}. The manager denies sending threatening messages or being nearby."
+    )
+    ground_truth = (
+        f"{manager} sent a threatening message before meeting {employee} at {place} at {t}. "
+        f"HR had warned {manager} one week earlier."
+    )
+    story = {
+        "message": f"I never sent {employee} any threatening message.",
+        "where": f"I was not near {place} that day.",
+        "warning": "HR never warned me about retaliation.",
+        "employee": f"{employee} and I barely interacted.",
+        "retaliation": "I did not retaliate against anyone.",
+    }
+    evidence = {
+        "message_export":
+            f"Company chat export: {manager} wrote to {employee}, 'Drop the complaint or regret it,' on {date}.",
+        "badge_scan":
+            f"Badge access log: {manager} entered {place} at {t} on {date}.",
+        "hr_warning_memo":
+            f"HR memo issued one week before {date}, warning {manager} not to contact {employee}.",
+        "security_clip":
+            f"Security clip still: {manager} standing outside {place} minutes before {employee} arrived.",
+        "cafeteria_menu":
+            "Cafeteria menu from that week, unrelated to the investigation.",
+    }
+    contradictions = [
+        Contradiction(
+            cid="c1_message_denial",
+            trigger_keywords=["message", "text", "chat", "threat", employee.split()[0].lower()],
+            sealed_claim=f"I never sent {employee} any threatening message.",
+            disprover_evidence_id="message_export",
+        ),
+        Contradiction(
+            cid="c2_location_denial",
+            trigger_keywords=["where", "location", "near", "badge", place.split()[0].lower()],
+            sealed_claim=f"I was nowhere near {place} on {date}.",
+            disprover_evidence_id="badge_scan",
+        ),
+        Contradiction(
+            cid="c3_warning_denial",
+            trigger_keywords=["warning", "hr", "memo", "retaliation", "complaint"],
+            sealed_claim="HR never warned me about contacting the employee.",
+            disprover_evidence_id="hr_warning_memo",
+        ),
+    ]
+    return _make_case_dict(case_id, brief, ground_truth, story, evidence, contradictions)
+
+
+# ---------------------------------------------------------------------------
+# Public factory function
+# ---------------------------------------------------------------------------
+CURRICULUM_DISTRIBUTIONS = {
+    "easy": {"easy": 1.0},
+    "warmup": {"easy": 1.0},
+    "medium": {"easy": 0.25, "medium": 0.75},
+    "main": {"easy": 0.2, "medium": 0.8},
+    "hard": {"easy": 0.1, "medium": 0.3, "hard": 0.6},
+    "challenge": {"medium": 0.25, "hard": 0.75},
+    "mixed": {"easy": 0.3, "medium": 0.45, "hard": 0.25},
+}
+
+
+def _sample_difficulty(curriculum_stage: str, distribution: Dict[str, float] | None = None) -> str:
+    choices = distribution or CURRICULUM_DISTRIBUTIONS.get(curriculum_stage, {curriculum_stage: 1.0})
+    labels = list(choices.keys())
+    weights = list(choices.values())
+    return random.choices(labels, weights=weights, k=1)[0]
+
+
+def _apply_difficulty(case: Dict, difficulty: str) -> Dict:
+    contradictions = list(case["contradictions"])
+
+    if difficulty == "easy":
+        case["contradictions"] = contradictions[:1]
+    elif difficulty == "medium":
+        case["contradictions"] = contradictions[:2]
+        for contradiction in case["contradictions"]:
+            if "where" not in contradiction.trigger_keywords:
+                contradiction.trigger_keywords.append("where")
+    elif difficulty == "hard":
+        case["contradictions"] = contradictions[: max(3, len(contradictions))]
+        case["evidence"]["irrelevant_weather_report"] = (
+            "Weather report: light rain near the courthouse. It does not address any witness claim."
+        )
+        case["evidence"]["unrelated_receipt"] = (
+            "Receipt for coffee purchased by an unrelated bystander earlier that afternoon."
+        )
+        for contradiction in case["contradictions"]:
+            if "why" not in contradiction.trigger_keywords:
+                contradiction.trigger_keywords.append("why")
+    else:
+        raise ValueError(f"Unknown difficulty: {difficulty}")
+
+    case["difficulty"] = difficulty
+    return case
+
+
+def generate_case(
+    difficulty: str | None = None,
+    curriculum_stage: str = "medium",
+    distribution: Dict[str, float] | None = None,
+) -> Dict:
+    """
+    Generate a random cross-examination case.
+
+    Args:
+        difficulty: "easy", "medium", or "hard" — controls number of contradictions.
+
+    Returns:
+        Case dict with brief, story, evidence, contradictions.
+    """
+    templates = [
+        generate_alibi_case,
+        generate_knowledge_denial_case,
+        generate_possession_denial_case,
+        generate_timeline_shift_case,
+        generate_motive_coverup_case,
+        generate_corporate_fraud_case,
+        generate_workplace_investigation_case,
+    ]
+    selected_difficulty = difficulty or _sample_difficulty(curriculum_stage, distribution)
+    return _apply_difficulty(random.choice(templates)(), selected_difficulty)
+
+
+if __name__ == "__main__":
+    # Test the generator
+    case = generate_case()
+    print(f"Case ID: {case['case_id']}")
+    print(f"Brief: {case['case_brief']}")
+    print(f"Contradictions: {len(case['contradictions'])}")
+    for c in case["contradictions"]:
+        print(f"  - {c.cid}: {c.trigger_keywords}")

server/counsel_env_environment.py

@@ -0,0 +1,394 @@
+import random
+import re
+from copy import deepcopy
+from typing import Any, Dict, List, Optional
+
+from openenv.core.env_server.interfaces import Environment
+
+try:
+    from ..models import CounselAction, CounselObservation, CounselState
+except ImportError:  # pragma: no cover - supports direct module execution
+    from models import CounselAction, CounselObservation, CounselState
+
+try:
+    from .case_generator import generate_case
+    from .rubrics import Total
+    from .witness import Contradiction, Witness
+except ImportError:  # pragma: no cover - supports direct module execution
+    from case_generator import generate_case
+    from rubrics import Total
+    from witness import Contradiction, Witness
+
+
+QUESTION_BUDGET = 15
+MAX_ACTIONS = QUESTION_BUDGET * 3
+PRIMARY_WEIGHT = 0.8
+AUXILIARY_WEIGHT = 0.2
+
+
+class CounselEnvironment(Environment):
+    """Cross-examination arena with deterministic witness mechanics."""
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+    QUESTION_BUDGET = QUESTION_BUDGET
+    MAX_ACTIONS = MAX_ACTIONS
+
+    def __init__(self):
+        super().__init__(rubric=Total())
+        self._initialize_empty_state()
+
+    def _initialize_empty_state(self) -> None:
+        self.case: Dict[str, Any] = {}
+        self.witness: Optional[Witness] = None
+        self.episode_id: Optional[str] = None
+        self.seed: Optional[int] = None
+        self.questions_used = 0
+        self.action_count = 0
+        self.transcript: List[str] = []
+        self.transcript_events: List[Dict[str, Any]] = []
+        self.asked_question_keys: set[str] = set()
+        self.question_lengths: List[int] = []
+        self.duplicate_question_count = 0
+        self.irrelevant_question_count = 0
+        self.inadmissible_count = 0
+        self.invalid_exhibit_count = 0
+        self.keyword_question_count = 0
+        self.contradictions_triggered_count = 0
+        self.trigger_action_by_cid: Dict[str, int] = {}
+        self.evidence_presented_count = 0
+        self.evidence_timing_successes = 0
+        self.blind_evidence_count = 0
+        self.done = False
+        self.latest_response = ""
+        self.reward_components: Dict[str, float] = {}
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        curriculum_stage: Optional[str] = None,
+        difficulty: Optional[str] = None,
+        **kwargs: Any,
+    ) -> CounselObservation:
+        """Reset the environment with a curriculum-aware generated case."""
+        if seed is not None:
+            random.seed(seed)
+
+        self._initialize_empty_state()
+        self.seed = seed
+        self.episode_id = episode_id
+        stage = curriculum_stage or kwargs.get("stage") or "medium"
+        self.case = generate_case(difficulty=difficulty, curriculum_stage=stage)
+        contradictions = [
+            Contradiction(
+                cid=c.cid if hasattr(c, "cid") else c["cid"],
+                trigger_keywords=(
+                    c.trigger_keywords if hasattr(c, "trigger_keywords") else c["trigger_keywords"]
+                ),
+                sealed_claim=c.sealed_claim if hasattr(c, "sealed_claim") else c["sealed_claim"],
+                disprover_evidence_id=(
+                    c.disprover_evidence_id
+                    if hasattr(c, "disprover_evidence_id")
+                    else c["disprover_evidence_id"]
+                ),
+            )
+            for c in self.case["contradictions"]
+        ]
+        self.witness = Witness(self.case["witness_story"], contradictions)
+        return self._obs("")
+
+    def step(
+        self,
+        action: CounselAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> CounselObservation:
+        """Execute an action and return the next observation."""
+        if self.done:
+            return self._obs("[Episode already over.]")
+
+        self.action_count += 1
+        tool = (action.tool or "").strip()
+
+        if self.action_count > self.MAX_ACTIONS:
+            self.done = True
+            return self._obs("[Safety stop: maximum action count reached.]")
+
+        if tool == "ask_question":
+            response = self._handle_question(action.text or "")
+        elif tool == "present_evidence":
+            response = self._handle_evidence(action.exhibit_id or "")
+        elif tool == "make_objection":
+            response = self._handle_objection(action.reason or "")
+        elif tool == "rest_case":
+            response = "[Counsel rests.]"
+            self.done = True
+        else:
+            self.inadmissible_count += 1
+            response = f"Invalid action: {tool or '<empty>'}."
+
+        self.latest_response = response
+        self.transcript.append(self._format_transcript_line(action, response))
+
+        if self.questions_used >= self.QUESTION_BUDGET:
+            self.done = True
+
+        return self._obs(response)
+
+    @property
+    def state(self) -> CounselState:
+        """Return compact state for OpenEnv clients and diagnostics."""
+        contradictions = self.witness.contradictions if self.witness is not None else []
+        return CounselState(
+            case_id=self.case.get("case_id", ""),
+            difficulty=self.case.get("difficulty", ""),
+            episode_id=self.episode_id,
+            step_count=self.action_count,
+            contradictions_total=len(contradictions),
+            contradictions_triggered=sum(1 for c in contradictions if c.triggered),
+            contradictions_surfaced=sum(1 for c in contradictions if c.surfaced),
+            questions_used=self.questions_used,
+            action_count=self.action_count,
+            duplicate_question_count=self.duplicate_question_count,
+            irrelevant_question_count=self.irrelevant_question_count,
+            inadmissible_count=self.inadmissible_count,
+            evidence_timing_successes=self.evidence_timing_successes,
+        )
+
+    def _handle_question(self, question: str) -> str:
+        if self.questions_used >= self.QUESTION_BUDGET:
+            self.done = True
+            return "Question budget exhausted."
+
+        clean_question = question.strip()
+        if not clean_question:
+            self.inadmissible_count += 1
+            return "Please ask a proper question."
+
+        if len(clean_question) > 1000:
+            clean_question = clean_question[:1000]
+
+        self.questions_used += 1
+        self.question_lengths.append(len(clean_question.split()))
+
+        if _is_inadmissible(clean_question):
+            self.inadmissible_count += 1
+            return "[Objection sustained: inadmissible question.]"
+
+        question_key = _semantic_key(clean_question)
+        if question_key in self.asked_question_keys:
+            self.duplicate_question_count += 1
+            return "You've already asked that question."
+        self.asked_question_keys.add(question_key)
+
+        before_triggered = self._triggered_count()
+        contains_trigger_keyword = self._contains_trigger_keyword(clean_question)
+        if contains_trigger_keyword:
+            self.keyword_question_count += 1
+
+        assert self.witness is not None
+        triggered_before = {c.cid for c in self.witness.contradictions if c.triggered}
+        response = self.witness.respond_to_question(clean_question)
+        triggered_after = {c.cid for c in self.witness.contradictions if c.triggered}
+        for cid in sorted(triggered_after - triggered_before):
+            self.trigger_action_by_cid[cid] = self.action_count
+        after_triggered = self._triggered_count()
+        self.contradictions_triggered_count += max(0, after_triggered - before_triggered)
+
+        if not contains_trigger_keyword and response == "I don't recall.":
+            self.irrelevant_question_count += 1
+
+        return response
+
+    def _handle_evidence(self, exhibit_id: str) -> str:
+        if not exhibit_id or exhibit_id not in self.case.get("evidence", {}):
+            self.inadmissible_count += 1
+            self.invalid_exhibit_count += 1
+            return "Invalid exhibit ID."
+
+        self.evidence_presented_count += 1
+        assert self.witness is not None
+        surfaced_before = {c.cid for c in self.witness.contradictions if c.surfaced}
+        response = self.witness.react_to_evidence(exhibit_id)
+        surfaced_after = {c.cid for c in self.witness.contradictions if c.surfaced}
+        newly_surfaced = surfaced_after - surfaced_before
+        if newly_surfaced:
+            for cid in newly_surfaced:
+                trigger_step = self.trigger_action_by_cid.get(cid)
+                if trigger_step is not None and self.action_count - trigger_step <= 2:
+                    self.evidence_timing_successes += 1
+        elif not any(c.disprover_evidence_id == exhibit_id and c.triggered for c in self.witness.contradictions):
+            self.blind_evidence_count += 1
+        return response
+
+    def _handle_objection(self, reason: str) -> str:
+        self.inadmissible_count += 1
+        if not reason.strip():
+            return "Objection requires a reason."
+        return "Objection overruled: no objection window is currently open."
+
+    def _obs(self, latest_response: str) -> CounselObservation:
+        components = self._calculate_reward_components()
+        reward = components["total_reward"] if self.done else 0.0
+        return CounselObservation(
+            witness_response=latest_response,
+            available_evidence=list(self.case.get("evidence", {}).keys()),
+            evidence_descriptions=deepcopy(self.case.get("evidence", {})),
+            questions_remaining=max(0, self.QUESTION_BUDGET - self.questions_used),
+            transcript_tail=self._get_transcript_tail(),
+            case_brief=self.case.get("case_brief", ""),
+            case_id=self.case.get("case_id", ""),
+            difficulty=self.case.get("difficulty", ""),
+            done=self.done,
+            reward=reward,
+            reward_components=components,
+        )
+
+    def _calculate_reward(self) -> float:
+        components = self._calculate_reward_components()
+        reward = (
+            PRIMARY_WEIGHT * components["primary_reward"]
+            + AUXILIARY_WEIGHT * components["auxiliary_reward_raw"]
+        )
+        return max(0.0, min(1.0, reward))
+
+    def _calculate_reward_components(self) -> Dict[str, float]:
+        contradictions = self.witness.contradictions if self.witness is not None else []
+        total = max(1, len(contradictions))
+        surfaced = sum(1 for c in contradictions if c.surfaced)
+        triggered = sum(1 for c in contradictions if c.triggered)
+        question_total = max(1, self.questions_used)
+
+        primary_reward = surfaced / total
+        auxiliary = 0.0
+        auxiliary += 0.2 * triggered
+        auxiliary += 0.1 * self.keyword_question_count
+        auxiliary += 0.1 * self.evidence_timing_successes
+        auxiliary -= 0.05 * (self.duplicate_question_count + self.irrelevant_question_count)
+        auxiliary -= 0.05 * self.blind_evidence_count
+        auxiliary -= 0.1 * self.inadmissible_count
+
+        self.reward_components = {
+            "primary_reward": primary_reward,
+            "auxiliary_reward_raw": auxiliary,
+            "total_reward": max(0.0, min(1.0, PRIMARY_WEIGHT * primary_reward + AUXILIARY_WEIGHT * auxiliary)),
+            "contradictions_total": float(len(contradictions)),
+            "contradictions_triggered": float(triggered),
+            "contradictions_surfaced": float(surfaced),
+            "keyword_questions": float(self.keyword_question_count),
+            "evidence_timing_successes": float(self.evidence_timing_successes),
+            "blind_evidence_count": float(self.blind_evidence_count),
+            "duplicate_questions": float(self.duplicate_question_count),
+            "irrelevant_questions": float(self.irrelevant_question_count),
+            "inadmissible_actions": float(self.inadmissible_count),
+            "useless_questions_ratio": (
+                (self.duplicate_question_count + self.irrelevant_question_count) / question_total
+            ),
+            "avg_question_length": (
+                sum(self.question_lengths) / len(self.question_lengths)
+                if self.question_lengths
+                else 0.0
+            ),
+        }
+        return self.reward_components
+
+    def _triggered_count(self) -> int:
+        if self.witness is None:
+            return 0
+        return sum(1 for c in self.witness.contradictions if c.triggered)
+
+    def _contains_trigger_keyword(self, question: str) -> bool:
+        if self.witness is None:
+            return False
+        q_lower = question.lower()
+        for contradiction in self.witness.contradictions:
+            if any(keyword.lower() in q_lower for keyword in contradiction.trigger_keywords):
+                return True
+        return False
+
+    def _format_transcript_line(self, action: CounselAction, response: str) -> str:
+        if action.tool == "ask_question":
+            action_text = action.text or ""
+            prefix = "Q"
+        elif action.tool == "present_evidence":
+            action_text = action.exhibit_id or ""
+            prefix = "Evidence"
+        elif action.tool == "make_objection":
+            action_text = action.reason or ""
+            prefix = "Objection"
+        else:
+            action_text = action.tool or ""
+            prefix = "Action"
+        event = {
+            "step": self.action_count,
+            "tool": action.tool or "",
+            "input": action_text,
+            "response": response,
+            "questions_remaining": max(0, self.QUESTION_BUDGET - self.questions_used),
+            "triggered": [c.cid for c in self.witness.contradictions if c.triggered] if self.witness else [],
+            "surfaced": [c.cid for c in self.witness.contradictions if c.surfaced] if self.witness else [],
+        }
+        self.transcript_events.append(event)
+        return f"{prefix}: {action_text}\nA: {response}"
+
+    def _get_transcript_tail(self) -> str:
+        return "\n".join(self.transcript[-5:])
+
+    def export_transcript_json(self) -> Dict[str, Any]:
+        """Return a replayable transcript payload for evaluation artifacts."""
+        return {
+            "episode_id": self.episode_id,
+            "seed": self.seed,
+            "case_id": self.case.get("case_id", ""),
+            "difficulty": self.case.get("difficulty", ""),
+            "case_brief": self.case.get("case_brief", ""),
+            "evidence": deepcopy(self.case.get("evidence", {})),
+            "reward_components": self._calculate_reward_components(),
+            "events": deepcopy(self.transcript_events),
+        }
+
+    def export_transcript_markdown(self) -> str:
+        """Return a compact human-readable transcript with contradiction labels."""
+        payload = self.export_transcript_json()
+        lines = [
+            f"## {payload['case_id']} ({payload['difficulty']})",
+            "",
+            payload["case_brief"],
+            "",
+            "### Transcript",
+        ]
+        for event in payload["events"]:
+            lines.append(
+                f"- Step {event['step']} `{event['tool']}`: {event['input']}\n"
+                f"  - Witness: {event['response']}\n"
+                f"  - Triggered: {', '.join(event['triggered']) or 'none'}; "
+                f"Surfaced: {', '.join(event['surfaced']) or 'none'}"
+            )
+        lines.extend(
+            [
+                "",
+                "### Reward",
+                "```json",
+                str(payload["reward_components"]).replace("'", '"'),
+                "```",
+            ]
+        )
+        return "\n".join(lines)
+
+
+def _semantic_key(question: str) -> str:
+    text = re.sub(r"[^a-z0-9\s]", " ", question.lower())
+    words = [word for word in text.split() if word not in {"the", "a", "an", "you", "your", "did"}]
+    return " ".join(words)
+
+
+def _is_inadmissible(question: str) -> bool:
+    q_lower = question.lower()
+    leading_patterns = ["isn't it true that", "didn't you", "wouldn't you agree"]
+    if any(pattern in q_lower for pattern in leading_patterns):
+        return True
+    if question.count("?") > 1:
+        return True
+    if q_lower.count(" and ") > 2:
+        return True
+    return False

server/diagnostics.py

@@ -0,0 +1,124 @@
+import json
+import random
+import re
+from pathlib import Path
+from typing import Callable, Dict, List
+
+from counsel_env.models import CounselAction
+from counsel_env.server.counsel_env_environment import CounselEnvironment
+
+
+def _question_pattern(question: str) -> str:
+    text = re.sub(r"[^a-z0-9\s]", " ", question.lower())
+    tokens = ["<num>" if token.isdigit() else token for token in text.split()]
+    return " ".join(tokens[:12])
+
+
+def _scripted_policy(env: CounselEnvironment, rng: random.Random) -> List[str]:
+    questions: List[str] = []
+    for contradiction in env.witness.contradictions[:2]:
+        question = f"{contradiction.trigger_keywords[0]}?"
+        questions.append(question)
+        env.step(CounselAction(tool="ask_question", text=question))
+        env.step(CounselAction(tool="present_evidence", exhibit_id=contradiction.disprover_evidence_id))
+        if env.done:
+            break
+    return questions
+
+
+def _random_policy(env: CounselEnvironment, rng: random.Random) -> List[str]:
+    questions: List[str] = []
+    generic_questions = [
+        "What happened that day?",
+        "Do you remember the weather?",
+        "Who else was nearby?",
+        "Can you describe your routine?",
+        "What did you eat for dinner?",
+        "Did anything unusual happen?",
+    ]
+    for _ in range(8):
+        if rng.random() < 0.75:
+            question = rng.choice(generic_questions)
+            questions.append(question)
+            env.step(CounselAction(tool="ask_question", text=question))
+        else:
+            exhibit = rng.choice(list(env.case["evidence"].keys()))
+            env.step(CounselAction(tool="present_evidence", exhibit_id=exhibit))
+        if env.done:
+            break
+    return questions
+
+
+def _mixed_policy(env: CounselEnvironment, rng: random.Random, episode: int) -> List[str]:
+    if episode in {0, 4, 8}:
+        return _scripted_policy(env, rng)
+    return _random_policy(env, rng)
+
+
+POLICIES: Dict[str, Callable[[CounselEnvironment, random.Random, int], List[str]]] = {
+    "mixed": _mixed_policy,
+    "scripted": lambda env, rng, episode: _scripted_policy(env, rng),
+    "random": lambda env, rng, episode: _random_policy(env, rng),
+}
+
+
+def run_rollout_diagnostics(
+    output_path: str | Path = "rollout_debug.jsonl",
+    num_episodes: int = 10,
+    policy: str = "mixed",
+    seed: int = 13,
+) -> List[dict]:
+    rng = random.Random(seed)
+    path = Path(output_path)
+    rows: List[dict] = []
+    stages = ["easy", "medium", "hard"]
+    policy_fn = POLICIES[policy]
+
+    with path.open("w", encoding="utf-8") as handle:
+        for episode in range(num_episodes):
+            env = CounselEnvironment()
+            stage = stages[episode % len(stages)]
+            obs = env.reset(curriculum_stage=stage)
+            questions = policy_fn(env, rng, episode)
+            obs = env.step(CounselAction(tool="rest_case")) if not env.done else obs
+            components = obs.reward_components
+            patterns = {_question_pattern(question) for question in questions}
+            action_types = [
+                line.split(":", 1)[0]
+                for line in env.transcript
+                if ":" in line
+            ]
+            row = {
+                "episode": episode,
+                "stage": stage,
+                "difficulty": env.case.get("difficulty"),
+                "case_id": env.case.get("case_id"),
+                "contradictions_total": int(components["contradictions_total"]),
+                "contradictions_triggered": int(components["contradictions_triggered"]),
+                "contradictions_surfaced": int(components["contradictions_surfaced"]),
+                "questions_asked": env.questions_used,
+                "evidence_presented": env.evidence_presented_count,
+                "useless_questions_ratio": components["useless_questions_ratio"],
+                "avg_question_length": components["avg_question_length"],
+                "unique_question_patterns": len(patterns),
+                "unique_question_patterns_pct": (len(patterns) / max(1, len(questions))),
+                "action_diversity": len(set(action_types)),
+                "primary_reward": components["primary_reward"],
+                "auxiliary_reward": components["auxiliary_reward_raw"],
+                "total_reward": obs.reward,
+                "success": obs.reward > 0.0,
+            }
+            rows.append(row)
+            handle.write(json.dumps(row, sort_keys=True) + "\n")
+
+    avg_reward = sum(row["total_reward"] for row in rows) / max(1, len(rows))
+    if avg_reward == 0:
+        print('WARNING: ENV TOO HARD')
+    if avg_reward > 0.7:
+        print('WARNING: ENV TOO EASY')
+    print(f"Wrote {len(rows)} rollout diagnostics to {path} (avg_reward={avg_reward:.3f})")
+    return rows
+
+
+if __name__ == "__main__":
+    run_rollout_diagnostics()

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

server/rubrics.py

@@ -0,0 +1,43 @@
+from typing import Any
+
+from openenv.core.rubrics import Rubric
+from openenv.core.rubrics.containers import WeightedSum
+
+
+def _component(observation: Any, name: str, default: float = 0.0) -> float:
+    components = getattr(observation, "reward_components", None)
+    if isinstance(components, dict):
+        return float(components.get(name, default))
+    if isinstance(observation, dict):
+        return float(observation.get(name, default))
+    return float(getattr(observation, name, default))
+
+
+class ContradictionsSurfaced(Rubric):
+    """Primary signal: normalized binary-per-contradiction success."""
+
+    def forward(self, action: Any, observation: Any) -> float:
+        return _component(observation, "primary_reward", 0.0)
+
+
+class AuxiliaryProgress(Rubric):
+    """Dense shaping signal used only as a minority component."""
+
+    def forward(self, action: Any, observation: Any) -> float:
+        return max(-1.0, min(1.0, _component(observation, "auxiliary_reward_raw", 0.0)))
+
+
+class Total(Rubric):
+    """OpenEnv rubric tree: primary reward dominates auxiliary shaping."""
+
+    def __init__(self):
+        super().__init__()
+        self.primary = ContradictionsSurfaced()
+        self.auxiliary = AuxiliaryProgress()
+        self.combined = WeightedSum(
+            [self.primary, self.auxiliary],
+            weights=[0.8, 0.2],
+        )
+
+    def forward(self, action: Any, observation: Any) -> float:
+        return self.combined(action, observation)

server/witness.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+@dataclass
+class Contradiction:
+    cid: str
+    trigger_keywords: List[str]
+    sealed_claim: str
+    disprover_evidence_id: str
+    triggered: bool = False
+    surfaced: bool = False
+
+class Witness:
+    def __init__(self, story: Dict[str, str], contradictions: List[Contradiction]):
+        self.story = story
+        self.contradictions = contradictions
+        self.committed_claims: List[str] = []
+
+    def respond_to_question(self, q: str) -> str:
+        q_lower = (q or "").lower()
+        for c in self.contradictions:
+            if any(kw in q_lower for kw in c.trigger_keywords):
+                if not c.triggered:
+                    c.triggered = True
+                    self.committed_claims.append(c.sealed_claim)
+                return c.sealed_claim
+        for topic, resp in self.story.items():
+            if topic in q_lower:
+                return resp
+        return "I don't recall."
+
+    def react_to_evidence(self, exhibit_id: str) -> str:
+        for c in self.contradictions:
+            if c.disprover_evidence_id == exhibit_id and c.triggered and not c.surfaced:
+                c.surfaced = True
+                return "[Witness stammers] I... I'm not sure what to say."
+        return "[Witness] I have no comment on that exhibit."

tests/test_smoke.py

@@ -0,0 +1,297 @@
+import random
+
+from counsel_env.models import CounselAction
+from counsel_env.evaluation import evaluate_agent, present_all_agent, keyword_spam_agent, oracle_scripted_agent
+from counsel_env.server.case_generator import generate_case
+from counsel_env.server.counsel_env_environment import CounselEnvironment
+from counsel_env.server.witness import Contradiction, Witness
+
+
+def _trigger_and_surface_first(env: CounselEnvironment):
+    contradiction = env.witness.contradictions[0]
+    env.step(CounselAction(tool="ask_question", text=f"{contradiction.trigger_keywords[0]}?"))
+    env.step(CounselAction(tool="present_evidence", exhibit_id=contradiction.disprover_evidence_id))
+    return contradiction
+
+
+class TestWitnessLogic:
+    def test_witness_trigger(self):
+        contradiction = Contradiction(
+            cid="c1",
+            trigger_keywords=["where were you", "alibi"],
+            sealed_claim="I was at the diner all night.",
+            disprover_evidence_id="phone_log",
+        )
+        witness = Witness({"motive": "No motive."}, [contradiction])
+
+        response = witness.respond_to_question("Where were you that night?")
+
+        assert response == contradiction.sealed_claim
+        assert contradiction.triggered is True
+        assert witness.committed_claims == [contradiction.sealed_claim]
+
+    def test_evidence_surface(self):
+        contradiction = Contradiction(
+            cid="c1",
+            trigger_keywords=["alibi"],
+            sealed_claim="I was at the diner.",
+            disprover_evidence_id="phone_log",
+        )
+        witness = Witness({}, [contradiction])
+
+        witness.respond_to_question("Tell us your alibi.")
+        response = witness.react_to_evidence("phone_log")
+
+        assert "stammers" in response.lower()
+        assert contradiction.surfaced is True
+
+    def test_no_false_positive(self):
+        contradiction = Contradiction(
+            cid="c1",
+            trigger_keywords=["alibi"],
+            sealed_claim="I was at the diner.",
+            disprover_evidence_id="phone_log",
+        )
+        witness = Witness({}, [contradiction])
+
+        response = witness.react_to_evidence("phone_log")
+
+        assert "no comment" in response.lower()
+        assert contradiction.surfaced is False
+
+
+class TestCaseGeneration:
+    def test_curriculum_difficulty_shapes_cases(self):
+        easy = generate_case(difficulty="easy")
+        medium = generate_case(difficulty="medium")
+        hard = generate_case(difficulty="hard")
+
+        assert len(easy["contradictions"]) == 1
+        assert len(medium["contradictions"]) == 2
+        assert len(hard["contradictions"]) >= 3
+        assert "irrelevant_weather_report" in hard["evidence"]
+
+    def test_curriculum_sampling_distribution(self):
+        cases = [
+            generate_case(curriculum_stage="mixed", distribution={"easy": 1.0})
+            for _ in range(5)
+        ]
+
+        assert {case["difficulty"] for case in cases} == {"easy"}
+
+    def test_seed_replay_is_deterministic(self):
+        env_a = CounselEnvironment()
+        env_b = CounselEnvironment()
+        obs_a = env_a.reset(seed=1234, difficulty="hard")
+        obs_b = env_b.reset(seed=1234, difficulty="hard")
+
+        assert obs_a.case_id == obs_b.case_id
+        assert obs_a.case_brief == obs_b.case_brief
+        assert obs_a.evidence_descriptions == obs_b.evidence_descriptions
+        assert [c.cid for c in env_a.witness.contradictions] == [c.cid for c in env_b.witness.contradictions]
+
+
+class TestEnvironmentLogic:
+    def test_reset_state(self):
+        env = CounselEnvironment()
+        obs = env.reset(difficulty="easy")
+
+        assert obs.questions_remaining == 15
+        assert obs.done is False
+        assert obs.reward == 0.0
+        assert obs.case_brief
+        assert obs.available_evidence
+        assert obs.evidence_descriptions
+        assert set(obs.available_evidence) == set(obs.evidence_descriptions)
+        assert obs.case_id == env.case["case_id"]
+        assert obs.difficulty == "easy"
+        assert env.state.contradictions_total == 1
+        assert env.state.questions_used == 0
+
+    def test_question_budget(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+
+        obs = None
+        for i in range(env.QUESTION_BUDGET):
+            obs = env.step(CounselAction(tool="ask_question", text=f"Off-topic question {i}?"))
+
+        assert obs is not None
+        assert obs.done is True
+        assert obs.questions_remaining == 0
+
+        after_done = env.step(CounselAction(tool="ask_question", text="One too many?"))
+        assert after_done.done is True
+        assert "already over" in after_done.witness_response.lower()
+
+    def test_duplicate_question_penalty(self):
+        clean_env = CounselEnvironment()
+        clean_env.reset(difficulty="easy")
+        _trigger_and_surface_first(clean_env)
+        clean_reward = clean_env.step(CounselAction(tool="rest_case")).reward
+
+        duplicate_env = CounselEnvironment()
+        duplicate_env.reset(difficulty="easy")
+        contradiction = duplicate_env.witness.contradictions[0]
+        question = f"{contradiction.trigger_keywords[0]}?"
+        duplicate_env.step(CounselAction(tool="ask_question", text=question))
+        duplicate_response = duplicate_env.step(CounselAction(tool="ask_question", text=question))
+        duplicate_env.step(CounselAction(tool="present_evidence", exhibit_id=contradiction.disprover_evidence_id))
+        duplicate_reward = duplicate_env.step(CounselAction(tool="rest_case")).reward
+
+        assert "already asked" in duplicate_response.witness_response.lower()
+        assert duplicate_env.duplicate_question_count == 1
+        assert duplicate_reward < clean_reward
+
+    def test_reward_components_primary_dominates(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+        _trigger_and_surface_first(env)
+        obs = env.step(CounselAction(tool="rest_case"))
+
+        assert obs.reward_components["primary_reward"] == 1.0
+        assert obs.reward >= 0.8
+        assert obs.reward_components["auxiliary_reward_raw"] > 0.0
+        assert obs.reward_components["evidence_timing_successes"] >= 1.0
+
+    def test_no_infinite_evidence_loop(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+        exhibit = env.available_evidence[0] if hasattr(env, "available_evidence") else env.case["evidence"].keys()
+        exhibit_id = next(iter(env.case["evidence"].keys()))
+
+        for _ in range(env.MAX_ACTIONS + 1):
+            obs = env.step(CounselAction(tool="present_evidence", exhibit_id=exhibit_id))
+            if obs.done:
+                break
+
+        assert obs.done is True
+        assert env.action_count >= env.MAX_ACTIONS
+
+    def test_transcript_export_contains_labels(self):
+        env = CounselEnvironment()
+        env.reset(seed=55, difficulty="easy", episode_id="demo")
+        _trigger_and_surface_first(env)
+        obs = env.step(CounselAction(tool="rest_case"))
+
+        payload = env.export_transcript_json()
+        markdown = env.export_transcript_markdown()
+
+        assert payload["episode_id"] == "demo"
+        assert payload["seed"] == 55
+        assert payload["events"]
+        assert payload["reward_components"]["total_reward"] == obs.reward
+        assert "Triggered:" in markdown
+        assert "Surfaced:" in markdown
+
+    def test_state_tracks_extended_diagnostics(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+        _trigger_and_surface_first(env)
+        state = env.state
+
+        assert state.contradictions_triggered == 1
+        assert state.contradictions_surfaced == 1
+        assert state.evidence_timing_successes == 1
+        assert state.action_count >= 2
+
+
+class TestRolloutValidation:
+    def test_scripted_agent_success(self):
+        successes = 0
+
+        for _ in range(10):
+            env = CounselEnvironment()
+            env.reset(curriculum_stage="mixed")
+            _trigger_and_surface_first(env)
+            obs = env.step(CounselAction(tool="rest_case"))
+            if obs.reward > 0:
+                successes += 1
+
+        assert successes >= 1
+
+    def test_random_agent_baseline(self):
+        rng = random.Random(7)
+        rewards = []
+
+        for _ in range(10):
+            env = CounselEnvironment()
+            obs = env.reset(difficulty="hard")
+            for _ in range(8):
+                if rng.random() < 0.7:
+                    obs = env.step(
+                        CounselAction(tool="ask_question", text=f"Random question {rng.randint(1, 999)}?")
+                    )
+                else:
+                    obs = env.step(
+                        CounselAction(tool="present_evidence", exhibit_id=rng.choice(obs.available_evidence))
+                    )
+                if obs.done:
+                    break
+            rewards.append(env.step(CounselAction(tool="rest_case")).reward)
+
+        avg_reward = sum(rewards) / len(rewards)
+        assert avg_reward < 0.35
+
+    def test_reward_hacking_baselines_stay_below_oracle(self):
+        seeds = [9001, 9002, 9003, 9004, 9005]
+        spam_rows, _ = evaluate_agent("keyword_spam", keyword_spam_agent, seeds, transcript_limit=0)
+        present_rows, _ = evaluate_agent("present_all", present_all_agent, seeds, transcript_limit=0)
+        oracle_rows, _ = evaluate_agent("scripted_oracle", oracle_scripted_agent, seeds, transcript_limit=0)
+
+        spam_reward = sum(row["reward"] for row in spam_rows) / len(spam_rows)
+        present_reward = sum(row["reward"] for row in present_rows) / len(present_rows)
+        oracle_reward = sum(row["reward"] for row in oracle_rows) / len(oracle_rows)
+
+        assert oracle_reward > spam_reward
+        assert oracle_reward > present_reward
+        assert present_reward == 0.0
+
+
+class TestEdgeCases:
+    def test_empty_question(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+
+        obs = env.step(CounselAction(tool="ask_question", text=""))
+
+        assert "proper question" in obs.witness_response.lower()
+        assert env.inadmissible_count == 1
+
+    def test_invalid_exhibit(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+
+        obs = env.step(CounselAction(tool="present_evidence", exhibit_id="nonexistent_exhibit"))
+
+        assert "invalid exhibit" in obs.witness_response.lower()
+        assert env.inadmissible_count == 1
+
+    def test_extremely_long_question(self):
+        env = CounselEnvironment()
+        env.reset(difficulty="easy")
+        long_question = "What is your alibi " + ("please explain " * 200)
+
+        obs = env.step(CounselAction(tool="ask_question", text=long_question))
+
+        assert obs.witness_response
+        assert obs.questions_remaining == env.QUESTION_BUDGET - 1
+
+    def test_no_trigger_keywords_case(self):
+        witness = Witness(
+            {"background": "I worked late."},
+            [
+                Contradiction(
+                    cid="c1",
+                    trigger_keywords=[],
+                    sealed_claim="Hidden claim.",
+                    disprover_evidence_id="log",
+                )
+            ],
+        )
+
+        response = witness.respond_to_question("What is your favorite color?")
+        evidence_response = witness.react_to_evidence("log")
+
+        assert response == "I don't recall."
+        assert "no comment" in evidence_response.lower()