Upload folder using huggingface_hub

CLAUDE.md

@@ -28,7 +28,7 @@ Wire-protocol classes are template-locked: `CrisisworldcortexAction`, `Crisiswor
 
 - The four wire-protocol class names above. Do not rename.
 - Flat package layout: `pyproject.toml:package-dir` maps `CrisisWorldCortex` to repo root. Do not move `models.py`, `client.py`, or root `__init__.py` off root.
-- Canonical wire-type imports in every `server/` module: `from CrisisWorldCortex.models import ...`.
+- Dual-import fallback pattern (`try: from ..models / except: from models`) in every `server/` module that imports `models`.
 - `pyproject.toml`: deps, entry points, `packages`, `package-dir`.
 - `openenv.yaml` keys: `spec_version`, `runtime`, `app`, `port`.
 - `server/app.py:create_app(...)` call signature.
@@ -47,7 +47,7 @@ Wire-protocol classes are template-locked: `CrisisworldcortexAction`, `Crisiswor
 ## Import-graph rule (enforced)
 
 - `cortex/` imports `models` and `cortex/*` only.
-- `server/` imports `models`, `openenv.core.*`, and package-relative `server` internals only. No `cortex/*`, no `training/*`, no `baselines/*`, no `demo/*`.
+- `server/` imports `models`, `openenv.core.*`, `server/*` only. No `cortex/*`, no `training/*`, no `baselines/*`, no `demo/*`.
 - `baselines/` imports `models`, `client`, `cortex/*`. Must not import `server/*` — baselines hit the env over HTTP like production.
 - `training/` imports `models`, `client`, `cortex/*`, `server.graders` (reward-name constants only). Must not import `server.simulator/*`.
 - `demo/` imports `cortex.schemas` (types only) and stdlib. Must not import `server/*`, `training/*`, `baselines/*`, `cortex.council`, `cortex.routing_policy`.
@@ -70,9 +70,9 @@ Do not restate subsystem APIs in this file or in other subsystem files.
 
 - Wire package: `from CrisisWorldCortex import CrisisworldcortexAction, ...`.
 - Dev / research directories (sibling-of-repo-root): bare-name — `import cortex`, `import baselines`, `import training`, `import demo`, `import scripts`.
-- Server-internal: package-relative imports such as `from .simulator import ...` or `from ..simulator import ...`; do not use `from CrisisWorldCortex.server...`.
+- Server-internal: `from server.simulator import ...`, `from server.graders import ...`.
 - **Cross-boundary into wire types**: when a dev / research directory (`cortex/`, `baselines/`, `training/`, `demo/`) crosses into the wire-protocol package, use `from CrisisWorldCortex.models import …` — **never** bare `from models import …`. Bare-name only applies to dev-directory siblings and to same-subpackage imports inside `server/`. The dual-path import creates distinct `sys.modules` entries and breaks Pydantic discriminator checks across import boundaries (verified by session 4's class-identity bug; `cortex/schemas.py:21` documents the canonicalised import).
-- **Cross-boundary into wire types from server modules**: every `server/` file imports wire types with `from CrisisWorldCortex.models import …`. Do not use `from ..models` or bare `from models`; both can create a second class identity under different launch modes and break Pydantic discriminated-union validation.
+- **Cross-boundary into wire types from deep server modules**: files inside `server/` more than one level deep (e.g., `server/simulator/seir_model.py`, `server/graders/outer_reward.py`) cannot use the `try: from ..models / except: from models` fallback — `..models` from a two-level-deep module resolves to a non-existent `CrisisWorldCortex.server.models`, the fallback fires, and bare `models` loads as a separate `sys.modules` entry. Use the absolute path: `from CrisisWorldCortex.models import …`. Session 4 (`cortex/schemas.py:21`) and Session 5a (`server/simulator/seir_model.py`, `server/simulator/tasks.py`) document this with inline comments. The dual-import fallback in `server/CrisisWorldCortex_environment.py` and `server/app.py` works only because they are one level deep (`..models` → `CrisisWorldCortex.models` directly).
 
 ## Commands (Git Bash; quote Windows paths)
 

README.md

@@ -1,255 +1,255 @@
----
-title: Crisisworldcortex Environment Server
-emoji: 🌟
-colorFrom: yellow
-colorTo: pink
-sdk: docker
-pinned: false
-app_port: 8000
-base_path: /web
-tags:
-  - openenv
----
-
-# Crisisworldcortex Environment
-
-A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
-
-## Quick Start
-
-The simplest way to use the Crisisworldcortex environment is through the `CrisisworldcortexEnv` class:
-
-```python
-from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexEnv
-
-try:
-    # Create environment from Docker image
-    CrisisWorldCortexenv = CrisisworldcortexEnv.from_docker_image("CrisisWorldCortex-env:latest")
-
-    # Reset
-    result = CrisisWorldCortexenv.reset()
-    print(f"Reset: {result.observation.echoed_message}")
-
-    # Send multiple messages
-    messages = ["Hello, World!", "Testing echo", "Final message"]
-
-    for msg in messages:
-        result = CrisisWorldCortexenv.step(CrisisworldcortexAction(message=msg))
-        print(f"Sent: '{msg}'")
-        print(f"  → Echoed: '{result.observation.echoed_message}'")
-        print(f"  → Length: {result.observation.message_length}")
-        print(f"  → Reward: {result.reward}")
-
-finally:
-    # Always clean up
-    CrisisWorldCortexenv.close()
-```
-
-That's it! The `CrisisworldcortexEnv.from_docker_image()` method handles:
-- Starting the Docker container
-- Waiting for the server to be ready
-- Connecting to the environment
-- Container cleanup when you call `close()`
-
-## Building the Docker Image
-
-Before using the environment, you need to build the Docker image:
-
-```bash
-# From project root
-docker build -t CrisisWorldCortex-env:latest -f server/Dockerfile .
-```
-
-## Deploying to Hugging Face Spaces
-
-You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
-
-```bash
-# From the environment directory (where openenv.yaml is located)
-openenv push
-
-# Or specify options
-openenv push --namespace my-org --private
-```
-
-The `openenv push` command will:
-1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
-2. Prepare a custom build for Hugging Face Docker space (enables web interface)
-3. Upload to Hugging Face (ensuring you're logged in)
-
-### Prerequisites
-
-- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
-
-### Options
-
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
-- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
-- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
-- `--private`: Deploy the space as private (default: public)
-
-### Examples
-
-```bash
-# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
-openenv push
-
-# Push to a specific repository
-openenv push --repo-id my-org/my-env
-
-# Push with a custom base image
-openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
-
-# Push as a private space
-openenv push --private
-
-# Combine options
-openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
-```
-
-After deployment, your space will be available at:
-`https://huggingface.co/spaces/<repo-id>`
-
-The deployed space includes:
-- **Web Interface** at `/web` - Interactive UI for exploring the environment
-- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
-- **Health Check** at `/health` - Container health monitoring
-- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
-
-## Environment Details
-
-### Action
-**CrisisworldcortexAction**: Contains a single field
-- `message` (str) - The message to echo back
-
-### Observation
-**CrisisworldcortexObservation**: Contains the echo response and metadata
-- `echoed_message` (str) - The message echoed back
-- `message_length` (int) - Length of the message
-- `reward` (float) - Reward based on message length (length × 0.1)
-- `done` (bool) - Always False for echo environment
-- `metadata` (dict) - Additional info like step count
-
-### Reward
-The reward is calculated as: `message_length × 0.1`
-- "Hi" → reward: 0.2
-- "Hello, World!" → reward: 1.3
-- Empty message → reward: 0.0
-
-## Advanced Usage
-
-### Connecting to an Existing Server
-
-If you already have a Crisisworldcortex environment server running, you can connect directly:
-
-```python
-from CrisisWorldCortex import CrisisworldcortexEnv
-
-# Connect to existing server
-CrisisWorldCortexenv = CrisisworldcortexEnv(base_url="<ENV_HTTP_URL_HERE>")
-
-# Use as normal
-result = CrisisWorldCortexenv.reset()
-result = CrisisWorldCortexenv.step(CrisisworldcortexAction(message="Hello!"))
-```
-
-Note: When connecting to an existing server, `CrisisWorldCortexenv.close()` will NOT stop the server.
-
-### Using the Context Manager
-
-The client supports context manager usage for automatic connection management:
-
-```python
-from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexEnv
-
-# Connect with context manager (auto-connects and closes)
-with CrisisworldcortexEnv(base_url="http://localhost:8000") as env:
-    result = env.reset()
-    print(f"Reset: {result.observation.echoed_message}")
-    # Multiple steps with low latency
-    for msg in ["Hello", "World", "!"]:
-        result = env.step(CrisisworldcortexAction(message=msg))
-        print(f"Echoed: {result.observation.echoed_message}")
-```
-
-The client uses WebSocket connections for:
-- **Lower latency**: No HTTP connection overhead per request
-- **Persistent session**: Server maintains your environment state
-- **Efficient for episodes**: Better for many sequential steps
-
-### Concurrent WebSocket Sessions
-
-The server supports multiple concurrent WebSocket connections. To enable this,
-modify `server/app.py` to use factory mode:
-
-```python
-# In server/app.py - use factory mode for concurrent sessions
-app = create_app(
-    CrisisworldcortexEnvironment,  # Pass class, not instance
-    CrisisworldcortexAction,
-    CrisisworldcortexObservation,
-    max_concurrent_envs=4,  # Allow 4 concurrent sessions
-)
-```
-
-Then multiple clients can connect simultaneously:
-
-```python
-from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexEnv
-from concurrent.futures import ThreadPoolExecutor
-
-def run_episode(client_id: int):
-    with CrisisworldcortexEnv(base_url="http://localhost:8000") as env:
-        result = env.reset()
-        for i in range(10):
-            result = env.step(CrisisworldcortexAction(message=f"Client {client_id}, step {i}"))
-        return client_id, result.observation.message_length
-
-# Run 4 episodes concurrently
-with ThreadPoolExecutor(max_workers=4) as executor:
-    results = list(executor.map(run_episode, range(4)))
-```
-
-## Development & Testing
-
-### Direct Environment Testing
-
-Test the environment logic directly without starting the HTTP server:
-
-```bash
-# From the server directory
-python3 server/CrisisWorldCortex_environment.py
-```
-
-This verifies that:
-- Environment resets correctly
-- Step executes actions properly
-- State tracking works
-- Rewards are calculated correctly
-
-### Running Locally
-
-Run the server locally for development:
-
-```bash
-uvicorn server.app:app --reload
-```
-
-## Project Structure
-
-```
-CrisisWorldCortex/
-├── .dockerignore         # Docker build exclusions
-├── __init__.py            # Module exports
-├── README.md              # This file
-├── openenv.yaml           # OpenEnv manifest
-├── pyproject.toml         # Project metadata and dependencies
-├── uv.lock                # Locked dependencies (generated)
-├── client.py              # CrisisworldcortexEnv client
-├── models.py              # Action and Observation models
-└── server/
-    ├── __init__.py        # Server module exports
-    ├── CrisisWorldCortex_environment.py  # Core environment logic
-    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
-    └── Dockerfile         # Container image definition
-```
+---
+title: Crisisworldcortex Environment Server
+emoji: 🌟
+colorFrom: yellow
+colorTo: pink
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Crisisworldcortex Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Crisisworldcortex environment is through the `CrisisworldcortexEnv` class:
+
+```python
+from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexEnv
+
+try:
+    # Create environment from Docker image
+    CrisisWorldCortexenv = CrisisworldcortexEnv.from_docker_image("CrisisWorldCortex-env:latest")
+
+    # Reset
+    result = CrisisWorldCortexenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = CrisisWorldCortexenv.step(CrisisworldcortexAction(message=msg))
+        print(f"Sent: '{msg}'")
+        print(f"  → Echoed: '{result.observation.echoed_message}'")
+        print(f"  → Length: {result.observation.message_length}")
+        print(f"  → Reward: {result.reward}")
+
+finally:
+    # Always clean up
+    CrisisWorldCortexenv.close()
+```
+
+That's it! The `CrisisworldcortexEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when you call `close()`
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t CrisisWorldCortex-env:latest -f server/Dockerfile .
+```
+
+## Deploying to Hugging Face Spaces
+
+You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# Or specify options
+openenv push --namespace my-org --private
+```
+
+The `openenv push` command will:
+1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+3. Upload to Hugging Face (ensuring you're logged in)
+
+### Prerequisites
+
+- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
+
+### Options
+
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+### Examples
+
+```bash
+# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
+openenv push
+
+# Push to a specific repository
+openenv push --repo-id my-org/my-env
+
+# Push with a custom base image
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
+```
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**CrisisworldcortexAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**CrisisworldcortexObservation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Crisisworldcortex environment server running, you can connect directly:
+
+```python
+from CrisisWorldCortex import CrisisworldcortexEnv
+
+# Connect to existing server
+CrisisWorldCortexenv = CrisisworldcortexEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = CrisisWorldCortexenv.reset()
+result = CrisisWorldCortexenv.step(CrisisworldcortexAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `CrisisWorldCortexenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexEnv
+
+# Connect with context manager (auto-connects and closes)
+with CrisisworldcortexEnv(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(CrisisworldcortexAction(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    CrisisworldcortexEnvironment,  # Pass class, not instance
+    CrisisworldcortexAction,
+    CrisisworldcortexObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with CrisisworldcortexEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(CrisisworldcortexAction(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/CrisisWorldCortex_environment.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running Locally
+
+Run the server locally for development:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+CrisisWorldCortex/
+├── .dockerignore         # Docker build exclusions
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # CrisisworldcortexEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── CrisisWorldCortex_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

__init__.py

@@ -1,16 +1,16 @@
-# 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.
-
-"""Crisisworldcortex Environment."""
-
-from .client import CrisisworldcortexEnv
-from .models import CrisisworldcortexAction, CrisisworldcortexObservation
-
-__all__ = [
-    "CrisisworldcortexAction",
-    "CrisisworldcortexObservation",
-    "CrisisworldcortexEnv",
-]
+# 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.
+
+"""Crisisworldcortex Environment."""
+
+from .client import CrisisworldcortexEnv
+from .models import CrisisworldcortexAction, CrisisworldcortexObservation
+
+__all__ = [
+    "CrisisworldcortexAction",
+    "CrisisworldcortexObservation",
+    "CrisisworldcortexEnv",
+]

cortex/brains/__init__.py

@@ -0,0 +1,26 @@
+"""Cortex brains (Session 11+).
+
+Public surface:
+    - Brain: per-brain class wiring Perception + Lens + 3 LLM subagents + Brain Executive.
+    - EpiBrain, LogisticsBrain, GovernanceBrain: factory functions.
+    - aggregate_brain_outputs: Brain Executive aggregation function.
+
+Each Brain holds its own LLMClient instance; the orchestration layer
+(Council Executive in Session 12, Workstream B trainers) constructs one
+Brain per brain id, optionally with different LLMClients pointing to
+different models. NO module-level state.
+"""
+
+from ._base import Brain
+from ._executive import aggregate_brain_outputs
+from .epidemiology import EpiBrain
+from .governance import GovernanceBrain
+from .logistics import LogisticsBrain
+
+__all__ = [
+    "Brain",
+    "EpiBrain",
+    "GovernanceBrain",
+    "LogisticsBrain",
+    "aggregate_brain_outputs",
+]

cortex/brains/_base.py

@@ -0,0 +1,201 @@
+"""Brain class - composes Perception + Lens + 3 Subagents + Brain Executive.
+
+Per cortex/CLAUDE.md: each brain has a deterministic Python Perception
++ Lens, three LLM subagents (router-callable), and a deterministic
+Python Brain Executive. The Brain class wires these together.
+
+Multi-model deployment: each Brain holds a SINGLE LLMClient instance
+passed at construction. Different brains can use different models by
+constructing each Brain with a different LLMClient (e.g., Qwen for epi,
+Llama for logistics). NO module-level state, NO shared singletons.
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal
+
+from cortex.lenses import lens_for
+from cortex.schemas import (
+    BeliefState,
+    BrainLensedObservation,
+    BrainRecommendation,
+    CandidatePlan,
+    CriticReport,
+    PerceptionReport,
+    SubagentInput,
+)
+from cortex.subagents import (
+    CriticSubagent,
+    PlannerSubagent,
+    WorldModelerSubagent,
+    perception_for,
+)
+from cortex.subagents._base import _LLMClientLike
+from CrisisWorldCortex.models import CrisisworldcortexObservation
+
+from ._executive import aggregate_brain_outputs
+
+_BrainId = Literal["epidemiology", "logistics", "governance"]
+
+
+class Brain:
+    """Per-brain pipeline holder.
+
+    Each Brain instance owns its own LLMClient. The orchestration layer
+    (Session 12 Council, Workstream B trainers) instantiates one Brain
+    per brain id, optionally with different LLMClients pointing to
+    different models. The Brain class itself has NO module-level state
+    and NO forced singleton.
+
+    Args:
+        brain_id: One of "epidemiology", "logistics", "governance".
+        llm_client: This brain's LLM client. Subagents are constructed
+            with the SAME client so token billing aggregates correctly.
+        wm: WorldModeler subagent.
+        planner: Planner subagent.
+        critic: Critic subagent.
+    """
+
+    def __init__(
+        self,
+        brain_id: _BrainId,
+        llm_client: _LLMClientLike,
+        wm: WorldModelerSubagent,
+        planner: PlannerSubagent,
+        critic: CriticSubagent,
+    ) -> None:
+        self.brain_id = brain_id
+        self.llm_client = llm_client
+        self.wm = wm
+        self.planner = planner
+        self.critic = critic
+
+    # ------------------------------------------------------------------
+    # Deterministic Python pieces (no LLM)
+    # ------------------------------------------------------------------
+
+    def compute_perception(self, obs: CrisisworldcortexObservation) -> PerceptionReport:
+        """Run this brain's Perception. Pure Python; no LLM."""
+        return perception_for(self.brain_id, obs)
+
+    def compute_lens(
+        self, obs: CrisisworldcortexObservation, last_reward: float
+    ) -> BrainLensedObservation:
+        """Run this brain's Lens. Pure Python; no LLM."""
+        return lens_for(self.brain_id, obs, last_reward)
+
+    def aggregate(
+        self,
+        perception: PerceptionReport,
+        beliefs: List[BeliefState],
+        plans: List[CandidatePlan],
+        critics: List[CriticReport],
+        tokens_used: int = 0,
+    ) -> BrainRecommendation:
+        """Run this brain's Brain Executive. Pure Python; no LLM."""
+        return aggregate_brain_outputs(
+            brain_id=self.brain_id,
+            perception=perception,
+            beliefs=beliefs,
+            plans=plans,
+            critics=critics,
+            tokens_used=tokens_used,
+        )
+
+    # ------------------------------------------------------------------
+    # High-level convenience: round-1 single tick
+    # ------------------------------------------------------------------
+
+    def run_tick(
+        self,
+        obs: CrisisworldcortexObservation,
+        last_reward: float,
+        tick: int,
+        round_: int = 1,
+    ) -> BrainRecommendation:
+        """Round-1 single-tick pipeline (Session 11 smoke).
+
+        Round 2 is orchestrated by the Council Executive (Session 12)
+        via the fine-grained methods (compute_perception, compute_lens,
+        wm.run / planner.run / critic.run, aggregate). Calling this
+        convenience method with ``round_!=1`` raises NotImplementedError
+        to prevent accidental misuse before the Council exists.
+        """
+        if round_ != 1:
+            raise NotImplementedError(
+                f"Round {round_} orchestration is the Council Executive's "
+                f"responsibility (Session 12). Use Brain.compute_perception/"
+                f"compute_lens + WorldModelerSubagent.run/PlannerSubagent.run/"
+                f"CriticSubagent.run + Brain.aggregate directly."
+            )
+
+        perception = self.compute_perception(obs)
+        # Lens is computed for completeness; Session 11 doesn't yet plumb
+        # it into SubagentInput (M-FR-4 step indices fixed). Session 12
+        # Council will extend the SubagentInput contract to carry lens
+        # output if subagents need it.
+        _ = self.compute_lens(obs, last_reward)
+
+        # WorldModeler (step_idx=0)
+        wm_input = SubagentInput(
+            brain=self.brain_id,
+            role="world_modeler",
+            tick=tick,
+            round=round_,
+            perception=perception,
+            prior_belief=None,
+            prior_plans=[],
+            target_plan_id=None,
+            last_reward=last_reward,
+            recent_action_log_excerpt=list(obs.recent_action_log),
+        )
+        belief = self.wm.run(wm_input, step_idx=0)
+
+        # Planner (step_idx=1)
+        planner_input = SubagentInput(
+            brain=self.brain_id,
+            role="planner",
+            tick=tick,
+            round=round_,
+            perception=perception,
+            prior_belief=belief,
+            prior_plans=[],
+            target_plan_id=None,
+            last_reward=last_reward,
+            recent_action_log_excerpt=list(obs.recent_action_log),
+        )
+        plan = self.planner.run(planner_input, step_idx=1)
+
+        # Critic (step_idx=2)
+        critic_input = SubagentInput(
+            brain=self.brain_id,
+            role="critic",
+            tick=tick,
+            round=round_,
+            perception=perception,
+            prior_belief=belief,
+            prior_plans=[plan],
+            target_plan_id="plan-0",
+            last_reward=last_reward,
+            recent_action_log_excerpt=list(obs.recent_action_log),
+        )
+        critic = self.critic.run(critic_input, step_idx=2)
+
+        # Tally tokens billed to this brain's caller_ids.
+        caller_id_base = f"cortex:{self.brain_id}"
+        tokens_used = sum(
+            self.llm_client.tokens_used_for(f"{caller_id_base}:{role}:t{tick}:r{round_}:s{idx}")
+            for role, idx in (
+                ("world_modeler", 0),
+                ("planner", 1),
+                ("critic", 2),
+            )
+        )
+
+        return self.aggregate(
+            perception=perception,
+            beliefs=[belief],
+            plans=[plan],
+            critics=[critic],
+            tokens_used=tokens_used,
+        )

cortex/brains/_executive.py

@@ -0,0 +1,144 @@
+"""Brain Executive - deterministic Python aggregation.
+
+Per Phase A docs/CORTEX_ARCHITECTURE.md Decisions 15-21 + M-FR-3 partial
+evidence union (perception + beliefs only; CandidatePlan and CriticReport
+schemas have no evidence fields).
+
+Brain Executive runs ONCE per brain at round end. NOT router-callable
+per cortex/CLAUDE.md.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from cortex.schemas import (
+    BeliefState,
+    BrainRecommendation,
+    CandidatePlan,
+    CriticReport,
+    EvidenceCitation,
+    PerceptionReport,
+)
+from CrisisWorldCortex.models import NoOp
+
+_REASONING_SUMMARY_MAX_CHARS = 400  # matches BrainRecommendation.reasoning_summary cap
+_FALSIFIERS_TO_JOIN = 3
+_FALSIFIER_FALLBACK = "(no falsifier provided)"
+_EMPTY_REASONING = "(empty: no subagent produced a parseable plan)"
+
+
+def aggregate_brain_outputs(
+    brain_id: str,
+    perception: PerceptionReport,
+    beliefs: List[BeliefState],
+    plans: List[CandidatePlan],
+    critics: List[CriticReport],
+    tokens_used: int = 0,
+) -> BrainRecommendation:
+    """Aggregate one brain's per-round subagent outputs into a recommendation.
+
+    Decisions:
+        D15: argmax over expected_value * confidence.
+        D16: top_confidence = chosen.confidence * (1 - chosen_belief.uncertainty).
+        D17: minority_actions = all expected_outer_actions except chosen.
+        D19: reasoning_summary = chosen.action_sketch[:400].
+        D20 (M-FR-3): evidence = perception.evidence + flat-union of beliefs[*].evidence.
+                      CandidatePlan/CriticReport carry no evidence fields.
+        D21: brain_id is lowercase per Pydantic Literal in BrainRecommendation.
+
+    Empty fallback (M-FR-7): no plans, or chosen plan has confidence==0
+    -> top_action=NoOp, top_confidence=0, uncertainty=1.0,
+    reasoning_summary=_EMPTY_REASONING.
+
+    Args:
+        brain_id: lowercase brain id ("epidemiology" / "logistics" / "governance").
+        perception: This brain's PerceptionReport for the tick.
+        beliefs: Per-round BeliefStates. Index aligned with ``plans``.
+        plans: Per-round CandidatePlans.
+        critics: Per-round CriticReports (currently unused in aggregation but
+            kept on the signature so the trajectory log captures the full
+            chain).
+        tokens_used: Total tokens billed across this brain's subagents.
+    """
+    if not plans:
+        return _empty_recommendation(brain_id, perception, beliefs, tokens_used)
+
+    # D15: argmax over expected_value * confidence
+    chosen_idx = max(
+        range(len(plans)),
+        key=lambda i: plans[i].expected_value * plans[i].confidence,
+    )
+    chosen_plan = plans[chosen_idx]
+
+    if chosen_plan.confidence == 0.0:
+        # All plans are empty fallbacks (or the only plan is empty).
+        # Brain Executive treats this as no-signal.
+        return _empty_recommendation(brain_id, perception, beliefs, tokens_used)
+
+    # D16: top_confidence = chosen.confidence * (1 - belief.uncertainty)
+    if chosen_idx < len(beliefs):
+        chosen_belief = beliefs[chosen_idx]
+        uncertainty = chosen_belief.uncertainty
+    else:
+        # Defensive: parallel arrays should match. If not, treat as max uncertainty.
+        uncertainty = 1.0
+    top_confidence = chosen_plan.confidence * (1.0 - uncertainty)
+
+    # D17: minority_actions = all plans except chosen
+    minority_actions = [
+        plans[i].expected_outer_action for i in range(len(plans)) if i != chosen_idx
+    ]
+
+    # D19: reasoning_summary
+    reasoning_summary = chosen_plan.action_sketch[:_REASONING_SUMMARY_MAX_CHARS]
+
+    # D20 (M-FR-3): evidence union from perception + beliefs only.
+    # CandidatePlan and CriticReport schemas (Session 9) have no evidence fields;
+    # the perception+beliefs union captures the actionable evidence chain since
+    # plans/critics derive from beliefs.
+    evidence: List[EvidenceCitation] = list(perception.evidence)
+    for b in beliefs:
+        evidence.extend(b.evidence)
+
+    # falsifier (M-FR-6): join up to 3 falsifiers; fallback if empty.
+    if chosen_plan.falsifiers:
+        falsifier = "; ".join(chosen_plan.falsifiers[:_FALSIFIERS_TO_JOIN])
+    else:
+        falsifier = _FALSIFIER_FALLBACK
+
+    return BrainRecommendation(
+        brain=brain_id,
+        top_action=chosen_plan.expected_outer_action,
+        top_confidence=top_confidence,
+        minority_actions=minority_actions,
+        reasoning_summary=reasoning_summary,
+        evidence=evidence,
+        falsifier=falsifier,
+        uncertainty=uncertainty,
+        tokens_used=tokens_used,
+    )
+
+
+def _empty_recommendation(
+    brain_id: str,
+    perception: PerceptionReport,
+    beliefs: List[BeliefState],
+    tokens_used: int,
+) -> BrainRecommendation:
+    """M-FR-7 empty fallback: NoOp + confidence=0 + uncertainty=1."""
+    evidence: List[EvidenceCitation] = list(perception.evidence)
+    for b in beliefs:
+        evidence.extend(b.evidence)
+
+    return BrainRecommendation(
+        brain=brain_id,
+        top_action=NoOp(),
+        top_confidence=0.0,
+        minority_actions=[],
+        reasoning_summary=_EMPTY_REASONING,
+        evidence=evidence,
+        falsifier=_FALSIFIER_FALLBACK,
+        uncertainty=1.0,
+        tokens_used=tokens_used,
+    )

cortex/brains/epidemiology.py

@@ -0,0 +1,25 @@
+"""Epidemiology brain factory."""
+
+from __future__ import annotations
+
+from cortex.subagents import CriticSubagent, PlannerSubagent, WorldModelerSubagent
+from cortex.subagents._base import _LLMClientLike
+
+from ._base import Brain
+
+
+def EpiBrain(llm_client: _LLMClientLike) -> Brain:
+    """Construct an Epidemiology Brain bound to ``llm_client``.
+
+    Multi-model deployment: pass a different ``llm_client`` per brain
+    instance to use different models per brain (e.g., Qwen for epi,
+    Llama for logistics). The 3 LLM subagents are constructed with the
+    SAME client so token billing aggregates correctly.
+    """
+    return Brain(
+        brain_id="epidemiology",
+        llm_client=llm_client,
+        wm=WorldModelerSubagent(llm_client),
+        planner=PlannerSubagent(llm_client),
+        critic=CriticSubagent(llm_client),
+    )

cortex/brains/governance.py

@@ -0,0 +1,22 @@
+"""Governance brain factory."""
+
+from __future__ import annotations
+
+from cortex.subagents import CriticSubagent, PlannerSubagent, WorldModelerSubagent
+from cortex.subagents._base import _LLMClientLike
+
+from ._base import Brain
+
+
+def GovernanceBrain(llm_client: _LLMClientLike) -> Brain:
+    """Construct a Governance Brain bound to ``llm_client``.
+
+    Multi-model deployment: see EpiBrain.
+    """
+    return Brain(
+        brain_id="governance",
+        llm_client=llm_client,
+        wm=WorldModelerSubagent(llm_client),
+        planner=PlannerSubagent(llm_client),
+        critic=CriticSubagent(llm_client),
+    )

cortex/brains/logistics.py

@@ -0,0 +1,23 @@
+"""Logistics brain factory."""
+
+from __future__ import annotations
+
+from cortex.subagents import CriticSubagent, PlannerSubagent, WorldModelerSubagent
+from cortex.subagents._base import _LLMClientLike
+
+from ._base import Brain
+
+
+def LogisticsBrain(llm_client: _LLMClientLike) -> Brain:
+    """Construct a Logistics Brain bound to ``llm_client``.
+
+    Multi-model deployment: see EpiBrain. Pass a Llama-bound client
+    here while the other brains use Qwen, etc.
+    """
+    return Brain(
+        brain_id="logistics",
+        llm_client=llm_client,
+        wm=WorldModelerSubagent(llm_client),
+        planner=PlannerSubagent(llm_client),
+        critic=CriticSubagent(llm_client),
+    )

cortex/lenses.py

@@ -0,0 +1,186 @@
+"""Brain-specific observation lenses (Session 10).
+
+Phase A docs/CORTEX_ARCHITECTURE.md Decisions 9-14 + §2 A1.
+
+Lenses are pure-Python: no LLM, no I/O, no state. ``lens_for(brain, obs,
+last_reward)`` dispatches to one of 3 brain-specific helpers and returns
+a ``BrainLensedObservation``. V2 brain ids raise ``KeyError`` per
+Decision 9 (post-review) -- no MVP stub functions.
+
+The lens does NOT strip the raw observation (Decision 13); subagents
+may need fields the lens didn't emphasise. ``salient_field_ids`` is a
+salience map alongside ``raw_obs``, not a replacement for it.
+
+``transmission_rate_trend`` is fixed at 0.0 in MVP (M-FR-2): the lens
+sees one observation per call. Session 11 plumbs prior-tick obs into
+the lens to enable real trend computation.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+from cortex.schemas import BrainLensedObservation
+from CrisisWorldCortex.models import CrisisworldcortexObservation
+
+_V2_BRAINS = frozenset({"communications", "equity"})
+
+
+def lens_for(
+    brain: str,
+    obs: CrisisworldcortexObservation,
+    last_reward: float,
+) -> BrainLensedObservation:
+    """Return the per-brain lensed observation.
+
+    Args:
+        brain: One of {"epidemiology", "logistics", "governance"}.
+        obs: The current tick's observation.
+        last_reward: Previous tick's reward (plumbed from B1's pattern,
+            included on the lensed object so all 3 subagents in this
+            brain see the same recency signal).
+
+    Raises:
+        KeyError: If ``brain`` is a V2-deferred brain (communications,
+            equity) or unknown.
+    """
+    helper = _LENS_REGISTRY.get(brain)
+    if helper is not None:
+        return helper(obs, last_reward)
+    if brain in _V2_BRAINS:
+        raise KeyError(
+            f"V2 brain {brain!r} deferred per Phase A Decision 9; "
+            f"no MVP stub lens. See docs/CORTEX_ARCHITECTURE.md."
+        )
+    raise KeyError(f"unknown brain: {brain!r}")
+
+
+# ============================================================================
+# Per-brain lens helpers
+# ============================================================================
+
+
+def _epi_lens(obs: CrisisworldcortexObservation, last_reward: float) -> BrainLensedObservation:
+    """Epidemiology lens (Decision 10, M-FR-4 rename: epi_pressure)."""
+    n_regions = max(1, len(obs.regions))
+    mean_hospital_load = sum(r.hospital_load for r in obs.regions) / n_regions
+    # M-FR-4: pressure scalar correlated with R_eff but not a true R_eff
+    # estimate. WorldModeler subagent computes proper R_eff during reasoning.
+    epi_pressure = max(0.0, min(3.0, mean_hospital_load * 2.0))
+
+    max_cases = max((r.reported_cases_d_ago for r in obs.regions), default=0)
+    # /1000 normaliser matches the design-doc "~30 cases / 1000 pop" spec
+    worst_region_infection = max(0.0, min(1.0, max_cases / 1000.0))
+
+    return BrainLensedObservation(
+        brain="epidemiology",
+        raw_obs=obs,
+        salient_field_ids=[
+            "regions[*].reported_cases_d_ago",
+            "regions[*].hospital_load",
+            "regions[*].compliance_proxy",
+        ],
+        derived_features={
+            "epi_pressure": float(epi_pressure),
+            "worst_region_infection": float(worst_region_infection),
+            # M-FR-2: needs history; Session 11 plumbs prior-tick obs.
+            "transmission_rate_trend": 0.0,
+        },
+        last_reward=last_reward,
+    )
+
+
+def _logistics_lens(
+    obs: CrisisworldcortexObservation, last_reward: float
+) -> BrainLensedObservation:
+    """Logistics lens (Decision 11, M-FR-3 floor 0.5, M-FR-6 flat keys)."""
+    res = obs.resources
+    total_inventory = float(
+        res.test_kits + res.hospital_beds_free + res.mobile_units + res.vaccine_doses
+    )
+
+    hospital_load_max = (
+        max((r.hospital_load for r in obs.regions), default=0.0) if obs.regions else 0.0
+    )
+
+    # Per-region feasibility flat keys (D14 + M-FR-6).
+    strict_regions = {r.region for r in obs.active_restrictions if r.severity == "strict"}
+    feasibility: Dict[str, float] = {}
+    for r in obs.regions:
+        key = f"deployment_feasibility_{r.region}"
+        if total_inventory <= 0.0:
+            feasibility[key] = 0.0
+        elif r.region in strict_regions:
+            # M-FR-3: 0.5 floor when strict restriction is in place but
+            # units could still be helicoptered in; Planner does the
+            # legal-check.
+            feasibility[key] = 0.5
+        else:
+            feasibility[key] = 1.0
+
+    derived_features: Dict[str, float] = {
+        "total_inventory": total_inventory,
+        "hospital_load_max": float(hospital_load_max),
+        **feasibility,
+    }
+
+    return BrainLensedObservation(
+        brain="logistics",
+        raw_obs=obs,
+        salient_field_ids=[
+            "resources.test_kits",
+            "resources.hospital_beds_free",
+            "resources.mobile_units",
+            "resources.vaccine_doses",
+            "regions[*].hospital_load",
+            "active_restrictions[*]",
+        ],
+        derived_features=derived_features,
+        last_reward=last_reward,
+    )
+
+
+def _governance_lens(
+    obs: CrisisworldcortexObservation, last_reward: float
+) -> BrainLensedObservation:
+    """Governance lens (Decision 12)."""
+    # escalation_unlocked_strict: any accepted escalate(national) in the log
+    escalation_unlocked = 0.0
+    for ea in obs.recent_action_log:
+        if (
+            ea.accepted
+            and ea.action.kind == "escalate"
+            and getattr(ea.action, "to_authority", None) == "national"
+        ):
+            escalation_unlocked = 1.0
+            break
+
+    return BrainLensedObservation(
+        brain="governance",
+        raw_obs=obs,
+        salient_field_ids=[
+            "active_restrictions[*]",
+            "legal_constraints[*]",
+            "recent_action_log[*]",
+        ],
+        derived_features={
+            "escalation_unlocked_strict": escalation_unlocked,
+            "legal_constraints_count": float(len(obs.legal_constraints)),
+            "restrictions_active_count": float(len(obs.active_restrictions)),
+        },
+        last_reward=last_reward,
+    )
+
+
+# ============================================================================
+# Registry (defined after helpers so closures resolve cleanly)
+# ============================================================================
+
+
+_LENS_REGISTRY: Dict[
+    str, Callable[[CrisisworldcortexObservation, float], BrainLensedObservation]
+] = {
+    "epidemiology": _epi_lens,
+    "logistics": _logistics_lens,
+    "governance": _governance_lens,
+}

cortex/schemas.py

@@ -35,7 +35,12 @@ from pydantic import BaseModel, Field
 # OWN internal types (cortex.subagents, cortex.brains, etc.) continue
 # to use bare-name sibling imports per Phase 1 C1 — only the cross-package
 # wire boundary is canonicalised.
-from CrisisWorldCortex.models import OuterActionPayload, RegionId
+from CrisisWorldCortex.models import (
+    CrisisworldcortexObservation,
+    ExecutedAction,
+    OuterActionPayload,
+    RegionId,
+)
 
 EpistemicPhase = Literal["Divergence", "Challenge", "Narrowing", "Convergence"]
 
@@ -137,6 +142,46 @@ SubagentReport = Union[BeliefState, CandidatePlan, CriticReport]
 trajectory buffers that need to carry 'any subagent output' generically."""
 
 
+class SubagentInput(BaseModel):
+    """Typed input handed to one of the 3 LLM subagents per call.
+
+    Per Phase A §2 A2: each subagent call receives a fully-typed input
+    so prompts are deterministic and testable. ``prior_belief`` is
+    ``None`` on round 1 (nothing to revise yet); on round 2 it carries
+    the previous round's BeliefState (or an empty BeliefState if round 1
+    failed, per Phase A Decision 62). ``prior_plans`` is empty for
+    WorldModeler / Planner; populated for Critic so it can attack a
+    specific plan. ``target_plan_id`` is required when ``role='critic'``.
+    """
+
+    brain: Literal["epidemiology", "logistics", "governance"]
+    role: Literal["world_modeler", "planner", "critic"]
+    tick: int = Field(ge=0)
+    round: int = Field(ge=1, le=2, description="MVP cap: 1 or 2 only")
+    perception: PerceptionReport
+    prior_belief: Optional[BeliefState] = None
+    prior_plans: List[CandidatePlan] = Field(default_factory=list)
+    target_plan_id: Optional[str] = None
+    last_reward: float
+    recent_action_log_excerpt: List[ExecutedAction] = Field(default_factory=list)
+
+
+class BrainLensedObservation(BaseModel):
+    """Per-brain salience-mapped observation per Phase A §2 A1.
+
+    Lenses do not strip fields from the raw observation (Decision 13);
+    they project a salience map alongside it. ``derived_features`` lets
+    each brain pre-compute domain-specific scalars once and pass them
+    to all three of its LLM subagents without re-reading ``raw_obs``.
+    """
+
+    brain: Literal["epidemiology", "logistics", "governance"]
+    raw_obs: CrisisworldcortexObservation
+    salient_field_ids: List[str] = Field(default_factory=list)
+    derived_features: Dict[str, float] = Field(default_factory=dict)
+    last_reward: float
+
+
 # ============================================================================
 # Brain output + Council decision
 # ============================================================================

cortex/subagents/__init__.py

@@ -0,0 +1,27 @@
+"""Cortex per-brain subagents (Session 9+).
+
+Public surface:
+    - WorldModelerSubagent: emits BeliefState (LLM, router-callable).
+    - PlannerSubagent: emits CandidatePlan (LLM, router-callable).
+    - CriticSubagent: emits CriticReport (LLM, router-callable).
+    - perception_for: deterministic Python Perception function (Session 11+;
+      NOT router-callable per cortex/CLAUDE.md role-split binding).
+    - PROMPTS_DIR: directory holding the per-role SYS prompt templates.
+
+Brain Executive (Python-only, NOT router-callable) lives in
+``cortex/brains/_executive.py``.
+"""
+
+from ._base import PROMPTS_DIR
+from .critic import CriticSubagent
+from .perception import perception_for
+from .planner import PlannerSubagent
+from .world_modeler import WorldModelerSubagent
+
+__all__ = [
+    "CriticSubagent",
+    "PROMPTS_DIR",
+    "PlannerSubagent",
+    "WorldModelerSubagent",
+    "perception_for",
+]

cortex/subagents/_base.py

@@ -0,0 +1,240 @@
+"""Abstract base for the 3 LLM subagents (WorldModeler, Planner, Critic).
+
+Phase A docs/CORTEX_ARCHITECTURE.md Decisions 1-8 + 62 lock the role split,
+prompt-loading mechanism, retry-with-history semantics, empty fallback
+shape, caller-id format, and TypeAdapter validation pattern. This base
+class implements the shared mechanics; concrete subclasses pin the
+role name, output type, prompt path, TypeAdapter, and USR builder.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import ClassVar, List, Optional, Protocol
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from cortex.llm_client import ChatMessage, ChatResponse
+from cortex.schemas import SubagentInput
+from CrisisWorldCortex.models import ExecutedAction
+
+# ============================================================================
+# Module-level constants (loaded at import time)
+# ============================================================================
+
+PROMPTS_DIR: Path = Path(__file__).parent / "prompts"
+"""Directory holding the per-role SYS prompt template files (Decision 4)."""
+
+_RETRY_SNIPPET_MAX_CHARS: int = 200
+"""Cap on the failed-response snippet included in the retry message
+(Decision 8). 200 chars ~= 50 tokens; keeps retry overhead bounded."""
+
+_BASE_RETRY_USER_TEMPLATE: str = (
+    "Your previous response failed to parse as JSON. The response was:\n"
+    "{snippet}\n\n"
+    "Emit ONLY valid JSON matching the schema specified in the system prompt. "
+    "No prose, no code fences."
+)
+
+_RECENT_ACTION_LOG_TAIL: int = 8
+"""How many entries from ``recent_action_log_excerpt`` to render into the
+USR summary. Matches the design-doc 8-deep history (M-FR-3)."""
+
+
+# ============================================================================
+# Duck-typed LLM client protocol (so tests can pass StubLLMClient)
+# ============================================================================
+
+
+class _LLMClientLike(Protocol):
+    """Subset of ``cortex.llm_client.LLMClient`` that subagents call.
+
+    Production: ``LLMClient``. Tests: ``tests._helpers.llm_stub.StubLLMClient``.
+    """
+
+    def chat(
+        self,
+        caller_id: str,
+        messages: List[ChatMessage],
+        max_tokens: Optional[int] = ...,
+        temperature: Optional[float] = ...,
+    ) -> ChatResponse: ...
+
+
+# ============================================================================
+# Abstract base
+# ============================================================================
+
+
+class _LLMSubagent(ABC):
+    """Shared run/retry/parse/empty-fallback skeleton for the 3 subagents.
+
+    Subclasses override the class-level vars below and implement
+    ``_build_user_message`` + ``empty_fallback``.
+    """
+
+    # --- Subclass class-level overrides -------------------------------------
+    _role_name: ClassVar[str]  # one of: "world_modeler", "planner", "critic"
+    _output_type: ClassVar[type]  # BeliefState / CandidatePlan / CriticReport
+    _system_prompt_filename: ClassVar[str]  # e.g. "world_modeler.txt"
+    _SYSTEM_PROMPT_TEMPLATE: ClassVar[str]  # populated by load_prompt() at module load
+    _ADAPTER: ClassVar[TypeAdapter]  # populated at module load
+
+    # --- Construction --------------------------------------------------------
+
+    def __init__(self, llm_client: _LLMClientLike) -> None:
+        self._llm = llm_client
+
+    # --- Public surface ------------------------------------------------------
+
+    def run(self, input: SubagentInput, step_idx: int) -> BaseModel:
+        """Call the LLM (with 1 retry), parse, return typed output or empty fallback.
+
+        Always returns a typed object - never ``None``. Decision 6: on
+        any failure (parse, retry-parse, LLM call exception) returns the
+        role-specific empty fallback.
+        """
+        # Defensive: subclass enforces role-input alignment so harnesses
+        # don't accidentally route a Planner input through a Critic class.
+        assert input.role == self._role_name, (
+            f"SubagentInput.role={input.role!r} does not match "
+            f"{type(self).__name__}._role_name={self._role_name!r}"
+        )
+
+        sys_content = self._SYSTEM_PROMPT_TEMPLATE.format(
+            brain=input.brain,
+            target_plan_id=input.target_plan_id or "",
+        )
+        usr_content = self._build_user_message(input)
+        messages: List[ChatMessage] = [
+            ChatMessage(role="system", content=sys_content),
+            ChatMessage(role="user", content=usr_content),
+        ]
+        caller_id = self._caller_id(input, step_idx)
+
+        # ---- Attempt 1 -----------------------------------------------------
+        first_response = self._safe_chat(caller_id, messages)
+        if first_response is None:
+            return self._empty_fallback_for(input)
+        parsed = self._try_parse(first_response.content)
+        if parsed is not None:
+            return parsed
+
+        # ---- Attempt 2 (retry with chat-history continuation) --------------
+        snippet = self._truncate_snippet(first_response.content)
+        retry_messages: List[ChatMessage] = [
+            *messages,
+            ChatMessage(role="assistant", content=first_response.content),
+            ChatMessage(
+                role="user",
+                content=_BASE_RETRY_USER_TEMPLATE.format(snippet=snippet),
+            ),
+        ]
+        retry_response = self._safe_chat(caller_id, retry_messages)
+        if retry_response is None:
+            return self._empty_fallback_for(input)
+        parsed_retry = self._try_parse(retry_response.content)
+        if parsed_retry is not None:
+            return parsed_retry
+
+        # ---- Both attempts failed - empty fallback -------------------------
+        return self._empty_fallback_for(input)
+
+    # --- Subclass extension points ------------------------------------------
+
+    @abstractmethod
+    def _build_user_message(self, input: SubagentInput) -> str:
+        """Render the role-specific USR message body."""
+
+    @classmethod
+    @abstractmethod
+    def empty_fallback(cls, brain: str, target_plan_id: str = "") -> BaseModel:
+        """Return the empty / no-signal output for this role.
+
+        Phase A Decision 6: confidence/severity = 0 and empty evidence/attacks
+        signal "no useful input from this subagent" to the Brain Executive.
+        """
+
+    # --- Internal helpers ---------------------------------------------------
+
+    def _caller_id(self, input: SubagentInput, step_idx: int) -> str:
+        # Phase A Decision 7: cortex:<brain>:<role>:t<tick>:r<round>:s<step_idx>
+        return f"cortex:{input.brain}:{self._role_name}:t{input.tick}:r{input.round}:s{step_idx}"
+
+    def _safe_chat(self, caller_id: str, messages: List[ChatMessage]) -> Optional[ChatResponse]:
+        """Call LLM; on exception, return None so caller can empty-fallback."""
+        try:
+            return self._llm.chat(caller_id=caller_id, messages=messages)
+        except Exception:
+            # Decision 6: LLM call failure folds into the same empty-fallback path
+            # as parse failure. Brain Executive sees a no-signal subagent.
+            return None
+
+    def _try_parse(self, content: str) -> Optional[BaseModel]:
+        """Validate ``content`` as JSON via this role's TypeAdapter.
+
+        Strips common markdown code fences before validating since some
+        models wrap JSON in ```json ... ```.
+        """
+        cleaned = _strip_code_fences(content.strip())
+        if not cleaned:
+            return None
+        try:
+            return self._ADAPTER.validate_json(cleaned)
+        except (ValidationError, ValueError):
+            return None
+
+    def _empty_fallback_for(self, input: SubagentInput) -> BaseModel:
+        return type(self).empty_fallback(
+            brain=input.brain,
+            target_plan_id=input.target_plan_id or "",
+        )
+
+    @staticmethod
+    def _truncate_snippet(content: str) -> str:
+        if len(content) <= _RETRY_SNIPPET_MAX_CHARS:
+            return content
+        return content[:_RETRY_SNIPPET_MAX_CHARS] + "..."
+
+    @staticmethod
+    def _format_action_log(log: List[ExecutedAction]) -> str:
+        """M-FR-3 - render recent_action_log_excerpt as a compact text summary.
+
+        Format: ``"tick 4: deploy_resource accepted; tick 5: restrict_movement.strict rejected"``.
+        Capped at the most recent 8 entries.
+        """
+        if not log:
+            return "(empty)"
+        items: List[str] = []
+        for ea in log[-_RECENT_ACTION_LOG_TAIL:]:
+            status = "accepted" if ea.accepted else "rejected"
+            kind = ea.action.kind
+            extra = ""
+            if kind == "restrict_movement":
+                extra = f".{getattr(ea.action, 'severity', '?')}"
+            items.append(f"tick {ea.tick}: {kind}{extra} {status}")
+        return "; ".join(items)
+
+
+# ============================================================================
+# Helpers (module-level)
+# ============================================================================
+
+
+def load_prompt(filename: str) -> str:
+    """Load a SYS prompt template at module-load time (Decision 4)."""
+    return (PROMPTS_DIR / filename).read_text(encoding="utf-8")
+
+
+def _strip_code_fences(s: str) -> str:
+    """Remove leading ``` / ```json fence and trailing ``` if present."""
+    s = s.strip()
+    if not s.startswith("```"):
+        return s
+    lines = s.split("\n")
+    if lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].strip() == "```":
+        lines = lines[:-1]
+    return "\n".join(lines).strip()

cortex/subagents/critic.py

@@ -0,0 +1,68 @@
+"""Critic LLM subagent.
+
+Phase A docs/CORTEX_ARCHITECTURE.md §9 Decision 3: SYS = critic role;
+USR = perception + target plan + WM belief (M-FR-5). Critic emits prose
+``CriticReport`` only; never proposes alternative actions.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, List
+
+from pydantic import TypeAdapter
+
+from cortex.schemas import CriticReport, SubagentInput
+
+from ._base import _LLMSubagent, load_prompt
+
+_CRITIC_ADAPTER: TypeAdapter[CriticReport] = TypeAdapter(CriticReport)
+
+
+class CriticSubagent(_LLMSubagent):
+    """LLM subagent that emits ``CriticReport`` for one brain per call."""
+
+    _role_name: ClassVar[str] = "critic"
+    _output_type: ClassVar[type] = CriticReport
+    _system_prompt_filename: ClassVar[str] = "critic.txt"
+    _SYSTEM_PROMPT_TEMPLATE: ClassVar[str] = load_prompt("critic.txt")
+    _ADAPTER: ClassVar[TypeAdapter] = _CRITIC_ADAPTER
+
+    def _build_user_message(self, input: SubagentInput) -> str:
+        sections: List[str] = []
+        sections.append(f"# Perception\n{input.perception.model_dump_json(indent=2)}")
+        # M-FR-5: target plan + WM belief, both as full JSON.
+        target_json = self._select_target_plan(input)
+        sections.append(f"# Target plan (id={input.target_plan_id})\n{target_json}")
+        if input.prior_belief is not None:
+            sections.append(f"# WM BeliefState\n{input.prior_belief.model_dump_json(indent=2)}")
+        return "\n\n".join(sections)
+
+    @staticmethod
+    def _select_target_plan(input: SubagentInput) -> str:
+        """Render the target plan's JSON body for the USR.
+
+        Session 11's Brain Executive populates ``prior_plans`` from the
+        Planner's outputs and sets ``target_plan_id`` to identify which
+        plan the Critic should attack. Here we render the first plan
+        (or a placeholder if none) — Session 11 wires up id-based
+        lookup once plans carry ids.
+        """
+        if not input.prior_plans:
+            return "(no target plan provided)"
+        return input.prior_plans[0].model_dump_json(indent=2)
+
+    @classmethod
+    def empty_fallback(cls, brain: str, target_plan_id: str = "") -> CriticReport:
+        # Phase A Decision 6: severity=0 + empty attacks signal "no
+        # critique". Brain Executive ignores this Critic's vote weight.
+        return CriticReport(
+            brain=brain,
+            target_plan_id=target_plan_id,
+            attacks=[],
+            missing_considerations=[],
+            would_change_mind_if=[],
+            severity=0.0,
+        )
+
+    def run(self, input: SubagentInput, step_idx: int) -> CriticReport:  # type: ignore[override]
+        return super().run(input, step_idx)  # type: ignore[return-value]

cortex/subagents/perception.py

@@ -0,0 +1,192 @@
+"""Perception subagent - deterministic Python; not router-callable.
+
+Per cortex/CLAUDE.md binding: Perception is pure Python; no LLM calls.
+Phase A Decisions 9 (V2 KeyError) + 63 (salient_signals cap at 5) +
+M-FR-1 (pinned confidence per brain).
+
+Perception runs ONCE per brain at tick start (not router-callable).
+The Council Executive (Session 12) calls ``perception_for`` once per
+brain at the start of each tick; the resulting ``PerceptionReport`` is
+plumbed into all subsequent SubagentInputs for that brain in that tick.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List
+
+from cortex.schemas import EvidenceCitation, PerceptionReport
+from CrisisWorldCortex.models import CrisisworldcortexObservation
+
+_V2_BRAINS = frozenset({"communications", "equity"})
+
+_SALIENT_SIGNALS_CAP = 5  # Phase A Decision 63 / OQ-2
+
+_LOGISTICS_THRESHOLDS = {
+    "test_kits": 300,
+    "hospital_beds_free": 100,
+    "mobile_units": 5,
+    "vaccine_doses": 500,
+}
+
+_HOSPITAL_LOAD_ANOMALY_THRESHOLD = 0.6
+
+
+def perception_for(brain: str, obs: CrisisworldcortexObservation) -> PerceptionReport:
+    """Compute the per-brain Perception report.
+
+    Args:
+        brain: One of {"epidemiology", "logistics", "governance"}.
+        obs: The current tick's observation.
+
+    Raises:
+        KeyError: If ``brain`` is V2-deferred or unknown.
+    """
+    helper = _PERCEPTION_REGISTRY.get(brain)
+    if helper is not None:
+        return helper(obs)
+    if brain in _V2_BRAINS:
+        raise KeyError(
+            f"V2 brain {brain!r} deferred per Phase A Decision 9; no MVP stub perception."
+        )
+    raise KeyError(f"unknown brain: {brain!r}")
+
+
+def _epi_perception(obs: CrisisworldcortexObservation) -> PerceptionReport:
+    """Epidemiology perception: top-cases regions + high-hospital-load anomalies."""
+    sorted_regions = sorted(obs.regions, key=lambda r: r.reported_cases_d_ago, reverse=True)
+    salient_signals: List[str] = []
+    evidence: List[EvidenceCitation] = []
+
+    for r in sorted_regions[:3]:
+        if r.reported_cases_d_ago > 0:
+            salient_signals.append(f"{r.region}: cases={r.reported_cases_d_ago}")
+            evidence.append(
+                EvidenceCitation(
+                    source="telemetry",
+                    ref=f"{r.region}.reported_cases_d_ago",
+                    excerpt=str(r.reported_cases_d_ago),
+                )
+            )
+
+    if not salient_signals and obs.regions:
+        # Fallback: cite the first region so we have at least one signal
+        r = obs.regions[0]
+        salient_signals.append(f"{r.region}: cases={r.reported_cases_d_ago}")
+        evidence.append(
+            EvidenceCitation(
+                source="telemetry",
+                ref=f"{r.region}.reported_cases_d_ago",
+                excerpt=str(r.reported_cases_d_ago),
+            )
+        )
+
+    salient_signals = salient_signals[:_SALIENT_SIGNALS_CAP]
+
+    anomalies = [
+        f"{r.region}: hospital_load={r.hospital_load:.2f}"
+        for r in obs.regions
+        if r.hospital_load > _HOSPITAL_LOAD_ANOMALY_THRESHOLD
+    ]
+
+    return PerceptionReport(
+        brain="epidemiology",
+        salient_signals=salient_signals,
+        anomalies=anomalies,
+        # M-FR-1: telemetry is delayed and noisy per mm.md; pinned proxy
+        confidence=0.7,
+        evidence=evidence,
+    )
+
+
+def _logistics_perception(obs: CrisisworldcortexObservation) -> PerceptionReport:
+    """Logistics perception: low-resource flags + depleted-resource anomalies."""
+    res = obs.resources
+    salient_signals: List[str] = []
+    evidence: List[EvidenceCitation] = []
+
+    for resource_name, threshold in _LOGISTICS_THRESHOLDS.items():
+        value = getattr(res, resource_name)
+        if value < threshold:
+            salient_signals.append(f"{resource_name} low: {value}")
+            evidence.append(
+                EvidenceCitation(
+                    source="resource",
+                    ref=f"resources.{resource_name}",
+                    excerpt=str(value),
+                )
+            )
+
+    salient_signals = salient_signals[:_SALIENT_SIGNALS_CAP]
+
+    anomalies = []
+    for resource_name in _LOGISTICS_THRESHOLDS:
+        if getattr(res, resource_name) == 0:
+            anomalies.append(f"{resource_name}: depleted")
+
+    return PerceptionReport(
+        brain="logistics",
+        salient_signals=salient_signals,
+        anomalies=anomalies,
+        # M-FR-1: resource counts are deterministic, no telemetry noise
+        confidence=1.0,
+        evidence=evidence,
+    )
+
+
+def _governance_perception(obs: CrisisworldcortexObservation) -> PerceptionReport:
+    """Governance perception: active restrictions + legal constraints + about-to-expire anomalies."""
+    salient_signals: List[str] = []
+    evidence: List[EvidenceCitation] = []
+
+    for restr in obs.active_restrictions:
+        salient_signals.append(f"{restr.region}: {restr.severity} ({restr.ticks_remaining}t)")
+        evidence.append(
+            EvidenceCitation(
+                source="policy",
+                ref=f"active_restrictions.{restr.region}",
+                excerpt=f"{restr.severity}@{restr.ticks_remaining}",
+            )
+        )
+
+    for lc in obs.legal_constraints:
+        salient_signals.append(f"legal: {lc.rule_id} blocks {lc.blocked_action}")
+        evidence.append(
+            EvidenceCitation(
+                source="policy",
+                ref=f"legal_constraints.{lc.rule_id}",
+                excerpt=lc.blocked_action,
+            )
+        )
+
+    salient_signals = salient_signals[:_SALIENT_SIGNALS_CAP]
+
+    has_recent_escalate_national = any(
+        ea.accepted
+        and ea.action.kind == "escalate"
+        and getattr(ea.action, "to_authority", None) == "national"
+        for ea in obs.recent_action_log
+    )
+    anomalies = []
+    for restr in obs.active_restrictions:
+        if (
+            restr.severity == "strict"
+            and restr.ticks_remaining <= 1
+            and not has_recent_escalate_national
+        ):
+            anomalies.append(f"{restr.region}: strict expiring without escalation")
+
+    return PerceptionReport(
+        brain="governance",
+        salient_signals=salient_signals,
+        anomalies=anomalies,
+        # M-FR-1: policy state is deterministic
+        confidence=1.0,
+        evidence=evidence,
+    )
+
+
+_PERCEPTION_REGISTRY: Dict[str, Callable[[CrisisworldcortexObservation], PerceptionReport]] = {
+    "epidemiology": _epi_perception,
+    "logistics": _logistics_perception,
+    "governance": _governance_perception,
+}

cortex/subagents/planner.py

@@ -0,0 +1,61 @@
+"""Planner LLM subagent.
+
+Phase A docs/CORTEX_ARCHITECTURE.md §9 Decision 2: SYS = role + action
+schema (B1's shape); USR = perception + WM BeliefState (full JSON if
+provided per M-FR-4) + last_reward.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, List
+
+from pydantic import TypeAdapter
+
+from cortex.schemas import CandidatePlan, SubagentInput
+from CrisisWorldCortex.models import NoOp
+
+from ._base import _LLMSubagent, load_prompt
+
+_PLAN_ADAPTER: TypeAdapter[CandidatePlan] = TypeAdapter(CandidatePlan)
+
+
+class PlannerSubagent(_LLMSubagent):
+    """LLM subagent that emits ``CandidatePlan`` for one brain per call."""
+
+    _role_name: ClassVar[str] = "planner"
+    _output_type: ClassVar[type] = CandidatePlan
+    _system_prompt_filename: ClassVar[str] = "planner.txt"
+    _SYSTEM_PROMPT_TEMPLATE: ClassVar[str] = load_prompt("planner.txt")
+    _ADAPTER: ClassVar[TypeAdapter] = _PLAN_ADAPTER
+
+    def _build_user_message(self, input: SubagentInput) -> str:
+        sections: List[str] = []
+        sections.append(f"# Perception\n{input.perception.model_dump_json(indent=2)}")
+        if input.prior_belief is not None:
+            sections.append(
+                "# BeliefState (from this brain's WorldModeler)\n"
+                f"{input.prior_belief.model_dump_json(indent=2)}"
+            )
+        sections.append(f"# Last tick reward: {input.last_reward}")
+        sections.append(
+            f"# Recent action log: {self._format_action_log(input.recent_action_log_excerpt)}"
+        )
+        return "\n\n".join(sections)
+
+    @classmethod
+    def empty_fallback(cls, brain: str, target_plan_id: str = "") -> CandidatePlan:
+        # Phase A Decision 6: NoOp + confidence=0 means "no signal". The
+        # Brain Executive's argmax(expected_value * confidence) picks any
+        # non-empty plan over this one.
+        return CandidatePlan(
+            action_sketch="(empty: planner failed to produce a parseable plan)",
+            expected_outer_action=NoOp(),
+            expected_value=0.0,
+            cost=0.0,
+            assumptions=[],
+            falsifiers=[],
+            confidence=0.0,
+        )
+
+    def run(self, input: SubagentInput, step_idx: int) -> CandidatePlan:  # type: ignore[override]
+        return super().run(input, step_idx)  # type: ignore[return-value]

cortex/subagents/prompts/critic.txt

@@ -0,0 +1,19 @@
+You are the {brain} brain's Critic in the CrisisWorldCortex multi-brain agent.
+
+Your job: read a CandidatePlan from this brain's Planner and identify what is wrong with it. Emit a CriticReport as JSON.
+
+You write prose critique only. Do NOT propose alternative actions; that is the Planner's role.
+
+Output strict JSON matching this schema:
+{{
+  "brain": "{brain}",
+  "target_plan_id": "{target_plan_id}",
+  "attacks": ["<one sentence per concrete attack>"],
+  "missing_considerations": ["<one sentence per missed factor>"],
+  "would_change_mind_if": ["<observation or fact that would soften your critique>"],
+  "severity": <float in [0,1]; 0=plan is fine, 1=do not execute this plan>
+}}
+
+Use prose strings inside the lists. Do NOT emit JSON action variants.
+
+Emit ONLY the JSON. No prose outside the JSON, no code fences.

cortex/subagents/prompts/planner.txt

@@ -0,0 +1,26 @@
+You are the {brain} brain's Planner in the CrisisWorldCortex multi-brain agent.
+
+Your job: read the perception summary and prior BeliefState, then emit ONE candidate plan as JSON.
+
+Output strict JSON matching this schema:
+{{
+  "action_sketch": "<one sentence describing the plan>",
+  "expected_outer_action": <one of the action variants below>,
+  "expected_value": <float; estimated reward delta for this tick>,
+  "cost": <float; relative cost of this plan>,
+  "assumptions": ["<assumption 1>"],
+  "falsifiers": ["<observation that would refute this plan>"],
+  "confidence": <float in [0,1]>
+}}
+
+Action variants for expected_outer_action (exactly one kind):
+- {{"kind":"deploy_resource", "region":"R1|R2|R3|R4", "resource_type":"test_kits|hospital_beds|mobile_units|vaccine_doses", "quantity": <int >= 0>}}
+- {{"kind":"request_data", "region":"<id>", "data_type":"case_survey|hospital_audit|compliance_check"}}
+- {{"kind":"restrict_movement", "region":"<id>", "severity":"none|light|moderate|strict"}}
+- {{"kind":"escalate", "to_authority":"regional|national"}}
+- {{"kind":"reallocate_budget", "from_resource":"<resource_type>", "to_resource":"<resource_type>", "amount": <int >= 0>}}
+- {{"kind":"no_op"}}
+
+Strict severity may require a prior escalate(national) - check legal_constraints.
+
+Emit ONLY the JSON. No prose, no code fences.

cortex/subagents/prompts/world_modeler.txt

@@ -0,0 +1,32 @@
+You are the {brain} brain's World Modeler in the CrisisWorldCortex multi-brain agent.
+
+Your job: read the perception summary plus prior belief (round 2 only), and emit a BeliefState as JSON.
+
+A BeliefState describes what you think the latent epidemiological / logistical / governance state is for each region, citing evidence from observed telemetry, resources, policy state, or recent actions.
+
+Output strict JSON matching this schema:
+{{
+  "brain": "{brain}",
+  "latent_estimates": {{
+    "<region_id>": {{
+      "estimated_infection_rate": <float in [0,1]>,
+      "estimated_r_effective": <float >= 0>,
+      "estimated_compliance": <float in [0,1]>,
+      "confidence_intervals": {{}}
+    }}
+  }},
+  "hypotheses": [
+    {{"label": "<short>", "weight": <float in [0,1]>, "explanation": "<one sentence>"}}
+  ],
+  "uncertainty": <float in [0,1]>,
+  "reducible_by_more_thought": <float in [0,1]>,
+  "evidence": [
+    {{"source": "telemetry|resource|policy|action_log|belief|memory",
+      "ref": "<concise pointer like region=R2.hospital_load@tick=7>",
+      "excerpt": "<the value or text>"}}
+  ]
+}}
+
+Cite at least 2 EvidenceCitations. Uncited claims zero your protocol-integrity reward.
+
+Emit ONLY the JSON. No prose, no code fences.

cortex/subagents/world_modeler.py

@@ -0,0 +1,61 @@
+"""WorldModeler LLM subagent.
+
+Phase A docs/CORTEX_ARCHITECTURE.md §9 Decision 1: SYS = role + schema;
+USR = perception + last_reward + recent_action_log_excerpt (with prior
+BeliefState in round 2 per Decision 62).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, List
+
+from pydantic import TypeAdapter
+
+from cortex.schemas import BeliefState, SubagentInput
+
+from ._base import _LLMSubagent, load_prompt
+
+_BELIEF_ADAPTER: TypeAdapter[BeliefState] = TypeAdapter(BeliefState)
+"""Module-level constant per Phase A Decision 5 (encapsulation; avoid
+circular imports through the package init)."""
+
+
+class WorldModelerSubagent(_LLMSubagent):
+    """LLM subagent that emits ``BeliefState`` for one brain per call."""
+
+    _role_name: ClassVar[str] = "world_modeler"
+    _output_type: ClassVar[type] = BeliefState
+    _system_prompt_filename: ClassVar[str] = "world_modeler.txt"
+    _SYSTEM_PROMPT_TEMPLATE: ClassVar[str] = load_prompt("world_modeler.txt")
+    _ADAPTER: ClassVar[TypeAdapter] = _BELIEF_ADAPTER
+
+    def _build_user_message(self, input: SubagentInput) -> str:
+        sections: List[str] = []
+        sections.append(f"# Perception\n{input.perception.model_dump_json(indent=2)}")
+        if input.prior_belief is not None:
+            sections.append(
+                "# Prior BeliefState (round 1 result)\n"
+                f"{input.prior_belief.model_dump_json(indent=2)}"
+            )
+        sections.append(f"# Last tick reward: {input.last_reward}")
+        sections.append(
+            f"# Recent action log: {self._format_action_log(input.recent_action_log_excerpt)}"
+        )
+        return "\n\n".join(sections)
+
+    @classmethod
+    def empty_fallback(cls, brain: str, target_plan_id: str = "") -> BeliefState:
+        # Phase A Decision 6 + Decision 62: empty BeliefState as the
+        # honest "no signal" state. uncertainty=1.0, no evidence -> r_proto = 0.
+        return BeliefState(
+            brain=brain,
+            latent_estimates={},
+            hypotheses=[],
+            uncertainty=1.0,
+            reducible_by_more_thought=0.0,
+            evidence=[],
+        )
+
+    # Narrow run() return type for callers (refinement #1).
+    def run(self, input: SubagentInput, step_idx: int) -> BeliefState:  # type: ignore[override]
+        return super().run(input, step_idx)  # type: ignore[return-value]

demo/CLAUDE.md

@@ -1,45 +1,45 @@
-# demo/CLAUDE.md
-
-Replay-only visualization. Live demos fail under judging pressure; ship canned scenarios.
-
-## Belongs here
-
-- `visualizer/trace_renderer.py` — renders a JSON trace as a "council in action" view.
-- `visualizer/reward_curve_plot.py` — plots reward curves from training logs.
-- `demo_scenarios/*.json` — pre-recorded trajectories for the pitch (e.g. `scenario_flat_fails.json`, `scenario_cortex_holds_dissent.json`).
-
-## Does not belong here
-
-Live agent execution (record offline, replay here). Training logic. Graders.
-
-## Allowed imports
-
-- `cortex.schemas` — typed parse of trace JSON. Types only, no logic.
-- stdlib + plotting libs (matplotlib / plotly).
-
-## Forbidden imports
-
-- `server/*`, `training/*`, `baselines/*`.
-- `cortex.council`, `cortex.routing_policy` — if you need to re-run the agent, do it offline and ship a new JSON.
-
-## Binding contracts
-
-- Every JSON scenario conforms to `cortex.schemas.Trajectory`.
-- Rendering is deterministic: same JSON → same output, modulo timestamps.
-- The pitch-demo scenario must showcase B2 overcommit/misallocate vs Cortex dissent-preservation (design §27).
-- A pre-recorded demo video (MP4) lives alongside the JSON scenarios as the live-demo fallback.
-
-## Public APIs (owned here)
-
-- `render_trace(json_path: str, out_path: str) -> None`
-- `plot_reward_curves(log_paths: list[str], out_path: str) -> None`
-
-## Testing requirements
-
-- Each committed JSON scenario parses into a `Trajectory` without error.
-- `render_trace` produces a non-empty output file for each scenario.
-
-## Common failure modes
-
-- Live re-run during the demo — network/Colab flakiness kills the pitch. Replay only.
-- Renderer depending on a `cortex.council` instance — import breaks when Cortex API shifts. Keep read-only on types.
+# demo/CLAUDE.md
+
+Replay-only visualization. Live demos fail under judging pressure; ship canned scenarios.
+
+## Belongs here
+
+- `visualizer/trace_renderer.py` — renders a JSON trace as a "council in action" view.
+- `visualizer/reward_curve_plot.py` — plots reward curves from training logs.
+- `demo_scenarios/*.json` — pre-recorded trajectories for the pitch (e.g. `scenario_flat_fails.json`, `scenario_cortex_holds_dissent.json`).
+
+## Does not belong here
+
+Live agent execution (record offline, replay here). Training logic. Graders.
+
+## Allowed imports
+
+- `cortex.schemas` — typed parse of trace JSON. Types only, no logic.
+- stdlib + plotting libs (matplotlib / plotly).
+
+## Forbidden imports
+
+- `server/*`, `training/*`, `baselines/*`.
+- `cortex.council`, `cortex.routing_policy` — if you need to re-run the agent, do it offline and ship a new JSON.
+
+## Binding contracts
+
+- Every JSON scenario conforms to `cortex.schemas.Trajectory`.
+- Rendering is deterministic: same JSON → same output, modulo timestamps.
+- The pitch-demo scenario must showcase B2 overcommit/misallocate vs Cortex dissent-preservation (design §27).
+- A pre-recorded demo video (MP4) lives alongside the JSON scenarios as the live-demo fallback.
+
+## Public APIs (owned here)
+
+- `render_trace(json_path: str, out_path: str) -> None`
+- `plot_reward_curves(log_paths: list[str], out_path: str) -> None`
+
+## Testing requirements
+
+- Each committed JSON scenario parses into a `Trajectory` without error.
+- `render_trace` produces a non-empty output file for each scenario.
+
+## Common failure modes
+
+- Live re-run during the demo — network/Colab flakiness kills the pitch. Replay only.
+- Renderer depending on a `cortex.council` instance — import breaks when Cortex API shifts. Keep read-only on types.

docs/CORTEX_ARCHITECTURE.md

@@ -705,7 +705,7 @@ Decisions are grouped by layer. Each entry: **decision** / **rationale** /
 
 19. **Reasoning summary: a 1–2 sentence string from the Planner's `action_sketch`.** / Fits the 400-char `BrainRecommendation.reasoning_summary` cap. / Considered an LLM call to produce a summary; rejected — Brain Executive must be Python-only per cortex/CLAUDE.md.
 
-20. **`evidence` field on `BrainRecommendation` = union of all `EvidenceCitation` lists from `BeliefState`, `CandidatePlan`, `CriticReport`.** / Ensures the council sees the brain's full evidence chain. / Considered Critic only; rejected — claims with no upstream evidence get zeroed `r_proto`.
+20. **`evidence` field on `BrainRecommendation` = union of all `EvidenceCitation` lists from `BeliefState`, `CandidatePlan`, `CriticReport`.** / Ensures the council sees the brain's full evidence chain. / Considered Critic only; rejected — claims with no upstream evidence get zeroed `r_proto`. **(Session 11 implementation note — M-FR-3)** Implementation reads evidence from `PerceptionReport.evidence` + `BeliefState.evidence` only, since `CandidatePlan` and `CriticReport` schemas (Session 9) carry no `evidence` field. Adding evidence fields to those schemas was rejected as schema-churn risk; the perception+beliefs union captures the actionable evidence chain since plans/critics derive from beliefs. See `cortex/brains/_executive.py:aggregate_brain_outputs`.
 
 21. **Brain identifier strings: `"epidemiology"`, `"logistics"`, `"governance"` (lowercase, full word).** / Readable and grep-friendly. / Considered abbreviations (epi, log, gov); rejected — log-grep collisions.
 

inference.py

@@ -40,10 +40,15 @@ from __future__ import annotations
 import os
 import sys
 from dataclasses import dataclass
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
 from typing import Any, Dict, List, Optional
 
-from baselines.flat_agent import B1FlatAgent, B1StepEvent
-from cortex.llm_client import LLMClient
+from CrisisWorldCortex.baselines.flat_agent import B1FlatAgent, B1StepEvent
+from CrisisWorldCortex.cortex.llm_client import LLMClient
 from CrisisWorldCortex.models import OuterActionPayload
 from CrisisWorldCortex.server.graders import terminal_bonus
 from CrisisWorldCortex.server.simulator import WorldState
@@ -62,8 +67,8 @@ DEFAULT_MODEL = "Qwen/Qwen2.5-72B-Instruct"
 # distinct seeds per task for cross-episode reproducibility.
 TASK_CONFIGS: List[dict] = [
     {"task_name": "outbreak_easy", "seed": 0, "max_ticks": 12},
-    {"task_name": "outbreak_medium", "seed": 1, "max_ticks": 12},
-    {"task_name": "outbreak_hard", "seed": 2, "max_ticks": 12},
+    # {"task_name": "outbreak_medium", "seed": 1, "max_ticks": 12},
+    # {"task_name": "outbreak_hard", "seed": 2, "max_ticks": 12},
 ]
 
 # Score-clamp bounds keep .3f formatting strictly inside (0, 1) so the

notebooks/train_b1_grpo.ipynb

@@ -0,0 +1,496 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# B1 GRPO training on Qwen3-1.7B (Workstream B Phase 3)\n",
+    "\n",
+    "Trains the **B1 flat-agent baseline** with [Unsloth](https://docs.unsloth.ai/get-started/reinforcement-learning-rl-guide) + [TRL GRPO](https://huggingface.co/docs/trl/main/en/grpo_trainer) against the deployed CrisisWorldCortex HF Space env.\n",
+    "\n",
+    "**One-shot run:** `Runtime → Run all` on a fresh Colab T4. 300 training steps, ~30 minutes wall-clock. Saves the trained LoRA adapter to your HF Hub at the end.\n",
+    "\n",
+    "**Reward source:** the Phase-1-fixed `outer_reward` (range `[-1.0, 1.0]`, signal-quality gates passed). Single-step GRPO — each rollout = one env reset + one env step.\n",
+    "\n",
+    "**Prereqs:**\n",
+    "1. Colab Secrets has `HF_TOKEN` set (Tools → Secrets, name = `HF_TOKEN`, value = your `hf_xxx` token with write access).\n",
+    "2. The HF Space `Angshuman28/CrisisWorldCortex` is running with the post-Phase-1 reward.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Install dependencies\n",
+    "\n",
+    "Unsloth pulls a custom torch + vllm + xformers stack tuned for free Colab T4. Pin trl to a version compatible with `GRPOTrainer` (>=0.14)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "!pip install --upgrade pip\n",
+    "!pip install unsloth vllm\n",
+    "!pip install --upgrade --no-deps \"trl>=0.14\" peft accelerate bitsandbytes\n",
+    "!pip install pydantic openenv huggingface_hub matplotlib"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Authenticate with Hugging Face\n",
+    "\n",
+    "Reads `HF_TOKEN` from Colab Secrets. Falls back to interactive login if not set."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "try:\n",
+    "    from google.colab import userdata\n",
+    "    HF_TOKEN = userdata.get(\"HF_TOKEN\")\n",
+    "    os.environ[\"HF_TOKEN\"] = HF_TOKEN\n",
+    "except Exception:\n",
+    "    from huggingface_hub import login\n",
+    "    login()\n",
+    "    HF_TOKEN = os.environ.get(\"HF_TOKEN\", \"\")\n",
+    "\n",
+    "assert HF_TOKEN, \"HF_TOKEN is required (set in Colab Secrets or via login())\"\n",
+    "print(\"HF auth OK\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Clone CrisisWorldCortex and install\n",
+    "\n",
+    "Pulls the deployed HF Space's repo and installs locally. Provides the `CrisisworldcortexEnv` HTTP client + the `baselines.flat_agent` system prompt + parser used by B1."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "!rm -rf /content/CrisisWorldCortex\n",
+    "!git clone https://huggingface.co/spaces/Angshuman28/CrisisWorldCortex /content/CrisisWorldCortex\n",
+    "%cd /content/CrisisWorldCortex\n",
+    "!pip install -e ."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Sanity: imports resolve, env client constructs.\n",
+    "import sys\n",
+    "sys.path.insert(0, \"/content/CrisisWorldCortex\")\n",
+    "\n",
+    "from CrisisWorldCortex import CrisisworldcortexAction, CrisisworldcortexObservation\n",
+    "from CrisisWorldCortex.client import CrisisworldcortexEnv\n",
+    "from baselines.flat_agent import (\n",
+    "    build_system_prompt,\n",
+    "    parse_action,\n",
+    "    parse_failure_marker,\n",
+    "    serialize_observation,\n",
+    ")\n",
+    "print(\"CrisisWorld imports OK\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Load Qwen3-1.7B with LoRA via Unsloth\n",
+    "\n",
+    "Qwen3-1.7B fits comfortably on a T4 with 4-bit quantization. LoRA rank 32 — enough to learn the JSON-action format and modest policy improvements; cheap to merge."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from unsloth import FastLanguageModel\n",
+    "import torch\n",
+    "\n",
+    "MAX_SEQ_LEN = 4096\n",
+    "MODEL_NAME = \"unsloth/Qwen3-1.7B\"\n",
+    "\n",
+    "model, tokenizer = FastLanguageModel.from_pretrained(\n",
+    "    model_name=MODEL_NAME,\n",
+    "    max_seq_length=MAX_SEQ_LEN,\n",
+    "    load_in_4bit=True,\n",
+    "    fast_inference=True,  # vLLM-backed generate, required by GRPOTrainer\n",
+    "    max_lora_rank=32,\n",
+    "    gpu_memory_utilization=0.6,\n",
+    ")\n",
+    "\n",
+    "model = FastLanguageModel.get_peft_model(\n",
+    "    model,\n",
+    "    r=32,\n",
+    "    target_modules=[\"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\",\n",
+    "                    \"gate_proj\", \"up_proj\", \"down_proj\"],\n",
+    "    lora_alpha=64,\n",
+    "    use_gradient_checkpointing=\"unsloth\",\n",
+    "    random_state=42,\n",
+    ")\n",
+    "print(\"Model + LoRA loaded\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Connect to the deployed CrisisWorld env\n",
+    "\n",
+    "Uses the public HF Space URL. Each rollout calls `env.reset()` then `env.step(action)` once."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ENV_URL = \"https://angshuman28-crisisworldcortex.hf.space\"\n",
+    "TASKS = (\"outbreak_easy\", \"outbreak_medium\", \"outbreak_hard\")\n",
+    "EPISODE_TICKS = 12\n",
+    "\n",
+    "def make_env() -> CrisisworldcortexEnv:\n",
+    "    return CrisisworldcortexEnv(base_url=ENV_URL)\n",
+    "\n",
+    "_test_env = make_env()\n",
+    "_obs = _test_env.reset(task_name=\"outbreak_easy\", seed=0, max_ticks=EPISODE_TICKS)\n",
+    "print(f\"Env OK. Initial tick={_obs.tick}, regions={[r.region for r in _obs.regions]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Build the prompt dataset and reward function\n",
+    "\n",
+    "Each example in the dataset is a `(task, seed)` pair. The reward function:\n",
+    "1. Resets the env to that `(task, seed)`.\n",
+    "2. Parses the model's completion as a `OuterActionPayload`.\n",
+    "3. Submits to the env, returns `obs.reward` (post-Phase-1 range `[-1, 1]`).\n",
+    "4. On parse failure, submits `parse_failure_marker()` so the §19 -1.0 + terminate contract fires."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datasets import Dataset\n",
+    "import random\n",
+    "\n",
+    "SYSTEM_PROMPT = build_system_prompt()\n",
+    "\n",
+    "def build_user_prompt(obs: CrisisworldcortexObservation) -> str:\n",
+    "    return serialize_observation(obs)\n",
+    "\n",
+    "def make_chat_prompt(obs: CrisisworldcortexObservation) -> str:\n",
+    "    return tokenizer.apply_chat_template(\n",
+    "        [\n",
+    "            {\"role\": \"system\", \"content\": SYSTEM_PROMPT},\n",
+    "            {\"role\": \"user\", \"content\": build_user_prompt(obs)},\n",
+    "        ],\n",
+    "        tokenize=False,\n",
+    "        add_generation_prompt=True,\n",
+    "    )\n",
+    "\n",
+    "rng = random.Random(0)\n",
+    "_seed_pool = []\n",
+    "for task in TASKS:\n",
+    "    for seed in range(50):\n",
+    "        _seed_pool.append({\"task\": task, \"seed\": seed})\n",
+    "rng.shuffle(_seed_pool)\n",
+    "\n",
+    "_prompts = []\n",
+    "_meta = []\n",
+    "for entry in _seed_pool:\n",
+    "    env = make_env()\n",
+    "    obs = env.reset(task_name=entry[\"task\"], seed=entry[\"seed\"], max_ticks=EPISODE_TICKS)\n",
+    "    _prompts.append(make_chat_prompt(obs))\n",
+    "    _meta.append(entry)\n",
+    "\n",
+    "train_dataset = Dataset.from_dict({\n",
+    "    \"prompt\": _prompts,\n",
+    "    \"task\": [m[\"task\"] for m in _meta],\n",
+    "    \"seed\": [m[\"seed\"] for m in _meta],\n",
+    "})\n",
+    "print(f\"Dataset built: {len(train_dataset)} examples\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def crisisworld_reward(\n",
+    "    prompts: list[str],\n",
+    "    completions: list[str],\n",
+    "    task: list[str],\n",
+    "    seed: list[int],\n",
+    "    **_kwargs,\n",
+    ") -> list[float]:\n",
+    "    \"\"\"GRPO reward function: one env step per (prompt, completion) pair.\n",
+    "\n",
+    "    Reward source: Phase-1-fixed env outer_reward in [-1, 1].\n",
+    "    Parse failure → submits parse_failure_marker → r_policy = -1.0 + terminate.\n",
+    "    \"\"\"\n",
+    "    rewards: list[float] = []\n",
+    "    for completion, t, s in zip(completions, task, seed):\n",
+    "        env = make_env()\n",
+    "        env.reset(task_name=t, seed=int(s), max_ticks=EPISODE_TICKS)\n",
+    "        action_payload = parse_action(completion)\n",
+    "        if action_payload is None:\n",
+    "            action_payload = parse_failure_marker()\n",
+    "        try:\n",
+    "            result = env.step(CrisisworldcortexAction(action=action_payload))\n",
+    "            reward = result.observation.reward if hasattr(result, \"observation\") else result.reward\n",
+    "            rewards.append(float(reward) if reward is not None else 0.0)\n",
+    "        except Exception as exc:\n",
+    "            print(f\"[WARN] env.step failed task={t} seed={s}: {exc}\")\n",
+    "            rewards.append(-1.0)\n",
+    "    return rewards"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. GRPO training\n",
+    "\n",
+    "300 steps × group size 4 = 1200 rollouts. Each rollout is one HF Space round-trip (~1s) — total ~20–30 min on T4."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from trl import GRPOConfig, GRPOTrainer\n",
+    "\n",
+    "MAX_TRAIN_STEPS = 300\n",
+    "GROUP_SIZE = 4\n",
+    "MAX_PROMPT_LEN = 2048\n",
+    "MAX_COMPLETION_LEN = 512\n",
+    "\n",
+    "training_args = GRPOConfig(\n",
+    "    output_dir=\"/content/b1_grpo_output\",\n",
+    "    learning_rate=5e-6,\n",
+    "    per_device_train_batch_size=GROUP_SIZE,\n",
+    "    gradient_accumulation_steps=1,\n",
+    "    num_generations=GROUP_SIZE,\n",
+    "    max_prompt_length=MAX_PROMPT_LEN,\n",
+    "    max_completion_length=MAX_COMPLETION_LEN,\n",
+    "    max_steps=MAX_TRAIN_STEPS,\n",
+    "    save_steps=100,\n",
+    "    logging_steps=5,\n",
+    "    report_to=\"none\",\n",
+    "    bf16=True,\n",
+    "    optim=\"adamw_8bit\",\n",
+    "    temperature=0.8,\n",
+    "    use_vllm=True,\n",
+    "    vllm_mode=\"colocate\",\n",
+    "    seed=42,\n",
+    ")\n",
+    "\n",
+    "trainer = GRPOTrainer(\n",
+    "    model=model,\n",
+    "    processing_class=tokenizer,\n",
+    "    reward_funcs=[crisisworld_reward],\n",
+    "    args=training_args,\n",
+    "    train_dataset=train_dataset,\n",
+    ")\n",
+    "print(\"GRPOTrainer constructed; starting train()...\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "trainer.train()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. Save the trained LoRA adapter to HF Hub\n",
+    "\n",
+    "Pushes to `<your-username>/crisisworld-b1-grpo-qwen3-1p7b`. Change the repo name below if you want a different namespace."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from huggingface_hub import HfApi\n",
+    "\n",
+    "HUB_REPO = \"Angshuman28/crisisworld-b1-grpo-qwen3-1p7b\"\n",
+    "\n",
+    "model.save_pretrained(\"/content/b1_grpo_lora\")\n",
+    "tokenizer.save_pretrained(\"/content/b1_grpo_lora\")\n",
+    "\n",
+    "api = HfApi()\n",
+    "api.create_repo(HUB_REPO, exist_ok=True, repo_type=\"model\", private=False, token=HF_TOKEN)\n",
+    "api.upload_folder(\n",
+    "    folder_path=\"/content/b1_grpo_lora\",\n",
+    "    repo_id=HUB_REPO,\n",
+    "    repo_type=\"model\",\n",
+    "    token=HF_TOKEN,\n",
+    ")\n",
+    "print(f\"Saved to https://huggingface.co/{HUB_REPO}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 9. Eval: trained adapter vs base model on 3 tasks\n",
+    "\n",
+    "Runs a single full episode (12 ticks) per task, per model. Reports cumulative reward."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def _hf_chat(model_inst, tokenizer_inst, system: str, user: str, max_new_tokens: int = 256) -> str:\n",
+    "    prompt = tokenizer_inst.apply_chat_template(\n",
+    "        [{\"role\": \"system\", \"content\": system}, {\"role\": \"user\", \"content\": user}],\n",
+    "        tokenize=False,\n",
+    "        add_generation_prompt=True,\n",
+    "    )\n",
+    "    inputs = tokenizer_inst(prompt, return_tensors=\"pt\").to(model_inst.device)\n",
+    "    with torch.no_grad():\n",
+    "        out = model_inst.generate(\n",
+    "            **inputs, max_new_tokens=max_new_tokens, do_sample=False, temperature=0.0,\n",
+    "        )\n",
+    "    return tokenizer_inst.decode(out[0][inputs[\"input_ids\"].shape[1]:], skip_special_tokens=True)\n",
+    "\n",
+    "def run_one_episode(model_inst, tokenizer_inst, task: str, seed: int) -> float:\n",
+    "    env = make_env()\n",
+    "    obs = env.reset(task_name=task, seed=seed, max_ticks=EPISODE_TICKS)\n",
+    "    cumulative = 0.0\n",
+    "    for tick in range(EPISODE_TICKS):\n",
+    "        completion = _hf_chat(model_inst, tokenizer_inst, SYSTEM_PROMPT, serialize_observation(obs))\n",
+    "        action = parse_action(completion) or parse_failure_marker()\n",
+    "        result = env.step(CrisisworldcortexAction(action=action))\n",
+    "        obs = result.observation if hasattr(result, \"observation\") else result\n",
+    "        reward = obs.reward if obs.reward is not None else 0.0\n",
+    "        cumulative += reward\n",
+    "        if obs.done:\n",
+    "            break\n",
+    "    return cumulative\n",
+    "\n",
+    "FastLanguageModel.for_inference(model)\n",
+    "trained_results = {t: run_one_episode(model, tokenizer, t, seed=0) for t in TASKS}\n",
+    "print(f\"Trained model cumulative reward per task: {trained_results}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Reload base Qwen3-1.7B (no LoRA) for the comparison.\n",
+    "base_model, base_tokenizer = FastLanguageModel.from_pretrained(\n",
+    "    model_name=MODEL_NAME,\n",
+    "    max_seq_length=MAX_SEQ_LEN,\n",
+    "    load_in_4bit=True,\n",
+    "    fast_inference=False,\n",
+    ")\n",
+    "FastLanguageModel.for_inference(base_model)\n",
+    "base_results = {t: run_one_episode(base_model, base_tokenizer, t, seed=0) for t in TASKS}\n",
+    "print(f\"Base model cumulative reward per task: {base_results}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 10. Plot eval comparison\n",
+    "\n",
+    "Bar chart: trained vs base, cumulative episode reward by task."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "\n",
+    "task_names = list(TASKS)\n",
+    "trained_vals = [trained_results[t] for t in task_names]\n",
+    "base_vals = [base_results[t] for t in task_names]\n",
+    "\n",
+    "x = np.arange(len(task_names))\n",
+    "width = 0.35\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(9, 5))\n",
+    "ax.bar(x - width/2, base_vals, width, label=\"Base Qwen3-1.7B\")\n",
+    "ax.bar(x + width/2, trained_vals, width, label=\"GRPO-trained Qwen3-1.7B\")\n",
+    "ax.set_xticks(x)\n",
+    "ax.set_xticklabels(task_names)\n",
+    "ax.set_ylabel(\"Cumulative episode reward\")\n",
+    "ax.set_title(\"B1 GRPO: trained vs base\")\n",
+    "ax.legend()\n",
+    "ax.axhline(0.0, linestyle=\":\", color=\"grey\")\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10"
+  },
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "T4",
+   "provenance": []
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

notebooks/train_cortex_router_grpo.ipynb

@@ -0,0 +1,567 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7fb27b941602401d91542211134fc71a",
+   "metadata": {},
+   "source": [
+    "# Cortex Small-LLM Router GRPO training (Workstream B Phase 4 — SKELETON, post-pivot)\n",
+    "\n",
+    "**Status:** scaffold with explicit `TODO(conv-point)` markers at every Cortex-dependent integration site. **Do not run end-to-end yet** — the cells marked TODO will fail until Workstream A's Session 13 ships:\n",
+    "\n",
+    "- `cortex.metacognition.MetacognitionState` — featurization source.\n",
+    "- `cortex.routing_policy.RoutingPolicy` — trainable interface (Phase A §6).\n",
+    "- `cortex.council.Council` — deliberation orchestrator that drives rollouts.\n",
+    "- `baselines.cortex_fixed_router.B3CortexFixedRouter` — generates the deterministic-router corpus.\n",
+    "\n",
+    "**Architecture (post-pivot — replaces the MLP-head approach in commit `5489e55`):**\n",
+    "- Router is a small LLM: `unsloth/Qwen3-1.5B-Instruct` + LoRA rank 16. Roughly 3 GB on a100-large in 4-bit.\n",
+    "- Input: NL summary of `MetacognitionState` (~300 tokens).\n",
+    "- Output: structured JSON matching `cortex.schemas.RoutingAction` (~150 tokens).\n",
+    "- GRPO via the same Unsloth + TRL `GRPOTrainer` pipeline as the B1 notebook (one less code path).\n",
+    "- Reward: Phase-1-fixed `outer_reward` ∈ [-1, 1] composed with the token-budget penalty via `training.reward_shaping.shape_reward`.\n",
+    "\n",
+    "**Why a small LLM (not an MLP)?** With A100 compute available, a small LLM gives better reasoning over complex MetacognitionState, is interpretable in the pitch demo (you can read what the router thinks), and reuses the exact training infrastructure as the B1 baseline."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "acae54e37e7d407bbb7b55eff062a284",
+   "metadata": {},
+   "source": [
+    "## 1. Install dependencies\n",
+    "\n",
+    "Same Unsloth + vLLM + TRL stack as the B1 notebook; smaller GPU footprint because the trainable router is 1.5B."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9a63283cbaf04dbcab1f6479b197f3a8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "!pip install --upgrade pip\n",
+    "!pip install unsloth vllm\n",
+    "!pip install --upgrade --no-deps \"trl>=0.14\" peft accelerate bitsandbytes\n",
+    "!pip install pydantic openenv huggingface_hub matplotlib"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8dd0d8092fe74a7c96281538738b07e2",
+   "metadata": {},
+   "source": [
+    "## 2. Authenticate with Hugging Face"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "72eea5119410473aa328ad9291626812",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "try:\n",
+    "    from google.colab import userdata\n",
+    "\n",
+    "    HF_TOKEN = userdata.get(\"HF_TOKEN\")\n",
+    "    os.environ[\"HF_TOKEN\"] = HF_TOKEN\n",
+    "except Exception:\n",
+    "    from huggingface_hub import login\n",
+    "\n",
+    "    login()\n",
+    "    HF_TOKEN = os.environ.get(\"HF_TOKEN\", \"\")\n",
+    "\n",
+    "assert HF_TOKEN, \"HF_TOKEN required\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8edb47106e1a46a883d545849b8ab81b",
+   "metadata": {},
+   "source": [
+    "## 3. Clone CrisisWorldCortex (post-Cortex-Session-13 deploy)\n",
+    "\n",
+    "**TODO(conv-point):** the target Space repo at convergence point will have `cortex/*` populated through Session 13 (subagents + lenses + brains + council + metacognition + routing_policy + B3). Until then, the Cortex-dependent imports below will fail."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10185d26023b46108eb7d9f57d49d2b3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "!rm -rf /content/CrisisWorldCortex\n",
+    "!git clone https://huggingface.co/spaces/Angshuman28/CrisisWorldCortex /content/CrisisWorldCortex\n",
+    "%cd /content/CrisisWorldCortex\n",
+    "!pip install -e ."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8763a12b2bbd4a93a75aff182afb95dc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "\n",
+    "sys.path.insert(0, \"/content/CrisisWorldCortex\")\n",
+    "\n",
+    "\n",
+    "# TODO(conv-point): uncomment when Cortex Session 13 lands.\n",
+    "# from cortex.schemas import MetacognitionState, RoutingAction, RouterStep\n",
+    "# from cortex.routing_policy import RoutingPolicy\n",
+    "# from cortex.council import Council\n",
+    "# from baselines.cortex_fixed_router import B3CortexFixedRouter\n",
+    "print(\"Phase-2 training utilities OK; Cortex imports gated until Session 13\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7623eae2785240b9bd12b16a66d81610",
+   "metadata": {},
+   "source": [
+    "## 4. Load Qwen3-1.5B-Instruct (router) with LoRA\n",
+    "\n",
+    "Small enough to fit alongside frozen 7B/8B brain LLMs on a100-large (80GB). LoRA rank 16 — tighter than the B1 notebook's 32 because the action space is structured JSON (small effective vocabulary)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7cdc8c89c7104fffa095e18ddfef8986",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from unsloth import FastLanguageModel\n",
+    "\n",
+    "ROUTER_MODEL = \"unsloth/Qwen3-1.5B-Instruct-bnb-4bit\"\n",
+    "MAX_SEQ_LEN = 2048\n",
+    "\n",
+    "router_model, router_tokenizer = FastLanguageModel.from_pretrained(\n",
+    "    model_name=ROUTER_MODEL,\n",
+    "    max_seq_length=MAX_SEQ_LEN,\n",
+    "    load_in_4bit=True,\n",
+    "    fast_inference=True,\n",
+    "    max_lora_rank=16,\n",
+    "    gpu_memory_utilization=0.5,  # share GPU with frozen brain LLMs at conv-point\n",
+    ")\n",
+    "\n",
+    "router_model = FastLanguageModel.get_peft_model(\n",
+    "    router_model,\n",
+    "    r=16,\n",
+    "    target_modules=[\"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\", \"gate_proj\", \"up_proj\", \"down_proj\"],\n",
+    "    lora_alpha=32,\n",
+    "    use_gradient_checkpointing=\"unsloth\",\n",
+    "    random_state=42,\n",
+    ")\n",
+    "print(\"Router (Qwen3-1.5B + LoRA r=16) loaded\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b118ea5561624da68c537baed56e602f",
+   "metadata": {},
+   "source": [
+    "## 5. Featurization: MetacognitionState → NL prompt + RoutingAction schema\n",
+    "\n",
+    "Replaces the MLP version's `(24,) np.float32` featurization. The router consumes a natural-language summary; output is structured JSON validated against `cortex.schemas.RoutingAction`.\n",
+    "\n",
+    "**TODO(conv-point):** the schema below references `cortex.schemas.MetacognitionState` (Session 13).\n",
+    "Per Phase A `cortex/schemas.py` and `docs/CORTEX_ARCHITECTURE.md` §6, the NL summary covers the 11 documented fields + the phase string."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "938c804e27f84196a10c8828c723f798",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ROUTER_SYSTEM_PROMPT = \"\"\"You are the Cortex router for CrisisWorldCortex. You receive a metacognition\n",
+    "state summary describing the current deliberation phase and emit ONE routing action as JSON.\n",
+    "\n",
+    "Allowed action kinds (per cortex/CLAUDE.md):\n",
+    "- call_subagent: invoke a brain's subagent. Required: brain (epidemiology|logistics|governance),\n",
+    "  subagent (world_modeler|planner|critic).\n",
+    "- request_challenge: cross-brain critique. Required: challenger_brain, target_brain.\n",
+    "- switch_phase: advance the phase machine. Required: new_phase (divergence|challenge|narrowing|convergence).\n",
+    "- preserve_dissent: tag a minority recommendation. Required: tag (string, max 80 chars).\n",
+    "- emit_outer_action: close the tick with a final action.\n",
+    "- stop_and_no_op: close the tick with a no-op.\n",
+    "\n",
+    "Hard caps (binding): ≤2 deliberation rounds/tick, ≤1 cross-brain challenge/tick,\n",
+    "≤1 critic call per brain/tick, ≤6000 token budget per tick.\n",
+    "\n",
+    "Output exactly one JSON object — no markdown fences, no prose around it.\"\"\"\n",
+    "\n",
+    "PHASE_NAMES = (\"divergence\", \"challenge\", \"narrowing\", \"convergence\")\n",
+    "\n",
+    "\n",
+    "def metacog_state_to_prompt(state) -> str:\n",
+    "    \"\"\"Convert MetacognitionState → NL summary for the router.\n",
+    "\n",
+    "    TODO(conv-point): change ``state`` typing to MetacognitionState\n",
+    "    (cortex.schemas) once Session 13 lands. Duck-typed for now.\n",
+    "    \"\"\"\n",
+    "    return (\n",
+    "        f\"Tick {getattr(state, 'tick', 0)}, round {getattr(state, 'round', 1)}, \"\n",
+    "        f\"phase={getattr(state, 'phase', 'divergence')}.\\n\"\n",
+    "        f\"Inter-brain agreement: {getattr(state, 'inter_brain_agreement', 0.0):.2f}.\\n\"\n",
+    "        f\"Average confidence: {getattr(state, 'average_confidence', 0.0):.2f}.\\n\"\n",
+    "        f\"Average evidence support: {getattr(state, 'average_evidence_support', 0.0):.2f}.\\n\"\n",
+    "        f\"Novelty yield (last round): {getattr(state, 'novelty_yield_last_round', 0.0):.2f}.\\n\"\n",
+    "        f\"Collapse suspicion: {getattr(state, 'collapse_suspicion', 0.0):.2f}.\\n\"\n",
+    "        f\"Budget remaining: {getattr(state, 'budget_remaining_frac', 1.0):.0%}.\\n\"\n",
+    "        f\"Urgency: {getattr(state, 'urgency', 0.0):.2f}.\\n\"\n",
+    "        f\"Preserved dissent count: {getattr(state, 'preserved_dissent_count', 0)}.\\n\"\n",
+    "        f\"Cross-brain challenge used this tick: \"\n",
+    "        f\"{bool(getattr(state, 'challenge_used_this_tick', 0))}.\\n\\n\"\n",
+    "        f\"Choose the next routing action.\"\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "def make_router_chat_prompt(state) -> str:\n",
+    "    return router_tokenizer.apply_chat_template(\n",
+    "        [\n",
+    "            {\"role\": \"system\", \"content\": ROUTER_SYSTEM_PROMPT},\n",
+    "            {\"role\": \"user\", \"content\": metacog_state_to_prompt(state)},\n",
+    "        ],\n",
+    "        tokenize=False,\n",
+    "        add_generation_prompt=True,\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "504fb2a444614c0babb325280ed9130a",
+   "metadata": {},
+   "source": [
+    "## 6. Connect to the deployed CrisisWorld env\n",
+    "\n",
+    "Same env client pattern as the B1 notebook."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "59bbdb311c014d738909a11f9e486628",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from CrisisWorldCortex.client import CrisisworldcortexEnv\n",
+    "\n",
+    "ENV_URL = \"https://angshuman28-crisisworldcortex.hf.space\"\n",
+    "TASKS = (\"outbreak_easy\", \"outbreak_medium\", \"outbreak_hard\")\n",
+    "EPISODE_TICKS = 12\n",
+    "\n",
+    "\n",
+    "def make_env() -> CrisisworldcortexEnv:\n",
+    "    return CrisisworldcortexEnv(base_url=ENV_URL)\n",
+    "\n",
+    "\n",
+    "_test_env = make_env()\n",
+    "_obs = _test_env.reset(task_name=\"outbreak_easy\", seed=0, max_ticks=EPISODE_TICKS)\n",
+    "print(f\"Env OK. Initial tick={_obs.tick}, regions={[r.region for r in _obs.regions]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b43b363d81ae4b689946ece5c682cd59",
+   "metadata": {},
+   "source": [
+    "## 7. Build training-data prompt set from B3 deterministic-router trajectories\n",
+    "\n",
+    "**TODO(conv-point):** B3CortexFixedRouter runs ~50 episodes. Each `RouterStep`'s `MetacognitionState` becomes a router-prompt; the GRPO completion is the router's emitted JSON.\n",
+    "\n",
+    "Replaces the MLP version's action-vocab + B3-trajectory-to-tuple pipeline. Same RolloutBuffer, different content shape."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8a65eabff63a45729fe45fb5ade58bdc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datasets import Dataset\n",
+    "\n",
+    "TRAIN_EPISODES = 50\n",
+    "\n",
+    "\n",
+    "def collect_b3_router_prompts(num_episodes: int = TRAIN_EPISODES) -> Dataset:\n",
+    "    \"\"\"Run B3 and convert each RouterStep into a (prompt, task, seed) row.\n",
+    "\n",
+    "    TODO(conv-point): uncomment the body when B3CortexFixedRouter ships.\n",
+    "    \"\"\"\n",
+    "    rows = {\"prompt\": [], \"task\": [], \"seed\": []}\n",
+    "    # TODO(conv-point):\n",
+    "    # b3 = B3CortexFixedRouter(env=make_env())\n",
+    "    # for ep in range(num_episodes):\n",
+    "    #     trajectory = b3.run_episode(task=\"outbreak_easy\", seed=ep)\n",
+    "    #     for router_step in trajectory.router_steps:\n",
+    "    #         rows[\"prompt\"].append(make_router_chat_prompt(router_step.metacognition_state))\n",
+    "    #         rows[\"task\"].append(\"outbreak_easy\")\n",
+    "    #         rows[\"seed\"].append(ep)\n",
+    "    return (\n",
+    "        Dataset.from_dict(rows)\n",
+    "        if rows[\"prompt\"]\n",
+    "        else Dataset.from_dict(\n",
+    "            {\"prompt\": [\"placeholder until conv-point\"], \"task\": [\"outbreak_easy\"], \"seed\": [0]}\n",
+    "        )\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "train_dataset = collect_b3_router_prompts()\n",
+    "print(f\"Dataset: {len(train_dataset)} rows (will be ~{TRAIN_EPISODES * 8} at conv-point)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c3933fab20d04ec698c2621248eb3be0",
+   "metadata": {},
+   "source": [
+    "## 8. Reward function: full-episode rollout per (prompt, completion)\n",
+    "\n",
+    "Uses Phase-1 `outer_reward` summed across the episode, with Phase-2 `shape_reward` token-budget penalty.\n",
+    "\n",
+    "**TODO(conv-point):** the rollout loop calls `Council.step` with the trainable router policy. Until Session 13 lands, the loop is stubbed and returns 0.0 for every (prompt, completion)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4dd4641cc4064e0191573fe9c69df29b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def cortex_router_reward(prompts, completions, task, seed, **_kwargs):\n",
+    "    \"\"\"Reward = sum(per-tick obs.reward) over a full episode driven by the\n",
+    "    trainable router's emitted RoutingAction JSON.\n",
+    "\n",
+    "    Each (prompt, completion) pair represents ONE router decision; the\n",
+    "    full episode reward is shared across all router decisions in that\n",
+    "    episode (GRPO group-relative advantage handles credit assignment).\n",
+    "\n",
+    "    TODO(conv-point): replace the stub body with the real Council-driven\n",
+    "    rollout once Session 13 ships.\n",
+    "    \"\"\"\n",
+    "    rewards = []\n",
+    "    for completion, t, s in zip(completions, task, seed):\n",
+    "        # TODO(conv-point):\n",
+    "        # try:\n",
+    "        #     routing_action = RoutingAction.model_validate_json(completion)\n",
+    "        # except ValidationError:\n",
+    "        #     rewards.append(-1.0)  # invalid JSON → terminal-equivalent penalty\n",
+    "        #     continue\n",
+    "        # council = Council(routing_policy=trainable_router_from(routing_action),\n",
+    "        #                   env=make_env(), brains=cortex_brains)\n",
+    "        # episode_return = council.run_episode(task=t, seed=int(s)).total_reward\n",
+    "        # rewards.append(episode_return)\n",
+    "        rewards.append(0.0)  # stub\n",
+    "    return rewards"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8309879909854d7188b41380fd92a7c3",
+   "metadata": {},
+   "source": [
+    "## 9. GRPO training\n",
+    "\n",
+    "Same TRL `GRPOTrainer` shape as the B1 notebook. ~300 steps × group size 4 = ~1200 router decisions × full-episode rollouts. Wall-clock ~1.5 hours on a100-large at convergence point (dominated by brain-LLM rollouts, not router fine-tuning)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3ed186c9a28b402fb0bc4494df01f08d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from trl import GRPOConfig, GRPOTrainer\n",
+    "\n",
+    "MAX_TRAIN_STEPS = 300\n",
+    "GROUP_SIZE = 4\n",
+    "MAX_PROMPT_LEN = 512\n",
+    "MAX_COMPLETION_LEN = 256  # router output is structured JSON (M-FR-11)\n",
+    "\n",
+    "training_args = GRPOConfig(\n",
+    "    output_dir=\"/content/cortex_router_grpo_output\",\n",
+    "    learning_rate=5e-6,\n",
+    "    per_device_train_batch_size=GROUP_SIZE,\n",
+    "    gradient_accumulation_steps=1,\n",
+    "    num_generations=GROUP_SIZE,\n",
+    "    max_prompt_length=MAX_PROMPT_LEN,\n",
+    "    max_completion_length=MAX_COMPLETION_LEN,\n",
+    "    max_steps=MAX_TRAIN_STEPS,\n",
+    "    save_steps=100,\n",
+    "    logging_steps=5,\n",
+    "    report_to=\"none\",\n",
+    "    bf16=True,\n",
+    "    optim=\"adamw_8bit\",\n",
+    "    temperature=0.8,\n",
+    "    use_vllm=True,\n",
+    "    vllm_mode=\"colocate\",\n",
+    "    seed=42,\n",
+    ")\n",
+    "\n",
+    "trainer = GRPOTrainer(\n",
+    "    model=router_model,\n",
+    "    processing_class=router_tokenizer,\n",
+    "    reward_funcs=[cortex_router_reward],\n",
+    "    args=training_args,\n",
+    "    train_dataset=train_dataset,\n",
+    ")\n",
+    "print(\"Router GRPOTrainer constructed.\")\n",
+    "print(\"# TODO(conv-point): uncomment trainer.train() once Cortex Session 13 lands.\")\n",
+    "# trainer.train()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cb1e1581032b452c9409d6c6813c49d1",
+   "metadata": {},
+   "source": [
+    "## 10. Save the trained router LoRA to HF Hub"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "379cbbc1e968416e875cc15c1202d7eb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from huggingface_hub import HfApi\n",
+    "\n",
+    "HUB_REPO = \"Angshuman28/crisisworld-cortex-router-llm\"\n",
+    "\n",
+    "router_model.save_pretrained(\"/content/cortex_router_lora\")\n",
+    "router_tokenizer.save_pretrained(\"/content/cortex_router_lora\")\n",
+    "\n",
+    "api = HfApi()\n",
+    "api.create_repo(HUB_REPO, exist_ok=True, repo_type=\"model\", private=False, token=HF_TOKEN)\n",
+    "api.upload_folder(\n",
+    "    folder_path=\"/content/cortex_router_lora\",\n",
+    "    repo_id=HUB_REPO,\n",
+    "    repo_type=\"model\",\n",
+    "    token=HF_TOKEN,\n",
+    ")\n",
+    "print(f\"Saved to https://huggingface.co/{HUB_REPO}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "277c27b1587741f2af2001be3712ef0d",
+   "metadata": {},
+   "source": [
+    "## 11. Eval: B6 (trained LLM router) vs B3 (deterministic) on 3 tasks\n",
+    "\n",
+    "**TODO(conv-point):** the comparison loop below requires both B3CortexFixedRouter (deterministic) and a way to swap the trainable router into Council.routing_policy. The eval is the headline result for the convergence point — its sign decides whether B6 ships or B3 ships per the Phase 7 hard-exit gate.\n",
+    "\n",
+    "Decision rule (per spec): if reward over training steps is INCREASING, ship B6. Else ship B3."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "db7b79bc585a40fcaf58bf750017e135",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TODO(conv-point):\n",
+    "# from cortex.routing_policy import DeterministicRouter, TrainableRouter\n",
+    "# from cortex.council import Council\n",
+    "# from baselines.cortex_fixed_router import B3CortexFixedRouter\n",
+    "#\n",
+    "# def run_b6_episode(task, seed):\n",
+    "#     trainable = TrainableRouter(\n",
+    "#         model=router_model,\n",
+    "#         tokenizer=router_tokenizer,\n",
+    "#         system_prompt=ROUTER_SYSTEM_PROMPT,\n",
+    "#         featurize=metacog_state_to_prompt,\n",
+    "#     )\n",
+    "#     council = Council(routing_policy=trainable, env=make_env(), brains=cortex_brains)\n",
+    "#     return council.run_episode(task=task, seed=seed).total_reward\n",
+    "#\n",
+    "# def run_b3_episode(task, seed):\n",
+    "#     b3 = B3CortexFixedRouter(env=make_env())\n",
+    "#     return b3.run_episode(task=task, seed=seed).total_reward\n",
+    "#\n",
+    "# b6_results = {t: run_b6_episode(t, 0) for t in TASKS}\n",
+    "# b3_results = {t: run_b3_episode(t, 0) for t in TASKS}\n",
+    "# print(f\"B6 (trained LLM router): {b6_results}\")\n",
+    "# print(f\"B3 (deterministic): {b3_results}\")\n",
+    "\n",
+    "print(\"Eval cell skeleton — uncomment when Cortex Session 13 ships\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "916684f9a58a4a2aa5f864670399430d",
+   "metadata": {},
+   "source": [
+    "## 12. Plot training reward curve\n",
+    "\n",
+    "Phase 7 hard-exit gate watches this curve. If reward is increasing across training steps → ship B6. Else → ship B3."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1671c31a24314836a5b85d7ef7fbf015",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "log_path = \"/content/cortex_router_grpo_output/trainer_state.json\"\n",
+    "if os.path.exists(log_path):\n",
+    "    import json as _json\n",
+    "\n",
+    "    with open(log_path) as fh:\n",
+    "        state = _json.load(fh)\n",
+    "    history = state.get(\"log_history\", [])\n",
+    "    rewards = [entry[\"reward\"] for entry in history if \"reward\" in entry]\n",
+    "    if rewards:\n",
+    "        fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "        ax.plot(rewards)\n",
+    "        ax.set_xlabel(\"GRPO step\")\n",
+    "        ax.set_ylabel(\"Mean reward\")\n",
+    "        ax.set_title(\"Cortex small-LLM router — training reward\")\n",
+    "        plt.tight_layout()\n",
+    "        plt.show()\n",
+    "    else:\n",
+    "        print(\"No reward entries yet — uncomment trainer.train() at conv-point\")\n",
+    "else:\n",
+    "    print(\"No trainer state yet — uncomment trainer.train() at conv-point\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "gpuType": "A100",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

openenv.yaml

@@ -1,7 +1,7 @@
-spec_version: 1
-name: CrisisWorldCortex
-type: space
-runtime: fastapi
-app: server.app:app
-port: 8000
-
+spec_version: 1
+name: CrisisWorldCortex
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

openenv_CrisisWorldCortex.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: openenv-CrisisWorldCortex
+Version: 0.1.0
+Summary: Crisisworldcortex environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]==0.2.3
+Requires-Dist: openai<3.0,>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"

openenv_CrisisWorldCortex.egg-info/SOURCES.txt

@@ -0,0 +1,48 @@
+README.md
+__init__.py
+client.py
+inference.py
+models.py
+pyproject.toml
+./__init__.py
+./client.py
+./inference.py
+./models.py
+openenv_CrisisWorldCortex.egg-info/PKG-INFO
+openenv_CrisisWorldCortex.egg-info/SOURCES.txt
+openenv_CrisisWorldCortex.egg-info/dependency_links.txt
+openenv_CrisisWorldCortex.egg-info/entry_points.txt
+openenv_CrisisWorldCortex.egg-info/requires.txt
+openenv_CrisisWorldCortex.egg-info/top_level.txt
+server/CrisisWorldCortex_environment.py
+server/__init__.py
+server/app.py
+tests/test_actions_round_trip.py
+tests/test_baseline_b1.py
+tests/test_baseline_b2.py
+tests/test_cortex_brain_executive.py
+tests/test_cortex_brain_smoke.py
+tests/test_cortex_lenses.py
+tests/test_cortex_perception.py
+tests/test_cortex_subagents.py
+tests/test_env_reset_kwargs.py
+tests/test_env_step_reward_wiring.py
+tests/test_import_graph.py
+tests/test_legal_constraint_enforcement.py
+tests/test_llm_client.py
+tests/test_observation_no_latent_leak.py
+tests/test_outer_reward_in_range.py
+tests/test_outer_reward_non_constancy.py
+tests/test_outer_reward_terminal_bonus.py
+tests/test_package_exports.py
+tests/test_reward_signal_quality.py
+tests/test_schemas_roundtrip.py
+tests/test_simulator_determinism.py
+tests/test_simulator_random_episode.py
+tests/test_simulator_task_configs.py
+tests/test_smoke_env.py
+tests/test_stdout_format.py
+tests/test_synthetic_rejection_payload.py
+tests/test_training_eval_metrics.py
+tests/test_training_reward_shaping.py
+tests/test_training_rollout_buffer.py

openenv_CrisisWorldCortex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_CrisisWorldCortex.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = CrisisWorldCortex.server.app:main

openenv_CrisisWorldCortex.egg-info/requires.txt

@@ -0,0 +1,9 @@
+openenv-core[core]==0.2.3
+openai<3.0,>=2.0
+python-dotenv>=1.0.0
+
+[dev]
+pre-commit>=4.0.0
+pytest>=8.0.0
+pytest-cov>=4.0.0
+ruff>=0.8.0

openenv_CrisisWorldCortex.egg-info/top_level.txt

@@ -0,0 +1 @@
+CrisisWorldCortex

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     # future uv sync from silently pulling 3.x. Bump explicitly when 3.0
     # ships and we've verified compatibility.
     "openai>=2.0,<3.0",
+    "python-dotenv>=1.0.0"
 ]
 
 [project.optional-dependencies]

server/CLAUDE.md

@@ -15,33 +15,24 @@ Cortex code (brains, subagents, router, metacognition), LLM clients, training lo
 
 ## Import rule (binding)
 
-**Inside `server/`, use package-relative imports for server internals**:
-`from .simulator import ...` from one-level modules and
-`from ..simulator import ...` from nested modules. This works when the
-server is loaded as either `CrisisWorldCortex.server.*` (`uv run server`)
-or top-level `server.*` (Docker / `uvicorn server.app:app`). Never use
-`from CrisisWorldCortex.server...` for server-internal imports.
+**Inside `server/`, use `from server.simulator import …`, never `from CrisisWorldCortex.server.simulator import …`.** Same rule for `server.graders`.
 
-For `models`, use the canonical package path in every server module that needs it:
+For `models`, use the dual-import fallback in every new server module that needs it:
 
 ```python
-from CrisisWorldCortex.models import CrisisworldcortexAction, CrisisworldcortexObservation
+try:
+    from ..models import CrisisworldcortexAction, CrisisworldcortexObservation
+except (ImportError, ModuleNotFoundError):
+    from models import CrisisworldcortexAction, CrisisworldcortexObservation
 ```
 
-The server runs under multiple import contexts (`uv run server`,
-`uvicorn server.app:app`, Docker `cd /app/env && uvicorn server.app:app`).
-Canonical wire imports keep Pydantic model identity stable across those modes.
+The server runs under ≥ 3 import contexts (`python -m server.app`, `uvicorn server.app:app`, Docker `cd /app/env && uvicorn server.app:app`); the fallback is load-bearing.
 
-**Wire-type imports from deep modules (binding)**: two-or-more-levels-deep
-files (`server/simulator/*`, `server/graders/*`) must still use
-`from CrisisWorldCortex.models import …`; `..models` from those depths
-resolves to a non-existent `CrisisWorldCortex.server.models`, and a bare
-fallback loads a second `models` module.
+**Wire-type imports from deep modules (binding)**: the dual-import fallback above only works for files **one level** inside `server/` (`server/CrisisWorldCortex_environment.py`, `server/app.py`). Two-or-more-levels-deep files (`server/simulator/*`, `server/graders/*`) **must** use `from CrisisWorldCortex.models import …` directly — `..models` from those depths resolves to a non-existent `CrisisWorldCortex.server.models`, the fallback fires, and bare `models` loads as a separate `sys.modules` entry, breaking Pydantic discriminator validation against types imported via the canonical path. Session 5a's `server/simulator/seir_model.py` and `server/simulator/tasks.py` document this with inline comments.
 
 ## Allowed imports
 
-`CrisisWorldCortex.models`, package-relative `server/simulator/*` and
-`server/graders/*`, `openenv.core.*`, stdlib, FastAPI, Pydantic, numpy.
+`models` (via dual-import fallback), `openenv.core.*`, `server/simulator/*`, `server/graders/*`, stdlib, FastAPI, Pydantic, numpy.
 
 ## Forbidden imports
 

server/CrisisWorldCortex_environment.py

@@ -121,10 +121,26 @@ class CrisisworldcortexEnvironment(Environment):
             )
         self._state.step_count += 1
         self._world_state = apply_tick(self._world_state, action.action)
+        # Parse-failure terminal contract (design §19, Phase-1 restoration):
+        # the synthetic parse_failure_marker (PublicCommunication with
+        # honesty=0.0, magic-string discriminator per Phase-A M3-B) ends
+        # the episode as state.terminal = "failure". apply_tick may have
+        # set terminal to "none"/"success"/"timeout" via the SEIR rules;
+        # we override here because parse-failure is a harness-level fault,
+        # not a simulator-level event.
+        payload = action.action
+        if (
+            payload.kind == "public_communication"
+            and getattr(payload, "honesty", None) == 0.0
+            and self._world_state.recent_action_log
+            and not self._world_state.recent_action_log[-1].accepted
+        ):
+            self._world_state.terminal = "failure"
         obs = make_observation(self._world_state)
-        # Per design §15: r_outer is the only env-side reward signal, in [0,1].
-        # Terminal bonus (+/-0.20) is composed downstream by the trainer per
-        # design §14.3 — never bundled into obs.reward.
+        # Per design §15: r_outer is the only env-side reward signal, in
+        # [-1.0, 1.0] post-Phase-1 (was [0, 1]). Terminal bonus (+/-0.20)
+        # is composed downstream by the trainer per design §14.3 — never
+        # bundled into obs.reward.
         obs.reward = outer_reward(self._world_state, action.action)
         return obs
 

server/__init__.py

@@ -1,11 +1,11 @@
-# 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.
-
-"""Crisisworldcortex environment server components."""
-
-from .CrisisWorldCortex_environment import CrisisworldcortexEnvironment
-
-__all__ = ["CrisisworldcortexEnvironment"]
+# 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.
+
+"""Crisisworldcortex environment server components."""
+
+from .CrisisWorldCortex_environment import CrisisworldcortexEnvironment
+
+__all__ = ["CrisisworldcortexEnvironment"]

server/app.py

@@ -29,8 +29,8 @@ Usage:
 """
 
 try:
-    # from openenv.core.env_server.http_server import create_app
-    from openenv.core.env_server import create_web_interface_app as create_app
+    from openenv.core.env_server.http_server import create_app
+    # from openenv.core.env_server import create_web_interface_app as 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'"

server/graders/outer_reward.py

@@ -5,16 +5,29 @@
 # LICENSE file in the root directory of this source tree.
 
 """
-Outer reward grader for CrisisWorld (design §15).
+Outer reward grader for CrisisWorld (design §15 + §19, post-Phase-1 fix).
 
 Public API (re-exported via ``server/graders/__init__.py``):
 - ``outer_reward(state, action) -> float`` — 6-component weighted score in
-  ``[0.0, 1.0]``, computed on post-``apply_tick`` state. The only env-side
-  reward signal per ``server/CLAUDE.md`` (binding contract).
+  ``[-1.0, 1.0]`` (Workstream-B Phase-1 range relaxation; was
+  ``[0.0, 1.0]``). Negative values come from ``r_policy = -0.5`` on rejected
+  actions and ``r_policy = -1.0`` on parse-failure markers (per design §19).
+  Computed on post-``apply_tick`` state. Still the only env-side reward
+  signal per ``server/CLAUDE.md``.
 - ``terminal_bonus(state) -> float`` — episode-end ±0.20 / 0.0 bonus,
   composed by trainer in ``training/reward_shaping.py`` per design §14.3
-  (``episode_return = Σ_t r_outer + terminal_bonus``). Kept separate so the
-  per-tick ``r_outer`` stays inside ``[0.0, 1.0]``.
+  (``episode_return = Σ_t r_outer + terminal_bonus``). Kept separate from
+  the per-tick scalar.
+
+Phase-1 changes (Workstream B):
+  - Steeper sensitivity on ``r_infect`` (``× 20``) and ``r_hosp`` (``× 10``)
+    so the gentle outbreak_easy task still produces gradient.
+  - Continuous ``r_casc`` (``1 - max(I)/0.30`` clamped) replaces binary.
+  - ``r_policy`` ∈ {-1.0 (parse-failure), -0.5 (rejected), 0.0 (accepted
+    no_op), +1.0 (accepted real action)} restoring §19 magnitudes.
+  - Weight redistribution: W_POLICY 0.12 → 0.35 (signal-driver); W_TIME
+    0.18 → 0.05 (action-independent noise); other components rebalanced.
+  - Final ``[0,1]`` clamp dropped (Phase-A M2-A).
 
 Wire-protocol imports use the absolute path ``CrisisWorldCortex.models``
 because this file lives two levels deep inside ``server/`` — see
@@ -38,25 +51,42 @@ from ..simulator import (
 )
 
 # ============================================================================
-# Component weights (design §15; sum to 1.00)
+# Component weights (design §15 + Phase-1 redistribution; sum to 1.00)
 # ============================================================================
 
-W_INFECT = 0.35
-W_TIME = 0.18
-W_HOSP = 0.17
-W_CASC = 0.15
-W_POLICY = 0.12
-W_FAIR = 0.03
+W_INFECT = 0.15  # was 0.35; iter-1 reduced because outbreak_easy keeps mean(I) tiny
+W_TIME = 0.05  # was 0.18; action-independent, no signal value
+W_HOSP = 0.10  # was 0.17; iter-1 reduction (gentle env keeps hosp_load low)
+W_CASC = 0.10  # was 0.15; iter-1 reduction
+W_POLICY = 0.55  # was 0.12; iter-1 dominant signal driver — accepted-real vs no_op vs rejected
+W_FAIR = 0.05  # was 0.03; tiny boost
+
+# Steepness coefficients (Phase-A M6, ONE-iteration tentative).
+# r_infect ≈ 0 when mean(I) >= 0.05; near 1 when mean(I) <= 0.0 → strong gradient.
+# r_hosp similarly sensitive to mean hospital_load.
+R_INFECT_STEEPNESS = 20.0
+R_HOSP_STEEPNESS = 10.0
+
+# r_policy values per design §19 (Phase-1 restoration).
+R_POLICY_PARSE_FAILURE = -1.0  # synthetic parse-failure marker
+R_POLICY_REJECTED = -0.5  # well-formed-illegal (V2 / legal-violation)
+R_POLICY_NOOP_ACCEPTED = 0.0  # accepted no-op (legal but inactive)
+R_POLICY_REAL_ACCEPTED = 1.0  # accepted real intervention
 
 # Terminal-bonus magnitudes (design §14.3 / §15).
 TERMINAL_BONUS_SUCCESS = 0.20
 TERMINAL_BONUS_FAILURE = -0.20
 
-# r_casc threshold: any region above this contributes a "hot" count;
-# matches the catastrophic-region threshold from design §6.4 so the
-# cascade-control signal aligns with the failure terminal.
+# r_casc threshold: at max(I) >= this, r_casc = 0 (catastrophe imminent).
+# Matches design §6.4's catastrophic-infection threshold so cascade
+# signal aligns with the failure terminal.
 R_CASC_HOT_THRESHOLD = CATASTROPHIC_INFECTION_THRESHOLD
 
+# Magic-string discriminator for parse-failure marker (Phase-A M3-B):
+# baselines.flat_agent.parse_failure_marker emits PublicCommunication with
+# honesty=0.0; intentional V2 attempts use honesty > 0.0.
+PARSE_FAILURE_HONESTY_SENTINEL = 0.0
+
 
 def _clamp01(x: float) -> float:
     if x < 0.0:
@@ -76,34 +106,56 @@ def _hospital_load(region_I: float) -> float:
     return _clamp01(region_I * HOSPITALIZATION_FRACTION_OF_I / HOSPITAL_CAPACITY_FRACTION)
 
 
+def _r_policy_value(action: OuterActionPayload, accepted: bool) -> float:
+    """Compute ``r_policy`` per design §19 four-state contract.
+
+    Returns one of {-1.0, -0.5, 0.0, +1.0} based on (action.kind, accepted).
+    Parse-failure detection uses the ``honesty == 0.0`` sentinel on a
+    rejected ``PublicCommunication`` payload (Phase-A M3-B magic string).
+    """
+    if not accepted:
+        # Rejected branch. Distinguish parse-failure marker from intentional
+        # V2-PublicCommunication / legal-violation rejection.
+        if (
+            action.kind == "public_communication"
+            and getattr(action, "honesty", None) == PARSE_FAILURE_HONESTY_SENTINEL
+        ):
+            return R_POLICY_PARSE_FAILURE
+        return R_POLICY_REJECTED
+    # Accepted branch.
+    if action.kind == "no_op":
+        return R_POLICY_NOOP_ACCEPTED
+    return R_POLICY_REAL_ACCEPTED
+
+
 def outer_reward(state: WorldState, action: OuterActionPayload) -> float:
-    """Compute per-tick outer reward in ``[0.0, 1.0]``.
+    """Compute per-tick outer reward in ``[-1.0, 1.0]`` (post-Phase-1 range).
 
     Read post-``apply_tick`` state: ``state.regions[*].I`` is the
     just-stepped ground-truth infection fraction. ``recent_action_log[-1]``
     holds the just-dispatched action's acceptance flag.
 
-    Six components (design §15):
-        r_infect  = 1 - mean(I)                          # weight 0.35
-        r_time    = 1 - tick / max_ticks                 # weight 0.18
-        r_hosp    = 1 - mean(hospital_load)              # weight 0.17
-        r_casc    = 1 if no region exceeds 0.30 else 0   # weight 0.15
-        r_policy  = 1 if last action accepted else 0     # weight 0.12
-        r_fair    = 1 - pstdev(I)                        # weight 0.03
+    Six components (design §15 + Phase-1 fix):
+        r_infect  = max(0, 1 - 20 × mean(I))                  # weight 0.25
+        r_time    = 1 - tick / max_ticks                       # weight 0.05
+        r_hosp    = max(0, 1 - 10 × mean(hospital_load))       # weight 0.15
+        r_casc    = max(0, 1 - max(I) / 0.30)                  # weight 0.15
+        r_policy  = {-1.0, -0.5, 0.0, +1.0} per §19            # weight 0.35
+        r_fair    = 1 - pstdev(I)                              # weight 0.05
 
     The ``action`` argument is the action just dispatched. We read its
     acceptance flag from ``state.recent_action_log[-1]`` rather than
     re-dispatching — the simulator already recorded it, and re-dispatch
-    would mutate state. ``action`` is kept in the signature for design
-    parity with ``training_reward(trajectory)`` and to support future
-    action-shape-dependent shaping without a signature break.
+    would mutate state.
     """
     if not state.regions:
         return 0.0
 
     I_values = [r.I for r in state.regions]
+    mean_I = sum(I_values) / len(I_values)
 
-    r_infect = _clamp01(1.0 - sum(I_values) / len(I_values))
+    # r_infect: steepened so gentle outbreak_easy still produces gradient.
+    r_infect = _clamp01(1.0 - R_INFECT_STEEPNESS * mean_I)
 
     if state.max_ticks > 0:
         r_time = _clamp01(1.0 - state.tick / state.max_ticks)
@@ -111,16 +163,22 @@ def outer_reward(state: WorldState, action: OuterActionPayload) -> float:
         r_time = 0.0
 
     hosp_loads = [_hospital_load(I) for I in I_values]
-    r_hosp = _clamp01(1.0 - sum(hosp_loads) / len(hosp_loads))
+    mean_hosp = sum(hosp_loads) / len(hosp_loads)
+    r_hosp = _clamp01(1.0 - R_HOSP_STEEPNESS * mean_hosp)
 
-    hot_regions = sum(1 for I in I_values if I > R_CASC_HOT_THRESHOLD)
-    r_casc = 1.0 if hot_regions == 0 else 0.0
+    # r_casc: continuous ramp (1.0 at max(I)=0; 0.0 at max(I) >= threshold).
+    max_I = max(I_values)
+    if R_CASC_HOT_THRESHOLD > 0:
+        r_casc = _clamp01(1.0 - max_I / R_CASC_HOT_THRESHOLD)
+    else:
+        r_casc = 0.0
 
+    # r_policy: design §19 four-state contract.
     if state.recent_action_log:
         last_entry = state.recent_action_log[-1]
-        r_policy = 1.0 if last_entry.accepted else 0.0
+        r_policy = _r_policy_value(last_entry.action, last_entry.accepted)
     else:
-        r_policy = 1.0  # No action dispatched yet → no penalty.
+        r_policy = R_POLICY_REAL_ACCEPTED  # No action dispatched yet → no penalty.
 
     if len(I_values) >= 2:
         r_fair = _clamp01(1.0 - statistics.pstdev(I_values))
@@ -135,8 +193,12 @@ def outer_reward(state: WorldState, action: OuterActionPayload) -> float:
         + W_POLICY * r_policy
         + W_FAIR * r_fair
     )
-    # Final clamp guards against floating-point drift past 1.0.
-    return _clamp01(score)
+    # Final clamp to [-1.0, 1.0] (no longer [0, 1] — M2-A drops the floor).
+    if score < -1.0:
+        return -1.0
+    if score > 1.0:
+        return 1.0
+    return score
 
 
 def terminal_bonus(state: WorldState) -> float:

server/requirements.txt

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

tests/CLAUDE.md

@@ -1,48 +1,48 @@
-# tests/CLAUDE.md
-
-Test surface per subsystem. Smoke bar first, boundary tests next, coverage last.
-
-## Belongs here
-
-- `conftest.py` — repo root on `sys.path` for bare-name imports.
-- One test module per subsystem boundary (table below).
-
-## Does not belong here
-
-Helpers that mutate real graders, simulator state, or disk. Fixtures that hit the live HF Space — mock or `pytest.skip`.
-
-## Run commands
-
-```bash
-uv run python -m pytest tests/ -v                                                               # all
-uv run python -m pytest tests/test_smoke_env.py::test_reset_returns_valid_observation -v        # one
-uv run python -m pytest --cov tests/                                                            # coverage
-```
-
-## Required tests — each maps to exactly one subsystem contract
-
-| File | Scope | Asserts |
-|---|---|---|
-| `test_package_exports.py` | wire package | Root `__init__` re-exports `CrisisworldcortexAction/Observation/Env`. |
-| `test_smoke_env.py` | `server/` env | `reset()` / `step()` return a valid `CrisisworldcortexObservation`. |
-| `test_actions_round_trip.py` | `server/` env | 6 MVP outer actions round-trip; `public_communication` is rejected at runtime. |
-| `test_reward_shape.py` | `server/graders/` | Every grader returns values in `[0.0, 1.0]`. |
-| `test_reward_non_constancy.py` | `server/graders/` | Grader output varies across ≥ 2 synthetic episodes. |
-| `test_anti_hivemind_protocol.py` | `cortex/` | 5 protocol steps fire in order; caps enforced (2 rounds, 1 cross-brain challenge, 1 Critic/brain/tick). |
-| `test_collapse_detector.py` | `cortex/` | Metacognition flags when all brains recommend the same action. |
-| `test_import_graph.py` | repo-wide | No `import server` under `cortex/**`; no `import cortex` under `server/**`; no `import server.simulator` under `training/**`. |
-| `test_baselines_smoke.py` | `baselines/` | B1 / B2 / B3 each run one episode on `outbreak_easy`. |
-| `test_training_smoke.py` | `training/` | `train_router.main()` runs one episode against a mocked env under 5 s. |
-
-## Binding rules
-
-- Every public API in a subsystem's CLAUDE.md has ≥ 1 test here.
-- Coverage target: 80% per subsystem; 100% for `server/graders/` and `cortex/anti_hivemind.py`.
-- No test may take > 10 s unless marked `@pytest.mark.slow` and gated behind `--runslow`.
-- `test_import_graph.py` uses a fresh subprocess import, not `sys.modules` monkey-patching — the latter passes under contamination.
-
-## Common failure modes
-
-- Smoke test asserting on current-echo values — breaks when real env logic lands. Assert on shape, not value.
-- Module-scope env instantiation in tests — slows collection and hides init errors until runtime.
-- Tests that hit the HF Space without a skip guard — CI flakes on rate limits.
+# tests/CLAUDE.md
+
+Test surface per subsystem. Smoke bar first, boundary tests next, coverage last.
+
+## Belongs here
+
+- `conftest.py` — repo root on `sys.path` for bare-name imports.
+- One test module per subsystem boundary (table below).
+
+## Does not belong here
+
+Helpers that mutate real graders, simulator state, or disk. Fixtures that hit the live HF Space — mock or `pytest.skip`.
+
+## Run commands
+
+```bash
+uv run python -m pytest tests/ -v                                                               # all
+uv run python -m pytest tests/test_smoke_env.py::test_reset_returns_valid_observation -v        # one
+uv run python -m pytest --cov tests/                                                            # coverage
+```
+
+## Required tests — each maps to exactly one subsystem contract
+
+| File | Scope | Asserts |
+|---|---|---|
+| `test_package_exports.py` | wire package | Root `__init__` re-exports `CrisisworldcortexAction/Observation/Env`. |
+| `test_smoke_env.py` | `server/` env | `reset()` / `step()` return a valid `CrisisworldcortexObservation`. |
+| `test_actions_round_trip.py` | `server/` env | 6 MVP outer actions round-trip; `public_communication` is rejected at runtime. |
+| `test_reward_shape.py` | `server/graders/` | Every grader returns values in `[0.0, 1.0]`. |
+| `test_reward_non_constancy.py` | `server/graders/` | Grader output varies across ≥ 2 synthetic episodes. |
+| `test_anti_hivemind_protocol.py` | `cortex/` | 5 protocol steps fire in order; caps enforced (2 rounds, 1 cross-brain challenge, 1 Critic/brain/tick). |
+| `test_collapse_detector.py` | `cortex/` | Metacognition flags when all brains recommend the same action. |
+| `test_import_graph.py` | repo-wide | No `import server` under `cortex/**`; no `import cortex` under `server/**`; no `import server.simulator` under `training/**`. |
+| `test_baselines_smoke.py` | `baselines/` | B1 / B2 / B3 each run one episode on `outbreak_easy`. |
+| `test_training_smoke.py` | `training/` | `train_router.main()` runs one episode against a mocked env under 5 s. |
+
+## Binding rules
+
+- Every public API in a subsystem's CLAUDE.md has ≥ 1 test here.
+- Coverage target: 80% per subsystem; 100% for `server/graders/` and `cortex/anti_hivemind.py`.
+- No test may take > 10 s unless marked `@pytest.mark.slow` and gated behind `--runslow`.
+- `test_import_graph.py` uses a fresh subprocess import, not `sys.modules` monkey-patching — the latter passes under contamination.
+
+## Common failure modes
+
+- Smoke test asserting on current-echo values — breaks when real env logic lands. Assert on shape, not value.
+- Module-scope env instantiation in tests — slows collection and hides init errors until runtime.
+- Tests that hit the HF Space without a skip guard — CI flakes on rate limits.

tests/_helpers/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable test helpers for cortex/baselines tests.
+
+Lives alongside ``tests/`` (not under ``cortex/``) so production code
+never imports test doubles. Sessions 9-13 reuse the LLMClient stub
+defined here.
+"""

tests/_helpers/llm_stub.py

@@ -0,0 +1,82 @@
+"""LLMClient-level test double.
+
+Drop-in replacement for ``cortex.llm_client.LLMClient`` for tests that
+exercise consumers of the client (subagents, brains, council). Differs
+from the SDK-level stub in ``tests/test_llm_client.py``: that one
+intercepts the OpenAI SDK; this one intercepts the ``LLMClient.chat``
+surface directly, which is what subagents and harnesses see.
+
+Reused by sessions 9-13 — do not bury role-specific test logic here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from cortex.llm_client import ChatMessage, ChatResponse
+
+
+@dataclass
+class RecordedCall:
+    """One captured ``chat()`` invocation. Tests assert on these."""
+
+    caller_id: str
+    messages: List[ChatMessage]
+    max_tokens: Optional[int]
+    temperature: Optional[float]
+
+
+@dataclass
+class StubLLMClient:
+    """Quacks like ``LLMClient`` for the ``chat()`` and counter surface.
+
+    Args:
+        scripted_responses: Yielded one per ``chat()`` call, in order.
+            Each entry is the response ``content`` string.
+        prompt_tokens_per_call: Fake prompt-token billing per call.
+        completion_tokens_per_call: Fake completion-token billing per call.
+    """
+
+    scripted_responses: List[str]
+    prompt_tokens_per_call: int = 50
+    completion_tokens_per_call: int = 30
+    calls: List[RecordedCall] = field(default_factory=list)
+    _counters: Dict[str, int] = field(default_factory=dict)
+
+    def chat(
+        self,
+        caller_id: str,
+        messages: List[ChatMessage],
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+    ) -> ChatResponse:
+        if not self.scripted_responses:
+            raise RuntimeError(
+                f"StubLLMClient exhausted: caller_id={caller_id!r}; "
+                f"add more scripted_responses or assert call_count earlier."
+            )
+        content = self.scripted_responses.pop(0)
+        self.calls.append(
+            RecordedCall(
+                caller_id=caller_id,
+                messages=list(messages),
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+        )
+        billed = self.prompt_tokens_per_call + self.completion_tokens_per_call
+        self._counters[caller_id] = self._counters.get(caller_id, 0) + billed
+        return ChatResponse(
+            content=content,
+            finish_reason="stop",
+            prompt_tokens=self.prompt_tokens_per_call,
+            completion_tokens=self.completion_tokens_per_call,
+        )
+
+    def tokens_used_for(self, caller_id: str) -> int:
+        return self._counters.get(caller_id, 0)
+
+    @property
+    def call_count(self) -> int:
+        return len(self.calls)

tests/test_baseline_b1.py

@@ -218,7 +218,13 @@ def test_b1_runs_episode_with_valid_json() -> None:
 def test_b1_parse_failure_submits_synthetic_rejection() -> None:
     """When the LLM emits unparseable text, B1 submits a synthetic
     PublicCommunication so the env rejects with accepted=False — landing
-    r_policy=0 in outer_reward, and the action log shows the rejection.
+    r_policy=-1.0 in outer_reward (Phase-1 fix per design §19) and the
+    action log shows the rejection.
+
+    Phase-1 contract: parse-failure now TERMINATES the episode at the
+    rejection tick (state.terminal = "failure" → obs.done = True). So
+    only the first parse-failure lands; the second LLM response in the
+    stub queue never gets dispatched.
     """
     env_inner = CrisisworldcortexEnvironment()
     env = _InProcessEnvAdapter(env_inner)
@@ -233,36 +239,26 @@ def test_b1_parse_failure_submits_synthetic_rejection() -> None:
 
     trajectory = agent.run_episode(task="outbreak_easy", seed=0, max_ticks=5)
 
-    # Both parse failures were detected and counted.
-    assert trajectory["parse_failure_count"] == 2
+    # Phase-1: parse-failure terminates → only the first marker lands.
+    assert trajectory["parse_failure_count"] == 1
 
-    # B1 did NOT crash on parse failure — at least 3 ticks ran, even
-    # though the env may then have hit a terminal (success-on-3-safe-ticks
-    # or otherwise). What's binding: parse failure does not raise.
-    assert trajectory["steps_taken"] >= 3, (
+    # B1 did NOT crash on parse failure — exactly 1 tick ran (parse-failure
+    # marker submitted, env terminated episode).
+    assert trajectory["steps_taken"] == 1, (
         f"steps_taken={trajectory['steps_taken']!r} - parse failure "
-        f"shouldn't kill the agent before tick 3"
+        f"should terminate at tick 1 under the §19 contract"
     )
 
-    # The first two action-log entries show V2 rejection (synthetic
-    # public_communication was submitted; env returned accepted=False).
+    # The action-log entry shows synthetic public_communication
+    # (parse-failure marker, honesty=0.0) — rejected by env.
     log = env_inner._world_state.recent_action_log
-    assert len(log) >= 2
+    assert len(log) == 1
     assert log[0].action.kind == "public_communication"
     assert log[0].accepted is False, "parse-failure synthetic must be rejected by env"
-    assert log[1].action.kind == "public_communication"
-    assert log[1].accepted is False
-
-    # The third entry should be the first parsed NoOp.
-    assert log[2].action.kind == "no_op"
-    assert log[2].accepted is True
 
-    # B1's local trajectory carries the raw snippets for forensic use.
+    # B1's local trajectory carries the raw snippet for forensic use.
     assert trajectory["action_history"][0]["parse_failure"] is True
     assert trajectory["action_history"][0]["raw_llm"] == "I cannot help with that."
-    assert trajectory["action_history"][1]["parse_failure"] is True
-    assert trajectory["action_history"][1]["raw_llm"] == "Sorry, no JSON."
-    assert trajectory["action_history"][2]["parse_failure"] is False
 
 
 def test_b1_caller_id_format_short_colon_separated() -> None:
@@ -335,7 +331,10 @@ def test_b1_step_event_carries_rich_context() -> None:
     from baselines.flat_agent import B1StepEvent
 
     env = _InProcessEnvAdapter(CrisisworldcortexEnvironment())
-    llm = _StubLLMClient(["I cannot help with that."] + ['{"kind": "no_op"}'] * 5)
+    # Use a clean-parse first response; parse-failure now terminates the
+    # episode at tick 1 under the §19 contract, so we exercise the
+    # tick-1 + tick-2 sequence with both responses being valid JSON.
+    llm = _StubLLMClient(['{"kind": "no_op"}'] * 5)
     agent = B1FlatAgent(env=env, llm=llm)
 
     events: list[B1StepEvent] = []
@@ -348,18 +347,17 @@ def test_b1_step_event_carries_rich_context() -> None:
 
     assert len(events) >= 2
 
-    # Tick 1: parse failure. Submitted action is the synthetic V2-rejected
-    # PublicCommunication marker; env returns accepted=False; reward in [0,1].
+    # Tick 1: clean parse. Submitted is NoOp. error must be None.
     e1 = events[0]
     assert e1.tick == 1
-    assert e1.parse_failure is True
-    assert e1.error == "parse_failure"
-    assert e1.raw_llm == "I cannot help with that."
-    assert e1.action.kind == "public_communication"
-    assert 0.0 <= e1.reward <= 1.0
+    assert e1.parse_failure is False
+    assert e1.error is None
+    assert e1.action.kind == "no_op"
+    assert e1.raw_llm == '{"kind": "no_op"}'
+    assert -1.0 <= e1.reward <= 1.0  # Phase-1 range relaxed from [0,1].
     assert isinstance(e1.done, bool)
 
-    # Tick 2: clean parse. Submitted is NoOp. error must be None.
+    # Tick 2: another clean parse. Submitted is NoOp. error must be None.
     e2 = events[1]
     assert e2.tick == 2
     assert e2.parse_failure is False

tests/test_cortex_brain_executive.py

@@ -0,0 +1,206 @@
+"""Session 11 - Brain Executive aggregation tests.
+
+Per Phase A docs/CORTEX_ARCHITECTURE.md Decisions 15-21 + M-FR-3
+(partial evidence union; CandidatePlan and CriticReport schemas have
+no evidence field).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from cortex.brains import aggregate_brain_outputs
+from cortex.schemas import (
+    BeliefState,
+    CandidatePlan,
+    CriticReport,
+    EvidenceCitation,
+    Hypothesis,
+    PerceptionReport,
+    RegionBeliefEstimate,
+)
+from CrisisWorldCortex.models import (
+    DeployResource,
+    NoOp,
+    RestrictMovement,
+)
+
+
+def _belief(uncertainty: float = 0.4, evidence_count: int = 1) -> BeliefState:
+    return BeliefState(
+        brain="epidemiology",
+        latent_estimates={
+            "R1": RegionBeliefEstimate(
+                estimated_infection_rate=0.05,
+                estimated_r_effective=1.2,
+                estimated_compliance=0.85,
+            ),
+        },
+        hypotheses=[Hypothesis(label="h1", weight=0.6, explanation="rising")],
+        uncertainty=uncertainty,
+        reducible_by_more_thought=0.3,
+        evidence=[
+            EvidenceCitation(source="telemetry", ref=f"R1.cases@{i}", excerpt=f"e{i}")
+            for i in range(evidence_count)
+        ],
+    )
+
+
+def _plan(action=None, confidence: float = 0.75, expected_value: float = 0.6) -> CandidatePlan:
+    if action is None:
+        action = DeployResource(region="R1", resource_type="test_kits", quantity=100)
+    return CandidatePlan(
+        action_sketch="Deploy 100 test_kits to R1",
+        expected_outer_action=action,
+        expected_value=expected_value,
+        cost=200.0,
+        assumptions=["kits available"],
+        falsifiers=["R1 cases drop without intervention"],
+        confidence=confidence,
+    )
+
+
+def _critic(severity: float = 0.3) -> CriticReport:
+    return CriticReport(
+        brain="epidemiology",
+        target_plan_id="plan-0",
+        attacks=["limited reach"],
+        missing_considerations=[],
+        would_change_mind_if=[],
+        severity=severity,
+    )
+
+
+def _perception(evidence_count: int = 1) -> PerceptionReport:
+    return PerceptionReport(
+        brain="epidemiology",
+        salient_signals=["R1 cases rising"],
+        anomalies=[],
+        confidence=0.7,
+        evidence=[
+            EvidenceCitation(source="telemetry", ref=f"R1.perception@{i}", excerpt=f"p{i}")
+            for i in range(evidence_count)
+        ],
+    )
+
+
+# T4
+def test_brain_executive_aggregates_subagent_outputs() -> None:
+    rec = aggregate_brain_outputs(
+        brain_id="epidemiology",
+        perception=_perception(),
+        beliefs=[_belief()],
+        plans=[_plan()],
+        critics=[_critic()],
+    )
+    assert rec.brain == "epidemiology"
+    assert rec.top_action.kind == "deploy_resource"
+    assert rec.top_confidence > 0.0
+    assert rec.tokens_used == 0
+
+
+# T5 -- Decision 16
+def test_brain_executive_top_confidence_includes_uncertainty() -> None:
+    rec = aggregate_brain_outputs(
+        brain_id="epidemiology",
+        perception=_perception(),
+        beliefs=[_belief(uncertainty=0.4)],
+        plans=[_plan(confidence=0.75)],
+        critics=[_critic()],
+    )
+    # D16: top_confidence == confidence x (1 - uncertainty) == 0.75 x 0.6 == 0.45
+    assert rec.top_confidence == pytest.approx(0.45)
+
+
+# T6 -- Decision 17
+def test_brain_executive_minority_actions_excludes_top() -> None:
+    plan_a = _plan(
+        action=DeployResource(region="R1", resource_type="test_kits", quantity=100),
+        confidence=0.8,
+        expected_value=0.7,
+    )
+    plan_b = _plan(
+        action=RestrictMovement(region="R1", severity="moderate"),
+        confidence=0.5,
+        expected_value=0.4,
+    )
+    # plan_a wins: 0.8 * 0.7 = 0.56 > 0.5 * 0.4 = 0.20
+
+    rec = aggregate_brain_outputs(
+        brain_id="epidemiology",
+        perception=_perception(),
+        beliefs=[_belief(), _belief(uncertainty=0.5)],
+        plans=[plan_a, plan_b],
+        critics=[_critic(), _critic()],
+    )
+
+    assert rec.top_action.kind == "deploy_resource"
+    assert len(rec.minority_actions) == 1
+    assert rec.minority_actions[0].kind == "restrict_movement"
+
+
+# T7 -- Decision 20 + M-FR-3
+def test_brain_executive_evidence_union() -> None:
+    perception = _perception(evidence_count=1)
+    belief = _belief(evidence_count=2)
+
+    rec = aggregate_brain_outputs(
+        brain_id="epidemiology",
+        perception=perception,
+        beliefs=[belief],
+        plans=[_plan()],
+        critics=[_critic()],
+    )
+
+    # M-FR-3: union of perception.evidence + belief.evidence (3 total)
+    assert len(rec.evidence) == 3
+    assert rec.evidence[0].ref.startswith("R1.perception")
+    assert rec.evidence[1].ref.startswith("R1.cases")
+
+
+# T8 -- empty fallback
+def test_brain_executive_handles_empty_subagent_outputs() -> None:
+    empty_belief = BeliefState(
+        brain="epidemiology",
+        latent_estimates={},
+        hypotheses=[],
+        uncertainty=1.0,
+        reducible_by_more_thought=0.0,
+        evidence=[],
+    )
+    empty_plan = CandidatePlan(
+        action_sketch="(empty)",
+        expected_outer_action=NoOp(),
+        expected_value=0.0,
+        cost=0.0,
+        assumptions=[],
+        falsifiers=[],
+        confidence=0.0,
+    )
+    empty_critic = CriticReport(
+        brain="epidemiology",
+        target_plan_id="",
+        attacks=[],
+        missing_considerations=[],
+        would_change_mind_if=[],
+        severity=0.0,
+    )
+    empty_perception = PerceptionReport(
+        brain="epidemiology",
+        salient_signals=[],
+        anomalies=[],
+        confidence=0.0,
+        evidence=[],
+    )
+
+    rec = aggregate_brain_outputs(
+        brain_id="epidemiology",
+        perception=empty_perception,
+        beliefs=[empty_belief],
+        plans=[empty_plan],
+        critics=[empty_critic],
+    )
+
+    assert rec.top_action.kind == "no_op"
+    assert rec.top_confidence == 0.0
+    assert rec.uncertainty == 1.0

tests/test_cortex_brain_smoke.py

@@ -0,0 +1,142 @@
+"""Session 11 - Single-brain end-to-end smoke + no-LLM-in-Python-layers test.
+
+T9 asserts Brain.compute_perception and Brain.compute_lens are pure
+Python (zero LLM calls). T10 is the integration smoke gate per Phase A
+section 10: a single brain runs end-to-end on a real observation,
+returns a BrainRecommendation. Three LLM calls in canonical
+WorldModeler -> Planner -> Critic order with locked caller_id format.
+"""
+
+from __future__ import annotations
+
+import json
+
+from cortex.brains import EpiBrain
+from cortex.schemas import BrainRecommendation
+from CrisisWorldCortex.models import (
+    CrisisworldcortexObservation,
+    RegionTelemetry,
+    ResourceInventory,
+)
+from tests._helpers.llm_stub import StubLLMClient
+
+
+def _make_obs() -> CrisisworldcortexObservation:
+    return CrisisworldcortexObservation(
+        regions=[
+            RegionTelemetry(
+                region=f"R{i + 1}",
+                reported_cases_d_ago=5 if i == 0 else 1,
+                hospital_load=0.3 if i == 0 else 0.1,
+                compliance_proxy=0.85,
+            )
+            for i in range(4)
+        ],
+        resources=ResourceInventory(
+            test_kits=1000,
+            hospital_beds_free=500,
+            mobile_units=20,
+            vaccine_doses=2000,
+        ),
+        active_restrictions=[],
+        legal_constraints=[],
+        tick=3,
+        ticks_remaining=9,
+        cognition_budget_remaining=5200,
+        recent_action_log=[],
+    )
+
+
+_VALID_BELIEF = json.dumps(
+    {
+        "brain": "epidemiology",
+        "latent_estimates": {
+            "R1": {
+                "estimated_infection_rate": 0.05,
+                "estimated_r_effective": 1.2,
+                "estimated_compliance": 0.85,
+                "confidence_intervals": {},
+            }
+        },
+        "hypotheses": [{"label": "rising", "weight": 0.6, "explanation": "R1 cases up"}],
+        "uncertainty": 0.4,
+        "reducible_by_more_thought": 0.3,
+        "evidence": [
+            {"source": "telemetry", "ref": "R1.cases", "excerpt": "5"},
+            {"source": "policy", "ref": "R1.restriction", "excerpt": "none"},
+        ],
+    }
+)
+
+_VALID_PLAN = json.dumps(
+    {
+        "action_sketch": "Deploy 100 test_kits to R1",
+        "expected_outer_action": {
+            "kind": "deploy_resource",
+            "region": "R1",
+            "resource_type": "test_kits",
+            "quantity": 100,
+        },
+        "expected_value": 0.6,
+        "cost": 200.0,
+        "assumptions": ["kits inventory > 100"],
+        "falsifiers": ["R1 cases drop without intervention"],
+        "confidence": 0.75,
+    }
+)
+
+_VALID_CRITIC = json.dumps(
+    {
+        "brain": "epidemiology",
+        "target_plan_id": "plan-0",
+        "attacks": ["ignores R3 hospital saturation"],
+        "missing_considerations": [],
+        "would_change_mind_if": [],
+        "severity": 0.3,
+    }
+)
+
+
+# T9
+def test_brain_runs_zero_llm_calls_in_python_layers() -> None:
+    """Perception and Lens are pure Python; no LLMClient invocation."""
+    stub = StubLLMClient(scripted_responses=[])  # any chat() would raise
+    brain = EpiBrain(stub)
+    obs = _make_obs()
+
+    perception = brain.compute_perception(obs)
+    lensed = brain.compute_lens(obs, last_reward=0.0)
+
+    assert stub.call_count == 0
+    assert perception.brain == "epidemiology"
+    assert lensed.brain == "epidemiology"
+
+
+# T10 -- integration smoke gate (Phase A section 10)
+def test_brain_smoke_one_tick_three_llm_calls_in_order() -> None:
+    """Full round-1 tick: WorldModeler -> Planner -> Critic, in that order."""
+    stub = StubLLMClient(scripted_responses=[_VALID_BELIEF, _VALID_PLAN, _VALID_CRITIC])
+    brain = EpiBrain(stub)
+    obs = _make_obs()
+
+    rec = brain.run_tick(obs, last_reward=0.0, tick=3)
+
+    assert isinstance(rec, BrainRecommendation)
+    assert rec.brain == "epidemiology"
+    assert rec.top_action.kind == "deploy_resource"
+    assert stub.call_count == 3, "exactly 3 LLM calls per Phase A 'WM + Planner + Critic'"
+
+    # Order pin per user adjustment: WM (s0) -> Planner (s1) -> Critic (s2)
+    assert stub.calls[0].caller_id.endswith(":world_modeler:t3:r1:s0"), (
+        f"first call must be WorldModeler, got {stub.calls[0].caller_id!r}"
+    )
+    assert stub.calls[1].caller_id.endswith(":planner:t3:r1:s1"), (
+        f"second call must be Planner, got {stub.calls[1].caller_id!r}"
+    )
+    assert stub.calls[2].caller_id.endswith(":critic:t3:r1:s2"), (
+        f"third call must be Critic, got {stub.calls[2].caller_id!r}"
+    )
+
+    # Brain prefix locks
+    for call in stub.calls:
+        assert call.caller_id.startswith("cortex:epidemiology:")

tests/test_cortex_lenses.py

@@ -0,0 +1,238 @@
+"""Session 10 - Cortex lens tests.
+
+Per Phase A docs/CORTEX_ARCHITECTURE.md Decisions 9-14 + §2 A1 and the
+user's Session 10 proposal acceptance with 8 tests + the M-FR-4 rename
+(epi_pressure) and T7 tightening (non-bool float).
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import pytest
+
+from cortex.lenses import lens_for
+from cortex.schemas import BrainLensedObservation
+from CrisisWorldCortex.models import (
+    CrisisworldcortexObservation,
+    Escalate,
+    ExecutedAction,
+    LegalConstraint,
+    NoOp,
+    RegionTelemetry,
+    ResourceInventory,
+    Restriction,
+)
+
+# ============================================================================
+# Test fixtures
+# ============================================================================
+
+
+def _make_obs(
+    cases_per_region: Iterable[int] = (5, 1, 1, 1),
+    hospital_loads: Iterable[float] = (0.3, 0.1, 0.1, 0.1),
+    compliance_proxies: Iterable[float] = (0.85, 0.95, 0.95, 0.95),
+    test_kits: int = 1000,
+    hospital_beds_free: int = 500,
+    mobile_units: int = 20,
+    vaccine_doses: int = 2000,
+    restrictions: Iterable[Restriction] = (),
+    legal_constraints: Iterable[LegalConstraint] = (),
+    recent_action_log: Iterable[ExecutedAction] = (),
+) -> CrisisworldcortexObservation:
+    cases = list(cases_per_region)
+    loads = list(hospital_loads)
+    comps = list(compliance_proxies)
+    return CrisisworldcortexObservation(
+        regions=[
+            RegionTelemetry(
+                region=f"R{i + 1}",
+                reported_cases_d_ago=cases[i],
+                hospital_load=loads[i],
+                compliance_proxy=comps[i],
+            )
+            for i in range(4)
+        ],
+        resources=ResourceInventory(
+            test_kits=test_kits,
+            hospital_beds_free=hospital_beds_free,
+            mobile_units=mobile_units,
+            vaccine_doses=vaccine_doses,
+        ),
+        active_restrictions=list(restrictions),
+        legal_constraints=list(legal_constraints),
+        tick=3,
+        ticks_remaining=9,
+        cognition_budget_remaining=5200,
+        recent_action_log=list(recent_action_log),
+    )
+
+
+# ============================================================================
+# T1 - Epi lens emphasizes telemetry; uses epi_pressure (M-FR-4 rename)
+# ============================================================================
+
+
+def test_epi_lens_emphasizes_telemetry() -> None:
+    obs = _make_obs()
+    lensed = lens_for("epidemiology", obs, last_reward=0.5)
+
+    assert isinstance(lensed, BrainLensedObservation)
+    assert lensed.brain == "epidemiology"
+    assert lensed.last_reward == 0.5
+
+    keys = set(lensed.derived_features.keys())
+    assert {"epi_pressure", "worst_region_infection", "transmission_rate_trend"} <= keys
+
+    # M-FR-2: trend is 0.0 in MVP (no history available in single-obs lens)
+    assert lensed.derived_features["transmission_rate_trend"] == 0.0
+
+    assert "regions[*].reported_cases_d_ago" in lensed.salient_field_ids
+    assert "regions[*].hospital_load" in lensed.salient_field_ids
+
+
+# ============================================================================
+# T2 - Logistics lens emphasizes resources
+# ============================================================================
+
+
+def test_logistics_lens_emphasizes_resources() -> None:
+    obs = _make_obs(test_kits=100, hospital_beds_free=50, mobile_units=10, vaccine_doses=200)
+    lensed = lens_for("logistics", obs, last_reward=0.5)
+
+    assert lensed.brain == "logistics"
+    keys = set(lensed.derived_features.keys())
+    expected_keys = {
+        "total_inventory",
+        "hospital_load_max",
+        "deployment_feasibility_R1",
+        "deployment_feasibility_R2",
+        "deployment_feasibility_R3",
+        "deployment_feasibility_R4",
+    }
+    assert expected_keys <= keys
+
+    # 100 + 50 + 10 + 200 = 360
+    assert lensed.derived_features["total_inventory"] == 360.0
+
+    assert "resources.test_kits" in lensed.salient_field_ids
+
+
+# ============================================================================
+# T3 - Governance lens emphasizes legal
+# ============================================================================
+
+
+def test_governance_lens_emphasizes_legal() -> None:
+    obs = _make_obs(
+        restrictions=[Restriction(region="R1", severity="moderate", ticks_remaining=3)],
+        legal_constraints=[
+            LegalConstraint(rule_id="L1", blocked_action="restrict_movement.strict")
+        ],
+    )
+    lensed = lens_for("governance", obs, last_reward=0.5)
+
+    assert lensed.brain == "governance"
+    keys = set(lensed.derived_features.keys())
+    assert {
+        "escalation_unlocked_strict",
+        "legal_constraints_count",
+        "restrictions_active_count",
+    } <= keys
+
+    assert lensed.derived_features["legal_constraints_count"] == 1.0
+    assert lensed.derived_features["restrictions_active_count"] == 1.0
+    assert "active_restrictions[*]" in lensed.salient_field_ids
+
+
+# ============================================================================
+# T4 - Lens does NOT strip raw_obs (D13)
+# ============================================================================
+
+
+def test_lens_does_not_strip_raw_obs() -> None:
+    obs = _make_obs(restrictions=[Restriction(region="R1", severity="moderate", ticks_remaining=3)])
+
+    for brain in ("epidemiology", "logistics", "governance"):
+        lensed = lens_for(brain, obs, last_reward=0.0)
+        # Pydantic deep-equality on the full observation
+        assert lensed.raw_obs == obs
+
+
+# ============================================================================
+# T5 - V2 brain ids raise KeyError (Decision 9, post-review)
+# ============================================================================
+
+
+def test_lens_for_v2_brain_raises_key_error() -> None:
+    obs = _make_obs()
+
+    for v2_brain in ("communications", "equity"):
+        with pytest.raises(KeyError):
+            lens_for(v2_brain, obs, last_reward=0.0)
+
+    with pytest.raises(KeyError):
+        lens_for("not_a_brain", obs, last_reward=0.0)
+
+
+# ============================================================================
+# T7 - All derived_features values are non-bool floats (D14 + tightened)
+# ============================================================================
+
+
+def test_lens_derived_features_all_floats() -> None:
+    obs = _make_obs(
+        restrictions=[Restriction(region="R1", severity="moderate", ticks_remaining=3)],
+        legal_constraints=[
+            LegalConstraint(rule_id="L1", blocked_action="restrict_movement.strict")
+        ],
+    )
+
+    for brain in ("epidemiology", "logistics", "governance"):
+        lensed = lens_for(brain, obs, last_reward=0.0)
+        for key, value in lensed.derived_features.items():
+            assert isinstance(value, float) and not isinstance(value, bool), (
+                f"derived_features[{key!r}] = {value!r} ({type(value).__name__}) "
+                f"is not a non-bool float"
+            )
+
+
+# ============================================================================
+# T8 - Governance lens detects accepted escalate(national)
+# ============================================================================
+
+
+def test_governance_lens_detects_escalation_unlocked() -> None:
+    obs_with_accepted = _make_obs(
+        recent_action_log=[
+            ExecutedAction(tick=1, action=NoOp(), accepted=True),
+            ExecutedAction(tick=2, action=Escalate(to_authority="national"), accepted=True),
+        ]
+    )
+    lensed = lens_for("governance", obs_with_accepted, last_reward=0.0)
+    assert lensed.derived_features["escalation_unlocked_strict"] == 1.0
+
+    obs_without = _make_obs(
+        recent_action_log=[ExecutedAction(tick=1, action=NoOp(), accepted=True)]
+    )
+    lensed_w = lens_for("governance", obs_without, last_reward=0.0)
+    assert lensed_w.derived_features["escalation_unlocked_strict"] == 0.0
+
+    # Rejected escalate must NOT count
+    obs_rejected = _make_obs(
+        recent_action_log=[
+            ExecutedAction(tick=1, action=Escalate(to_authority="national"), accepted=False),
+        ]
+    )
+    lensed_r = lens_for("governance", obs_rejected, last_reward=0.0)
+    assert lensed_r.derived_features["escalation_unlocked_strict"] == 0.0
+
+    # Accepted escalate(regional) must NOT count -- only "national" unlocks strict
+    obs_regional = _make_obs(
+        recent_action_log=[
+            ExecutedAction(tick=1, action=Escalate(to_authority="regional"), accepted=True),
+        ]
+    )
+    lensed_re = lens_for("governance", obs_regional, last_reward=0.0)
+    assert lensed_re.derived_features["escalation_unlocked_strict"] == 0.0

tests/test_cortex_perception.py

@@ -0,0 +1,116 @@
+"""Session 11 - Perception subagent tests (deterministic Python; no LLM).
+
+Per cortex/CLAUDE.md binding (Perception is pure Python) and Phase A
+Decisions 9 (V2 KeyError) + 63 (salient_signals cap at 5).
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import pytest
+
+from cortex.schemas import PerceptionReport
+from cortex.subagents import perception_for
+from CrisisWorldCortex.models import (
+    CrisisworldcortexObservation,
+    LegalConstraint,
+    RegionTelemetry,
+    ResourceInventory,
+    Restriction,
+)
+
+
+def _make_obs(
+    cases_per_region: Iterable[int] = (5, 1, 0, 0),
+    hospital_loads: Iterable[float] = (0.7, 0.1, 0.1, 0.1),
+    test_kits: int = 200,
+    hospital_beds_free: int = 50,
+    mobile_units: int = 2,
+    vaccine_doses: int = 300,
+    restrictions: Iterable[Restriction] = (),
+    legal_constraints: Iterable[LegalConstraint] = (),
+) -> CrisisworldcortexObservation:
+    cases = list(cases_per_region)
+    loads = list(hospital_loads)
+    return CrisisworldcortexObservation(
+        regions=[
+            RegionTelemetry(
+                region=f"R{i + 1}",
+                reported_cases_d_ago=cases[i],
+                hospital_load=loads[i],
+                compliance_proxy=0.85,
+            )
+            for i in range(4)
+        ],
+        resources=ResourceInventory(
+            test_kits=test_kits,
+            hospital_beds_free=hospital_beds_free,
+            mobile_units=mobile_units,
+            vaccine_doses=vaccine_doses,
+        ),
+        active_restrictions=list(restrictions),
+        legal_constraints=list(legal_constraints),
+        tick=3,
+        ticks_remaining=9,
+        cognition_budget_remaining=5200,
+        recent_action_log=[],
+    )
+
+
+# T1
+def test_perception_runs_without_llm_call() -> None:
+    """Perception is pure Python; the function does not take an LLMClient."""
+    obs = _make_obs()
+    for brain in ("epidemiology", "logistics", "governance"):
+        report = perception_for(brain, obs)
+        assert isinstance(report, PerceptionReport)
+        assert report.brain == brain
+        assert isinstance(report.confidence, float)
+        assert 0.0 <= report.confidence <= 1.0
+
+
+# T2
+def test_perception_for_v2_brain_raises_key_error() -> None:
+    obs = _make_obs()
+    for v2_brain in ("communications", "equity"):
+        with pytest.raises(KeyError):
+            perception_for(v2_brain, obs)
+    with pytest.raises(KeyError):
+        perception_for("not_a_brain", obs)
+
+
+# T3
+@pytest.mark.parametrize("brain", ["epidemiology", "logistics", "governance"])
+def test_perception_brain_specific_signals(brain: str) -> None:
+    obs = _make_obs(
+        cases_per_region=(20, 1, 0, 0),
+        hospital_loads=(0.7, 0.1, 0.1, 0.1),
+        test_kits=100,  # below threshold (300)
+        hospital_beds_free=50,  # below threshold (100)
+        mobile_units=2,  # below threshold (5)
+        vaccine_doses=200,  # below threshold (500)
+        restrictions=[
+            Restriction(region="R1", severity="moderate", ticks_remaining=3),
+        ],
+        legal_constraints=[
+            LegalConstraint(rule_id="L1", blocked_action="restrict_movement.strict"),
+        ],
+    )
+    report = perception_for(brain, obs)
+
+    assert report.brain == brain
+    # Decision 63 / OQ-2 cap: at most 5 entries
+    assert len(report.salient_signals) <= 5
+
+    if brain == "epidemiology":
+        assert any("R1" in s for s in report.salient_signals), (
+            f"epi salient_signals should reference R1, got {report.salient_signals}"
+        )
+    elif brain == "logistics":
+        joined = " ".join(report.salient_signals).lower()
+        assert "kits" in joined or "mobile" in joined or "vaccine" in joined or "beds" in joined
+    elif brain == "governance":
+        assert any("R1" in s and "moderate" in s.lower() for s in report.salient_signals), (
+            f"governance salient_signals should mention R1 moderate, got {report.salient_signals}"
+        )

tests/test_cortex_subagents.py

@@ -0,0 +1,387 @@
+"""Session 9 - Cortex subagent tests (WorldModeler, Planner, Critic).
+
+Per Phase A docs/CORTEX_ARCHITECTURE.md Decisions 1-8 + 62 and the user's
+proposal acceptance with 11 tests total. RED-tests-first.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, Optional
+
+import pytest
+
+from cortex.schemas import (
+    BeliefState,
+    CandidatePlan,
+    CriticReport,
+    EvidenceCitation,
+    PerceptionReport,
+    SubagentInput,
+)
+from cortex.subagents import (
+    PROMPTS_DIR,
+    CriticSubagent,
+    PlannerSubagent,
+    WorldModelerSubagent,
+)
+from tests._helpers.llm_stub import StubLLMClient
+
+# ============================================================================
+# Test fixtures
+# ============================================================================
+
+
+_VALID_BELIEF_PAYLOAD: Dict[str, Any] = {
+    "brain": "epidemiology",
+    "latent_estimates": {
+        "R1": {
+            "estimated_infection_rate": 0.05,
+            "estimated_r_effective": 1.2,
+            "estimated_compliance": 0.85,
+            "confidence_intervals": {},
+        },
+    },
+    "hypotheses": [{"label": "rising-r1", "weight": 0.6, "explanation": "telemetry trending up"}],
+    "uncertainty": 0.4,
+    "reducible_by_more_thought": 0.3,
+    "evidence": [
+        {"source": "telemetry", "ref": "R1.reported_cases@t3", "excerpt": "rising"},
+        {"source": "policy", "ref": "R1.restriction", "excerpt": "moderate"},
+    ],
+}
+
+
+_VALID_PLAN_PAYLOAD: Dict[str, Any] = {
+    "action_sketch": "Deploy 100 test_kits to R1",
+    "expected_outer_action": {
+        "kind": "deploy_resource",
+        "region": "R1",
+        "resource_type": "test_kits",
+        "quantity": 100,
+    },
+    "expected_value": 0.6,
+    "cost": 200.0,
+    "assumptions": ["kits inventory > 100"],
+    "falsifiers": ["R1 cases drop without intervention"],
+    "confidence": 0.75,
+}
+
+
+_VALID_CRITIC_PAYLOAD: Dict[str, Any] = {
+    "brain": "logistics",
+    "target_plan_id": "plan-1",
+    "attacks": ["ignores R3 hospital saturation"],
+    "missing_considerations": ["compliance decay over 4 ticks"],
+    "would_change_mind_if": ["new R3 telemetry shows under-utilisation"],
+    "severity": 0.6,
+}
+
+
+def _valid_json_for(role: str, brain: str = "epidemiology") -> str:
+    """Return a valid JSON-schema response for ``role``, brain-substituted."""
+    if role == "world_modeler":
+        payload = dict(_VALID_BELIEF_PAYLOAD)
+        payload["brain"] = brain
+        return json.dumps(payload)
+    if role == "planner":
+        return json.dumps(_VALID_PLAN_PAYLOAD)
+    if role == "critic":
+        payload = dict(_VALID_CRITIC_PAYLOAD)
+        payload["brain"] = brain
+        return json.dumps(payload)
+    raise ValueError(f"unknown role: {role}")
+
+
+def _make_subagent_input(
+    brain: str = "epidemiology",
+    role: str = "world_modeler",
+    tick: int = 3,
+    round_: int = 1,
+    target_plan_id: Optional[str] = None,
+) -> SubagentInput:
+    """Minimal valid SubagentInput. ``round_`` arg avoids shadowing builtin."""
+    return SubagentInput(
+        brain=brain,
+        role=role,
+        tick=tick,
+        round=round_,
+        perception=PerceptionReport(
+            brain=brain,
+            salient_signals=["R1 cases rising"],
+            anomalies=[],
+            confidence=0.7,
+            evidence=[EvidenceCitation(source="telemetry", ref="R1.cases", excerpt="rising")],
+        ),
+        prior_belief=None,
+        prior_plans=[],
+        target_plan_id=target_plan_id,
+        last_reward=0.5,
+        recent_action_log_excerpt=[],
+    )
+
+
+# ============================================================================
+# T1 - WorldModeler emits BeliefState
+# ============================================================================
+
+
+def test_world_modeler_emits_belief_state() -> None:
+    stub = StubLLMClient(scripted_responses=[_valid_json_for("world_modeler", "epidemiology")])
+    agent = WorldModelerSubagent(llm_client=stub)
+    input_data = _make_subagent_input(brain="epidemiology", role="world_modeler")
+
+    result = agent.run(input_data, step_idx=0)
+
+    assert isinstance(result, BeliefState)
+    assert result.brain == "epidemiology"
+    assert "R1" in result.latent_estimates
+    assert len(result.evidence) >= 1
+    assert stub.call_count == 1
+
+
+# ============================================================================
+# T2 - Planner emits CandidatePlan
+# ============================================================================
+
+
+def test_planner_emits_candidate_plan() -> None:
+    stub = StubLLMClient(scripted_responses=[_valid_json_for("planner", "epidemiology")])
+    agent = PlannerSubagent(llm_client=stub)
+    input_data = _make_subagent_input(brain="epidemiology", role="planner")
+
+    result = agent.run(input_data, step_idx=1)
+
+    assert isinstance(result, CandidatePlan)
+    assert result.expected_outer_action.kind == "deploy_resource"
+    assert result.confidence == 0.75
+
+
+# ============================================================================
+# T3 - Critic emits CriticReport
+# ============================================================================
+
+
+def test_critic_emits_critic_report() -> None:
+    stub = StubLLMClient(scripted_responses=[_valid_json_for("critic", "logistics")])
+    agent = CriticSubagent(llm_client=stub)
+    input_data = _make_subagent_input(brain="logistics", role="critic", target_plan_id="plan-1")
+
+    result = agent.run(input_data, step_idx=2)
+
+    assert isinstance(result, CriticReport)
+    assert result.brain == "logistics"
+    assert result.target_plan_id == "plan-1"
+    assert result.severity == 0.6
+
+
+# ============================================================================
+# T4 - Parse failure then retry succeeds (2 LLM calls)
+# ============================================================================
+
+
+def test_subagent_parse_failure_then_retry_succeeds() -> None:
+    stub = StubLLMClient(
+        scripted_responses=["not-json-garbage", _valid_json_for("world_modeler", "epidemiology")]
+    )
+    agent = WorldModelerSubagent(llm_client=stub)
+
+    result = agent.run(_make_subagent_input(), step_idx=0)
+
+    assert isinstance(result, BeliefState)
+    assert result.brain == "epidemiology"
+    assert stub.call_count == 2, "expected 1 initial call + 1 retry"
+
+
+# ============================================================================
+# T5 - Parse failure twice -> empty fallback (no third LLM call)
+# ============================================================================
+
+
+def test_subagent_parse_failure_then_retry_fails_returns_empty() -> None:
+    stub = StubLLMClient(scripted_responses=["garbage-1", "garbage-2"])
+    agent = WorldModelerSubagent(llm_client=stub)
+
+    result = agent.run(_make_subagent_input(), step_idx=0)
+
+    assert isinstance(result, BeliefState)
+    assert result.brain == "epidemiology"
+    assert result.latent_estimates == {}
+    assert result.hypotheses == []
+    assert result.evidence == []
+    assert result.uncertainty == 1.0
+    assert result.reducible_by_more_thought == 0.0
+    assert stub.call_count == 2, "must NOT make a 3rd call after retry failure"
+
+
+# ============================================================================
+# T6 - caller_id format matches Phase A Decision 7
+# ============================================================================
+
+
+_CALLER_ID_RE = re.compile(
+    r"^cortex:(epidemiology|logistics|governance):"
+    r"(world_modeler|planner|critic):"
+    r"t\d+:r[12]:s\d+$"
+)
+
+
+@pytest.mark.parametrize(
+    "role_cls,brain,role_name",
+    [
+        (WorldModelerSubagent, "epidemiology", "world_modeler"),
+        (PlannerSubagent, "logistics", "planner"),
+        (CriticSubagent, "governance", "critic"),
+    ],
+)
+def test_subagent_caller_id_format(
+    role_cls: type,
+    brain: str,
+    role_name: str,
+) -> None:
+    stub = StubLLMClient(scripted_responses=[_valid_json_for(role_name, brain)])
+    agent = role_cls(llm_client=stub)
+    input_data = _make_subagent_input(
+        brain=brain,
+        role=role_name,
+        tick=7,
+        round_=2,
+        target_plan_id="plan-X" if role_name == "critic" else None,
+    )
+
+    agent.run(input_data, step_idx=4)
+
+    caller_id = stub.calls[0].caller_id
+    assert _CALLER_ID_RE.match(caller_id), (
+        f"caller_id={caller_id!r} does not match the locked format"
+    )
+    assert caller_id == f"cortex:{brain}:{role_name}:t7:r2:s4"
+
+
+# ============================================================================
+# T8 - SYS prompt loaded from prompts/<role>.txt and brain-formatted
+# (folds in the prompt-formatting refinement: format() must not raise)
+# ============================================================================
+
+
+@pytest.mark.parametrize(
+    "role_cls,role_name",
+    [
+        (WorldModelerSubagent, "world_modeler"),
+        (PlannerSubagent, "planner"),
+        (CriticSubagent, "critic"),
+    ],
+)
+def test_subagent_uses_loaded_prompt_from_file(role_cls: type, role_name: str) -> None:
+    raw = (PROMPTS_DIR / f"{role_name}.txt").read_text(encoding="utf-8")
+
+    # Refinement: format() must not raise even with extra kwargs ignored.
+    # Catches {{/}}-escape regressions in JSON-schema sections of the prompts.
+    formatted = raw.format(brain="epidemiology", target_plan_id="plan-X")
+    assert isinstance(formatted, str)
+    assert "epidemiology" in formatted
+
+    stub = StubLLMClient(scripted_responses=[_valid_json_for(role_name, "epidemiology")])
+    agent = role_cls(llm_client=stub)
+    input_data = _make_subagent_input(
+        brain="epidemiology",
+        role=role_name,
+        target_plan_id="plan-X" if role_name == "critic" else None,
+    )
+
+    agent.run(input_data, step_idx=0)
+
+    sys_msg = stub.calls[0].messages[0]
+    assert sys_msg.role == "system"
+    assert sys_msg.content == formatted
+
+
+# ============================================================================
+# T9 - Token counter is billed to the expected caller_id
+# ============================================================================
+
+
+def test_subagent_token_counter_billed_correctly() -> None:
+    stub = StubLLMClient(scripted_responses=[_valid_json_for("world_modeler", "epidemiology")])
+    agent = WorldModelerSubagent(llm_client=stub)
+    input_data = _make_subagent_input(brain="epidemiology", role="world_modeler", tick=3, round_=1)
+
+    agent.run(input_data, step_idx=0)
+
+    expected_caller_id = "cortex:epidemiology:world_modeler:t3:r1:s0"
+    assert stub.tokens_used_for(expected_caller_id) > 0, (
+        "tokens must be billed to the per-role caller_id, not silently lost"
+    )
+    assert stub.tokens_used_for("never:called") == 0
+
+
+# ============================================================================
+# T10 - empty_fallback shape locked per Phase A Decisions 6 + 62
+# ============================================================================
+
+
+def test_subagent_empty_fallback_shape_locked() -> None:
+    # WorldModeler: empty BeliefState
+    bs = WorldModelerSubagent.empty_fallback("epidemiology")
+    assert isinstance(bs, BeliefState)
+    assert bs.brain == "epidemiology"
+    assert bs.latent_estimates == {}
+    assert bs.hypotheses == []
+    assert bs.uncertainty == 1.0
+    assert bs.reducible_by_more_thought == 0.0
+    assert bs.evidence == []
+
+    # Planner: empty CandidatePlan with NoOp + confidence=0
+    cp = PlannerSubagent.empty_fallback("epidemiology")
+    assert isinstance(cp, CandidatePlan)
+    assert cp.expected_outer_action.kind == "no_op"
+    assert cp.expected_value == 0.0
+    assert cp.cost == 0.0
+    assert cp.assumptions == []
+    assert cp.falsifiers == []
+    assert cp.confidence == 0.0
+
+    # Critic: empty CriticReport with severity=0
+    cr = CriticSubagent.empty_fallback("epidemiology", target_plan_id="plan-X")
+    assert isinstance(cr, CriticReport)
+    assert cr.brain == "epidemiology"
+    assert cr.target_plan_id == "plan-X"
+    assert cr.attacks == []
+    assert cr.missing_considerations == []
+    assert cr.would_change_mind_if == []
+    assert cr.severity == 0.0
+
+
+# ============================================================================
+# T11 - retry call uses chat-history continuation (sys + usr + bad + retry)
+# ============================================================================
+
+
+def test_subagent_run_uses_chat_history_on_retry() -> None:
+    stub = StubLLMClient(
+        scripted_responses=["bad-json", _valid_json_for("world_modeler", "epidemiology")]
+    )
+    agent = WorldModelerSubagent(llm_client=stub)
+
+    agent.run(_make_subagent_input(brain="epidemiology", role="world_modeler"), step_idx=0)
+
+    assert stub.call_count == 2, "expected 2 LLM calls (initial + retry)"
+    call1, call2 = stub.calls
+
+    # call 1 has the original sys + user (2 messages).
+    assert len(call1.messages) == 2
+    assert call1.messages[0].role == "system"
+    assert call1.messages[1].role == "user"
+
+    # call 2 must contain: original sys + original user + assistant(bad-json) + retry-user.
+    # Without chat-history continuation the LLM loses schema context on retry.
+    assert len(call2.messages) == 4, "retry must append to the chat history, not start fresh"
+    assert call2.messages[0].role == "system"
+    assert call2.messages[0].content == call1.messages[0].content
+    assert call2.messages[1].role == "user"
+    assert call2.messages[1].content == call1.messages[1].content
+    assert call2.messages[2].role == "assistant"
+    assert call2.messages[2].content == "bad-json"
+    assert call2.messages[3].role == "user"
+    assert "failed to parse" in call2.messages[3].content.lower()

tests/test_outer_reward_in_range.py

@@ -1,8 +1,10 @@
-"""Outer reward stays in ``[0.0, 1.0]`` across diverse states.
+"""Outer reward stays in ``[-1.0, 1.0]`` across diverse states.
 
-Required by ``server/CLAUDE.md`` ("Every grader scalar reward component
-lives in ``[0.0, 1.0]``") and the ``tests/CLAUDE.md`` row
-``test_reward_shape.py``. Covers:
+Range relaxed by Workstream-B Phase-1 fix (M2-A): rejected actions land
+``r_policy = -0.5`` and parse-failure markers land ``r_policy = -1.0``,
+so the per-tick total can go negative. Upper bound stays at 1.0.
+
+Covers:
 
   - Initial state (right after ``load_task``, no ticks applied).
   - Mid-episode rollouts on all 3 tasks with varied actions.
@@ -29,7 +31,7 @@ def test_outer_reward_in_range_at_episode_start() -> None:
     for name in TASKS:
         state = load_task(name, episode_seed=0)
         r = outer_reward(state, NoOp())
-        assert 0.0 <= r <= 1.0, f"{name}: r={r!r} out of [0,1] at tick 0"
+        assert -1.0 <= r <= 1.0, f"{name}: r={r!r} out of [-1,1] at tick 0"
 
 
 def test_outer_reward_in_range_during_rollout() -> None:
@@ -51,8 +53,8 @@ def test_outer_reward_in_range_during_rollout() -> None:
         for action in actions:
             state = apply_tick(state, action)
             r = outer_reward(state, action)
-            assert 0.0 <= r <= 1.0, (
-                f"{name} tick={state.tick}: r={r!r} out of [0,1] after action kind={action.kind!r}"
+            assert -1.0 <= r <= 1.0, (
+                f"{name} tick={state.tick}: r={r!r} out of [-1,1] after action kind={action.kind!r}"
             )
 
 
@@ -67,7 +69,7 @@ def test_outer_reward_in_range_with_high_infection() -> None:
         region.S, region.E, region.I, region.R = 0.0, 0.0, 0.95, 0.05
     state.tick = state.max_ticks  # r_time → 0
     r = outer_reward(state, NoOp())
-    assert 0.0 <= r <= 1.0, f"high-I worst case: r={r!r}"
+    assert -1.0 <= r <= 1.0, f"high-I worst case: r={r!r}"
 
 
 def test_outer_reward_in_range_with_rejected_actions() -> None:
@@ -81,7 +83,7 @@ def test_outer_reward_in_range_with_rejected_actions() -> None:
     )
     state = apply_tick(state, a_v2)
     r = outer_reward(state, a_v2)
-    assert 0.0 <= r <= 1.0, f"V2-rejected: r={r!r}"
+    assert -1.0 <= r <= 1.0, f"V2-rejected: r={r!r}"
 
     # Legal-violation: strict severity before escalate-national on hard.
     state2 = load_task("outbreak_hard", episode_seed=0)
@@ -89,4 +91,4 @@ def test_outer_reward_in_range_with_rejected_actions() -> None:
     state2 = apply_tick(state2, a_legal)
     assert state2.recent_action_log[-1].accepted is False
     r2 = outer_reward(state2, a_legal)
-    assert 0.0 <= r2 <= 1.0, f"legal-violation: r={r2!r}"
+    assert -1.0 <= r2 <= 1.0, f"legal-violation: r={r2!r}"

tests/test_outer_reward_non_constancy.py

@@ -15,6 +15,11 @@ from CrisisWorldCortex.models import (
     RestrictMovement,
 )
 from CrisisWorldCortex.server.graders import outer_reward
+from CrisisWorldCortex.server.graders.outer_reward import (
+    R_POLICY_NOOP_ACCEPTED,
+    R_POLICY_REJECTED,
+    W_POLICY,
+)
 from CrisisWorldCortex.server.simulator import apply_tick, load_task
 
 
@@ -87,8 +92,12 @@ def test_reward_differs_for_accepted_vs_rejected_action() -> None:
 
     Compare two episodes from the same starting state: one issues NoOp
     (accepted), the other issues PublicCommunication (V2-rejected). The
-    SEIR step runs identically; only ``r_policy`` differs. With weight
-    0.12, the gap should be exactly 0.12 (modulo float rounding).
+    SEIR step runs identically; only ``r_policy`` differs. After the
+    Workstream-B Phase-1 four-state contract, NoOp(accepted) →
+    R_POLICY_NOOP_ACCEPTED (0.0) and PublicCommunication(honesty=0.9,
+    rejected as legal-violation) → R_POLICY_REJECTED (-0.5). The exact
+    gap is therefore ``(R_POLICY_NOOP_ACCEPTED - R_POLICY_REJECTED) *
+    W_POLICY`` (modulo float rounding).
     """
     s_a = load_task("outbreak_easy", episode_seed=42)
     s_b = load_task("outbreak_easy", episode_seed=42)
@@ -109,7 +118,7 @@ def test_reward_differs_for_accepted_vs_rejected_action() -> None:
     assert r_ok > r_bad, (
         f"accepted action should score higher than rejected: ok={r_ok!r} bad={r_bad!r}"
     )
-    # Exact gap = 0.12 because the only differing component is r_policy.
-    assert abs((r_ok - r_bad) - 0.12) < 1e-9, (
-        f"r_policy gap mismatch: ok-bad={r_ok - r_bad!r}, expected 0.12"
+    expected_gap = (R_POLICY_NOOP_ACCEPTED - R_POLICY_REJECTED) * W_POLICY
+    assert abs((r_ok - r_bad) - expected_gap) < 1e-9, (
+        f"r_policy gap mismatch: ok-bad={r_ok - r_bad!r}, expected {expected_gap!r}"
     )